| blob | ea8f4ed220aaa81429878b99e6fb041b19e96293 |
1 .\" $Id: eqn.7,v 1.36 2017/07/20 11:07:27 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
5 .\"
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
9 .\"
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 .\"
18 .Dd $Mdocdate: July 20 2017 $
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
42 .Nm
43 specification (see
44 .Sx SEE ALSO
45 for references).
46 .Pp
47 Equations within
48 .Xr mdoc 5
49 or
50 .Xr man 5
51 documents are enclosed by the standalone
52 .Sq \&.EQ
53 and
54 .Sq \&.EN
55 tags.
56 Equations are multi-line blocks consisting of formulas and control
57 statements.
58 .Sh EQUATION STRUCTURE
59 Each equation is bracketed by
60 .Sq \&.EQ
61 and
62 .Sq \&.EN
63 strings.
64 .Em Note :
65 these are not the same as
66 .Xr mandoc_roff 5
67 macros, and may only be invoked as
68 .Sq \&.EQ .
69 .Pp
70 The equation grammar is as follows, where quoted strings are
71 case-sensitive literals in the input:
72 .Bd -literal -offset indent
73 eqn : box | eqn box
74 box : text
75 | \(dq{\(dq eqn \(dq}\(dq
76 | \(dqdefine\(dq text text
77 | \(dqndefine\(dq text text
78 | \(dqtdefine\(dq text text
79 | \(dqgfont\(dq text
80 | \(dqgsize\(dq text
81 | \(dqset\(dq text text
82 | \(dqundef\(dq text
83 | \(dqsqrt\(dq box
84 | box pos box
85 | box mark
86 | \(dqmatrix\(dq \(dq{\(dq [col \(dq{\(dq list \(dq}\(dq ]*
87 | pile \(dq{\(dq list \(dq}\(dq
88 | font box
89 | \(dqsize\(dq text box
90 | \(dqleft\(dq text eqn [\(dqright\(dq text]
91 col : \(dqlcol\(dq | \(dqrcol\(dq | \(dqccol\(dq | \(dqcol\(dq
92 text : [^space\e\(dq]+ | \e\(dq.*\e\(dq
93 pile : \(dqlpile\(dq | \(dqcpile\(dq | \(dqrpile\(dq | \(dqpile\(dq
94 pos : \(dqover\(dq | \(dqsup\(dq | \(dqsub\(dq | \(dqto\(dq | \(dqfrom\(dq
95 mark : \(dqdot\(dq | \(dqdotdot\(dq | \(dqhat\(dq | \(dqtilde\(dq | \(dqvec\(dq
96 | \(dqdyad\(dq | \(dqbar\(dq | \(dqunder\(dq
97 font : \(dqroman\(dq | \(dqitalic\(dq | \(dqbold\(dq | \(dqfat\(dq
98 list : eqn
99 | list \(dqabove\(dq eqn
100 space : [\e^~ \et]
101 .Ed
102 .Pp
103 White-space consists of the space, tab, circumflex, and tilde
104 characters.
105 It is required to delimit tokens consisting of alphabetic characters
106 and it is ignored at other places.
107 Braces and quotes also delimit tokens.
108 If within a quoted string, these space characters are retained.
109 Quoted strings are also not scanned for keywords, glyph names,
110 and expansion of definitions.
111 To print a literal quote character, it can be prepended with a
112 backslash or expressed with the \e(dq escape sequence.
113 .Pp
114 Subequations can be enclosed in braces to pass them as arguments
115 to operation keywords, overriding standard operation precedence.
116 Braces can be nested.
117 To set a brace verbatim, it needs to be enclosed in quotes.
118 .Pp
119 The following text terms are translated into a rendered glyph, if
120 available: alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa,
121 lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta,
122 upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA,
123 THETA, UPSILON, XI, inter (intersection), union (union), prod (product),
124 int (integral), sum (summation), grad (gradient), del (vector
125 differential), times (multiply), cdot (center-dot), nothing (zero-width
126 space), approx (approximately equals), prime (prime), half (one-half),
127 partial (partial differential), inf (infinity), >> (much greater), <<
128 (much less), <\- (left arrow), \-> (right arrow), +\- (plus-minus), !=
129 (not equal), == (equivalence), <= (less-than-equal), and >=
130 (more-than-equal).
131 The character escape sequences documented in
132 .Xr mandoc_char 5
133 can be used, too.
134 .Pp
135 The following control statements are available:
136 .Bl -tag -width Ds
137 .It Cm define
138 Replace all occurrences of a key with a value.
139 Its syntax is as follows:
140 .Pp
141 .D1 Cm define Ar key cvalc
142 .Pp
143 The first character of the value string,
144 .Ar c ,
145 is used as the delimiter for the value
146 .Ar val .
147 This allows for arbitrary enclosure of terms (not just quotes), such as
148 .Pp
149 .D1 Cm define Ar foo \(aqbar baz\(aq
150 .D1 Cm define Ar foo cbar bazc
151 .Pp
152 It is an error to have an empty
153 .Ar key
154 or
155 .Ar val .
156 Note that a quoted
157 .Ar key
158 causes errors in some
159 .Nm
160 implementations and should not be considered portable.
161 It is not expanded for replacements.
162 Definitions may refer to other definitions; these are evaluated
163 recursively when text replacement occurs and not when the definition is
164 created.
165 .Pp
166 Definitions can create arbitrary strings, for example, the following is
167 a legal construction.
168 .Bd -literal -offset indent
169 define foo \(aqdefine\(aq
170 foo bar \(aqbaz\(aq
171 .Ed
172 .Pp
173 Self-referencing definitions will raise an error.
174 The
175 .Cm ndefine
176 statement is a synonym for
177 .Cm define ,
178 while
179 .Cm tdefine
180 is discarded.
181 .It Cm gfont
182 Set the default font of subsequent output.
183 Its syntax is as follows:
184 .Pp
185 .D1 Cm gfont Ar font
186 .Pp
187 In mandoc, this value is discarded.
188 .It Cm gsize
189 Set the default size of subsequent output.
190 Its syntax is as follows:
191 .Pp
192 .D1 Cm gsize Oo +|\- Oc Ns Ar size
193 .Pp
194 The
195 .Ar size
196 value should be an integer.
197 If prepended by a sign,
198 the font size is changed relative to the current size.
199 .It Cm set
200 Set an equation mode.
201 In mandoc, both arguments are thrown away.
202 Its syntax is as follows:
203 .Pp
204 .D1 Cm set Ar key val
205 .Pp
206 The
207 .Ar key
208 and
209 .Ar val
210 are not expanded for replacements.
211 This statement is a GNU extension.
212 .It Cm undef
213 Unset a previously-defined key.
214 Its syntax is as follows:
215 .Pp
216 .D1 Cm define Ar key
217 .Pp
218 Once invoked, the definition for
219 .Ar key
220 is discarded.
221 The
222 .Ar key
223 is not expanded for replacements.
224 This statement is a GNU extension.
225 .El
226 .Pp
227 Operation keywords have the following semantics:
228 .Bl -tag -width Ds
229 .It Cm above
230 See
231 .Cm pile .
232 .It Cm bar
233 Draw a line over the preceding box.
234 .It Cm bold
235 Set the following box using bold font.
236 .It Cm ccol
237 Like
238 .Cm cpile ,
239 but for use in
240 .Cm matrix .
241 .It Cm cpile
242 Like
243 .Cm pile ,
244 but with slightly increased vertical spacing.
245 .It Cm dot
246 Set a single dot over the preceding box.
247 .It Cm dotdot
248 Set two dots (dieresis) over the preceding box.
249 .It Cm dyad
250 Set a dyad symbol (left-right arrow) over the preceding box.
251 .It Cm fat
252 A synonym for
253 .Cm bold .
254 .It Cm font
255 Set the second argument using the font specified by the first argument;
256 currently not recognized by the
257 .Xr mandoc 1
258 .Nm
259 parser.
260 .It Cm from
261 Set the following box below the preceding box,
262 using a slightly smaller font.
263 Used for sums, integrals, limits, and the like.
264 .It Cm hat
265 Set a hat (circumflex) over the preceding box.
266 .It Cm italic
267 Set the following box using italic font.
268 .It Cm lcol
269 Like
270 .Cm lpile ,
271 but for use in
272 .Cm matrix .
273 .It Cm left
274 Set the first argument as a big left delimiter before the second argument.
275 As an optional third argument,
276 .Cm right
277 can follow.
278 In that case, the fourth argument is set as a big right delimiter after
279 the second argument.
280 .It Cm lpile
281 Like
282 .Cm cpile ,
283 but subequations are left-justified.
284 .It Cm matrix
285 Followed by a list of columns enclosed in braces.
286 All columns need to have the same number of subequations.
287 The columns are set as a matrix.
288 The difference compared to multiple subsequent
289 .Cm pile
290 operators is that in a
291 .Cm matrix ,
292 corresponding subequations in all columns line up horizontally,
293 while each
294 .Cm pile
295 does vertical spacing independently.
296 .It Cm over
297 Set a fraction.
298 The preceding box is the numerator, the following box is the denominator.
299 .It Cm pile
300 Followed by a list of subequations enclosed in braces,
301 the subequations being separated by
302 .Cm above
303 keywords.
304 Sets the subequations one above the other, each of them centered.
305 Typically used to represent vectors in coordinate representation.
306 .It Cm rcol
307 Like
308 .Cm rpile ,
309 but for use in
310 .Cm matrix .
311 .It Cm right
312 See
313 .Cm left ;
314 .Cm right
315 cannot be used without
316 .Cm left .
317 To set a big right delimiter without a big left delimiter, the following
318 construction can be used:
319 .Pp
320 .D1 Cm left No \(dq\(dq Ar box Cm right Ar delimiter
321 .It Cm roman
322 Set the following box using the default font.
323 .It Cm rpile
324 Like
325 .Cm cpile ,
326 but subequations are right-justified.
327 .It Cm size
328 Set the second argument with the font size specified by the first
329 argument; currently ignored by
330 .Xr mandoc 1 .
331 By prepending a plus or minus sign to the first argument,
332 the font size can be selected relative to the current size.
333 .It Cm sqrt
334 Set the square root of the following box.
335 .It Cm sub
336 Set the following box as a subscript to the preceding box.
337 .It Cm sup
338 Set the following box as a superscript to the preceding box.
339 As a special case, if a
340 .Cm sup
341 clause immediately follows a
342 .Cm sub
343 clause as in
344 .Pp
345 .D1 Ar mainbox Cm sub Ar subbox Cm sup Ar supbox
346 .Pp
347 both are set with respect to the same
348 .Ar mainbox ,
349 that is,
350 .Ar supbox
351 is set above
352 .Ar subbox .
353 .It Cm tilde
354 Set a tilde over the preceding box.
355 .It Cm to
356 Set the following box above the preceding box,
357 using a slightly smaller font.
358 Used for sums and integrals and the like.
359 As a special case, if a
360 .Cm to
361 clause immediately follows a
362 .Cm from
363 clause as in
364 .Pp
365 .D1 Ar mainbox Cm from Ar frombox Cm to Ar tobox
366 .Pp
367 both are set below and above the same
368 .Ar mainbox .
369 .It Cm under
370 Underline the preceding box.
371 .It Cm vec
372 Set a vector symbol (right arrow) over the preceding box.
373 .El
374 .Pp
375 The binary operations
376 .Cm from ,
377 .Cm to ,
378 .Cm sub ,
379 and
380 .Cm sup
381 group to the right, that is,
382 .Pp
383 .D1 Ar mainbox Cm sup Ar supbox Cm sub Ar subbox
384 .Pp
385 is the same as
386 .Pp
387 .D1 Ar mainbox Cm sup Brq Ar supbox Cm sub Ar subbox
388 .Pp
389 and different from
390 .Pp
391 .D1 Bro Ar mainbox Cm sup Ar supbox Brc Cm sub Ar subbox .
392 .Pp
393 By contrast,
394 .Cm over
395 groups to the left.
396 .Pp
397 In the following list, earlier operations bind more tightly than
398 later operations:
399 .Pp
400 .Bl -enum -compact
401 .It
402 .Cm dyad ,
403 .Cm vec ,
404 .Cm under ,
405 .Cm bar ,
406 .Cm tilde ,
407 .Cm hat ,
408 .Cm dot ,
409 .Cm dotdot
410 .It
411 .Cm fat ,
412 .Cm roman ,
413 .Cm italic ,
414 .Cm bold ,
415 .Cm size
416 .It
417 .Cm sub ,
418 .Cm sup
419 .It
420 .Cm sqrt
421 .It
422 .Cm over
423 .It
424 .Cm from ,
425 .Cm to
426 .El
427 .Sh COMPATIBILITY
428 This section documents the compatibility of mandoc
429 .Nm
430 and the troff
431 .Nm
432 implementation (including GNU troff).
433 .Pp
434 .Bl -dash -compact
435 .It
436 The text string
437 .Sq \e\(dq
438 is interpreted as a literal quote in troff.
439 In mandoc, this is interpreted as a comment.
440 .It
441 In troff, The circumflex and tilde white-space symbols map to
442 fixed-width spaces.
443 In mandoc, these characters are synonyms for the space character.
444 .It
445 The troff implementation of
446 .Nm
447 allows for equation alignment with the
448 .Cm mark
449 and
450 .Cm lineup
451 tokens.
452 mandoc discards these tokens.
453 The
454 .Cm back Ar n ,
455 .Cm fwd Ar n ,
456 .Cm up Ar n ,
457 and
458 .Cm down Ar n
459 commands are also ignored.
460 .El
461 .Sh SEE ALSO
462 .Xr mandoc 1 ,
463 .Xr man 5 ,
464 .Xr mandoc_char 5 ,
465 .Xr mandoc_roff 5 ,
466 .Xr mdoc 5
467 .Rs
468 .%A Brian W. Kernighan
469 .%A Lorinda L. Cherry
470 .%T System for Typesetting Mathematics
471 .%J Communications of the ACM
472 .%V 18
473 .%P 151\(en157
474 .%D March, 1975
475 .Re
476 .Rs
477 .%A Brian W. Kernighan
478 .%A Lorinda L. Cherry
479 .%T Typesetting Mathematics, User's Guide
480 .%D 1976
481 .Re
482 .Rs
483 .%A Brian W. Kernighan
484 .%A Lorinda L. Cherry
485 .%T Typesetting Mathematics, User's Guide (Second Edition)
486 .%D 1978
487 .Re
488 .Sh HISTORY
489 The eqn utility, a preprocessor for troff, was originally written by
490 Brian W. Kernighan and Lorinda L. Cherry in 1975.
491 The GNU reimplementation of eqn, part of the GNU troff package, was
492 released in 1989 by James Clark.
493 The eqn component of
494 .Xr mandoc 1
495 was added in 2011.
496 .Sh AUTHORS
497 This
498 .Nm
499 reference was written by
500 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .