eqn.7

   1 .\"     $Id: eqn.7,v 1.17 2011/07/22 14:55:07 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 22 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 subset of the
  34 .Nm
  35 language accepted by the
  36 .Xr mandoc 1
  37 utility.
  38 .Pp
  39 Equations within
  40 .Xr mdoc 7
  41 or
  42 .Xr man 7
  43 documents are enclosed by the standalone
  44 .Sq \&.EQ
  45 and
  46 .Sq \&.EN
  47 tags.
  48 Equations are multi-line blocks consisting of formulas and control
  49 statements.
  50 .Sh EQUATION STRUCTURE
  51 Each equation is bracketed by
  52 .Sq \&.EQ
  53 and
  54 .Sq \&.EN
  55 strings.
  56 .Em Note :
  57 these are not the same as
  58 .Xr roff 7
  59 macros, and may only be invoked as
  60 .Sq \&.EQ .
  61 .Pp
  62 The equation grammar is as follows, where quoted strings are
  63 case-sensitive literals in the input:
  64 .Bd -literal -offset indent
  65 eqn     : box | eqn box
  66 box     : text
  67         | "{" eqn "}"
  68         | "define" text text
  69         | "gsize" text
  70         | "set" text text
  71         | "undef" text
  72         | box pos box
  73         | box mark
  74         | pile "{" list "}"
  75         | font box
  76         | "size" text box
  77         | "left" text eqn ["right" text]
  78 text    : TEXT
  79 pile    : "lpile" | "cpile" | "rpile"
  80 pos     : "over" | "sup" | "sub" | "to" | "from"
  81 mark    : "dot" | "dotdot" | "hat" | "tilde" | "vec"
  82         | "dyad" | "bar" | "under"
  83 font    : "roman" | "italic" | "bold"
  84 list    : eqn
  85         | list "above" eqn
  86 .Ed
  87 .Pp
  88 Data in TEXT form is a non-empty sequence of non-space characters or a
  89 non-empty quoted string.
  90 Unless within a quoted string, white-space (and enclosing literal quote
  91 pairs) is thrown away.
  92 Quoted strings are not scanned for replacement definitions.
  93 .Pp
  94 The following TEXT terms are translated into a rendered glyph, if
  95 available: alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa,
  96 lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta,
  97 upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA,
  98 THETA, UPSILON, XI, inter (intersection), union (union), prod (product),
  99 int (integral), sum (summation), grad (gradient), del (vector
 100 differential), times (multiply), cdot (centre-dot), nothing (zero-width
 101 space), approx (approximately equals), prime (prime), half (one-half),
 102 partial (partial differential), inf (infinity), >> (much greater), <<
 103 (much less), \-> (left arrow), <\- (right arrow), += (plus-minus), !=
 104 (not equal), == (equivalence), <= (less-than-equal), and >=
 105 (more-than-equal).
 106 .Pp
 107 The following control statements are available:
 108 .Bl -tag -width Ds
 109 .It Cm define
 110 Replace all occurances of a key with a value.
 111 Its syntax is as follows:
 112 .Pp
 113 .D1 define Ar key cvalc
 114 .Pp
 115 The first character of the value string,
 116 .Ar c ,
 117 is used as the delimiter for the value
 118 .Ar val .
 119 This allows for arbitrary enclosure of terms (not just quotes), such as
 120 .Pp
 121 .D1 define Ar foo 'bar baz'
 122 .D1 define Ar foo cbar bazc
 123 .Pp
 124 It is an error to have an empty
 125 .Ar key or
 126 .Ar val .
 127 Note that a quoted
 128 .Ar key
 129 causes errors in some
 130 .Nm
 131 implementations and should not be considered portable.
 132 It is not expanded for replacements.
 133 Definitions may refer to other definitions; these are evaluated
 134 recursively when text replacement occurs and not when the definition is
 135 created.
 136 .Pp
 137 Definitions can create arbitrary strings, for example, the following is
 138 a legal construction.
 139 .Bd -literal -offset indent
 140 define foo 'define'
 141 foo bar 'baz'
 142 .Ed
 143 .Pp
 144 Self-referencing definitions will raise an error.
 145 .It Cm gsize
 146 Set the default size of subsequent output.
 147 Its syntax is as follows:
 148 .Pp
 149 .D1 define Ar size
 150 .Pp
 151 The
 152 .Ar size
 153 value should be an integer.
 154 .It Cm set
 155 Set an equation mode.
 156 Both arguments are thrown away.
 157 Its syntax is as follows:
 158 .Pp
 159 .D1 set Ar key val
 160 .Pp
 161 The
 162 .Ar key
 163 and
 164 .Ar val
 165 are not expanded for replacements.
 166 .It Cm undef
 167 Unset a previously-defined key.
 168 Its syntax is as follows:
 169 .Pp
 170 .D1 define Ar key
 171 .Pp
 172 Once invoked, the definition for
 173 .Ar key
 174 is discarded.
 175 The
 176 .Ar key
 177 is not expanded for replacements.
 178 .El
 179 .Sh COMPATIBILITY
 180 This section documents the compatibility of mandoc
 181 .Nm
 182 and the troff
 183 .Nm
 184 implementation (including GNU troff).
 185 .Pp
 186 .Bl -dash -compact
 187 .It
 188 The text string
 189 .Sq \e\*q
 190 is interpreted as a literal quote in troff.
 191 In mandoc, this is interpreted as a comment.
 192 .El
 193 .Sh SEE ALSO
 194 .Xr mandoc 1 ,
 195 .Xr man 7 ,
 196 .Xr mandoc_char 7 ,
 197 .Xr mdoc 7 ,
 198 .Xr roff 7
 199 .Rs
 200 .%A Brian W. Kernighan
 201 .%A Lorinda L. Cherry
 202 .%T System for Typesetting Mathematics
 203 .%J Communications of the ACM
 204 .%V 18
 205 .%P 151\(en157
 206 .%D March, 1975
 207 .Re
 208 .Rs
 209 .%A Brian W. Kernighan
 210 .%A Lorinda L. Cherry
 211 .%T Typesetting Mathematics, User's Guide
 212 .%D 1976
 213 .Re
 214 .Rs
 215 .%A Brian W. Kernighan
 216 .%A Lorinda L. Cherry
 217 .%T Typesetting Mathematics, User's Guide (Second Edition)
 218 .%D 1978
 219 .Re
 220 .Sh HISTORY
 221 The eqn utility, a preprocessor for troff, was originally written by
 222 Brian W. Kernighan and Lorinda L. Cherry in 1975.
 223 The GNU reimplementation of eqn, part of the GNU troff package, was
 224 released in 1989 by James Clark.
 225 The eqn component of
 226 .Xr mandoc 1
 227 was added in 2011.
 228 .Sh AUTHORS
 229 This
 230 .Nm
 231 reference was written by
 232 .An Kristaps Dzonsons Aq kristaps@bsd.lv .