eqn.7

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