Annotation of mandoc/eqn.7, Revision 1.38
1.38 ! schwarze 1: .\" $Id: eqn.7,v 1.37 2017/09/04 10:35:27 schwarze Exp $
1.1 kristaps 2: .\"
3: .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
1.31 schwarze 4: .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
1.1 kristaps 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: .\"
1.38 ! schwarze 18: .Dd $Mdocdate: September 4 2017 $
1.1 kristaps 19: .Dt EQN 7
20: .Os
21: .Sh NAME
22: .Nm eqn
23: .Nd eqn language reference for mandoc
24: .Sh DESCRIPTION
25: The
26: .Nm eqn
1.28 schwarze 27: language is an equation-formatting language.
1.1 kristaps 28: It is used within
29: .Xr mdoc 7
30: and
31: .Xr man 7
32: .Ux
33: manual pages.
1.25 kristaps 34: It describes the
35: .Em structure
36: of an equation, not its mathematical meaning.
1.23 kristaps 37: This manual describes the
1.1 kristaps 38: .Nm
39: language accepted by the
40: .Xr mandoc 1
1.31 schwarze 41: utility, which corresponds to the Second Edition
42: .Nm
43: specification (see
1.23 kristaps 44: .Sx SEE ALSO
45: for references).
1.1 kristaps 46: .Pp
47: Equations within
48: .Xr mdoc 7
49: or
50: .Xr man 7
1.3 kristaps 51: documents are enclosed by the standalone
52: .Sq \&.EQ
1.1 kristaps 53: and
1.3 kristaps 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 roff 7
67: macros, and may only be invoked as
68: .Sq \&.EQ .
69: .Pp
1.15 kristaps 70: The equation grammar is as follows, where quoted strings are
71: case-sensitive literals in the input:
1.3 kristaps 72: .Bd -literal -offset indent
73: eqn : box | eqn box
74: box : text
1.34 schwarze 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
1.11 kristaps 84: | box pos box
1.9 kristaps 85: | box mark
1.37 schwarze 86: | \(dqmatrix\(dq \(dq{\(dq [col \(dq{\(dq list \(dq}\(dq]* \(dq}\(dq
1.34 schwarze 87: | pile \(dq{\(dq list \(dq}\(dq
1.10 kristaps 88: | font box
1.34 schwarze 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
1.19 kristaps 98: list : eqn
1.34 schwarze 99: | list \(dqabove\(dq eqn
1.19 kristaps 100: space : [\e^~ \et]
1.3 kristaps 101: .Ed
102: .Pp
1.19 kristaps 103: White-space consists of the space, tab, circumflex, and tilde
104: characters.
1.31 schwarze 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.
1.19 kristaps 108: If within a quoted string, these space characters are retained.
1.31 schwarze 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.
1.16 kristaps 118: .Pp
1.19 kristaps 119: The following text terms are translated into a rendered glyph, if
1.16 kristaps 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
1.32 schwarze 125: differential), times (multiply), cdot (center-dot), nothing (zero-width
1.16 kristaps 126: space), approx (approximately equals), prime (prime), half (one-half),
127: partial (partial differential), inf (infinity), >> (much greater), <<
1.36 schwarze 128: (much less), <\- (left arrow), \-> (right arrow), +\- (plus-minus), !=
1.16 kristaps 129: (not equal), == (equivalence), <= (less-than-equal), and >=
130: (more-than-equal).
1.31 schwarze 131: The character escape sequences documented in
132: .Xr mandoc_char 7
133: can be used, too.
1.3 kristaps 134: .Pp
135: The following control statements are available:
136: .Bl -tag -width Ds
137: .It Cm define
1.27 kristaps 138: Replace all occurrences of a key with a value.
1.3 kristaps 139: Its syntax is as follows:
140: .Pp
1.31 schwarze 141: .D1 Cm define Ar key cvalc
1.5 kristaps 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
1.35 schwarze 149: .D1 Cm define Ar foo \(aqbar baz\(aq
1.31 schwarze 150: .D1 Cm define Ar foo cbar bazc
1.2 kristaps 151: .Pp
1.3 kristaps 152: It is an error to have an empty
1.28 schwarze 153: .Ar key
154: or
1.5 kristaps 155: .Ar val .
1.3 kristaps 156: Note that a quoted
157: .Ar key
158: causes errors in some
1.2 kristaps 159: .Nm
1.3 kristaps 160: implementations and should not be considered portable.
1.7 kristaps 161: It is not expanded for replacements.
1.4 kristaps 162: Definitions may refer to other definitions; these are evaluated
163: recursively when text replacement occurs and not when the definition is
164: created.
1.5 kristaps 165: .Pp
166: Definitions can create arbitrary strings, for example, the following is
167: a legal construction.
168: .Bd -literal -offset indent
1.35 schwarze 169: define foo \(aqdefine\(aq
170: foo bar \(aqbaz\(aq
1.5 kristaps 171: .Ed
172: .Pp
1.4 kristaps 173: Self-referencing definitions will raise an error.
1.23 kristaps 174: The
175: .Cm ndefine
176: statement is a synonym for
177: .Cm define ,
178: while
179: .Cm tdefine
180: is discarded.
1.18 kristaps 181: .It Cm gfont
182: Set the default font of subsequent output.
183: Its syntax is as follows:
184: .Pp
1.31 schwarze 185: .D1 Cm gfont Ar font
1.18 kristaps 186: .Pp
187: In mandoc, this value is discarded.
1.17 kristaps 188: .It Cm gsize
189: Set the default size of subsequent output.
190: Its syntax is as follows:
191: .Pp
1.31 schwarze 192: .D1 Cm gsize Oo +|\- Oc Ns Ar size
1.17 kristaps 193: .Pp
194: The
195: .Ar size
196: value should be an integer.
1.31 schwarze 197: If prepended by a sign,
198: the font size is changed relative to the current size.
1.3 kristaps 199: .It Cm set
1.4 kristaps 200: Set an equation mode.
1.18 kristaps 201: In mandoc, both arguments are thrown away.
1.7 kristaps 202: Its syntax is as follows:
203: .Pp
1.31 schwarze 204: .D1 Cm set Ar key val
1.7 kristaps 205: .Pp
206: The
207: .Ar key
208: and
209: .Ar val
210: are not expanded for replacements.
1.24 kristaps 211: This statement is a GNU extension.
1.3 kristaps 212: .It Cm undef
213: Unset a previously-defined key.
214: Its syntax is as follows:
215: .Pp
1.31 schwarze 216: .D1 Cm define Ar key
1.2 kristaps 217: .Pp
1.3 kristaps 218: Once invoked, the definition for
219: .Ar key
220: is discarded.
1.7 kristaps 221: The
222: .Ar key
223: is not expanded for replacements.
1.24 kristaps 224: This statement is a GNU extension.
1.3 kristaps 225: .El
1.31 schwarze 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
1.5 kristaps 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
1.34 schwarze 437: .Sq \e\(dq
1.5 kristaps 438: is interpreted as a literal quote in troff.
439: In mandoc, this is interpreted as a comment.
1.19 kristaps 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.
1.21 kristaps 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.
1.5 kristaps 460: .El
1.1 kristaps 461: .Sh SEE ALSO
462: .Xr mandoc 1 ,
463: .Xr man 7 ,
464: .Xr mandoc_char 7 ,
465: .Xr mdoc 7 ,
466: .Xr roff 7
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
1.38 ! schwarze 473: .%P pp. 151\(en157
1.1 kristaps 474: .%D March, 1975
475: .Re
1.5 kristaps 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
1.15 kristaps 489: The eqn utility, a preprocessor for troff, was originally written by
1.5 kristaps 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.
1.1 kristaps 496: .Sh AUTHORS
1.5 kristaps 497: This
1.1 kristaps 498: .Nm
499: reference was written by
1.29 schwarze 500: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
CVSweb