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