contrib/mdocml/eqn.7

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