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