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