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 Jul 19, 2014
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
171 .Xr mandoc 1 ,
172 this value is discarded.
173 .It Cm gsize
174 Set the default size of subsequent output.
175 Its syntax is as follows:
176 .Pp
177 .D1 gsize Ar size
178 .Pp
179 The
180 .Ar size
181 value should be an integer.
182 .It Cm set
183 Set an equation mode.
184 In
185 .Xr mandoc 1 ,
186 both arguments are thrown away.
187 Its syntax is as follows:
188 .Pp
189 .D1 set Ar key val
190 .Pp
191 The
192 .Ar key
193 and
194 .Ar val
195 are not expanded for replacements.
196 This statement is a GNU extension.
197 .It Cm undef
198 Unset a previously-defined key.
199 Its syntax is as follows:
200 .Pp
201 .D1 define Ar key
202 .Pp
203 Once invoked, the definition for
204 .Ar key
205 is discarded.
206 The
207 .Ar key
208 is not expanded for replacements.
209 This statement is a GNU extension.
210 .El
211 .Sh COMPATIBILITY
212 This section documents the compatibility of
213 .Xr mandoc 1
214 .Nm
215 and the
216 .Xr troff 1
217 .Nm
218 implementation (including GNU troff).
219 .Pp
220 .Bl -dash -compact
221 .It
222 The text string
223 .Sq \e\*q
224 is interpreted as a literal quote in
225 .Xr troff 1 .
226 In
227 .Xr mandoc 1 ,
228 this is interpreted as a comment.
229 .It
230 In
231 .Xr troff 1 ,
232 The circumflex and tilde white-space symbols map to
233 fixed-width spaces.
234 In
235 .Xr mandoc 1 ,
236 these characters are synonyms for the space character.
237 .It
238 The
239 .Xr troff 1 ,
240 implementation of
241 .Nm
242 allows for equation alignment with the
243 .Cm mark
244 and
245 .Cm lineup
246 tokens.
247 .Xr mandoc 1
248 discards these tokens.
249 The
250 .Cm back Ar n ,
251 .Cm fwd Ar n ,
252 .Cm up Ar n ,
253 and
254 .Cm down Ar n
255 commands are also ignored.
256 .El
257 .Sh SEE ALSO
258 .Xr mandoc 1 ,
259 .Xr man 5 ,
260 .Xr mandoc_char 5 ,
261 .Xr mdoc 5 ,
262 .Xr roff 5
263 .Rs
264 .%A Brian W. Kernighan
265 .%A Lorinda L. Cherry
266 .%T System for Typesetting Mathematics
267 .%J Communications of the ACM
268 .%V 18
269 .%P 151\(en157
270 .%D March, 1975
271 .Re
272 .Rs
273 .%A Brian W. Kernighan
274 .%A Lorinda L. Cherry
275 .%T Typesetting Mathematics, User's Guide
276 .%D 1976
277 .Re
278 .Rs
279 .%A Brian W. Kernighan
280 .%A Lorinda L. Cherry
281 .%T Typesetting Mathematics, User's Guide (Second Edition)
282 .%D 1978
283 .Re
284 .Sh HISTORY
285 The eqn utility, a preprocessor for troff, was originally written by
286 Brian W. Kernighan and Lorinda L. Cherry in 1975.
287 The GNU reimplementation of eqn, part of the GNU troff package, was
288 released in 1989 by James Clark.
289 The eqn component of
290 .Xr mandoc 1
291 was added in 2011.
292 .Sh AUTHORS
293 This
294 .Nm
295 reference was written by
296 .An Kristaps Dzonsons ,
297 .Mt kristaps@bsd.lv .