1.\" $OpenBSD: eqn.7,v 1.1 2011/09/18 10:38:57 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: September 18 2011 $ 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 a 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 correspond 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 or 136.Ar val . 137Note that a quoted 138.Ar key 139causes errors in some 140.Nm 141implementations and should not be considered portable. 142It is not expanded for replacements. 143Definitions may refer to other definitions; these are evaluated 144recursively when text replacement occurs and not when the definition is 145created. 146.Pp 147Definitions can create arbitrary strings, for example, the following is 148a legal construction. 149.Bd -literal -offset indent 150define foo 'define' 151foo bar 'baz' 152.Ed 153.Pp 154Self-referencing definitions will raise an error. 155The 156.Cm ndefine 157statement is a synonym for 158.Cm define , 159while 160.Cm tdefine 161is discarded. 162.It Cm gfont 163Set the default font of subsequent output. 164Its syntax is as follows: 165.Pp 166.D1 gfont Ar font 167.Pp 168In mandoc, this value is discarded. 169.It Cm gsize 170Set the default size of subsequent output. 171Its syntax is as follows: 172.Pp 173.D1 gsize Ar size 174.Pp 175The 176.Ar size 177value should be an integer. 178.It Cm set 179Set an equation mode. 180In mandoc, both arguments are thrown away. 181Its syntax is as follows: 182.Pp 183.D1 set Ar key val 184.Pp 185The 186.Ar key 187and 188.Ar val 189are not expanded for replacements. 190This statement is a GNU extension. 191.It Cm undef 192Unset a previously-defined key. 193Its syntax is as follows: 194.Pp 195.D1 define Ar key 196.Pp 197Once invoked, the definition for 198.Ar key 199is discarded. 200The 201.Ar key 202is not expanded for replacements. 203This statement is a GNU extension. 204.El 205.Sh COMPATIBILITY 206This section documents the compatibility of mandoc 207.Nm 208and the troff 209.Nm 210implementation (including GNU troff). 211.Pp 212.Bl -dash -compact 213.It 214The text string 215.Sq \e\*q 216is interpreted as a literal quote in troff. 217In mandoc, this is interpreted as a comment. 218.It 219In troff, The circumflex and tilde white-space symbols map to 220fixed-width spaces. 221In mandoc, these characters are synonyms for the space character. 222.It 223The troff implementation of 224.Nm 225allows for equation alignment with the 226.Cm mark 227and 228.Cm lineup 229tokens. 230mandoc discards these tokens. 231The 232.Cm back Ar n , 233.Cm fwd Ar n , 234.Cm up Ar n , 235and 236.Cm down Ar n 237commands are also ignored. 238.El 239.Sh SEE ALSO 240.Xr mandoc 1 , 241.Xr man 7 , 242.Xr mandoc_char 7 , 243.Xr mdoc 7 , 244.Xr roff 7 245.Rs 246.%A Brian W. Kernighan 247.%A Lorinda L. Cherry 248.%T System for Typesetting Mathematics 249.%J Communications of the ACM 250.%V 18 251.%P 151\(en157 252.%D March, 1975 253.Re 254.Rs 255.%A Brian W. Kernighan 256.%A Lorinda L. Cherry 257.%T Typesetting Mathematics, User's Guide 258.%D 1976 259.Re 260.Rs 261.%A Brian W. Kernighan 262.%A Lorinda L. Cherry 263.%T Typesetting Mathematics, User's Guide (Second Edition) 264.%D 1978 265.Re 266.Sh HISTORY 267The eqn utility, a preprocessor for troff, was originally written by 268Brian W. Kernighan and Lorinda L. Cherry in 1975. 269The GNU reimplementation of eqn, part of the GNU troff package, was 270released in 1989 by James Clark. 271The eqn component of 272.Xr mandoc 1 273was added in 2011. 274.Sh AUTHORS 275This 276.Nm 277reference was written by 278.An Kristaps Dzonsons , 279.Mt kristaps@bsd.lv . 280