[BACK]Return to eqn.7 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/eqn.7, Revision 1.31

1.31    ! schwarze    1: .\"    $Id: eqn.7,v 1.30 2014/10/10 08:44:24 kristaps Exp $
1.1       kristaps    2: .\"
                      3: .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
1.31    ! schwarze    4: .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
1.1       kristaps    5: .\"
                      6: .\" Permission to use, copy, modify, and distribute this software for any
                      7: .\" purpose with or without fee is hereby granted, provided that the above
                      8: .\" copyright notice and this permission notice appear in all copies.
                      9: .\"
                     10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
                     11: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
                     12: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
                     13: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
                     14: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
                     15: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
                     16: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
                     17: .\"
1.31    ! schwarze   18: .Dd $Mdocdate: October 10 2014 $
1.1       kristaps   19: .Dt EQN 7
                     20: .Os
                     21: .Sh NAME
                     22: .Nm eqn
                     23: .Nd eqn language reference for mandoc
                     24: .Sh DESCRIPTION
                     25: The
                     26: .Nm eqn
1.28      schwarze   27: language is an equation-formatting language.
1.1       kristaps   28: It is used within
                     29: .Xr mdoc 7
                     30: and
                     31: .Xr man 7
                     32: .Ux
                     33: manual pages.
1.25      kristaps   34: It describes the
                     35: .Em structure
                     36: of an equation, not its mathematical meaning.
1.23      kristaps   37: This manual describes the
1.1       kristaps   38: .Nm
                     39: language accepted by the
                     40: .Xr mandoc 1
1.31    ! schwarze   41: utility, which corresponds to the Second Edition
        !            42: .Nm
        !            43: specification (see
1.23      kristaps   44: .Sx SEE ALSO
                     45: for references).
1.1       kristaps   46: .Pp
                     47: Equations within
                     48: .Xr mdoc 7
                     49: or
                     50: .Xr man 7
1.3       kristaps   51: documents are enclosed by the standalone
                     52: .Sq \&.EQ
1.1       kristaps   53: and
1.3       kristaps   54: .Sq \&.EN
                     55: tags.
                     56: Equations are multi-line blocks consisting of formulas and control
                     57: statements.
                     58: .Sh EQUATION STRUCTURE
                     59: Each equation is bracketed by
                     60: .Sq \&.EQ
                     61: and
                     62: .Sq \&.EN
                     63: strings.
                     64: .Em Note :
                     65: these are not the same as
                     66: .Xr roff 7
                     67: macros, and may only be invoked as
                     68: .Sq \&.EQ .
                     69: .Pp
1.15      kristaps   70: The equation grammar is as follows, where quoted strings are
                     71: case-sensitive literals in the input:
1.3       kristaps   72: .Bd -literal -offset indent
                     73: eqn     : box | eqn box
                     74: box     : text
1.19      kristaps   75:         | \*q{\*q eqn \*q}\*q
                     76:         | \*qdefine\*q text text
1.23      kristaps   77:         | \*qndefine\*q text text
                     78:         | \*qtdefine\*q text text
1.19      kristaps   79:         | \*qgfont\*q text
                     80:         | \*qgsize\*q text
1.31    ! schwarze   81:         | \*qset\*q text text
1.19      kristaps   82:         | \*qundef\*q text
1.31    ! schwarze   83:         | \*qsqrt\*q box
1.11      kristaps   84:         | box pos box
1.9       kristaps   85:         | box mark
1.20      kristaps   86:         | \*qmatrix\*q \*q{\*q [col \*q{\*q list \*q}\*q ]*
1.19      kristaps   87:         | pile \*q{\*q list \*q}\*q
1.10      kristaps   88:         | font box
1.19      kristaps   89:         | \*qsize\*q text box
                     90:         | \*qleft\*q text eqn [\*qright\*q text]
1.24      kristaps   91: col     : \*qlcol\*q | \*qrcol\*q | \*qccol\*q | \*qcol\*q
1.19      kristaps   92: text    : [^space\e\*q]+ | \e\*q.*\e\*q
1.24      kristaps   93: pile    : \*qlpile\*q | \*qcpile\*q | \*qrpile\*q | \*qpile\*q
1.19      kristaps   94: pos     : \*qover\*q | \*qsup\*q | \*qsub\*q | \*qto\*q | \*qfrom\*q
                     95: mark   : \*qdot\*q | \*qdotdot\*q | \*qhat\*q | \*qtilde\*q | \*qvec\*q
                     96:         | \*qdyad\*q | \*qbar\*q | \*qunder\*q
1.22      kristaps   97: font    : \*qroman\*q | \*qitalic\*q | \*qbold\*q | \*qfat\*q
1.19      kristaps   98: list    : eqn
                     99:         | list \*qabove\*q eqn
                    100: space   : [\e^~ \et]
1.3       kristaps  101: .Ed
                    102: .Pp
1.19      kristaps  103: White-space consists of the space, tab, circumflex, and tilde
                    104: characters.
1.31    ! schwarze  105: It is required to delimit tokens consisting of alphabetic characters
        !           106: and it is ignored at other places.
        !           107: Braces and quotes also delimit tokens.
1.19      kristaps  108: If within a quoted string, these space characters are retained.
1.31    ! schwarze  109: Quoted strings are also not scanned for keywords, glyph names,
        !           110: and expansion of definitions.
        !           111: To print a literal quote character, it can be prepended with a
        !           112: backslash or expressed with the \e(dq escape sequence.
        !           113: .Pp
        !           114: Subequations can be enclosed in braces to pass them as arguments
        !           115: to operation keywords, overriding standard operation precedence.
        !           116: Braces can be nested.
        !           117: To set a brace verbatim, it needs to be enclosed in quotes.
1.16      kristaps  118: .Pp
1.19      kristaps  119: The following text terms are translated into a rendered glyph, if
1.16      kristaps  120: available: alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa,
                    121: lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta,
                    122: upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA,
                    123: THETA, UPSILON, XI, inter (intersection), union (union), prod (product),
                    124: int (integral), sum (summation), grad (gradient), del (vector
                    125: differential), times (multiply), cdot (centre-dot), nothing (zero-width
                    126: space), approx (approximately equals), prime (prime), half (one-half),
                    127: partial (partial differential), inf (infinity), >> (much greater), <<
1.31    ! schwarze  128: (much less), \-> (left arrow), <\- (right arrow), +\- (plus-minus), !=
1.16      kristaps  129: (not equal), == (equivalence), <= (less-than-equal), and >=
                    130: (more-than-equal).
1.31    ! schwarze  131: The character escape sequences documented in
        !           132: .Xr mandoc_char 7
        !           133: can be used, too.
1.3       kristaps  134: .Pp
                    135: The following control statements are available:
                    136: .Bl -tag -width Ds
                    137: .It Cm define
1.27      kristaps  138: Replace all occurrences of a key with a value.
1.3       kristaps  139: Its syntax is as follows:
                    140: .Pp
1.31    ! schwarze  141: .D1 Cm define Ar key cvalc
1.5       kristaps  142: .Pp
                    143: The first character of the value string,
                    144: .Ar c ,
                    145: is used as the delimiter for the value
                    146: .Ar val .
                    147: This allows for arbitrary enclosure of terms (not just quotes), such as
                    148: .Pp
1.31    ! schwarze  149: .D1 Cm define Ar foo 'bar baz'
        !           150: .D1 Cm define Ar foo cbar bazc
1.2       kristaps  151: .Pp
1.3       kristaps  152: It is an error to have an empty
1.28      schwarze  153: .Ar key
                    154: or
1.5       kristaps  155: .Ar val .
1.3       kristaps  156: Note that a quoted
                    157: .Ar key
                    158: causes errors in some
1.2       kristaps  159: .Nm
1.3       kristaps  160: implementations and should not be considered portable.
1.7       kristaps  161: It is not expanded for replacements.
1.4       kristaps  162: Definitions may refer to other definitions; these are evaluated
                    163: recursively when text replacement occurs and not when the definition is
                    164: created.
1.5       kristaps  165: .Pp
                    166: Definitions can create arbitrary strings, for example, the following is
                    167: a legal construction.
                    168: .Bd -literal -offset indent
                    169: define foo 'define'
                    170: foo bar 'baz'
                    171: .Ed
                    172: .Pp
1.4       kristaps  173: Self-referencing definitions will raise an error.
1.23      kristaps  174: The
                    175: .Cm ndefine
                    176: statement is a synonym for
                    177: .Cm define ,
                    178: while
                    179: .Cm tdefine
                    180: is discarded.
1.18      kristaps  181: .It Cm gfont
                    182: Set the default font of subsequent output.
                    183: Its syntax is as follows:
                    184: .Pp
1.31    ! schwarze  185: .D1 Cm gfont Ar font
1.18      kristaps  186: .Pp
                    187: In mandoc, this value is discarded.
1.17      kristaps  188: .It Cm gsize
                    189: Set the default size of subsequent output.
                    190: Its syntax is as follows:
                    191: .Pp
1.31    ! schwarze  192: .D1 Cm gsize Oo +|\- Oc Ns Ar size
1.17      kristaps  193: .Pp
                    194: The
                    195: .Ar size
                    196: value should be an integer.
1.31    ! schwarze  197: If prepended by a sign,
        !           198: the font size is changed relative to the current size.
1.3       kristaps  199: .It Cm set
1.4       kristaps  200: Set an equation mode.
1.18      kristaps  201: In mandoc, both arguments are thrown away.
1.7       kristaps  202: Its syntax is as follows:
                    203: .Pp
1.31    ! schwarze  204: .D1 Cm set Ar key val
1.7       kristaps  205: .Pp
                    206: The
                    207: .Ar key
                    208: and
                    209: .Ar val
                    210: are not expanded for replacements.
1.24      kristaps  211: This statement is a GNU extension.
1.3       kristaps  212: .It Cm undef
                    213: Unset a previously-defined key.
                    214: Its syntax is as follows:
                    215: .Pp
1.31    ! schwarze  216: .D1 Cm define Ar key
1.2       kristaps  217: .Pp
1.3       kristaps  218: Once invoked, the definition for
                    219: .Ar key
                    220: is discarded.
1.7       kristaps  221: The
                    222: .Ar key
                    223: is not expanded for replacements.
1.24      kristaps  224: This statement is a GNU extension.
1.3       kristaps  225: .El
1.31    ! schwarze  226: .Pp
        !           227: Operation keywords have the following semantics:
        !           228: .Bl -tag -width Ds
        !           229: .It Cm above
        !           230: See
        !           231: .Cm pile .
        !           232: .It Cm bar
        !           233: Draw a line over the preceding box.
        !           234: .It Cm bold
        !           235: Set the following box using bold font.
        !           236: .It Cm ccol
        !           237: Like
        !           238: .Cm cpile ,
        !           239: but for use in
        !           240: .Cm matrix .
        !           241: .It Cm cpile
        !           242: Like
        !           243: .Cm pile ,
        !           244: but with slightly increased vertical spacing.
        !           245: .It Cm dot
        !           246: Set a single dot over the preceding box.
        !           247: .It Cm dotdot
        !           248: Set two dots (dieresis) over the preceding box.
        !           249: .It Cm dyad
        !           250: Set a dyad symbol (left-right arrow) over the preceding box.
        !           251: .It Cm fat
        !           252: A synonym for
        !           253: .Cm bold .
        !           254: .It Cm font
        !           255: Set the second argument using the font specified by the first argument;
        !           256: currently not recognized by the
        !           257: .Xr mandoc 1
        !           258: .Nm
        !           259: parser.
        !           260: .It Cm from
        !           261: Set the following box below the preceding box,
        !           262: using a slightly smaller font.
        !           263: Used for sums, integrals, limits, and the like.
        !           264: .It Cm hat
        !           265: Set a hat (circumflex) over the preceding box.
        !           266: .It Cm italic
        !           267: Set the following box using italic font.
        !           268: .It Cm lcol
        !           269: Like
        !           270: .Cm lpile ,
        !           271: but for use in
        !           272: .Cm matrix .
        !           273: .It Cm left
        !           274: Set the first argument as a big left delimiter before the second argument.
        !           275: As an optional third argument,
        !           276: .Cm right
        !           277: can follow.
        !           278: In that case, the fourth argument is set as a big right delimiter after
        !           279: the second argument.
        !           280: .It Cm lpile
        !           281: Like
        !           282: .Cm cpile ,
        !           283: but subequations are left-justified.
        !           284: .It Cm matrix
        !           285: Followed by a list of columns enclosed in braces.
        !           286: All columns need to have the same number of subequations.
        !           287: The columns are set as a matrix.
        !           288: The difference compared to multiple subsequent
        !           289: .Cm pile
        !           290: operators is that in a
        !           291: .Cm matrix ,
        !           292: corresponding subequations in all columns line up horizontally,
        !           293: while each
        !           294: .Cm pile
        !           295: does vertical spacing independently.
        !           296: .It Cm over
        !           297: Set a fraction.
        !           298: The preceding box is the numerator, the following box is the denominator.
        !           299: .It Cm pile
        !           300: Followed by a list of subequations enclosed in braces,
        !           301: the subequations being separated by
        !           302: .Cm above
        !           303: keywords.
        !           304: Sets the subequations one above the other, each of them centered.
        !           305: Typically used to represent vectors in coordinate representation.
        !           306: .It Cm rcol
        !           307: Like
        !           308: .Cm rpile ,
        !           309: but for use in
        !           310: .Cm matrix .
        !           311: .It Cm right
        !           312: See
        !           313: .Cm left ;
        !           314: .Cm right
        !           315: cannot be used without
        !           316: .Cm left .
        !           317: To set a big right delimiter without a big left delimiter, the following
        !           318: construction can be used:
        !           319: .Pp
        !           320: .D1 Cm left No \(dq\(dq Ar box Cm right Ar delimiter
        !           321: .It Cm roman
        !           322: Set the following box using the default font.
        !           323: .It Cm rpile
        !           324: Like
        !           325: .Cm cpile ,
        !           326: but subequations are right-justified.
        !           327: .It Cm size
        !           328: Set the second argument with the font size specified by the first
        !           329: argument; currently ignored by
        !           330: .Xr mandoc 1 .
        !           331: By prepending a plus or minus sign to the first argument,
        !           332: the font size can be selected relative to the current size.
        !           333: .It Cm sqrt
        !           334: Set the square root of the following box.
        !           335: .It Cm sub
        !           336: Set the following box as a subscript to the preceding box.
        !           337: .It Cm sup
        !           338: Set the following box as a superscript to the preceding box.
        !           339: As a special case, if a
        !           340: .Cm sup
        !           341: clause immediately follows a
        !           342: .Cm sub
        !           343: clause as in
        !           344: .Pp
        !           345: .D1 Ar mainbox Cm sub Ar subbox Cm sup Ar supbox
        !           346: .Pp
        !           347: both are set with respect to the same
        !           348: .Ar mainbox ,
        !           349: that is,
        !           350: .Ar supbox
        !           351: is set above
        !           352: .Ar subbox .
        !           353: .It Cm tilde
        !           354: Set a tilde over the preceding box.
        !           355: .It Cm to
        !           356: Set the following box above the preceding box,
        !           357: using a slightly smaller font.
        !           358: Used for sums and integrals and the like.
        !           359: As a special case, if a
        !           360: .Cm to
        !           361: clause immediately follows a
        !           362: .Cm from
        !           363: clause as in
        !           364: .Pp
        !           365: .D1 Ar mainbox Cm from Ar frombox Cm to Ar tobox
        !           366: .Pp
        !           367: both are set below and above the same
        !           368: .Ar mainbox .
        !           369: .It Cm under
        !           370: Underline the preceding box.
        !           371: .It Cm vec
        !           372: Set a vector symbol (right arrow) over the preceding box.
        !           373: .El
        !           374: .Pp
        !           375: The binary operations
        !           376: .Cm from ,
        !           377: .Cm to ,
        !           378: .Cm sub ,
        !           379: and
        !           380: .Cm sup
        !           381: group to the right, that is,
        !           382: .Pp
        !           383: .D1 Ar mainbox Cm sup Ar supbox Cm sub Ar subbox
        !           384: .Pp
        !           385: is the same as
        !           386: .Pp
        !           387: .D1 Ar mainbox Cm sup Brq Ar supbox Cm sub Ar subbox
        !           388: .Pp
        !           389: and different from
        !           390: .Pp
        !           391: .D1 Bro Ar mainbox Cm sup Ar supbox Brc Cm sub Ar subbox .
        !           392: .Pp
        !           393: By contrast,
        !           394: .Cm over
        !           395: groups to the left.
        !           396: .Pp
        !           397: In the following list, earlier operations bind more tightly than
        !           398: later operations:
        !           399: .Pp
        !           400: .Bl -enum -compact
        !           401: .It
        !           402: .Cm dyad ,
        !           403: .Cm vec ,
        !           404: .Cm under ,
        !           405: .Cm bar ,
        !           406: .Cm tilde ,
        !           407: .Cm hat ,
        !           408: .Cm dot ,
        !           409: .Cm dotdot
        !           410: .It
        !           411: .Cm fat ,
        !           412: .Cm roman ,
        !           413: .Cm italic ,
        !           414: .Cm bold ,
        !           415: .Cm size
        !           416: .It
        !           417: .Cm sub ,
        !           418: .Cm sup
        !           419: .It
        !           420: .Cm sqrt
        !           421: .It
        !           422: .Cm over
        !           423: .It
        !           424: .Cm from ,
        !           425: .Cm to
        !           426: .El
1.5       kristaps  427: .Sh COMPATIBILITY
                    428: This section documents the compatibility of mandoc
                    429: .Nm
                    430: and the troff
                    431: .Nm
                    432: implementation (including GNU troff).
                    433: .Pp
                    434: .Bl -dash -compact
                    435: .It
                    436: The text string
                    437: .Sq \e\*q
                    438: is interpreted as a literal quote in troff.
                    439: In mandoc, this is interpreted as a comment.
1.19      kristaps  440: .It
                    441: In troff, The circumflex and tilde white-space symbols map to
                    442: fixed-width spaces.
                    443: In mandoc, these characters are synonyms for the space character.
1.21      kristaps  444: .It
                    445: The troff implementation of
                    446: .Nm
                    447: allows for equation alignment with the
                    448: .Cm mark
                    449: and
                    450: .Cm lineup
                    451: tokens.
                    452: mandoc discards these tokens.
                    453: The
                    454: .Cm back Ar n ,
                    455: .Cm fwd Ar n ,
                    456: .Cm up Ar n ,
                    457: and
                    458: .Cm down Ar n
                    459: commands are also ignored.
1.31    ! schwarze  460: .It
        !           461: Inline equations and the
        !           462: .Cm delim
        !           463: control statement are not yet implemented in
        !           464: .Xr mandoc 1 .
1.5       kristaps  465: .El
1.1       kristaps  466: .Sh SEE ALSO
                    467: .Xr mandoc 1 ,
                    468: .Xr man 7 ,
                    469: .Xr mandoc_char 7 ,
                    470: .Xr mdoc 7 ,
                    471: .Xr roff 7
                    472: .Rs
                    473: .%A Brian W. Kernighan
                    474: .%A Lorinda L. Cherry
                    475: .%T System for Typesetting Mathematics
                    476: .%J Communications of the ACM
                    477: .%V 18
                    478: .%P 151\(en157
                    479: .%D March, 1975
                    480: .Re
1.5       kristaps  481: .Rs
                    482: .%A Brian W. Kernighan
                    483: .%A Lorinda L. Cherry
                    484: .%T Typesetting Mathematics, User's Guide
                    485: .%D 1976
                    486: .Re
                    487: .Rs
                    488: .%A Brian W. Kernighan
                    489: .%A Lorinda L. Cherry
                    490: .%T Typesetting Mathematics, User's Guide (Second Edition)
                    491: .%D 1978
                    492: .Re
                    493: .Sh HISTORY
1.15      kristaps  494: The eqn utility, a preprocessor for troff, was originally written by
1.5       kristaps  495: Brian W. Kernighan and Lorinda L. Cherry in 1975.
                    496: The GNU reimplementation of eqn, part of the GNU troff package, was
                    497: released in 1989 by James Clark.
                    498: The eqn component of
                    499: .Xr mandoc 1
                    500: was added in 2011.
1.1       kristaps  501: .Sh AUTHORS
1.5       kristaps  502: This
1.1       kristaps  503: .Nm
                    504: reference was written by
1.29      schwarze  505: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .

CVSweb