version 1.10, 2011/07/21 13:37:04 |
version 1.39, 2020/01/10 11:55:04 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" 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 |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
|
|
.Sh DESCRIPTION |
.Sh DESCRIPTION |
The |
The |
.Nm eqn |
.Nm eqn |
language is a equation-formatting language. |
language is an equation-formatting language. |
It is used within |
It is used within |
.Xr mdoc 7 |
.Xr mdoc 7 |
and |
and |
.Xr man 7 |
.Xr man 7 |
.Ux |
.Ux |
manual pages. |
manual pages. |
This manual describes the subset of the |
It describes the |
|
.Em structure |
|
of an equation, not its mathematical meaning. |
|
This manual describes the |
.Nm |
.Nm |
language accepted by the |
language accepted by the |
.Xr mandoc 1 |
.Xr mandoc 1 |
utility. |
utility, which corresponds to the Second Edition |
|
.Nm |
|
specification (see |
|
.Sx SEE ALSO |
|
for references). |
.Pp |
.Pp |
Equations within |
An equation starts with an input line containing exactly the characters |
.Xr mdoc 7 |
.Sq \&.EQ , |
or |
may contain multiple input lines, and ends with an input line |
.Xr man 7 |
containing exactly the characters |
documents are enclosed by the standalone |
.Sq \&.EN . |
.Sq \&.EQ |
Equivalently, an equation can be given in the middle of a single |
and |
text input line by surrounding it with the equation delimiters |
.Sq \&.EN |
defined with the |
tags. |
.Cm delim |
Equations are multi-line blocks consisting of formulas and control |
statement. |
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 |
.Pp |
The equation grammar is as follows: |
The equation grammar is as follows, where quoted strings are |
|
case-sensitive literals in the input: |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
eqn : box | eqn box |
eqn : box | eqn box |
box : text |
box : text |
| { eqn } |
| \(dq{\(dq eqn \(dq}\(dq |
| DEFINE text text |
| \(dqdefine\(dq text text |
| SET text text |
| \(dqndefine\(dq text text |
| UNDEF 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 |
| box mark |
|
| \(dqmatrix\(dq \(dq{\(dq [col \(dq{\(dq list \(dq}\(dq]* \(dq}\(dq |
|
| pile \(dq{\(dq list \(dq}\(dq |
| font box |
| font box |
text : TEXT |
| \(dqsize\(dq text box |
mark : DOT |
| \(dqleft\(dq text eqn [\(dqright\(dq text] |
| DOTDOT |
col : \(dqlcol\(dq | \(dqrcol\(dq | \(dqccol\(dq | \(dqcol\(dq |
| HAT |
text : [^space\e\(dq]+ | \e\(dq.*\e\(dq |
| TILDE |
pile : \(dqlpile\(dq | \(dqcpile\(dq | \(dqrpile\(dq | \(dqpile\(dq |
| VEC |
pos : \(dqover\(dq | \(dqsup\(dq | \(dqsub\(dq | \(dqto\(dq | \(dqfrom\(dq |
| DYAD |
mark : \(dqdot\(dq | \(dqdotdot\(dq | \(dqhat\(dq | \(dqtilde\(dq | \(dqvec\(dq |
| BAR |
| \(dqdyad\(dq | \(dqbar\(dq | \(dqunder\(dq |
| UNDER |
font : \(dqroman\(dq | \(dqitalic\(dq | \(dqbold\(dq | \(dqfat\(dq |
font : ROMAN |
list : eqn |
| ITALIC |
| list \(dqabove\(dq eqn |
| BOLD |
space : [\e^~ \et] |
.Ed |
.Ed |
.Pp |
.Pp |
Data in TEXT form is a non-empty sequence of non-space characters or a |
White-space consists of the space, tab, circumflex, and tilde |
non-empty quoted string. |
characters. |
Unless within a quoted string, white-space (and enclosing literal quote |
It is required to delimit tokens consisting of alphabetic characters |
pairs) is thrown away. |
and it is ignored at other places. |
Quoted strings are not scanned for replacement definitions. |
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 |
.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: |
The following control statements are available: |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
.It Cm define |
.It Cm define |
Replace all occurances of a key with a value. |
Replace all occurrences of a key with a value. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 define Ar key cvalc |
.D1 Cm define Ar key cvalc |
.Pp |
.Pp |
The first character of the value string, |
The first character of the value string, |
.Ar c , |
.Ar c , |
Line 103 is used as the delimiter for the value |
|
Line 134 is used as the delimiter for the value |
|
.Ar val . |
.Ar val . |
This allows for arbitrary enclosure of terms (not just quotes), such as |
This allows for arbitrary enclosure of terms (not just quotes), such as |
.Pp |
.Pp |
.D1 define Ar foo 'bar baz' |
.D1 Cm define Ar foo \(aqbar baz\(aq |
.D1 define Ar foo cbar bazc |
.D1 Cm define Ar foo cbar bazc |
.Pp |
.Pp |
It is an error to have an empty |
It is an error to have an empty |
.Ar key or |
.Ar key |
|
or |
.Ar val . |
.Ar val . |
Note that a quoted |
Note that a quoted |
.Ar key |
.Ar key |
|
|
Definitions can create arbitrary strings, for example, the following is |
Definitions can create arbitrary strings, for example, the following is |
a legal construction. |
a legal construction. |
.Bd -literal -offset indent |
.Bd -literal -offset indent |
define foo 'define' |
define foo \(aqdefine\(aq |
foo bar 'baz' |
foo bar \(aqbaz\(aq |
.Ed |
.Ed |
.Pp |
.Pp |
Self-referencing definitions will raise an error. |
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 |
.It Cm set |
Set an equation mode. |
Set an equation mode. |
Both arguments are thrown away. |
In mandoc, both arguments are thrown away. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 set Ar key val |
.D1 Cm set Ar key val |
.Pp |
.Pp |
The |
The |
.Ar key |
.Ar key |
and |
and |
.Ar val |
.Ar val |
are not expanded for replacements. |
are not expanded for replacements. |
|
This statement is a GNU extension. |
.It Cm undef |
.It Cm undef |
Unset a previously-defined key. |
Unset a previously-defined key. |
Its syntax is as follows: |
Its syntax is as follows: |
.Pp |
.Pp |
.D1 define Ar key |
.D1 Cm define Ar key |
.Pp |
.Pp |
Once invoked, the definition for |
Once invoked, the definition for |
.Ar key |
.Ar key |
|
|
The |
The |
.Ar key |
.Ar key |
is not expanded for replacements. |
is not expanded for replacements. |
|
This statement is a GNU extension. |
.El |
.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 |
.Sh COMPATIBILITY |
This section documents the compatibility of mandoc |
This section documents the compatibility of mandoc |
.Nm |
.Nm |
Line 162 implementation (including GNU troff). |
|
Line 441 implementation (including GNU troff). |
|
.Bl -dash -compact |
.Bl -dash -compact |
.It |
.It |
The text string |
The text string |
.Sq \e\*q |
.Sq \e\(dq |
is interpreted as a literal quote in troff. |
is interpreted as a literal quote in troff. |
In mandoc, this is interpreted as a comment. |
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 |
.El |
.Sh SEE ALSO |
.Sh SEE ALSO |
.Xr mandoc 1 , |
.Xr mandoc 1 , |
Line 178 In mandoc, this is interpreted as a comment. |
|
Line 477 In mandoc, this is interpreted as a comment. |
|
.%T System for Typesetting Mathematics |
.%T System for Typesetting Mathematics |
.%J Communications of the ACM |
.%J Communications of the ACM |
.%V 18 |
.%V 18 |
.%P 151\(en157 |
.%P pp. 151\(en157 |
.%D March, 1975 |
.%D March, 1975 |
.Re |
.Re |
.Rs |
.Rs |
Line 194 In mandoc, this is interpreted as a comment. |
|
Line 493 In mandoc, this is interpreted as a comment. |
|
.%D 1978 |
.%D 1978 |
.Re |
.Re |
.Sh HISTORY |
.Sh HISTORY |
The eqn utility, a preprocessor for troff, was originally written by |
The eqn utility, a preprocessor for troff, was originally written by |
Brian W. Kernighan and Lorinda L. Cherry in 1975. |
Brian W. Kernighan and Lorinda L. Cherry in 1975. |
The GNU reimplementation of eqn, part of the GNU troff package, was |
The GNU reimplementation of eqn, part of the GNU troff package, was |
released in 1989 by James Clark. |
released in 1989 by James Clark. |
Line 205 was added in 2011. |
|
Line 504 was added in 2011. |
|
This |
This |
.Nm |
.Nm |
reference was written by |
reference was written by |
.An Kristaps Dzonsons Aq kristaps@bsd.lv . |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . |