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