280 lines
7 KiB
Groff
280 lines
7 KiB
Groff
.\" $Vendor-Id: eqn.7,v 1.28 2011/09/25 18:37:09 schwarze Exp $
|
|
.\"
|
|
.\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
|
|
.\"
|
|
.\" 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 September 25, 2011
|
|
.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 eqn specification (see
|
|
.Sx SEE ALSO
|
|
for references).
|
|
.Pp
|
|
Equations within
|
|
.Xr mdoc 7
|
|
or
|
|
.Xr man 7
|
|
documents are enclosed by the standalone
|
|
.Sq \&.EQ
|
|
and
|
|
.Sq \&.EN
|
|
tags.
|
|
Equations are multi-line blocks consisting of formulas and control
|
|
statements.
|
|
.Sh EQUATION STRUCTURE
|
|
Each equation is bracketed by
|
|
.Sq \&.EQ
|
|
and
|
|
.Sq \&.EN
|
|
strings.
|
|
.Em Note :
|
|
these are not the same as
|
|
.Xr roff 7
|
|
macros, and may only be invoked as
|
|
.Sq \&.EQ .
|
|
.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
|
|
| \*q{\*q eqn \*q}\*q
|
|
| \*qdefine\*q text text
|
|
| \*qndefine\*q text text
|
|
| \*qtdefine\*q text text
|
|
| \*qgfont\*q text
|
|
| \*qgsize\*q text
|
|
| \*qset\*q text text
|
|
| \*qundef\*q text
|
|
| box pos box
|
|
| box mark
|
|
| \*qmatrix\*q \*q{\*q [col \*q{\*q list \*q}\*q ]*
|
|
| pile \*q{\*q list \*q}\*q
|
|
| font box
|
|
| \*qsize\*q text box
|
|
| \*qleft\*q text eqn [\*qright\*q text]
|
|
col : \*qlcol\*q | \*qrcol\*q | \*qccol\*q | \*qcol\*q
|
|
text : [^space\e\*q]+ | \e\*q.*\e\*q
|
|
pile : \*qlpile\*q | \*qcpile\*q | \*qrpile\*q | \*qpile\*q
|
|
pos : \*qover\*q | \*qsup\*q | \*qsub\*q | \*qto\*q | \*qfrom\*q
|
|
mark : \*qdot\*q | \*qdotdot\*q | \*qhat\*q | \*qtilde\*q | \*qvec\*q
|
|
| \*qdyad\*q | \*qbar\*q | \*qunder\*q
|
|
font : \*qroman\*q | \*qitalic\*q | \*qbold\*q | \*qfat\*q
|
|
list : eqn
|
|
| list \*qabove\*q eqn
|
|
space : [\e^~ \et]
|
|
.Ed
|
|
.Pp
|
|
White-space consists of the space, tab, circumflex, and tilde
|
|
characters.
|
|
If within a quoted string, these space characters are retained.
|
|
Quoted strings are also not scanned for replacement definitions.
|
|
.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 (centre-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).
|
|
.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 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 define Ar foo 'bar baz'
|
|
.D1 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 'define'
|
|
foo bar 'baz'
|
|
.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 gfont
|
|
Set the default font of subsequent output.
|
|
Its syntax is as follows:
|
|
.Pp
|
|
.D1 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 gsize Ar size
|
|
.Pp
|
|
The
|
|
.Ar size
|
|
value should be an integer.
|
|
.It Cm set
|
|
Set an equation mode.
|
|
In mandoc, both arguments are thrown away.
|
|
Its syntax is as follows:
|
|
.Pp
|
|
.D1 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 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
|
|
.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\*q
|
|
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 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 ,
|
|
.Mt kristaps@bsd.lv .
|