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

Annotation of mandoc/eqn.7, Revision 1.37

1.37    ! schwarze    1: .\"    $Id: eqn.7,v 1.36 2017/07/20 11:07:27 schwarze 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.37    ! schwarze   18: .Dd $Mdocdate: July 20 2017 $
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.34      schwarze   75:         | \(dq{\(dq eqn \(dq}\(dq
                     76:         | \(dqdefine\(dq text text
                     77:         | \(dqndefine\(dq text text
                     78:         | \(dqtdefine\(dq text text
                     79:         | \(dqgfont\(dq text
                     80:         | \(dqgsize\(dq text
                     81:         | \(dqset\(dq text text
                     82:         | \(dqundef\(dq text
                     83:         | \(dqsqrt\(dq box
1.11      kristaps   84:         | box pos box
1.9       kristaps   85:         | box mark
1.37    ! schwarze   86:         | \(dqmatrix\(dq \(dq{\(dq [col \(dq{\(dq list \(dq}\(dq]* \(dq}\(dq
1.34      schwarze   87:         | pile \(dq{\(dq list \(dq}\(dq
1.10      kristaps   88:         | font box
1.34      schwarze   89:         | \(dqsize\(dq text box
                     90:         | \(dqleft\(dq text eqn [\(dqright\(dq text]
                     91: col     : \(dqlcol\(dq | \(dqrcol\(dq | \(dqccol\(dq | \(dqcol\(dq
                     92: text    : [^space\e\(dq]+ | \e\(dq.*\e\(dq
                     93: pile    : \(dqlpile\(dq | \(dqcpile\(dq | \(dqrpile\(dq | \(dqpile\(dq
                     94: pos     : \(dqover\(dq | \(dqsup\(dq | \(dqsub\(dq | \(dqto\(dq | \(dqfrom\(dq
                     95: mark   : \(dqdot\(dq | \(dqdotdot\(dq | \(dqhat\(dq | \(dqtilde\(dq | \(dqvec\(dq
                     96:         | \(dqdyad\(dq | \(dqbar\(dq | \(dqunder\(dq
                     97: font    : \(dqroman\(dq | \(dqitalic\(dq | \(dqbold\(dq | \(dqfat\(dq
1.19      kristaps   98: list    : eqn
1.34      schwarze   99:         | list \(dqabove\(dq eqn
1.19      kristaps  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
1.32      schwarze  125: differential), times (multiply), cdot (center-dot), nothing (zero-width
1.16      kristaps  126: space), approx (approximately equals), prime (prime), half (one-half),
                    127: partial (partial differential), inf (infinity), >> (much greater), <<
1.36      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.35      schwarze  149: .D1 Cm define Ar foo \(aqbar baz\(aq
1.31      schwarze  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
1.35      schwarze  169: define foo \(aqdefine\(aq
                    170: foo bar \(aqbaz\(aq
1.5       kristaps  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
1.34      schwarze  437: .Sq \e\(dq
1.5       kristaps  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.5       kristaps  460: .El
1.1       kristaps  461: .Sh SEE ALSO
                    462: .Xr mandoc 1 ,
                    463: .Xr man 7 ,
                    464: .Xr mandoc_char 7 ,
                    465: .Xr mdoc 7 ,
                    466: .Xr roff 7
                    467: .Rs
                    468: .%A Brian W. Kernighan
                    469: .%A Lorinda L. Cherry
                    470: .%T System for Typesetting Mathematics
                    471: .%J Communications of the ACM
                    472: .%V 18
                    473: .%P 151\(en157
                    474: .%D March, 1975
                    475: .Re
1.5       kristaps  476: .Rs
                    477: .%A Brian W. Kernighan
                    478: .%A Lorinda L. Cherry
                    479: .%T Typesetting Mathematics, User's Guide
                    480: .%D 1976
                    481: .Re
                    482: .Rs
                    483: .%A Brian W. Kernighan
                    484: .%A Lorinda L. Cherry
                    485: .%T Typesetting Mathematics, User's Guide (Second Edition)
                    486: .%D 1978
                    487: .Re
                    488: .Sh HISTORY
1.15      kristaps  489: The eqn utility, a preprocessor for troff, was originally written by
1.5       kristaps  490: Brian W. Kernighan and Lorinda L. Cherry in 1975.
                    491: The GNU reimplementation of eqn, part of the GNU troff package, was
                    492: released in 1989 by James Clark.
                    493: The eqn component of
                    494: .Xr mandoc 1
                    495: was added in 2011.
1.1       kristaps  496: .Sh AUTHORS
1.5       kristaps  497: This
1.1       kristaps  498: .Nm
                    499: reference was written by
1.29      schwarze  500: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .

CVSweb