# eqn

## format equations for troff or MathML

## SYNOPSIS

eqn [-rvCNR] [-d xy] [-T name] [-M dir] [-f F] [-s n] [-p n] [-m n] [file ...]

## DESCRIPTION

This manual page describes the GNU version of eqn, which is part of the groff document formatting system. eqn compiles descriptions of equa‐ tions embedded within troff input files into commands that are under‐ stood by troff. Normally, it should be invoked using the -e option of groff. The syntax is quite compatible with Unix eqn. The output of GNU eqn cannot be processed with Unix troff; it must be processed with GNU troff. If no files are given on the command line, the standard in‐ put is read. A filename of - causes the standard input to be read. eqn searches for the file eqnrc in the directories given with the -M option first, then in /usr/lib/groff/site-tmac, /usr/share/groff/ site-tmac, and finally in the standard macro directory /usr/share/ groff/1.22.4/tmac. If it exists, eqn processes it before the other in‐ put files. The -R option prevents this. GNU eqn does not provide the functionality of neqn: it does not support low-resolution, typewriter-like devices (although it may work ade‐ quately for very simple input).

## OPTIONS

Whitespace is permitted between a command-line option and its argument. -dxy Specify delimiters x and y for the left and right end, respec‐ tively, of in-line equations. Any delim statements in the source file overrides this. -C Recognize .EQ and .EN even when followed by a character other than space or newline. Also, the statement ‘delim on’ is not handled specially. -N Don't allow newlines within delimiters. This option allows eqn to recover better from missing closing delimiters. -v Print the version number. -r Only one size reduction. -mn The minimum point-size is n. eqn does not reduce the size of subscripts or superscripts to a smaller size than n. -Tname The output is for device name. Normally, the only effect of this is to define a macro name with a value of 1; eqnrc uses this to provide definitions appropriate for the output device. However, if the specified device is “MathML”, the output is MathML markup rather than troff commands, and eqnrc is not loaded at all. The default output device is ps. -Mdir Search dir for eqnrc before the default directories. -R Don't load eqnrc. -fF This is equivalent to a gfont F command. -sn This is equivalent to a gsize n command. This option is depre‐ cated. eqn normally sets equations at whatever the current point size is when the equation is encountered. -pn This says that subscripts and superscripts should be n points smaller than the surrounding text. This option is deprecated. Normally eqn sets subscripts and superscripts at 70% of the size of the surrounding text.

## USAGE

Only the differences between GNU eqn and Unix eqn are described here.
GNU eqn emits Presentation MathML output when invoked with the
-T MathML option.
GNU eqn sets the input token "..." as three periods or low dots,
rather than the three centered dots of classic eqn. To get three cen‐
tered dots, write cdots or cdot cdot cdot.
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.
Controlling delimiters
If not in compatibility mode, eqn recognizes
delim on
to restore the delimiters which have been previously disabled with a
call to ‘delim off’. If delimiters haven't been specified, the call
has no effect.
Automatic spacing
eqn gives each component of an equation a type, and adjusts the spacing
between components using that type. Possible types are described in
the table below.
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 a opening bracket such as ‘(’
closing a closing bracket such as ‘)’
punctuation a punctuation character such as ‘,’
inner a subformula contained within brackets
suppress a type that suppresses automatic spacing adjustment
Components of an equation get a type in one of two ways.
type t e
This yields an equation component that contains e but that has
type t, where t is one of the types mentioned above. For exam‐
ple, times is defined as
type "binary" \(mu
The name of the type doesn't have to be quoted, but quoting pro‐
tects from macro expansion.
chartype t text
Unquoted groups of characters are split up into individual char‐
acters, and the type of each character is looked up; this
changes the type that is stored for each character; it says that
the characters in text from now on have type t. For example,
chartype "punctuation" .,;:
would make the characters ‘.,;:’ have type punctuation whenever
they subsequently appeared in an equation. The type t can also
be letter or digit; in these cases chartype changes the font
type of the characters. See subsection “Fonts” below.
New primitives
big e Enlarges the expression it modifies; intended to have semantics
like CSS ‘large’. In troff output, the point size is increased
by 5; in MathML output, the expression uses
**troff(1)** macro named
text. When the macro is called, the string 0s contains the out‐
put for e, and the number registers 0w, 0h, 0d, 0skern, and
0skew contain the width, height, depth, subscript kern, and skew
of e. (The subscript kern of an object says how much a sub‐
script on that object should be tucked in; the skew of an object
says how far to the right of the center of the object an accent
over the object should be placed.) The macro must modify 0s so
that it outputs the desired result with its origin at the cur‐
rent point, and increase the current horizontal position by the
width of the object. The number registers must also be modified
so that they correspond to the result.
For example, suppose you wanted a construct that ‘cancels’ an
expression by drawing a diagonal line through it.
.EQ
define cancel 'special Ca'
.EN
.de Ca
. ds 0s \
\Z'\\*(0s'\
\v'\\n(0du'\
\D'l \\n(0wu -\\n(0hu-\\n(0du'\
\v'\\n(0hu'
..
Then you could cancel an expression e with cancel { e }
Here's a more complicated construct that draws a box round an
expression:
.EQ
define box 'special Bx'
.EN
.de Bx
. ds 0s \
\Z'\h'1n'\\*(0s'\
\Z'\
\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
..
space n
A positive value of the integer n (in hundredths of an em) sets
the vertical spacing before the equation, a negative value sets
the spacing after the equation, replacing the default values.
This primitive provides an interface to groff's \x escape (but
with opposite sign).
This keyword has no effect if the equation is part of a pic pic‐
ture.
Extended primitives
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 ver‐
tical spacing between rows, using groff's \x escape (the value
has no effect in MathML mode). Negative values are possible but
have no effect. If there is more than a single value given in a
matrix, the biggest one is used.
Customization
When eqn is generating troff markup, 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 down‐
stream to a MathML rendering engine. These parameters can be set using
the set command.
set p n
This sets parameter p to value n; 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 hun‐
dredths of an em unless otherwise stated. These descriptions
are intended to be expository rather than definitive.
minimum_size
eqn doesn't set anything at a smaller point-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; in‐
stead, fat text uses

## FILES

/usr/share/groff/1.22.4/tmac/eqnrc Initialization file.

## MATHML MODE LIMITATIONS

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 imple‐
mented, and yield a MathML ‘

## BUGS

Inline equations are set at the point size that is current at the be‐
ginning of the input line.
In MathML mode, the mark and lineup features don't work. These could,
in theory, be implemented with ‘