man pages section 1: User Commands
Updated: July 2014

geqn (1)

Name

geqn - format equations for troff

Synopsis

geqn [ -rvCNR ] [ -dxy ] [ -Tname ] [ -Mdir ] [ -fF ]
[ -sn ] [ -pn ] [ -mn ] [ files... ]

It is possible to have whitespace  between  a  command  line
option and its parameter.

Description



User Commands                                             GEQN(1)

NAME
geqn - format equations for troff

SYNOPSIS
geqn [ -rvCNR ] [ -dxy ] [ -Tname ] [ -Mdir ] [ -fF ]
[ -sn ] [ -pn ] [ -mn ] [ files... ]

It is possible to have whitespace  between  a  command  line
option and its parameter.

DESCRIPTION
This  manual page describes the GNU version of eqn, which is
part of the groff document formatting system.  eqn  compiles
descriptions  of equations embedded within troff input files
into commands that are understood 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 input will be read.  A filename of - will cause
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/sparcv9/groff/site-tmac,     /usr/share/groff/site-
tmac,   and   finally   in   the  standard  macro  directory
/usr/share/groff/1.19.2/tmac.   If  it  exists,   eqn   will
process it before the other input files.  The -R option pre-
vents this.

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).

OPTIONS
-dxy Specify delimiters x and y for the left and right  end,
respectively,  of  in-line equations.  Any delim state-
ments in the source file overrides this.

-C   Recognize .EQ and .EN even when followed by a character
other than space or newline.

-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 will not reduce the
size of subscripts or superscripts to  a  smaller  size

Groff Version 1.19Last change: 20 February 2005                 1

User Commands                                             GEQN(1)

than n.

-Tname
The output is for device name.  The only effect of this
is to define a macro name with a value of 1.  Typically
eqnrc  will use this to provide definitions appropriate
for the output device.  The default  output  device  is
ps.

-Mdir
Search dir for eqnrc before the default directories.

-fF  This is equivalent to a gfont F command.

-sn  This  is  equivalent to a gsize n command.  This option
is deprecated.  eqn  will  normally  set  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  makes  sets  sub-
scripts and superscripts at 70% of the size of the sur-
rounding text.

USAGE
Only the differences  between  GNU  eqn  and  Unix  eqn  are
described here.

Most of the new features of GNU eqn 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.

Automatic spacing
eqn gives each component of an equation a type, and  adjusts
the  spacing  between  components using that type.  Possible
types are:

ordinary     an ordinary character such as 1' or x';

operator     a large operator  such  as  the  summation
operator;

binary       a binary operator such as +';

relation     a relation such as =';

opening      a opening bracket such as (';

Groff Version 1.19Last change: 20 February 2005                 2

User Commands                                             GEQN(1)

closing      a closing bracket such as )';

punctuation  a punctuation character such as ,';

inner        a subformula contained within brackets;

suppress     spacing  that suppresses automatic spacing

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 example, times is defined as

type "binary" \(mu

The name of the type doesn't have  to  be  quoted,  but
quoting protects from macro expansion.

chartype t text
Unquoted  groups  of characters are split up into indi-
vidual characters, 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
the Fonts subsection.

New primitives
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 corre-
sponds 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  charac-
ters  such  as +' and -' are centered; also it is the
vertical position used for the bar of  fractions.   For
example, sum is defined as

{ type "operator" vcenter size +5 \(*S }

Groff Version 1.19Last change: 20 February 2005                 3

User Commands                                             GEQN(1)

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  will
be moved down according if e1 is taller or shorter than
a lowercase letter.  For example, hat is defined as

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 will be moved down if e1 has a descender.
utilde is pre-defined 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  will  be  split  up  and  the  spacing
between individual characters will be adjusted.

nosplit text
This has the same effect as

"text"

but  because  text  is not quoted it will be subject to
macro expansion; text will not  be  split  up  and  the
spacing  between  individual  characters  will  not  be

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  will
be  tucked  under the prime as a subscript to the A (as
is conventional in mathematical  typesetting),  whereas
with prime the 1 will be a subscript to the prime char-
acter.  The precedence of opprime is the same  as  that
of  bar  and under, which is higher than that of every-
thing except accent and uaccent.  In unquoted text a  '
that  is  not  the first character will be treated like
opprime.

special text e
This constructs a new object from e using  a  gtroff(1)

Groff Version 1.19Last change: 20 February 2005                 4

User Commands                                             GEQN(1)

macro named text.  When the macro is called, the string
0s will contain the output for e, and the number regis-
ters  0w,  0h,  0d,  0skern, and 0skew will 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 will output the
desired result with its origin at  the  current  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 can-
cels' 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

Groff Version 1.19Last change: 20 February 2005                 5

User Commands                                             GEQN(1)

..

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 picture.

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 vertical spacing between  rows,  using  groff's  \x
escape.   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
The  appearance of equations is controlled by a large number
of parameters.  These 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 hundredths of an em unless  otherwise  stated.
These descriptions are intended to be expository rather
than definitive.

minimum_size
eqn will not set anything at a smaller  point-size
than this.  The value is in points.

fat_offset
The  fat  primitive emboldens an equation by over-
printing two copies of the  equation  horizontally

Groff Version 1.19Last change: 20 February 2005                 6

User Commands                                             GEQN(1)

offset by this amount.

over_hang
A fraction bar will be longer by twice this amount
than the maximum of the widths  of  the  numerator
and  denominator; in other words, it will overhang
the numerator and denominator  by  at  least  this
amount.

accent_width
When  bar  or under is applied to a single charac-
ter, the line will be 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  will 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 will 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.

Groff Version 1.19Last change: 20 February 2005                 7

User Commands                                             GEQN(1)

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 set to the thickness of the \(ru char-
acter, or the thickness of horizontal  lines  pro-
duced with the \D escape sequence.

num1 The over command will shift up the numerator by at
least this amount.

num2 The smallover command will shift up the  numerator
by at least this amount.

denom1
The  over  command will shift down the denominator
by at least this amount.

denom2
The smallover command will shift down the  denomi-
nator by at least this amount.

sup1 Normally  superscripts  will  be  shifted up by at
least this amount.

sup2 Superscripts within superscripts or  upper  limits
or  numerators  of  smallover  fractions  will  be
shifted up by at least this amount.  This is  usu-
ally less than sup1.

sup3 Superscripts  within  denominators or square roots
or subscripts or lower limits will be  shifted  up
by  at  least  this  amount.  This is usually less
than sup2.

sub1 Subscripts will normally be  shifted  down  by  at
least this amount.

sub2 When  there is both a subscript and a superscript,
the subscript will be shifted  down  by  at  least
this amount.

sup_drop
The baseline of a superscript will be no more than
this much amount below the top of  the  object  on

Groff Version 1.19Last change: 20 February 2005                 8

User Commands                                             GEQN(1)

which the superscript is set.

sub_drop
The  baseline of a subscript will be 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 will be 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 will be 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 will be 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 will be at least this
much below the bottom of the object on  which  the
limit is set.

big_op_spacing5
This  much  vertical space will be added above and
below limits.

baseline_sep
The baselines of the rows in a pile or matrix will
normally  be  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 bot-
tom  baseline  in a matrix or pile will be shifted
down by this much from the axis.   In  most  cases
this should be equal to axis_height.

column_sep
This much space will be added between columns in a
matrix.

matrix_side_sep
This much space will be added at each  side  of  a
matrix.

draw_lines
If this is non-zero, lines will be drawn using the

Groff Version 1.19Last change: 20 February 2005                 9

User Commands                                             GEQN(1)

\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 will be 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  will  be 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 will behave like
define and tdefine will be ignored, otherwise tde-
fine  will  behave like define and ndefine will be
ignored.  The default value is 0  (This  is  typi-
cally  changed  to  1  by  the  eqnrc file for the
ascii, latin1, utf8, and cp1047 devices.)

A more precise description of the role of many of these
parameters can be found in Appendix H of The TeXbook.

Macros
Macros  can  take arguments.  In a macro body, \$n where n is
between 1 and 9, will be replaced by the  n-th  argument  if
the  macro is called with arguments; if there are fewer than
n arguments, it will be replaced by nothing.   A  word  con-
taining a left parenthesis where the part of the word before
the left parenthesis has been defined using the define  com-
mand  will  be  recognized  as  a macro call with arguments;
characters following the left parenthesis up to  a  matching
right  parenthesis  will be treated as comma-separated argu-
ments; commas inside nested parentheses do not terminate  an
argument.

sdefine name X anything X
This  is  like the define command, but name will not be
recognized if called with arguments.

include "file"
copy "file"
Include the contents of file (include and copy are syn-
onyms).   Lines  of file beginning with .EQ or .EN will
be ignored.

ifdef name X anything X
If name has been defined by define (or has  been  auto-
matically  defined  because  name is the output device)

Groff Version 1.19Last change: 20 February 2005                10

User Commands                                             GEQN(1)

process anything; otherwise ignore anything.  X can  be
any character not appearing in anything.

undef name
Remove definition of name, making it undefined.

Besides  the  macros  mentioned above, the following defini-
tions are available: Alpha, Beta, ..., Omega  (this  is  the
same  as  ALPHA, BETA, ..., OMEGA), ldots (three dots on the
base line), and dollar.

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 existing gfont command 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.   There  is  also  a  new  gbfont command, which
changes the font used by the bold primitive.   If  you  only
use  the  roman, italic and bold primitives to changes fonts
within an equation, you can change all  the  fonts  used  by
your  equations  just by using gfont, grfont and gbfont com-
mands.

You can control which characters are treated as letters (and
therefore  set  in  italics)  by  using the chartype command
described above.  A type of letter will cause a character to
be set in italic type.  A type of digit will cause a charac-
ter to be set in roman type.

FILES
/usr/share/groff/1.19.2/tmac/eqnrc
Initialization file.

BUGS
Inline equations will be set at the point size that is  cur-
rent at the beginning of the input line.

ATTRIBUTES
See   attributes(5)   for   descriptions  of  the  following
attributes:

Groff Version 1.19Last change: 20 February 2005                11

User Commands                                             GEQN(1)

+---------------+-----------------------+
|ATTRIBUTE TYPE |   ATTRIBUTE VALUE     |
+---------------+-----------------------+
|Availability   | text/groff/groff-core |
+---------------+-----------------------+
|Stability      | Uncommitted           |
+---------------+-----------------------+
groff(1), gtroff(1), gpic(1), groff_font(5), The TeXbook

NOTES
This  software  was   built   from   source   available   at
https://java.net/projects/solaris-userland.    The  original
http://ftp.gnu.org/gnu/groff/groff-1.19.2.tar.gz

open source community  website  at  http://www.gnu.org/soft-
ware/groff/.

Groff Version 1.19Last change: 20 February 2005                12