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