contrib/mandoc/eqn.7

   1 .\"     $Id: eqn.7,v 1.38 2019/04/23 17:57:49 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
   4 .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd $Mdocdate: April 23 2019 $
  19 .Dt EQN 7
  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 7
  30 and
  31 .Xr man 7
  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
  42 .Nm
  43 specification (see
  44 .Sx SEE ALSO
  45 for references).
  46 .Pp
  47 Equations within
  48 .Xr mdoc 7
  49 or
  50 .Xr man 7
  51 documents are enclosed by the standalone
  52 .Sq \&.EQ
  53 and
  54 .Sq \&.EN
  55 tags.
  56 Equations are multi-line blocks consisting of formulas and control
  57 statements.
  58 .Sh EQUATION STRUCTURE
  59 Each equation is bracketed by
  60 .Sq \&.EQ
  61 and
  62 .Sq \&.EN
  63 strings.
  64 .Em Note :
  65 these are not the same as
  66 .Xr roff 7
  67 macros, and may only be invoked as
  68 .Sq \&.EQ .
  69 .Pp
  70 The equation grammar is as follows, where quoted strings are
  71 case-sensitive literals in the input:
  72 .Bd -literal -offset indent
  73 eqn     : box | eqn box
  74 box     : text
  75         | \(dq{\(dq eqn \(dq}\(dq
  76         | \(dqdefine\(dq text text
  77         | \(dqndefine\(dq text text
  78         | \(dqtdefine\(dq text text
  79         | \(dqgfont\(dq text
  80         | \(dqgsize\(dq text
  81         | \(dqset\(dq text text
  82         | \(dqundef\(dq text
  83         | \(dqsqrt\(dq box
  84         | box pos box
  85         | box mark
  86         | \(dqmatrix\(dq \(dq{\(dq [col \(dq{\(dq list \(dq}\(dq]* \(dq}\(dq
  87         | pile \(dq{\(dq list \(dq}\(dq
  88         | font box
  89         | \(dqsize\(dq text box
  90         | \(dqleft\(dq text eqn [\(dqright\(dq text]
  91 col     : \(dqlcol\(dq | \(dqrcol\(dq | \(dqccol\(dq | \(dqcol\(dq
  92 text    : [^space\e\(dq]+ | \e\(dq.*\e\(dq
  93 pile    : \(dqlpile\(dq | \(dqcpile\(dq | \(dqrpile\(dq | \(dqpile\(dq
  94 pos     : \(dqover\(dq | \(dqsup\(dq | \(dqsub\(dq | \(dqto\(dq | \(dqfrom\(dq
  95 mark    : \(dqdot\(dq | \(dqdotdot\(dq | \(dqhat\(dq | \(dqtilde\(dq | \(dqvec\(dq
  96         | \(dqdyad\(dq | \(dqbar\(dq | \(dqunder\(dq
  97 font    : \(dqroman\(dq | \(dqitalic\(dq | \(dqbold\(dq | \(dqfat\(dq
  98 list    : eqn
  99         | list \(dqabove\(dq eqn
 100 space   : [\e^~ \et]
 101 .Ed
 102 .Pp
 103 White-space consists of the space, tab, circumflex, and tilde
 104 characters.
 105 It is required to delimit tokens consisting of alphabetic characters
 106 and it is ignored at other places.
 107 Braces and quotes also delimit tokens.
 108 If within a quoted string, these space characters are retained.
 109 Quoted strings are also not scanned for keywords, glyph names,
 110 and expansion of definitions.
 111 To print a literal quote character, it can be prepended with a
 112 backslash or expressed with the \e(dq escape sequence.
 113 .Pp
 114 Subequations can be enclosed in braces to pass them as arguments
 115 to operation keywords, overriding standard operation precedence.
 116 Braces can be nested.
 117 To set a brace verbatim, it needs to be enclosed in quotes.
 118 .Pp
 119 The following text terms are translated into a rendered glyph, if
 120 available: alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa,
 121 lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta,
 122 upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA,
 123 THETA, UPSILON, XI, inter (intersection), union (union), prod (product),
 124 int (integral), sum (summation), grad (gradient), del (vector
 125 differential), times (multiply), cdot (center-dot), nothing (zero-width
 126 space), approx (approximately equals), prime (prime), half (one-half),
 127 partial (partial differential), inf (infinity), >> (much greater), <<
 128 (much less), <\- (left arrow), \-> (right arrow), +\- (plus-minus), !=
 129 (not equal), == (equivalence), <= (less-than-equal), and >=
 130 (more-than-equal).
 131 The character escape sequences documented in
 132 .Xr mandoc_char 7
 133 can be used, too.
 134 .Pp
 135 The following control statements are available:
 136 .Bl -tag -width Ds
 137 .It Cm define
 138 Replace all occurrences of a key with a value.
 139 Its syntax is as follows:
 140 .Pp
 141 .D1 Cm define Ar key cvalc
 142 .Pp
 143 The first character of the value string,
 144 .Ar c ,
 145 is used as the delimiter for the value
 146 .Ar val .
 147 This allows for arbitrary enclosure of terms (not just quotes), such as
 148 .Pp
 149 .D1 Cm define Ar foo \(aqbar baz\(aq
 150 .D1 Cm define Ar foo cbar bazc
 151 .Pp
 152 It is an error to have an empty
 153 .Ar key
 154 or
 155 .Ar val .
 156 Note that a quoted
 157 .Ar key
 158 causes errors in some
 159 .Nm
 160 implementations and should not be considered portable.
 161 It is not expanded for replacements.
 162 Definitions may refer to other definitions; these are evaluated
 163 recursively when text replacement occurs and not when the definition is
 164 created.
 165 .Pp
 166 Definitions can create arbitrary strings, for example, the following is
 167 a legal construction.
 168 .Bd -literal -offset indent
 169 define foo \(aqdefine\(aq
 170 foo bar \(aqbaz\(aq
 171 .Ed
 172 .Pp
 173 Self-referencing definitions will raise an error.
 174 The
 175 .Cm ndefine
 176 statement is a synonym for
 177 .Cm define ,
 178 while
 179 .Cm tdefine
 180 is discarded.
 181 .It Cm gfont
 182 Set the default font of subsequent output.
 183 Its syntax is as follows:
 184 .Pp
 185 .D1 Cm gfont Ar font
 186 .Pp
 187 In mandoc, this value is discarded.
 188 .It Cm gsize
 189 Set the default size of subsequent output.
 190 Its syntax is as follows:
 191 .Pp
 192 .D1 Cm gsize Oo +|\- Oc Ns Ar size
 193 .Pp
 194 The
 195 .Ar size
 196 value should be an integer.
 197 If prepended by a sign,
 198 the font size is changed relative to the current size.
 199 .It Cm set
 200 Set an equation mode.
 201 In mandoc, both arguments are thrown away.
 202 Its syntax is as follows:
 203 .Pp
 204 .D1 Cm set Ar key val
 205 .Pp
 206 The
 207 .Ar key
 208 and
 209 .Ar val
 210 are not expanded for replacements.
 211 This statement is a GNU extension.
 212 .It Cm undef
 213 Unset a previously-defined key.
 214 Its syntax is as follows:
 215 .Pp
 216 .D1 Cm define Ar key
 217 .Pp
 218 Once invoked, the definition for
 219 .Ar key
 220 is discarded.
 221 The
 222 .Ar key
 223 is not expanded for replacements.
 224 This statement is a GNU extension.
 225 .El
 226 .Pp
 227 Operation keywords have the following semantics:
 228 .Bl -tag -width Ds
 229 .It Cm above
 230 See
 231 .Cm pile .
 232 .It Cm bar
 233 Draw a line over the preceding box.
 234 .It Cm bold
 235 Set the following box using bold font.
 236 .It Cm ccol
 237 Like
 238 .Cm cpile ,
 239 but for use in
 240 .Cm matrix .
 241 .It Cm cpile
 242 Like
 243 .Cm pile ,
 244 but with slightly increased vertical spacing.
 245 .It Cm dot
 246 Set a single dot over the preceding box.
 247 .It Cm dotdot
 248 Set two dots (dieresis) over the preceding box.
 249 .It Cm dyad
 250 Set a dyad symbol (left-right arrow) over the preceding box.
 251 .It Cm fat
 252 A synonym for
 253 .Cm bold .
 254 .It Cm font
 255 Set the second argument using the font specified by the first argument;
 256 currently not recognized by the
 257 .Xr mandoc 1
 258 .Nm
 259 parser.
 260 .It Cm from
 261 Set the following box below the preceding box,
 262 using a slightly smaller font.
 263 Used for sums, integrals, limits, and the like.
 264 .It Cm hat
 265 Set a hat (circumflex) over the preceding box.
 266 .It Cm italic
 267 Set the following box using italic font.
 268 .It Cm lcol
 269 Like
 270 .Cm lpile ,
 271 but for use in
 272 .Cm matrix .
 273 .It Cm left
 274 Set the first argument as a big left delimiter before the second argument.
 275 As an optional third argument,
 276 .Cm right
 277 can follow.
 278 In that case, the fourth argument is set as a big right delimiter after
 279 the second argument.
 280 .It Cm lpile
 281 Like
 282 .Cm cpile ,
 283 but subequations are left-justified.
 284 .It Cm matrix
 285 Followed by a list of columns enclosed in braces.
 286 All columns need to have the same number of subequations.
 287 The columns are set as a matrix.
 288 The difference compared to multiple subsequent
 289 .Cm pile
 290 operators is that in a
 291 .Cm matrix ,
 292 corresponding subequations in all columns line up horizontally,
 293 while each
 294 .Cm pile
 295 does vertical spacing independently.
 296 .It Cm over
 297 Set a fraction.
 298 The preceding box is the numerator, the following box is the denominator.
 299 .It Cm pile
 300 Followed by a list of subequations enclosed in braces,
 301 the subequations being separated by
 302 .Cm above
 303 keywords.
 304 Sets the subequations one above the other, each of them centered.
 305 Typically used to represent vectors in coordinate representation.
 306 .It Cm rcol
 307 Like
 308 .Cm rpile ,
 309 but for use in
 310 .Cm matrix .
 311 .It Cm right
 312 See
 313 .Cm left ;
 314 .Cm right
 315 cannot be used without
 316 .Cm left .
 317 To set a big right delimiter without a big left delimiter, the following
 318 construction can be used:
 319 .Pp
 320 .D1 Cm left No \(dq\(dq Ar box Cm right Ar delimiter
 321 .It Cm roman
 322 Set the following box using the default font.
 323 .It Cm rpile
 324 Like
 325 .Cm cpile ,
 326 but subequations are right-justified.
 327 .It Cm size
 328 Set the second argument with the font size specified by the first
 329 argument; currently ignored by
 330 .Xr mandoc 1 .
 331 By prepending a plus or minus sign to the first argument,
 332 the font size can be selected relative to the current size.
 333 .It Cm sqrt
 334 Set the square root of the following box.
 335 .It Cm sub
 336 Set the following box as a subscript to the preceding box.
 337 .It Cm sup
 338 Set the following box as a superscript to the preceding box.
 339 As a special case, if a
 340 .Cm sup
 341 clause immediately follows a
 342 .Cm sub
 343 clause as in
 344 .Pp
 345 .D1 Ar mainbox Cm sub Ar subbox Cm sup Ar supbox
 346 .Pp
 347 both are set with respect to the same
 348 .Ar mainbox ,
 349 that is,
 350 .Ar supbox
 351 is set above
 352 .Ar subbox .
 353 .It Cm tilde
 354 Set a tilde over the preceding box.
 355 .It Cm to
 356 Set the following box above the preceding box,
 357 using a slightly smaller font.
 358 Used for sums and integrals and the like.
 359 As a special case, if a
 360 .Cm to
 361 clause immediately follows a
 362 .Cm from
 363 clause as in
 364 .Pp
 365 .D1 Ar mainbox Cm from Ar frombox Cm to Ar tobox
 366 .Pp
 367 both are set below and above the same
 368 .Ar mainbox .
 369 .It Cm under
 370 Underline the preceding box.
 371 .It Cm vec
 372 Set a vector symbol (right arrow) over the preceding box.
 373 .El
 374 .Pp
 375 The binary operations
 376 .Cm from ,
 377 .Cm to ,
 378 .Cm sub ,
 379 and
 380 .Cm sup
 381 group to the right, that is,
 382 .Pp
 383 .D1 Ar mainbox Cm sup Ar supbox Cm sub Ar subbox
 384 .Pp
 385 is the same as
 386 .Pp
 387 .D1 Ar mainbox Cm sup Brq Ar supbox Cm sub Ar subbox
 388 .Pp
 389 and different from
 390 .Pp
 391 .D1 Bro Ar mainbox Cm sup Ar supbox Brc Cm sub Ar subbox .
 392 .Pp
 393 By contrast,
 394 .Cm over
 395 groups to the left.
 396 .Pp
 397 In the following list, earlier operations bind more tightly than
 398 later operations:
 399 .Pp
 400 .Bl -enum -compact
 401 .It
 402 .Cm dyad ,
 403 .Cm vec ,
 404 .Cm under ,
 405 .Cm bar ,
 406 .Cm tilde ,
 407 .Cm hat ,
 408 .Cm dot ,
 409 .Cm dotdot
 410 .It
 411 .Cm fat ,
 412 .Cm roman ,
 413 .Cm italic ,
 414 .Cm bold ,
 415 .Cm size
 416 .It
 417 .Cm sub ,
 418 .Cm sup
 419 .It
 420 .Cm sqrt
 421 .It
 422 .Cm over
 423 .It
 424 .Cm from ,
 425 .Cm to
 426 .El
 427 .Sh COMPATIBILITY
 428 This section documents the compatibility of mandoc
 429 .Nm
 430 and the troff
 431 .Nm
 432 implementation (including GNU troff).
 433 .Pp
 434 .Bl -dash -compact
 435 .It
 436 The text string
 437 .Sq \e\(dq
 438 is interpreted as a literal quote in troff.
 439 In mandoc, this is interpreted as a comment.
 440 .It
 441 In troff, The circumflex and tilde white-space symbols map to
 442 fixed-width spaces.
 443 In mandoc, these characters are synonyms for the space character.
 444 .It
 445 The troff implementation of
 446 .Nm
 447 allows for equation alignment with the
 448 .Cm mark
 449 and
 450 .Cm lineup
 451 tokens.
 452 mandoc discards these tokens.
 453 The
 454 .Cm back Ar n ,
 455 .Cm fwd Ar n ,
 456 .Cm up Ar n ,
 457 and
 458 .Cm down Ar n
 459 commands are also ignored.
 460 .El
 461 .Sh SEE ALSO
 462 .Xr mandoc 1 ,
 463 .Xr man 7 ,
 464 .Xr mandoc_char 7 ,
 465 .Xr mdoc 7 ,
 466 .Xr roff 7
 467 .Rs
 468 .%A Brian W. Kernighan
 469 .%A Lorinda L. Cherry
 470 .%T System for Typesetting Mathematics
 471 .%J Communications of the ACM
 472 .%V 18
 473 .%P pp. 151\(en157
 474 .%D March, 1975
 475 .Re
 476 .Rs
 477 .%A Brian W. Kernighan
 478 .%A Lorinda L. Cherry
 479 .%T Typesetting Mathematics, User's Guide
 480 .%D 1976
 481 .Re
 482 .Rs
 483 .%A Brian W. Kernighan
 484 .%A Lorinda L. Cherry
 485 .%T Typesetting Mathematics, User's Guide (Second Edition)
 486 .%D 1978
 487 .Re
 488 .Sh HISTORY
 489 The eqn utility, a preprocessor for troff, was originally written by
 490 Brian W. Kernighan and Lorinda L. Cherry in 1975.
 491 The GNU reimplementation of eqn, part of the GNU troff package, was
 492 released in 1989 by James Clark.
 493 The eqn component of
 494 .Xr mandoc 1
 495 was added in 2011.
 496 .Sh AUTHORS
 497 This
 498 .Nm
 499 reference was written by
 500 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .