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

Annotation of mandoc/eqn.7, Revision 1.15

1.15    ! kristaps    1: .\"    $Id: eqn.7,v 1.14 2011/07/22 12:55:02 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.15    ! kristaps   17: .Dd $Mdocdate: July 22 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
                     26: language is a equation-formatting language.
                     27: It is used within
                     28: .Xr mdoc 7
                     29: and
                     30: .Xr man 7
                     31: .Ux
                     32: manual pages.
                     33: This manual describes the subset of the
                     34: .Nm
                     35: language accepted by the
                     36: .Xr mandoc 1
                     37: utility.
                     38: .Pp
                     39: Equations within
                     40: .Xr mdoc 7
                     41: or
                     42: .Xr man 7
1.3       kristaps   43: documents are enclosed by the standalone
                     44: .Sq \&.EQ
1.1       kristaps   45: and
1.3       kristaps   46: .Sq \&.EN
                     47: tags.
                     48: Equations are multi-line blocks consisting of formulas and control
                     49: statements.
                     50: .Sh EQUATION STRUCTURE
                     51: Each equation is bracketed by
                     52: .Sq \&.EQ
                     53: and
                     54: .Sq \&.EN
                     55: strings.
                     56: .Em Note :
                     57: these are not the same as
                     58: .Xr roff 7
                     59: macros, and may only be invoked as
                     60: .Sq \&.EQ .
                     61: .Pp
1.15    ! kristaps   62: The equation grammar is as follows, where quoted strings are
        !            63: case-sensitive literals in the input:
1.3       kristaps   64: .Bd -literal -offset indent
                     65: eqn     : box | eqn box
                     66: box     : text
1.15    ! kristaps   67:         | "{" eqn "}"
        !            68:         | "define" text text
        !            69:         | "set" text text
        !            70:         | "undef" text
1.11      kristaps   71:         | box pos box
1.9       kristaps   72:         | box mark
1.15    ! kristaps   73:         | pile "{" list "}"
1.10      kristaps   74:         | font box
1.15    ! kristaps   75:         | "size" text box
        !            76:         | "left" text eqn ["right" text]
1.3       kristaps   77: text    : TEXT
1.15    ! kristaps   78: pile    : "lpile" | "cpile" | "rpile"
        !            79: pos     : "over" | "sup" | "sub" | "to" | "from"
        !            80: mark   : "dot" | "dotdot" | "hat" | "tilde" | "vec"
        !            81:         | "dyad" | "bar" | "under"
        !            82: font    : "roman" | "italic" | "bold"
        !            83: list    : eqn
        !            84:         | list "above" eqn
1.3       kristaps   85: .Ed
                     86: .Pp
                     87: Data in TEXT form is a non-empty sequence of non-space characters or a
                     88: non-empty quoted string.
1.5       kristaps   89: Unless within a quoted string, white-space (and enclosing literal quote
                     90: pairs) is thrown away.
1.6       kristaps   91: Quoted strings are not scanned for replacement definitions.
1.15    ! kristaps   92: The following text tokens are translated into an acceptable front-end
        !            93: format, if available: alpha, beta, chi, delta, epsilon, eta, gamma,
        !            94: iota, kappa, lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma,
        !            95: tau, theta, upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI,
        !            96: PSI, SIGMA, THETA, UPSILON, and XI.
1.3       kristaps   97: .Pp
                     98: The following control statements are available:
                     99: .Bl -tag -width Ds
                    100: .It Cm define
                    101: Replace all occurances of a key with a value.
                    102: Its syntax is as follows:
                    103: .Pp
1.5       kristaps  104: .D1 define Ar key cvalc
                    105: .Pp
                    106: The first character of the value string,
                    107: .Ar c ,
                    108: is used as the delimiter for the value
                    109: .Ar val .
                    110: This allows for arbitrary enclosure of terms (not just quotes), such as
                    111: .Pp
                    112: .D1 define Ar foo 'bar baz'
                    113: .D1 define Ar foo cbar bazc
1.2       kristaps  114: .Pp
1.3       kristaps  115: It is an error to have an empty
                    116: .Ar key or
1.5       kristaps  117: .Ar val .
1.3       kristaps  118: Note that a quoted
                    119: .Ar key
                    120: causes errors in some
1.2       kristaps  121: .Nm
1.3       kristaps  122: implementations and should not be considered portable.
1.7       kristaps  123: It is not expanded for replacements.
1.4       kristaps  124: Definitions may refer to other definitions; these are evaluated
                    125: recursively when text replacement occurs and not when the definition is
                    126: created.
1.5       kristaps  127: .Pp
                    128: Definitions can create arbitrary strings, for example, the following is
                    129: a legal construction.
                    130: .Bd -literal -offset indent
                    131: define foo 'define'
                    132: foo bar 'baz'
                    133: .Ed
                    134: .Pp
1.4       kristaps  135: Self-referencing definitions will raise an error.
1.3       kristaps  136: .It Cm set
1.4       kristaps  137: Set an equation mode.
1.3       kristaps  138: Both arguments are thrown away.
1.7       kristaps  139: Its syntax is as follows:
                    140: .Pp
                    141: .D1 set Ar key val
                    142: .Pp
                    143: The
                    144: .Ar key
                    145: and
                    146: .Ar val
                    147: are not expanded for replacements.
1.3       kristaps  148: .It Cm undef
                    149: Unset a previously-defined key.
                    150: Its syntax is as follows:
                    151: .Pp
                    152: .D1 define Ar key
1.2       kristaps  153: .Pp
1.3       kristaps  154: Once invoked, the definition for
                    155: .Ar key
                    156: is discarded.
1.7       kristaps  157: The
                    158: .Ar key
                    159: is not expanded for replacements.
1.3       kristaps  160: .El
1.5       kristaps  161: .Sh COMPATIBILITY
                    162: This section documents the compatibility of mandoc
                    163: .Nm
                    164: and the troff
                    165: .Nm
                    166: implementation (including GNU troff).
                    167: .Pp
                    168: .Bl -dash -compact
                    169: .It
                    170: The text string
                    171: .Sq \e\*q
                    172: is interpreted as a literal quote in troff.
                    173: In mandoc, this is interpreted as a comment.
                    174: .El
1.1       kristaps  175: .Sh SEE ALSO
                    176: .Xr mandoc 1 ,
                    177: .Xr man 7 ,
                    178: .Xr mandoc_char 7 ,
                    179: .Xr mdoc 7 ,
                    180: .Xr roff 7
                    181: .Rs
                    182: .%A Brian W. Kernighan
                    183: .%A Lorinda L. Cherry
                    184: .%T System for Typesetting Mathematics
                    185: .%J Communications of the ACM
                    186: .%V 18
                    187: .%P 151\(en157
                    188: .%D March, 1975
                    189: .Re
1.5       kristaps  190: .Rs
                    191: .%A Brian W. Kernighan
                    192: .%A Lorinda L. Cherry
                    193: .%T Typesetting Mathematics, User's Guide
                    194: .%D 1976
                    195: .Re
                    196: .Rs
                    197: .%A Brian W. Kernighan
                    198: .%A Lorinda L. Cherry
                    199: .%T Typesetting Mathematics, User's Guide (Second Edition)
                    200: .%D 1978
                    201: .Re
                    202: .Sh HISTORY
1.15    ! kristaps  203: The eqn utility, a preprocessor for troff, was originally written by
1.5       kristaps  204: Brian W. Kernighan and Lorinda L. Cherry in 1975.
                    205: The GNU reimplementation of eqn, part of the GNU troff package, was
                    206: released in 1989 by James Clark.
                    207: The eqn component of
                    208: .Xr mandoc 1
                    209: was added in 2011.
1.1       kristaps  210: .Sh AUTHORS
1.5       kristaps  211: This
1.1       kristaps  212: .Nm
                    213: reference was written by
                    214: .An Kristaps Dzonsons Aq kristaps@bsd.lv .

CVSweb