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