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