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