eqn.7

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