1.\" $Id: eqn.7,v 1.29 2013/07/13 19:41:16 schwarze Exp $ 2.\" 3.\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: July 13 2013 $ 18.Dt EQN 7 19.Os 20.Sh NAME 21.Nm eqn 22.Nd eqn language reference for mandoc 23.Sh DESCRIPTION 24The 25.Nm eqn 26language is an equation-formatting language. 27It is used within 28.Xr mdoc 7 29and 30.Xr man 7 31.Ux 32manual pages. 33It describes the 34.Em structure 35of an equation, not its mathematical meaning. 36This manual describes the 37.Nm 38language accepted by the 39.Xr mandoc 1 40utility, which corresponds to the Second Edition eqn specification (see 41.Sx SEE ALSO 42for references). 43.Pp 44Equations within 45.Xr mdoc 7 46or 47.Xr man 7 48documents are enclosed by the standalone 49.Sq \&.EQ 50and 51.Sq \&.EN 52tags. 53Equations are multi-line blocks consisting of formulas and control 54statements. 55.Sh EQUATION STRUCTURE 56Each equation is bracketed by 57.Sq \&.EQ 58and 59.Sq \&.EN 60strings. 61.Em Note : 62these are not the same as 63.Xr roff 7 64macros, and may only be invoked as 65.Sq \&.EQ . 66.Pp 67The equation grammar is as follows, where quoted strings are 68case-sensitive literals in the input: 69.Bd -literal -offset indent 70eqn : box | eqn box 71box : text 72 | \*q{\*q eqn \*q}\*q 73 | \*qdefine\*q text text 74 | \*qndefine\*q text text 75 | \*qtdefine\*q text text 76 | \*qgfont\*q text 77 | \*qgsize\*q text 78 | \*qset\*q text text 79 | \*qundef\*q text 80 | box pos box 81 | box mark 82 | \*qmatrix\*q \*q{\*q [col \*q{\*q list \*q}\*q ]* 83 | pile \*q{\*q list \*q}\*q 84 | font box 85 | \*qsize\*q text box 86 | \*qleft\*q text eqn [\*qright\*q text] 87col : \*qlcol\*q | \*qrcol\*q | \*qccol\*q | \*qcol\*q 88text : [^space\e\*q]+ | \e\*q.*\e\*q 89pile : \*qlpile\*q | \*qcpile\*q | \*qrpile\*q | \*qpile\*q 90pos : \*qover\*q | \*qsup\*q | \*qsub\*q | \*qto\*q | \*qfrom\*q 91mark : \*qdot\*q | \*qdotdot\*q | \*qhat\*q | \*qtilde\*q | \*qvec\*q 92 | \*qdyad\*q | \*qbar\*q | \*qunder\*q 93font : \*qroman\*q | \*qitalic\*q | \*qbold\*q | \*qfat\*q 94list : eqn 95 | list \*qabove\*q eqn 96space : [\e^~ \et] 97.Ed 98.Pp 99White-space consists of the space, tab, circumflex, and tilde 100characters. 101If within a quoted string, these space characters are retained. 102Quoted strings are also not scanned for replacement definitions. 103.Pp 104The following text terms are translated into a rendered glyph, if 105available: alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa, 106lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta, 107upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA, 108THETA, UPSILON, XI, inter (intersection), union (union), prod (product), 109int (integral), sum (summation), grad (gradient), del (vector 110differential), times (multiply), cdot (centre-dot), nothing (zero-width 111space), approx (approximately equals), prime (prime), half (one-half), 112partial (partial differential), inf (infinity), >> (much greater), << 113(much less), \-> (left arrow), <\- (right arrow), += (plus-minus), != 114(not equal), == (equivalence), <= (less-than-equal), and >= 115(more-than-equal). 116.Pp 117The following control statements are available: 118.Bl -tag -width Ds 119.It Cm define 120Replace all occurrences of a key with a value. 121Its syntax is as follows: 122.Pp 123.D1 define Ar key cvalc 124.Pp 125The first character of the value string, 126.Ar c , 127is used as the delimiter for the value 128.Ar val . 129This allows for arbitrary enclosure of terms (not just quotes), such as 130.Pp 131.D1 define Ar foo 'bar baz' 132.D1 define Ar foo cbar bazc 133.Pp 134It is an error to have an empty 135.Ar key 136or 137.Ar val . 138Note that a quoted 139.Ar key 140causes errors in some 141.Nm 142implementations and should not be considered portable. 143It is not expanded for replacements. 144Definitions may refer to other definitions; these are evaluated 145recursively when text replacement occurs and not when the definition is 146created. 147.Pp 148Definitions can create arbitrary strings, for example, the following is 149a legal construction. 150.Bd -literal -offset indent 151define foo 'define' 152foo bar 'baz' 153.Ed 154.Pp 155Self-referencing definitions will raise an error. 156The 157.Cm ndefine 158statement is a synonym for 159.Cm define , 160while 161.Cm tdefine 162is discarded. 163.It Cm gfont 164Set the default font of subsequent output. 165Its syntax is as follows: 166.Pp 167.D1 gfont Ar font 168.Pp 169In mandoc, this value is discarded. 170.It Cm gsize 171Set the default size of subsequent output. 172Its syntax is as follows: 173.Pp 174.D1 gsize Ar size 175.Pp 176The 177.Ar size 178value should be an integer. 179.It Cm set 180Set an equation mode. 181In mandoc, both arguments are thrown away. 182Its syntax is as follows: 183.Pp 184.D1 set Ar key val 185.Pp 186The 187.Ar key 188and 189.Ar val 190are not expanded for replacements. 191This statement is a GNU extension. 192.It Cm undef 193Unset a previously-defined key. 194Its syntax is as follows: 195.Pp 196.D1 define Ar key 197.Pp 198Once invoked, the definition for 199.Ar key 200is discarded. 201The 202.Ar key 203is not expanded for replacements. 204This statement is a GNU extension. 205.El 206.Sh COMPATIBILITY 207This section documents the compatibility of mandoc 208.Nm 209and the troff 210.Nm 211implementation (including GNU troff). 212.Pp 213.Bl -dash -compact 214.It 215The text string 216.Sq \e\*q 217is interpreted as a literal quote in troff. 218In mandoc, this is interpreted as a comment. 219.It 220In troff, The circumflex and tilde white-space symbols map to 221fixed-width spaces. 222In mandoc, these characters are synonyms for the space character. 223.It 224The troff implementation of 225.Nm 226allows for equation alignment with the 227.Cm mark 228and 229.Cm lineup 230tokens. 231mandoc discards these tokens. 232The 233.Cm back Ar n , 234.Cm fwd Ar n , 235.Cm up Ar n , 236and 237.Cm down Ar n 238commands are also ignored. 239.El 240.Sh SEE ALSO 241.Xr mandoc 1 , 242.Xr man 7 , 243.Xr mandoc_char 7 , 244.Xr mdoc 7 , 245.Xr roff 7 246.Rs 247.%A Brian W. Kernighan 248.%A Lorinda L. Cherry 249.%T System for Typesetting Mathematics 250.%J Communications of the ACM 251.%V 18 252.%P 151\(en157 253.%D March, 1975 254.Re 255.Rs 256.%A Brian W. Kernighan 257.%A Lorinda L. Cherry 258.%T Typesetting Mathematics, User's Guide 259.%D 1976 260.Re 261.Rs 262.%A Brian W. Kernighan 263.%A Lorinda L. Cherry 264.%T Typesetting Mathematics, User's Guide (Second Edition) 265.%D 1978 266.Re 267.Sh HISTORY 268The eqn utility, a preprocessor for troff, was originally written by 269Brian W. Kernighan and Lorinda L. Cherry in 1975. 270The GNU reimplementation of eqn, part of the GNU troff package, was 271released in 1989 by James Clark. 272The eqn component of 273.Xr mandoc 1 274was added in 2011. 275.Sh AUTHORS 276This 277.Nm 278reference was written by 279.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 280