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

Annotation of mandoc/eqn.7, Revision 1.28

1.28    ! schwarze    1: .\"    $Id: eqn.7,v 1.27 2011/09/02 19:37:35 kristaps Exp $
1.1       kristaps    2: .\"
                      3: .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
                      4: .\"
                      5: .\" Permission to use, copy, modify, and distribute this software for any
                      6: .\" purpose with or without fee is hereby granted, provided that the above
                      7: .\" copyright notice and this permission notice appear in all copies.
                      8: .\"
                      9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
                     10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
                     11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
                     12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
                     13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
                     14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
                     15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
                     16: .\"
1.28    ! schwarze   17: .Dd $Mdocdate: September 2 2011 $
1.1       kristaps   18: .Dt EQN 7
                     19: .Os
                     20: .Sh NAME
                     21: .Nm eqn
                     22: .Nd eqn language reference for mandoc
                     23: .Sh DESCRIPTION
                     24: The
                     25: .Nm eqn
1.28    ! schwarze   26: language is an equation-formatting language.
1.1       kristaps   27: It is used within
                     28: .Xr mdoc 7
                     29: and
                     30: .Xr man 7
                     31: .Ux
                     32: manual pages.
1.25      kristaps   33: It describes the
                     34: .Em structure
                     35: of an equation, not its mathematical meaning.
1.23      kristaps   36: This manual describes the
1.1       kristaps   37: .Nm
                     38: language accepted by the
                     39: .Xr mandoc 1
1.28    ! schwarze   40: utility, which corresponds to the Second Edition eqn specification (see
1.23      kristaps   41: .Sx SEE ALSO
                     42: for references).
1.1       kristaps   43: .Pp
                     44: Equations within
                     45: .Xr mdoc 7
                     46: or
                     47: .Xr man 7
1.3       kristaps   48: documents are enclosed by the standalone
                     49: .Sq \&.EQ
1.1       kristaps   50: and
1.3       kristaps   51: .Sq \&.EN
                     52: tags.
                     53: Equations are multi-line blocks consisting of formulas and control
                     54: statements.
                     55: .Sh EQUATION STRUCTURE
                     56: Each equation is bracketed by
                     57: .Sq \&.EQ
                     58: and
                     59: .Sq \&.EN
                     60: strings.
                     61: .Em Note :
                     62: these are not the same as
                     63: .Xr roff 7
                     64: macros, and may only be invoked as
                     65: .Sq \&.EQ .
                     66: .Pp
1.15      kristaps   67: The equation grammar is as follows, where quoted strings are
                     68: case-sensitive literals in the input:
1.3       kristaps   69: .Bd -literal -offset indent
                     70: eqn     : box | eqn box
                     71: box     : text
1.19      kristaps   72:         | \*q{\*q eqn \*q}\*q
                     73:         | \*qdefine\*q text text
1.23      kristaps   74:         | \*qndefine\*q text text
                     75:         | \*qtdefine\*q text text
1.19      kristaps   76:         | \*qgfont\*q text
                     77:         | \*qgsize\*q text
                     78:         | \*qset\*q text text
                     79:         | \*qundef\*q text
1.11      kristaps   80:         | box pos box
1.9       kristaps   81:         | box mark
1.20      kristaps   82:         | \*qmatrix\*q \*q{\*q [col \*q{\*q list \*q}\*q ]*
1.19      kristaps   83:         | pile \*q{\*q list \*q}\*q
1.10      kristaps   84:         | font box
1.19      kristaps   85:         | \*qsize\*q text box
                     86:         | \*qleft\*q text eqn [\*qright\*q text]
1.24      kristaps   87: col     : \*qlcol\*q | \*qrcol\*q | \*qccol\*q | \*qcol\*q
1.19      kristaps   88: text    : [^space\e\*q]+ | \e\*q.*\e\*q
1.24      kristaps   89: pile    : \*qlpile\*q | \*qcpile\*q | \*qrpile\*q | \*qpile\*q
1.19      kristaps   90: pos     : \*qover\*q | \*qsup\*q | \*qsub\*q | \*qto\*q | \*qfrom\*q
                     91: mark   : \*qdot\*q | \*qdotdot\*q | \*qhat\*q | \*qtilde\*q | \*qvec\*q
                     92:         | \*qdyad\*q | \*qbar\*q | \*qunder\*q
1.22      kristaps   93: font    : \*qroman\*q | \*qitalic\*q | \*qbold\*q | \*qfat\*q
1.19      kristaps   94: list    : eqn
                     95:         | list \*qabove\*q eqn
                     96: space   : [\e^~ \et]
1.3       kristaps   97: .Ed
                     98: .Pp
1.19      kristaps   99: White-space consists of the space, tab, circumflex, and tilde
                    100: characters.
                    101: If within a quoted string, these space characters are retained.
                    102: Quoted strings are also not scanned for replacement definitions.
1.16      kristaps  103: .Pp
1.19      kristaps  104: The following text terms are translated into a rendered glyph, if
1.16      kristaps  105: available: alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa,
                    106: lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta,
                    107: upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA,
                    108: THETA, UPSILON, XI, inter (intersection), union (union), prod (product),
                    109: int (integral), sum (summation), grad (gradient), del (vector
                    110: differential), times (multiply), cdot (centre-dot), nothing (zero-width
                    111: space), approx (approximately equals), prime (prime), half (one-half),
                    112: partial (partial differential), inf (infinity), >> (much greater), <<
                    113: (much less), \-> (left arrow), <\- (right arrow), += (plus-minus), !=
                    114: (not equal), == (equivalence), <= (less-than-equal), and >=
                    115: (more-than-equal).
1.3       kristaps  116: .Pp
                    117: The following control statements are available:
                    118: .Bl -tag -width Ds
                    119: .It Cm define
1.27      kristaps  120: Replace all occurrences of a key with a value.
1.3       kristaps  121: Its syntax is as follows:
                    122: .Pp
1.5       kristaps  123: .D1 define Ar key cvalc
                    124: .Pp
                    125: The first character of the value string,
                    126: .Ar c ,
                    127: is used as the delimiter for the value
                    128: .Ar val .
                    129: This allows for arbitrary enclosure of terms (not just quotes), such as
                    130: .Pp
                    131: .D1 define Ar foo 'bar baz'
                    132: .D1 define Ar foo cbar bazc
1.2       kristaps  133: .Pp
1.3       kristaps  134: It is an error to have an empty
1.28    ! schwarze  135: .Ar key
        !           136: or
1.5       kristaps  137: .Ar val .
1.3       kristaps  138: Note that a quoted
                    139: .Ar key
                    140: causes errors in some
1.2       kristaps  141: .Nm
1.3       kristaps  142: implementations and should not be considered portable.
1.7       kristaps  143: It is not expanded for replacements.
1.4       kristaps  144: Definitions may refer to other definitions; these are evaluated
                    145: recursively when text replacement occurs and not when the definition is
                    146: created.
1.5       kristaps  147: .Pp
                    148: Definitions can create arbitrary strings, for example, the following is
                    149: a legal construction.
                    150: .Bd -literal -offset indent
                    151: define foo 'define'
                    152: foo bar 'baz'
                    153: .Ed
                    154: .Pp
1.4       kristaps  155: Self-referencing definitions will raise an error.
1.23      kristaps  156: The
                    157: .Cm ndefine
                    158: statement is a synonym for
                    159: .Cm define ,
                    160: while
                    161: .Cm tdefine
                    162: is discarded.
1.18      kristaps  163: .It Cm gfont
                    164: Set the default font of subsequent output.
                    165: Its syntax is as follows:
                    166: .Pp
                    167: .D1 gfont Ar font
                    168: .Pp
                    169: In mandoc, this value is discarded.
1.17      kristaps  170: .It Cm gsize
                    171: Set the default size of subsequent output.
                    172: Its syntax is as follows:
                    173: .Pp
1.18      kristaps  174: .D1 gsize Ar size
1.17      kristaps  175: .Pp
                    176: The
                    177: .Ar size
                    178: value should be an integer.
1.3       kristaps  179: .It Cm set
1.4       kristaps  180: Set an equation mode.
1.18      kristaps  181: In mandoc, both arguments are thrown away.
1.7       kristaps  182: Its syntax is as follows:
                    183: .Pp
                    184: .D1 set Ar key val
                    185: .Pp
                    186: The
                    187: .Ar key
                    188: and
                    189: .Ar val
                    190: are not expanded for replacements.
1.24      kristaps  191: This statement is a GNU extension.
1.3       kristaps  192: .It Cm undef
                    193: Unset a previously-defined key.
                    194: Its syntax is as follows:
                    195: .Pp
                    196: .D1 define Ar key
1.2       kristaps  197: .Pp
1.3       kristaps  198: Once invoked, the definition for
                    199: .Ar key
                    200: is discarded.
1.7       kristaps  201: The
                    202: .Ar key
                    203: is not expanded for replacements.
1.24      kristaps  204: This statement is a GNU extension.
1.3       kristaps  205: .El
1.5       kristaps  206: .Sh COMPATIBILITY
                    207: This section documents the compatibility of mandoc
                    208: .Nm
                    209: and the troff
                    210: .Nm
                    211: implementation (including GNU troff).
                    212: .Pp
                    213: .Bl -dash -compact
                    214: .It
                    215: The text string
                    216: .Sq \e\*q
                    217: is interpreted as a literal quote in troff.
                    218: In mandoc, this is interpreted as a comment.
1.19      kristaps  219: .It
                    220: In troff, The circumflex and tilde white-space symbols map to
                    221: fixed-width spaces.
                    222: In mandoc, these characters are synonyms for the space character.
1.21      kristaps  223: .It
                    224: The troff implementation of
                    225: .Nm
                    226: allows for equation alignment with the
                    227: .Cm mark
                    228: and
                    229: .Cm lineup
                    230: tokens.
                    231: mandoc discards these tokens.
                    232: The
                    233: .Cm back Ar n ,
                    234: .Cm fwd Ar n ,
                    235: .Cm up Ar n ,
                    236: and
                    237: .Cm down Ar n
                    238: commands are also ignored.
1.5       kristaps  239: .El
1.1       kristaps  240: .Sh SEE ALSO
                    241: .Xr mandoc 1 ,
                    242: .Xr man 7 ,
                    243: .Xr mandoc_char 7 ,
                    244: .Xr mdoc 7 ,
                    245: .Xr roff 7
                    246: .Rs
                    247: .%A Brian W. Kernighan
                    248: .%A Lorinda L. Cherry
                    249: .%T System for Typesetting Mathematics
                    250: .%J Communications of the ACM
                    251: .%V 18
                    252: .%P 151\(en157
                    253: .%D March, 1975
                    254: .Re
1.5       kristaps  255: .Rs
                    256: .%A Brian W. Kernighan
                    257: .%A Lorinda L. Cherry
                    258: .%T Typesetting Mathematics, User's Guide
                    259: .%D 1976
                    260: .Re
                    261: .Rs
                    262: .%A Brian W. Kernighan
                    263: .%A Lorinda L. Cherry
                    264: .%T Typesetting Mathematics, User's Guide (Second Edition)
                    265: .%D 1978
                    266: .Re
                    267: .Sh HISTORY
1.15      kristaps  268: The eqn utility, a preprocessor for troff, was originally written by
1.5       kristaps  269: Brian W. Kernighan and Lorinda L. Cherry in 1975.
                    270: The GNU reimplementation of eqn, part of the GNU troff package, was
                    271: released in 1989 by James Clark.
                    272: The eqn component of
                    273: .Xr mandoc 1
                    274: was added in 2011.
1.1       kristaps  275: .Sh AUTHORS
1.5       kristaps  276: This
1.1       kristaps  277: .Nm
                    278: reference was written by
1.26      kristaps  279: .An Kristaps Dzonsons ,
                    280: .Mt kristaps@bsd.lv .

CVSweb