eqn.7 (12862B)
- .\" $Id: eqn.7,v 1.39 2020/01/10 11:55:04 schwarze Exp $
- .\"
- .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
- .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
- .\"
- .\" Permission to use, copy, modify, and distribute this software for any
- .\" purpose with or without fee is hereby granted, provided that the above
- .\" copyright notice and this permission notice appear in all copies.
- .\"
- .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
- .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
- .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
- .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
- .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
- .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
- .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
- .\"
- .Dd $Mdocdate: January 10 2020 $
- .Dt EQN 7
- .Os
- .Sh NAME
- .Nm eqn
- .Nd eqn language reference for mandoc
- .Sh DESCRIPTION
- The
- .Nm eqn
- language is an equation-formatting language.
- It is used within
- .Xr mdoc 7
- and
- .Xr man 7
- .Ux
- manual pages.
- It describes the
- .Em structure
- of an equation, not its mathematical meaning.
- This manual describes the
- .Nm
- language accepted by the
- .Xr mandoc 1
- utility, which corresponds to the Second Edition
- .Nm
- specification (see
- .Sx SEE ALSO
- for references).
- .Pp
- An equation starts with an input line containing exactly the characters
- .Sq \&.EQ ,
- may contain multiple input lines, and ends with an input line
- containing exactly the characters
- .Sq \&.EN .
- Equivalently, an equation can be given in the middle of a single
- text input line by surrounding it with the equation delimiters
- defined with the
- .Cm delim
- statement.
- .Pp
- The equation grammar is as follows, where quoted strings are
- case-sensitive literals in the input:
- .Bd -literal -offset indent
- eqn : box | eqn box
- box : text
- | \(dq{\(dq eqn \(dq}\(dq
- | \(dqdefine\(dq text text
- | \(dqndefine\(dq text text
- | \(dqtdefine\(dq text text
- | \(dqgfont\(dq text
- | \(dqgsize\(dq text
- | \(dqset\(dq text text
- | \(dqundef\(dq text
- | \(dqsqrt\(dq box
- | box pos box
- | box mark
- | \(dqmatrix\(dq \(dq{\(dq [col \(dq{\(dq list \(dq}\(dq]* \(dq}\(dq
- | pile \(dq{\(dq list \(dq}\(dq
- | font box
- | \(dqsize\(dq text box
- | \(dqleft\(dq text eqn [\(dqright\(dq text]
- col : \(dqlcol\(dq | \(dqrcol\(dq | \(dqccol\(dq | \(dqcol\(dq
- text : [^space\e\(dq]+ | \e\(dq.*\e\(dq
- pile : \(dqlpile\(dq | \(dqcpile\(dq | \(dqrpile\(dq | \(dqpile\(dq
- pos : \(dqover\(dq | \(dqsup\(dq | \(dqsub\(dq | \(dqto\(dq | \(dqfrom\(dq
- mark : \(dqdot\(dq | \(dqdotdot\(dq | \(dqhat\(dq | \(dqtilde\(dq | \(dqvec\(dq
- | \(dqdyad\(dq | \(dqbar\(dq | \(dqunder\(dq
- font : \(dqroman\(dq | \(dqitalic\(dq | \(dqbold\(dq | \(dqfat\(dq
- list : eqn
- | list \(dqabove\(dq eqn
- space : [\e^~ \et]
- .Ed
- .Pp
- White-space consists of the space, tab, circumflex, and tilde
- characters.
- It is required to delimit tokens consisting of alphabetic characters
- and it is ignored at other places.
- Braces and quotes also delimit tokens.
- If within a quoted string, these space characters are retained.
- Quoted strings are also not scanned for keywords, glyph names,
- and expansion of definitions.
- To print a literal quote character, it can be prepended with a
- backslash or expressed with the \e(dq escape sequence.
- .Pp
- Subequations can be enclosed in braces to pass them as arguments
- to operation keywords, overriding standard operation precedence.
- Braces can be nested.
- To set a brace verbatim, it needs to be enclosed in quotes.
- .Pp
- The following text terms are translated into a rendered glyph, if
- available: alpha, beta, chi, delta, epsilon, eta, gamma, iota, kappa,
- lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta,
- upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA,
- THETA, UPSILON, XI, inter (intersection), union (union), prod (product),
- int (integral), sum (summation), grad (gradient), del (vector
- differential), times (multiply), cdot (center-dot), nothing (zero-width
- space), approx (approximately equals), prime (prime), half (one-half),
- partial (partial differential), inf (infinity), >> (much greater), <<
- (much less), <\- (left arrow), \-> (right arrow), +\- (plus-minus), !=
- (not equal), == (equivalence), <= (less-than-equal), and >=
- (more-than-equal).
- The character escape sequences documented in
- .Xr mandoc_char 7
- can be used, too.
- .Pp
- The following control statements are available:
- .Bl -tag -width Ds
- .It Cm define
- Replace all occurrences of a key with a value.
- Its syntax is as follows:
- .Pp
- .D1 Cm define Ar key cvalc
- .Pp
- The first character of the value string,
- .Ar c ,
- is used as the delimiter for the value
- .Ar val .
- This allows for arbitrary enclosure of terms (not just quotes), such as
- .Pp
- .D1 Cm define Ar foo \(aqbar baz\(aq
- .D1 Cm define Ar foo cbar bazc
- .Pp
- It is an error to have an empty
- .Ar key
- or
- .Ar val .
- Note that a quoted
- .Ar key
- causes errors in some
- .Nm
- implementations and should not be considered portable.
- It is not expanded for replacements.
- Definitions may refer to other definitions; these are evaluated
- recursively when text replacement occurs and not when the definition is
- created.
- .Pp
- Definitions can create arbitrary strings, for example, the following is
- a legal construction.
- .Bd -literal -offset indent
- define foo \(aqdefine\(aq
- foo bar \(aqbaz\(aq
- .Ed
- .Pp
- Self-referencing definitions will raise an error.
- The
- .Cm ndefine
- statement is a synonym for
- .Cm define ,
- while
- .Cm tdefine
- is discarded.
- .It Cm delim
- This statement takes a string argument consisting of two bytes,
- to be used as the opening and closing delimiters for equations
- in the middle of text input lines.
- Conventionally, the dollar sign is used for both delimiters,
- as follows:
- .Bd -literal -offset indent
- \&.EQ
- delim $$
- \&.EN
- An equation like $sin pi = 0$ can now be entered
- in the middle of a text input line.
- .Ed
- .Pp
- The special statement
- .Cm delim off
- temporarily disables previously declared delimiters and
- .Cm delim on
- reenables them.
- .It Cm gfont
- Set the default font of subsequent output.
- Its syntax is as follows:
- .Pp
- .D1 Cm gfont Ar font
- .Pp
- In mandoc, this value is discarded.
- .It Cm gsize
- Set the default size of subsequent output.
- Its syntax is as follows:
- .Pp
- .D1 Cm gsize Oo +|\- Oc Ns Ar size
- .Pp
- The
- .Ar size
- value should be an integer.
- If prepended by a sign,
- the font size is changed relative to the current size.
- .It Cm set
- Set an equation mode.
- In mandoc, both arguments are thrown away.
- Its syntax is as follows:
- .Pp
- .D1 Cm set Ar key val
- .Pp
- The
- .Ar key
- and
- .Ar val
- are not expanded for replacements.
- This statement is a GNU extension.
- .It Cm undef
- Unset a previously-defined key.
- Its syntax is as follows:
- .Pp
- .D1 Cm define Ar key
- .Pp
- Once invoked, the definition for
- .Ar key
- is discarded.
- The
- .Ar key
- is not expanded for replacements.
- This statement is a GNU extension.
- .El
- .Pp
- Operation keywords have the following semantics:
- .Bl -tag -width Ds
- .It Cm above
- See
- .Cm pile .
- .It Cm bar
- Draw a line over the preceding box.
- .It Cm bold
- Set the following box using bold font.
- .It Cm ccol
- Like
- .Cm cpile ,
- but for use in
- .Cm matrix .
- .It Cm cpile
- Like
- .Cm pile ,
- but with slightly increased vertical spacing.
- .It Cm dot
- Set a single dot over the preceding box.
- .It Cm dotdot
- Set two dots (dieresis) over the preceding box.
- .It Cm dyad
- Set a dyad symbol (left-right arrow) over the preceding box.
- .It Cm fat
- A synonym for
- .Cm bold .
- .It Cm font
- Set the second argument using the font specified by the first argument;
- currently not recognized by the
- .Xr mandoc 1
- .Nm
- parser.
- .It Cm from
- Set the following box below the preceding box,
- using a slightly smaller font.
- Used for sums, integrals, limits, and the like.
- .It Cm hat
- Set a hat (circumflex) over the preceding box.
- .It Cm italic
- Set the following box using italic font.
- .It Cm lcol
- Like
- .Cm lpile ,
- but for use in
- .Cm matrix .
- .It Cm left
- Set the first argument as a big left delimiter before the second argument.
- As an optional third argument,
- .Cm right
- can follow.
- In that case, the fourth argument is set as a big right delimiter after
- the second argument.
- .It Cm lpile
- Like
- .Cm cpile ,
- but subequations are left-justified.
- .It Cm matrix
- Followed by a list of columns enclosed in braces.
- All columns need to have the same number of subequations.
- The columns are set as a matrix.
- The difference compared to multiple subsequent
- .Cm pile
- operators is that in a
- .Cm matrix ,
- corresponding subequations in all columns line up horizontally,
- while each
- .Cm pile
- does vertical spacing independently.
- .It Cm over
- Set a fraction.
- The preceding box is the numerator, the following box is the denominator.
- .It Cm pile
- Followed by a list of subequations enclosed in braces,
- the subequations being separated by
- .Cm above
- keywords.
- Sets the subequations one above the other, each of them centered.
- Typically used to represent vectors in coordinate representation.
- .It Cm rcol
- Like
- .Cm rpile ,
- but for use in
- .Cm matrix .
- .It Cm right
- See
- .Cm left ;
- .Cm right
- cannot be used without
- .Cm left .
- To set a big right delimiter without a big left delimiter, the following
- construction can be used:
- .Pp
- .D1 Cm left No \(dq\(dq Ar box Cm right Ar delimiter
- .It Cm roman
- Set the following box using the default font.
- .It Cm rpile
- Like
- .Cm cpile ,
- but subequations are right-justified.
- .It Cm size
- Set the second argument with the font size specified by the first
- argument; currently ignored by
- .Xr mandoc 1 .
- By prepending a plus or minus sign to the first argument,
- the font size can be selected relative to the current size.
- .It Cm sqrt
- Set the square root of the following box.
- .It Cm sub
- Set the following box as a subscript to the preceding box.
- .It Cm sup
- Set the following box as a superscript to the preceding box.
- As a special case, if a
- .Cm sup
- clause immediately follows a
- .Cm sub
- clause as in
- .Pp
- .D1 Ar mainbox Cm sub Ar subbox Cm sup Ar supbox
- .Pp
- both are set with respect to the same
- .Ar mainbox ,
- that is,
- .Ar supbox
- is set above
- .Ar subbox .
- .It Cm tilde
- Set a tilde over the preceding box.
- .It Cm to
- Set the following box above the preceding box,
- using a slightly smaller font.
- Used for sums and integrals and the like.
- As a special case, if a
- .Cm to
- clause immediately follows a
- .Cm from
- clause as in
- .Pp
- .D1 Ar mainbox Cm from Ar frombox Cm to Ar tobox
- .Pp
- both are set below and above the same
- .Ar mainbox .
- .It Cm under
- Underline the preceding box.
- .It Cm vec
- Set a vector symbol (right arrow) over the preceding box.
- .El
- .Pp
- The binary operations
- .Cm from ,
- .Cm to ,
- .Cm sub ,
- and
- .Cm sup
- group to the right, that is,
- .Pp
- .D1 Ar mainbox Cm sup Ar supbox Cm sub Ar subbox
- .Pp
- is the same as
- .Pp
- .D1 Ar mainbox Cm sup Brq Ar supbox Cm sub Ar subbox
- .Pp
- and different from
- .Pp
- .D1 Bro Ar mainbox Cm sup Ar supbox Brc Cm sub Ar subbox .
- .Pp
- By contrast,
- .Cm over
- groups to the left.
- .Pp
- In the following list, earlier operations bind more tightly than
- later operations:
- .Pp
- .Bl -enum -compact
- .It
- .Cm dyad ,
- .Cm vec ,
- .Cm under ,
- .Cm bar ,
- .Cm tilde ,
- .Cm hat ,
- .Cm dot ,
- .Cm dotdot
- .It
- .Cm fat ,
- .Cm roman ,
- .Cm italic ,
- .Cm bold ,
- .Cm size
- .It
- .Cm sub ,
- .Cm sup
- .It
- .Cm sqrt
- .It
- .Cm over
- .It
- .Cm from ,
- .Cm to
- .El
- .Sh COMPATIBILITY
- This section documents the compatibility of mandoc
- .Nm
- and the troff
- .Nm
- implementation (including GNU troff).
- .Pp
- .Bl -dash -compact
- .It
- The text string
- .Sq \e\(dq
- is interpreted as a literal quote in troff.
- In mandoc, this is interpreted as a comment.
- .It
- In troff, The circumflex and tilde white-space symbols map to
- fixed-width spaces.
- In mandoc, these characters are synonyms for the space character.
- .It
- The troff implementation of
- .Nm
- allows for equation alignment with the
- .Cm mark
- and
- .Cm lineup
- tokens.
- mandoc discards these tokens.
- The
- .Cm back Ar n ,
- .Cm fwd Ar n ,
- .Cm up Ar n ,
- and
- .Cm down Ar n
- commands are also ignored.
- .El
- .Sh SEE ALSO
- .Xr mandoc 1 ,
- .Xr man 7 ,
- .Xr mandoc_char 7 ,
- .Xr mdoc 7 ,
- .Xr roff 7
- .Rs
- .%A Brian W. Kernighan
- .%A Lorinda L. Cherry
- .%T System for Typesetting Mathematics
- .%J Communications of the ACM
- .%V 18
- .%P pp. 151\(en157
- .%D March, 1975
- .Re
- .Rs
- .%A Brian W. Kernighan
- .%A Lorinda L. Cherry
- .%T Typesetting Mathematics, User's Guide
- .%D 1976
- .Re
- .Rs
- .%A Brian W. Kernighan
- .%A Lorinda L. Cherry
- .%T Typesetting Mathematics, User's Guide (Second Edition)
- .%D 1978
- .Re
- .Sh HISTORY
- The eqn utility, a preprocessor for troff, was originally written by
- Brian W. Kernighan and Lorinda L. Cherry in 1975.
- The GNU reimplementation of eqn, part of the GNU troff package, was
- released in 1989 by James Clark.
- The eqn component of
- .Xr mandoc 1
- was added in 2011.
- .Sh AUTHORS
- This
- .Nm
- reference was written by
- .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .