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