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

Annotation of mandoc/eqn.7, Revision 1.39

1.39    ! schwarze    1: .\"    $Id: eqn.7,v 1.38 2019/04/23 17:57:49 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.39    ! schwarze   18: .Dd $Mdocdate: April 23 2019 $
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
1.39    ! schwarze   47: An equation starts with an input line containing exactly the characters
        !            48: .Sq \&.EQ ,
        !            49: may contain multiple input lines, and ends with an input line
        !            50: containing exactly the characters
        !            51: .Sq \&.EN .
        !            52: Equivalently, an equation can be given in the middle of a single
        !            53: text input line by surrounding it with the equation delimiters
        !            54: defined with the
        !            55: .Cm delim
        !            56: statement.
1.3       kristaps   57: .Pp
1.15      kristaps   58: The equation grammar is as follows, where quoted strings are
                     59: case-sensitive literals in the input:
1.3       kristaps   60: .Bd -literal -offset indent
                     61: eqn     : box | eqn box
                     62: box     : text
1.34      schwarze   63:         | \(dq{\(dq eqn \(dq}\(dq
                     64:         | \(dqdefine\(dq text text
                     65:         | \(dqndefine\(dq text text
                     66:         | \(dqtdefine\(dq text text
                     67:         | \(dqgfont\(dq text
                     68:         | \(dqgsize\(dq text
                     69:         | \(dqset\(dq text text
                     70:         | \(dqundef\(dq text
                     71:         | \(dqsqrt\(dq box
1.11      kristaps   72:         | box pos box
1.9       kristaps   73:         | box mark
1.37      schwarze   74:         | \(dqmatrix\(dq \(dq{\(dq [col \(dq{\(dq list \(dq}\(dq]* \(dq}\(dq
1.34      schwarze   75:         | pile \(dq{\(dq list \(dq}\(dq
1.10      kristaps   76:         | font box
1.34      schwarze   77:         | \(dqsize\(dq text box
                     78:         | \(dqleft\(dq text eqn [\(dqright\(dq text]
                     79: col     : \(dqlcol\(dq | \(dqrcol\(dq | \(dqccol\(dq | \(dqcol\(dq
                     80: text    : [^space\e\(dq]+ | \e\(dq.*\e\(dq
                     81: pile    : \(dqlpile\(dq | \(dqcpile\(dq | \(dqrpile\(dq | \(dqpile\(dq
                     82: pos     : \(dqover\(dq | \(dqsup\(dq | \(dqsub\(dq | \(dqto\(dq | \(dqfrom\(dq
                     83: mark   : \(dqdot\(dq | \(dqdotdot\(dq | \(dqhat\(dq | \(dqtilde\(dq | \(dqvec\(dq
                     84:         | \(dqdyad\(dq | \(dqbar\(dq | \(dqunder\(dq
                     85: font    : \(dqroman\(dq | \(dqitalic\(dq | \(dqbold\(dq | \(dqfat\(dq
1.19      kristaps   86: list    : eqn
1.34      schwarze   87:         | list \(dqabove\(dq eqn
1.19      kristaps   88: space   : [\e^~ \et]
1.3       kristaps   89: .Ed
                     90: .Pp
1.19      kristaps   91: White-space consists of the space, tab, circumflex, and tilde
                     92: characters.
1.31      schwarze   93: It is required to delimit tokens consisting of alphabetic characters
                     94: and it is ignored at other places.
                     95: Braces and quotes also delimit tokens.
1.19      kristaps   96: If within a quoted string, these space characters are retained.
1.31      schwarze   97: Quoted strings are also not scanned for keywords, glyph names,
                     98: and expansion of definitions.
                     99: To print a literal quote character, it can be prepended with a
                    100: backslash or expressed with the \e(dq escape sequence.
                    101: .Pp
                    102: Subequations can be enclosed in braces to pass them as arguments
                    103: to operation keywords, overriding standard operation precedence.
                    104: Braces can be nested.
                    105: To set a brace verbatim, it needs to be enclosed in quotes.
1.16      kristaps  106: .Pp
1.19      kristaps  107: The following text terms are translated into a rendered glyph, if
1.16      kristaps  108: available: alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa,
                    109: lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta,
                    110: upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA,
                    111: THETA, UPSILON, XI, inter (intersection), union (union), prod (product),
                    112: int (integral), sum (summation), grad (gradient), del (vector
1.32      schwarze  113: differential), times (multiply), cdot (center-dot), nothing (zero-width
1.16      kristaps  114: space), approx (approximately equals), prime (prime), half (one-half),
                    115: partial (partial differential), inf (infinity), >> (much greater), <<
1.36      schwarze  116: (much less), <\- (left arrow), \-> (right arrow), +\- (plus-minus), !=
1.16      kristaps  117: (not equal), == (equivalence), <= (less-than-equal), and >=
                    118: (more-than-equal).
1.31      schwarze  119: The character escape sequences documented in
                    120: .Xr mandoc_char 7
                    121: can be used, too.
1.3       kristaps  122: .Pp
                    123: The following control statements are available:
                    124: .Bl -tag -width Ds
                    125: .It Cm define
1.27      kristaps  126: Replace all occurrences of a key with a value.
1.3       kristaps  127: Its syntax is as follows:
                    128: .Pp
1.31      schwarze  129: .D1 Cm define Ar key cvalc
1.5       kristaps  130: .Pp
                    131: The first character of the value string,
                    132: .Ar c ,
                    133: is used as the delimiter for the value
                    134: .Ar val .
                    135: This allows for arbitrary enclosure of terms (not just quotes), such as
                    136: .Pp
1.35      schwarze  137: .D1 Cm define Ar foo \(aqbar baz\(aq
1.31      schwarze  138: .D1 Cm define Ar foo cbar bazc
1.2       kristaps  139: .Pp
1.3       kristaps  140: It is an error to have an empty
1.28      schwarze  141: .Ar key
                    142: or
1.5       kristaps  143: .Ar val .
1.3       kristaps  144: Note that a quoted
                    145: .Ar key
                    146: causes errors in some
1.2       kristaps  147: .Nm
1.3       kristaps  148: implementations and should not be considered portable.
1.7       kristaps  149: It is not expanded for replacements.
1.4       kristaps  150: Definitions may refer to other definitions; these are evaluated
                    151: recursively when text replacement occurs and not when the definition is
                    152: created.
1.5       kristaps  153: .Pp
                    154: Definitions can create arbitrary strings, for example, the following is
                    155: a legal construction.
                    156: .Bd -literal -offset indent
1.35      schwarze  157: define foo \(aqdefine\(aq
                    158: foo bar \(aqbaz\(aq
1.5       kristaps  159: .Ed
                    160: .Pp
1.4       kristaps  161: Self-referencing definitions will raise an error.
1.23      kristaps  162: The
                    163: .Cm ndefine
                    164: statement is a synonym for
                    165: .Cm define ,
                    166: while
                    167: .Cm tdefine
                    168: is discarded.
1.39    ! schwarze  169: .It Cm delim
        !           170: This statement takes a string argument consisting of two bytes,
        !           171: to be used as the opening and closing delimiters for equations
        !           172: in the middle of text input lines.
        !           173: Conventionally, the dollar sign is used for both delimiters,
        !           174: as follows:
        !           175: .Bd -literal -offset indent
        !           176: \&.EQ
        !           177: delim $$
        !           178: \&.EN
        !           179: An equation like $sin pi = 0$ can now be entered
        !           180: in the middle of a text input line.
        !           181: .Ed
        !           182: .Pp
        !           183: The special statement
        !           184: .Cm delim off
        !           185: temporarily disables previously declared delimiters and
        !           186: .Cm delim on
        !           187: reenables them.
1.18      kristaps  188: .It Cm gfont
                    189: Set the default font of subsequent output.
                    190: Its syntax is as follows:
                    191: .Pp
1.31      schwarze  192: .D1 Cm gfont Ar font
1.18      kristaps  193: .Pp
                    194: In mandoc, this value is discarded.
1.17      kristaps  195: .It Cm gsize
                    196: Set the default size of subsequent output.
                    197: Its syntax is as follows:
                    198: .Pp
1.31      schwarze  199: .D1 Cm gsize Oo +|\- Oc Ns Ar size
1.17      kristaps  200: .Pp
                    201: The
                    202: .Ar size
                    203: value should be an integer.
1.31      schwarze  204: If prepended by a sign,
                    205: the font size is changed relative to the current size.
1.3       kristaps  206: .It Cm set
1.4       kristaps  207: Set an equation mode.
1.18      kristaps  208: In mandoc, both arguments are thrown away.
1.7       kristaps  209: Its syntax is as follows:
                    210: .Pp
1.31      schwarze  211: .D1 Cm set Ar key val
1.7       kristaps  212: .Pp
                    213: The
                    214: .Ar key
                    215: and
                    216: .Ar val
                    217: are not expanded for replacements.
1.24      kristaps  218: This statement is a GNU extension.
1.3       kristaps  219: .It Cm undef
                    220: Unset a previously-defined key.
                    221: Its syntax is as follows:
                    222: .Pp
1.31      schwarze  223: .D1 Cm define Ar key
1.2       kristaps  224: .Pp
1.3       kristaps  225: Once invoked, the definition for
                    226: .Ar key
                    227: is discarded.
1.7       kristaps  228: The
                    229: .Ar key
                    230: is not expanded for replacements.
1.24      kristaps  231: This statement is a GNU extension.
1.3       kristaps  232: .El
1.31      schwarze  233: .Pp
                    234: Operation keywords have the following semantics:
                    235: .Bl -tag -width Ds
                    236: .It Cm above
                    237: See
                    238: .Cm pile .
                    239: .It Cm bar
                    240: Draw a line over the preceding box.
                    241: .It Cm bold
                    242: Set the following box using bold font.
                    243: .It Cm ccol
                    244: Like
                    245: .Cm cpile ,
                    246: but for use in
                    247: .Cm matrix .
                    248: .It Cm cpile
                    249: Like
                    250: .Cm pile ,
                    251: but with slightly increased vertical spacing.
                    252: .It Cm dot
                    253: Set a single dot over the preceding box.
                    254: .It Cm dotdot
                    255: Set two dots (dieresis) over the preceding box.
                    256: .It Cm dyad
                    257: Set a dyad symbol (left-right arrow) over the preceding box.
                    258: .It Cm fat
                    259: A synonym for
                    260: .Cm bold .
                    261: .It Cm font
                    262: Set the second argument using the font specified by the first argument;
                    263: currently not recognized by the
                    264: .Xr mandoc 1
                    265: .Nm
                    266: parser.
                    267: .It Cm from
                    268: Set the following box below the preceding box,
                    269: using a slightly smaller font.
                    270: Used for sums, integrals, limits, and the like.
                    271: .It Cm hat
                    272: Set a hat (circumflex) over the preceding box.
                    273: .It Cm italic
                    274: Set the following box using italic font.
                    275: .It Cm lcol
                    276: Like
                    277: .Cm lpile ,
                    278: but for use in
                    279: .Cm matrix .
                    280: .It Cm left
                    281: Set the first argument as a big left delimiter before the second argument.
                    282: As an optional third argument,
                    283: .Cm right
                    284: can follow.
                    285: In that case, the fourth argument is set as a big right delimiter after
                    286: the second argument.
                    287: .It Cm lpile
                    288: Like
                    289: .Cm cpile ,
                    290: but subequations are left-justified.
                    291: .It Cm matrix
                    292: Followed by a list of columns enclosed in braces.
                    293: All columns need to have the same number of subequations.
                    294: The columns are set as a matrix.
                    295: The difference compared to multiple subsequent
                    296: .Cm pile
                    297: operators is that in a
                    298: .Cm matrix ,
                    299: corresponding subequations in all columns line up horizontally,
                    300: while each
                    301: .Cm pile
                    302: does vertical spacing independently.
                    303: .It Cm over
                    304: Set a fraction.
                    305: The preceding box is the numerator, the following box is the denominator.
                    306: .It Cm pile
                    307: Followed by a list of subequations enclosed in braces,
                    308: the subequations being separated by
                    309: .Cm above
                    310: keywords.
                    311: Sets the subequations one above the other, each of them centered.
                    312: Typically used to represent vectors in coordinate representation.
                    313: .It Cm rcol
                    314: Like
                    315: .Cm rpile ,
                    316: but for use in
                    317: .Cm matrix .
                    318: .It Cm right
                    319: See
                    320: .Cm left ;
                    321: .Cm right
                    322: cannot be used without
                    323: .Cm left .
                    324: To set a big right delimiter without a big left delimiter, the following
                    325: construction can be used:
                    326: .Pp
                    327: .D1 Cm left No \(dq\(dq Ar box Cm right Ar delimiter
                    328: .It Cm roman
                    329: Set the following box using the default font.
                    330: .It Cm rpile
                    331: Like
                    332: .Cm cpile ,
                    333: but subequations are right-justified.
                    334: .It Cm size
                    335: Set the second argument with the font size specified by the first
                    336: argument; currently ignored by
                    337: .Xr mandoc 1 .
                    338: By prepending a plus or minus sign to the first argument,
                    339: the font size can be selected relative to the current size.
                    340: .It Cm sqrt
                    341: Set the square root of the following box.
                    342: .It Cm sub
                    343: Set the following box as a subscript to the preceding box.
                    344: .It Cm sup
                    345: Set the following box as a superscript to the preceding box.
                    346: As a special case, if a
                    347: .Cm sup
                    348: clause immediately follows a
                    349: .Cm sub
                    350: clause as in
                    351: .Pp
                    352: .D1 Ar mainbox Cm sub Ar subbox Cm sup Ar supbox
                    353: .Pp
                    354: both are set with respect to the same
                    355: .Ar mainbox ,
                    356: that is,
                    357: .Ar supbox
                    358: is set above
                    359: .Ar subbox .
                    360: .It Cm tilde
                    361: Set a tilde over the preceding box.
                    362: .It Cm to
                    363: Set the following box above the preceding box,
                    364: using a slightly smaller font.
                    365: Used for sums and integrals and the like.
                    366: As a special case, if a
                    367: .Cm to
                    368: clause immediately follows a
                    369: .Cm from
                    370: clause as in
                    371: .Pp
                    372: .D1 Ar mainbox Cm from Ar frombox Cm to Ar tobox
                    373: .Pp
                    374: both are set below and above the same
                    375: .Ar mainbox .
                    376: .It Cm under
                    377: Underline the preceding box.
                    378: .It Cm vec
                    379: Set a vector symbol (right arrow) over the preceding box.
                    380: .El
                    381: .Pp
                    382: The binary operations
                    383: .Cm from ,
                    384: .Cm to ,
                    385: .Cm sub ,
                    386: and
                    387: .Cm sup
                    388: group to the right, that is,
                    389: .Pp
                    390: .D1 Ar mainbox Cm sup Ar supbox Cm sub Ar subbox
                    391: .Pp
                    392: is the same as
                    393: .Pp
                    394: .D1 Ar mainbox Cm sup Brq Ar supbox Cm sub Ar subbox
                    395: .Pp
                    396: and different from
                    397: .Pp
                    398: .D1 Bro Ar mainbox Cm sup Ar supbox Brc Cm sub Ar subbox .
                    399: .Pp
                    400: By contrast,
                    401: .Cm over
                    402: groups to the left.
                    403: .Pp
                    404: In the following list, earlier operations bind more tightly than
                    405: later operations:
                    406: .Pp
                    407: .Bl -enum -compact
                    408: .It
                    409: .Cm dyad ,
                    410: .Cm vec ,
                    411: .Cm under ,
                    412: .Cm bar ,
                    413: .Cm tilde ,
                    414: .Cm hat ,
                    415: .Cm dot ,
                    416: .Cm dotdot
                    417: .It
                    418: .Cm fat ,
                    419: .Cm roman ,
                    420: .Cm italic ,
                    421: .Cm bold ,
                    422: .Cm size
                    423: .It
                    424: .Cm sub ,
                    425: .Cm sup
                    426: .It
                    427: .Cm sqrt
                    428: .It
                    429: .Cm over
                    430: .It
                    431: .Cm from ,
                    432: .Cm to
                    433: .El
1.5       kristaps  434: .Sh COMPATIBILITY
                    435: This section documents the compatibility of mandoc
                    436: .Nm
                    437: and the troff
                    438: .Nm
                    439: implementation (including GNU troff).
                    440: .Pp
                    441: .Bl -dash -compact
                    442: .It
                    443: The text string
1.34      schwarze  444: .Sq \e\(dq
1.5       kristaps  445: is interpreted as a literal quote in troff.
                    446: In mandoc, this is interpreted as a comment.
1.19      kristaps  447: .It
                    448: In troff, The circumflex and tilde white-space symbols map to
                    449: fixed-width spaces.
                    450: In mandoc, these characters are synonyms for the space character.
1.21      kristaps  451: .It
                    452: The troff implementation of
                    453: .Nm
                    454: allows for equation alignment with the
                    455: .Cm mark
                    456: and
                    457: .Cm lineup
                    458: tokens.
                    459: mandoc discards these tokens.
                    460: The
                    461: .Cm back Ar n ,
                    462: .Cm fwd Ar n ,
                    463: .Cm up Ar n ,
                    464: and
                    465: .Cm down Ar n
                    466: commands are also ignored.
1.5       kristaps  467: .El
1.1       kristaps  468: .Sh SEE ALSO
                    469: .Xr mandoc 1 ,
                    470: .Xr man 7 ,
                    471: .Xr mandoc_char 7 ,
                    472: .Xr mdoc 7 ,
                    473: .Xr roff 7
                    474: .Rs
                    475: .%A Brian W. Kernighan
                    476: .%A Lorinda L. Cherry
                    477: .%T System for Typesetting Mathematics
                    478: .%J Communications of the ACM
                    479: .%V 18
1.38      schwarze  480: .%P pp. 151\(en157
1.1       kristaps  481: .%D March, 1975
                    482: .Re
1.5       kristaps  483: .Rs
                    484: .%A Brian W. Kernighan
                    485: .%A Lorinda L. Cherry
                    486: .%T Typesetting Mathematics, User's Guide
                    487: .%D 1976
                    488: .Re
                    489: .Rs
                    490: .%A Brian W. Kernighan
                    491: .%A Lorinda L. Cherry
                    492: .%T Typesetting Mathematics, User's Guide (Second Edition)
                    493: .%D 1978
                    494: .Re
                    495: .Sh HISTORY
1.15      kristaps  496: The eqn utility, a preprocessor for troff, was originally written by
1.5       kristaps  497: Brian W. Kernighan and Lorinda L. Cherry in 1975.
                    498: The GNU reimplementation of eqn, part of the GNU troff package, was
                    499: released in 1989 by James Clark.
                    500: The eqn component of
                    501: .Xr mandoc 1
                    502: was added in 2011.
1.1       kristaps  503: .Sh AUTHORS
1.5       kristaps  504: This
1.1       kristaps  505: .Nm
                    506: reference was written by
1.29      schwarze  507: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .

CVSweb