Annotation of mandoc/eqn.7, Revision 1.31
1.31 ! schwarze 1: .\" $Id: eqn.7,v 1.30 2014/10/10 08:44:24 kristaps 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.31 ! schwarze 18: .Dd $Mdocdate: October 10 2014 $
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.19 kristaps 75: | \*q{\*q eqn \*q}\*q
76: | \*qdefine\*q text text
1.23 kristaps 77: | \*qndefine\*q text text
78: | \*qtdefine\*q text text
1.19 kristaps 79: | \*qgfont\*q text
80: | \*qgsize\*q text
1.31 ! schwarze 81: | \*qset\*q text text
1.19 kristaps 82: | \*qundef\*q text
1.31 ! schwarze 83: | \*qsqrt\*q box
1.11 kristaps 84: | box pos box
1.9 kristaps 85: | box mark
1.20 kristaps 86: | \*qmatrix\*q \*q{\*q [col \*q{\*q list \*q}\*q ]*
1.19 kristaps 87: | pile \*q{\*q list \*q}\*q
1.10 kristaps 88: | font box
1.19 kristaps 89: | \*qsize\*q text box
90: | \*qleft\*q text eqn [\*qright\*q text]
1.24 kristaps 91: col : \*qlcol\*q | \*qrcol\*q | \*qccol\*q | \*qcol\*q
1.19 kristaps 92: text : [^space\e\*q]+ | \e\*q.*\e\*q
1.24 kristaps 93: pile : \*qlpile\*q | \*qcpile\*q | \*qrpile\*q | \*qpile\*q
1.19 kristaps 94: pos : \*qover\*q | \*qsup\*q | \*qsub\*q | \*qto\*q | \*qfrom\*q
95: mark : \*qdot\*q | \*qdotdot\*q | \*qhat\*q | \*qtilde\*q | \*qvec\*q
96: | \*qdyad\*q | \*qbar\*q | \*qunder\*q
1.22 kristaps 97: font : \*qroman\*q | \*qitalic\*q | \*qbold\*q | \*qfat\*q
1.19 kristaps 98: list : eqn
99: | list \*qabove\*q eqn
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
125: differential), times (multiply), cdot (centre-dot), nothing (zero-width
126: space), approx (approximately equals), prime (prime), half (one-half),
127: partial (partial differential), inf (infinity), >> (much greater), <<
1.31 ! 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.31 ! schwarze 149: .D1 Cm define Ar foo 'bar baz'
! 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
169: define foo 'define'
170: foo bar 'baz'
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
437: .Sq \e\*q
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.31 ! schwarze 460: .It
! 461: Inline equations and the
! 462: .Cm delim
! 463: control statement are not yet implemented in
! 464: .Xr mandoc 1 .
1.5 kristaps 465: .El
1.1 kristaps 466: .Sh SEE ALSO
467: .Xr mandoc 1 ,
468: .Xr man 7 ,
469: .Xr mandoc_char 7 ,
470: .Xr mdoc 7 ,
471: .Xr roff 7
472: .Rs
473: .%A Brian W. Kernighan
474: .%A Lorinda L. Cherry
475: .%T System for Typesetting Mathematics
476: .%J Communications of the ACM
477: .%V 18
478: .%P 151\(en157
479: .%D March, 1975
480: .Re
1.5 kristaps 481: .Rs
482: .%A Brian W. Kernighan
483: .%A Lorinda L. Cherry
484: .%T Typesetting Mathematics, User's Guide
485: .%D 1976
486: .Re
487: .Rs
488: .%A Brian W. Kernighan
489: .%A Lorinda L. Cherry
490: .%T Typesetting Mathematics, User's Guide (Second Edition)
491: .%D 1978
492: .Re
493: .Sh HISTORY
1.15 kristaps 494: The eqn utility, a preprocessor for troff, was originally written by
1.5 kristaps 495: Brian W. Kernighan and Lorinda L. Cherry in 1975.
496: The GNU reimplementation of eqn, part of the GNU troff package, was
497: released in 1989 by James Clark.
498: The eqn component of
499: .Xr mandoc 1
500: was added in 2011.
1.1 kristaps 501: .Sh AUTHORS
1.5 kristaps 502: This
1.1 kristaps 503: .Nm
504: reference was written by
1.29 schwarze 505: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
CVSweb