|
Name | Synopsis | Description | Options | Files | MathML mode limitations | Bugs | See also | COLOPHON |
|
|
|
eqn(1) General Commands Manual eqn(1)
eqn - format equations for groff or MathML
eqn [-CNrR] [-d xy] [-f F] [-m n] [-M dir] [-p n] [-s n] [-T
name] [file ...]
eqn --help
eqn -v
eqn --version
The GNU implemenation of eqn is part of the document formatting
system. eqn is a preprocessor that translates descriptions of
equations embedded in input files into the language understood by
It copies the contents of each file to the standard output
stream, except that lines between .EQ and .EN (or “inline” within
a pair of user-specified delimiters) are interpreted as equation
descriptions. Normally, eqn is not executed directly by the
user, but invoked by specifying the -e option to While GNU eqn's
input syntax is highly compatible with AT&T eqn, the output eqn
produces cannot be processed by AT&T troff; GNU troff (or a troff
implementing relevant GNU extensions) must be used. If no file
operands are given on the command line, or if file is “-”, the
standard input stream is read.
Unless the -R option is given, eqn searches for the file eqnrc in
the directories given with the -M option first, then in /usr/
local/share/groff/site-tmac, and finally in the standard macro
directory /usr/local/share/groff/1.23.0/tmac. If it exists, eqn
processes it before the other input files.
This man page primarily discusses the differences between GNU eqn
and AT&T eqn. Most of the new features of the GNU eqn input
language are based on TeX. There are some references to the
differences between TeX and GNU eqn below; these may safely be
ignored if you do not know TeX.
Three points are worth special note.
• GNU eqn emits Presentation MathML output when invoked with the
“-T MathML” option.
• GNU eqn does not provide the functionality of neqn: it does not
support low-resolution, typewriter-like devices (although it
may work adequately for very simple input).
• GNU eqn sets the input token “...” as three periods or low
dots, rather than the three centered dots of AT&T eqn. To get
three centered dots, write cdots or “cdot cdot cdot”.
Automatic spacing
eqn imputes a type to each component of an equation, adjusting
the spacing between them accordingly. Recognized types are as
follows.
ordinary an ordinary character such as “1” or “x”
operator a large operator such as “Σ”
binary a binary operator such as “+”
relation a relation such as “=”
opening an opening bracket such as “(”
closing a closing bracket such as “)”
punctuation a punctuation character such as “,”
inner a sub-formula contained within brackets
suppress a type without automatic spacing adjustment
Two primitives apply types to equation components. Quote type
names in eqn commands to prevent macro expansion from being
attempted on their names.
type t e
Apply type t to expression e. For example, “times” is
defined as if by the following.
define times ' type "binary" \(mu '
chartype t text
Each (unquoted) character in text is assigned type t,
persistently. If t is “letter” or “digit”, chartype also
assigns a typeface to each character in text. See
subsection “Fonts” below. As an example, the default
spacing for some punctuation characters is set up as if by
the following eqn command.
chartype "punctuation" .,;:
Primitives
eqn supports without alteration the AT&T eqn primitives above,
back, bar, bold, define, down, fat, font, from, fwd, gfont,
gsize, italic, left, lineup, mark, matrix, ndefine, over, right,
roman, size, sqrt, sub, sup, tdefine, to, under, and up.
New primitives
big e Enlarges the expression it modifies; intended to have
semantics like CSS “large”. In troff output, the type
size is increased by 5. MathML output emits the
following.
<mstyle mathsize='big'>
e1 smallover e2
This is similar to over; smallover reduces the size of e1
and e2; it also puts less vertical space between e1 or e2
and the fraction bar. The over primitive corresponds to
the TeX \over primitive in display styles; smallover
corresponds to \over in non-display styles.
vcenter e
This vertically centers e about the math axis. The math
axis is the vertical position about which characters such
as “+” and “−” are centered; it is also the vertical
position used for fraction bars. For example, sum is
defined as follows.
{ type "operator" vcenter size +5 \(*S }
vcenter is silently ignored when generating MathML.
e1 accent e2
This sets e2 as an accent over e1. e2 is assumed to be at
the correct height for a lowercase letter; e2 is moved
down according to whether e1 is taller or shorter than a
lowercase letter. For example, hat is defined as follows.
accent { "^" }
dotdot, dot, tilde, vec, and dyad are also defined using
the accent primitive.
e1 uaccent e2
This sets e2 as an accent under e1. e2 is assumed to be
at the correct height for a character without a descender;
e2 is moved down if e1 has a descender. utilde is
predefined using uaccent as a tilde accent below the
baseline.
split "text"
This has the same effect as simply
text
but text is not subject to macro expansion because it is
quoted; text is split up and the spacing between
individual characters is adjusted.
nosplit text
This has the same effect as
"text"
but because text is not quoted it is subject to macro
expansion; text is not split up and the spacing between
individual characters is not adjusted.
e opprime
This is a variant of prime that acts as an operator on e.
It produces a different result from prime in a case such
as “A opprime sub 1”: with opprime the “1” is tucked under
the prime as a subscript to the “A” (as is conventional in
mathematical typesetting), whereas with prime the “1” is a
subscript to the prime character. The precedence of
opprime is the same as that of bar and under, which is
higher than that of everything except accent and uaccent.
In unquoted text, a neutral apostrophe (') that is not the
first character on the input line is treated like opprime.
special text e
Construct an object by calling the troff macro text on e.
The troff string 0s contains the eqn output for e, and the
registers 0w, 0h, 0d, 0skern, and 0skew the width, height,
depth, subscript kern, and skew of e, respectively. (The
subscript kern of an object indicates how much a subscript
on that object should be “tucked in”, or placed to the
left relative to a non-subscripted glyph of the same size.
The skew of an object is how far to the right of the
center of the object an accent over it should be placed.)
The macro must modify 0s so that it outputs the desired
result, returns the drawing position to the text baseline
at the beginning of e, and updates the foregoing registers
to correspond to the new dimensions of the result.
For example, suppose you wanted a construct that “cancels”
an expression by drawing a diagonal line through it.
.de Ca
. ds 0s \
\Z'\\*(0s'\
\v'\\n(0du'\
\D'l \\n(0wu -\\n(0hu-\\n(0du'\
\v'\\n(0hu'
..
.EQ
special Ca "x \[mi] 3 \[pl] x" ~ 3
.EN
We use the \[mi] and \[pl] special characters instead of +
and - because they are part of the argument to a troff
macro, so eqn does not transform them to mathematical
glyphs for us. Here's a more complicated construct that
draws a box around an expression; the bottom of the box
rests on the text baseline. We define the eqn macro box
to wrap the call of the troff macro Bx.
.de Bx
.ds 0s \
\Z'\\h'1n'\\*[0s]'\
\v'\\n(0du+1n'\
\D'l \\n(0wu+2n 0'\
\D'l 0 -\\n(0hu-\\n(0du-2n'\
\D'l -\\n(0wu-2n 0'\
\D'l 0 \\n(0hu+\\n(0du+2n'\
\h'\\n(0wu+2n'
.nr 0w +2n
.nr 0d +1n
.nr 0h +1n
..
.EQ
define box ' special Bx $1 '
box(foo) ~ "bar"
.EN
space n
Set extra vertical spacing around the equation, replacing
the default values, where n is an integer in hundredths of
an em. If positive, n increases vertical spacing before
the equation; if negative, it does so after the equation.
This primitive provides an interface to groff's \x escape
sequence, but with the opposite sign convention. It has
no effect if the equation is part of a picture.
Extended primitives
eqn recognizes an “on” argument to the delim primitive specially,
restoring any delimiters previously disabled with “delim off”.
If delimiters haven't been specified, neither command has effect.
col n { ... }
ccol n { ... }
lcol n { ... }
rcol n { ... }
pile n { ... }
cpile n { ... }
lpile n { ... }
rpile n { ... }
The integer value n (in hundredths of an em) increases the
vertical spacing between rows, using groff's \x escape
sequence (the value has no effect in MathML mode).
Negative values are possible but have no effect. If more
than one n occurs in a matrix, the largest is used.
Customization
When eqn generates troff input, the appearance of equations is
controlled by a large number of parameters. They have no effect
when generating MathML mode, which pushes typesetting and fine
motions downstream to a MathML rendering engine. These
parameters can be set using the set primitive.
set p n
This sets parameter p to value n, where n is an integer.
For example,
set x_height 45
says that eqn should assume an x height of 0.45 ems.
Possible parameters are as follows. Values are in units
of hundredths of an em unless otherwise stated. These
descriptions are intended to be expository rather than
definitive.
minimum_size
eqn won't set anything at a smaller type size than
this. The value is in points.
fat_offset
The fat primitive emboldens an equation by
overprinting two copies of the equation
horizontally offset by this amount. This parameter
is not used in MathML mode; fat text uses
<mstyle mathvariant='double-struck'>
instead.
over_hang
A fraction bar is longer by twice this amount than
the maximum of the widths of the numerator and
denominator; in other words, it overhangs the
numerator and denominator by at least this amount.
accent_width
When bar or under is applied to a single character,
the line is this long. Normally, bar or under
produces a line whose length is the width of the
object to which it applies; in the case of a single
character, this tends to produce a line that looks
too long.
delimiter_factor
Extensible delimiters produced with the left and
right primitives have a combined height and depth
of at least this many thousandths of twice the
maximum amount by which the sub-equation that the
delimiters enclose extends away from the axis.
delimiter_shortfall
Extensible delimiters produced with the left and
right primitives have a combined height and depth
not less than the difference of twice the maximum
amount by which the sub-equation that the
delimiters enclose extends away from the axis and
this amount.
null_delimiter_space
This much horizontal space is inserted on each side
of a fraction.
script_space
The width of subscripts and superscripts is
increased by this amount.
thin_space
This amount of space is automatically inserted
after punctuation characters.
medium_space
This amount of space is automatically inserted on
either side of binary operators.
thick_space
This amount of space is automatically inserted on
either side of relations.
x_height
The height of lowercase letters without ascenders
such as “x”.
axis_height
The height above the baseline of the center of
characters such as “+” and “−”. It is important
that this value is correct for the font you are
using.
default_rule_thickness
This should be set to the thickness of the \[ru]
character, or the thickness of horizontal lines
produced with the \D escape sequence.
num1 The over primitive shifts up the numerator by at
least this amount.
num2 The smallover primitive shifts up the numerator by
at least this amount.
denom1 The over primitive shifts down the denominator by
at least this amount.
denom2 The smallover primitive shifts down the denominator
by at least this amount.
sup1 Normally superscripts are shifted up by at least
this amount.
sup2 Superscripts within superscripts or upper limits or
numerators of smallover fractions are shifted up by
at least this amount. This is usually less than
sup1.
sup3 Superscripts within denominators or square roots or
subscripts or lower limits are shifted up by at
least this amount. This is usually less than sup2.
sub1 Subscripts are normally shifted down by at least
this amount.
sub2 When there is both a subscript and a superscript,
the subscript is shifted down by at least this
amount.
sup_drop
The baseline of a superscript is no more than this
much below the top of the object on which the
superscript is set.
sub_drop
The baseline of a subscript is at least this much
below the bottom of the object on which the
subscript is set.
big_op_spacing1
The baseline of an upper limit is at least this
much above the top of the object on which the limit
is set.
big_op_spacing2
The baseline of a lower limit is at least this much
below the bottom of the object on which the limit
is set.
big_op_spacing3
The bottom of an upper limit is at least this much
above the top of the object on which the limit is
set.
big_op_spacing4
The top of a lower limit is at least this much
below the bottom of the object on which the limit
is set.
big_op_spacing5
This much vertical space is added above and below
limits.
baseline_sep
The baselines of the rows in a pile or matrix are
normally this far apart. In most cases this should
be equal to the sum of num1 and denom1.
shift_down
The midpoint between the top baseline and the
bottom baseline in a matrix or pile is shifted down
by this much from the axis. In most cases this
should be equal to axis_height.
column_sep
This much space is added between columns in a
matrix.
matrix_side_sep
This much space is added at each side of a matrix.
draw_lines
If this is non-zero, lines are drawn using the \D
escape sequence, rather than with the \l escape
sequence and the \[ru] character.
body_height
The amount by which the height of the equation
exceeds this is added as extra space before the
line containing the equation (using \x). The
default value is 85.
body_depth
The amount by which the depth of the equation
exceeds this is added as extra space after the line
containing the equation (using \x). The default
value is 35.
nroff If this is non-zero, then ndefine behaves like
define and tdefine is ignored, otherwise tdefine
behaves like define and ndefine is ignored. The
default value is 0; the eqnrc file sets it to 1 for
the ascii, latin1, utf8, and cp1047 output devices.
Appendix H of The TeXbook discusses many of these
parameters in greater detail.
Macros
In GNU eqn, macros can take arguments. In a macro body, $n where
n is between 1 and 9, is replaced by the nth argument if the
macro is called with arguments; if there are fewer than
n arguments, it is replaced by nothing. A word containing a left
parenthesis where the part of the word before the left
parenthesis has been defined using the define primitive is
recognized as a macro call with arguments; characters following
the left parenthesis up to a matching right parenthesis are
treated as comma-separated arguments. Commas inside nested
parentheses do not terminate an argument. In the following
synopses, X can be any character not appearing in the parameter
thus bracketed.
sdefine name X anything X
This is like the define primitive, but name is not
recognized if called with arguments.
include file
copy file
Interpolate the contents of file. Lines in file beginning
with .EQ or .EN are ignored.
ifdef name X anything X
If name has been defined by define (or has been
automatically defined because name is the output driver)
process anything; otherwise ignore anything.
undef name
Remove definition of name, making it undefined.
Predefined macros
GNU eqn supports the predefined macros offered by AT&T eqn: and,
approx, arc, cos, cosh, del, det, dot, dotdot, dyad, exp, for,
grad, half, hat, if, inter, Im, inf, int, lim, ln, log, max, min,
nothing, partial, prime, prod, Re, sin, sinh, sum, tan, tanh,
tilde, times, union, vec, ==, !=, +=, ->, <-, <<, >>, and “...”.
The lowercase classical Greek letters are available as alpha,
beta, chi, delta, epsilon, eta, gamma, iota, kappa, lambda, mu,
nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta,
upsilon, xi, and zeta. Obtain their uppercase forms by spelling
these names with an initial capital letter or in full capitals,
as in Alpha or ALPHA.
GNU eqn further defines the macros cdot, cdots, and utilde (all
discussed above), dollar, which sets a dollar sign, and ldots,
which sets three dots on the baseline.
Fonts
eqn normally uses at least two fonts to set an equation: an
italic font for letters, and a roman font for everything else.
The AT&T eqn gfont primitive changes the font that is used as the
italic font. By default this is I. The font that is used as the
roman font can be changed using the new grfont command.
grfont f
Set the roman font to f.
The italic primitive uses the current italic font set by gfont;
the roman primitive uses the current roman font set by grfont.
GNU eqn offers a gbfont primitive, which changes the font used by
the bold primitive. If you use only the roman, italic and bold
primitives to change fonts within an equation, then gfont, grfont
and gbfont suffice to configure all the typefaces used by your
equations.
You can control which characters are treated as letters (and
therefore set in italics) by using the chartype primitive
described above. A type of letter causes a character to be set
in italic type. A type of digit causes a character to be set in
roman type.
--help displays a usage message, while -v and --version show
version information; all exit afterward.
-C Recognize .EQ and .EN even when followed by a character
other than space or newline.
-d xy Specify delimiters x and y for the left and right ends,
respectively, of inline equations. x and y need not be
distinct. Any delim xy statements in the source file
override this option.
-f F is equivalent to “gfont F”.
-m n Set the minimum type size to n points. eqn will not
reduce the size of sub- or superscripts beyond this size.
-M dir Search dir for eqnrc before those listed in section
“Description” above.
-N Prohibit newlines within delimiters. This option allows
eqn to recover better from missing closing delimiters.
-p n Set sub- and superscripts n points smaller than the
surrounding text. This option is deprecated. eqn
normally sets sub- and superscripts at 70% of the type
size of the surrounding text.
-r Reduce the type size of subscripts at most once relative
to the base type size for the equation.
-R Don't load eqnrc.
-s n This is equivalent to a “gsize n” command. This option is
deprecated. eqn normally sets equations at the type size
current when the equation is encountered.
-T name
Prepare output for the device name. In most cases, the
effect of this is to define a macro name with a value
of 1; eqnrc uses this to provide definitions appropriate
for the device. However, if the specified driver is
“MathML”, the output is MathML markup rather than troff
input, and eqnrc is not loaded at all. The default output
device is ps.
/usr/local/share/groff/1.23.0/tmac/eqnrc
Initialization file.
MathML is designed on the assumption that it cannot know the
exact physical characteristics of the media and devices on which
it will be rendered. It does not support fine control of motions
and sizes to the same degree troff does. Thus:
• eqn parameters have no effect on the generated MathML.
• The special, up, down, fwd, and back operations cannot be
implemented, and yield a MathML “<merror>” message instead.
• The vcenter keyword is silently ignored, as centering on the
math axis is the MathML default.
• Characters that eqn sets extra large in troff mode—notably the
integral sign—may appear too small and need to have their
“<mstyle>” wrappers adjusted by hand.
As in its troff mode, eqn in MathML mode leaves the .EQ and .EN
delimiters in place for displayed equations, but emits no
explicit delimiters around inline equations. They can, however,
be recognized as strings that begin with “<math>” and end with
“</math>” and do not cross line boundaries.
Words must be quoted anywhere they occur in eqn input if they are
not to be recognized as names of macros or primitives, or if they
are to be interpreted by troff. These names, particularly short
ones like “pi” and “PI”, can collide with troff identifiers. For
instance, the eqn command
gfont PI
does not select groff's Palatino italic font for the “global”
equation face; you must use
gfont "PI"
instead.
Inline equations are set at the type size that is current at the
beginning of the input line.
In MathML mode, the mark and lineup features don't work. These
could, in theory, be implemented with “<maligngroup>” elements.
In MathML mode, each digit of a numeric literal gets a separate
“<mn></mn>” pair, and decimal points are tagged with “<mo></mo>”.
This is allowed by the specification, but inefficient.
“Typesetting Mathematics—User's Guide” (2nd edition), by Brian W.
Kernighan and Lorinda L. Cherry, 1978, AT&T Bell Laboratories
Computing Science Technical Report No. 17.
The TeXbook, by Donald E. Knuth, 1984, Addison-Wesley
Professional.
particularly subsections “Logical symbols”, “Mathematical
symbols”, and “Greek glyphs”, documents a variety of special
character escape sequences useful in mathematical typesetting.
This page is part of the groff (GNU troff) project. Information
about the project can be found at
⟨http://www.gnu.org/software/groff/⟩. If you have a bug report
for this manual page, see ⟨http://www.gnu.org/software/groff/⟩.
This page was obtained from the project's upstream Git repository
⟨https://git.savannah.gnu.org/git/groff.git⟩ on 2022-12-17. (At
that time, the date of the most recent commit that was found in
the repository was 2022-12-14.) If you discover any rendering
problems in this HTML version of the page, or you believe there
is a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
groff 1.23.0.rc1.3569-94746-d1i4rtDyecember 2022 eqn(1)
|
HTML rendering created 2022-12-18 by Michael Kerrisk, author of The Linux Programming Interface, maintainer of the Linux man-pages project. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|