contrib/mandoc/eqn.7

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