Groff by example: equations with eqn

groff is an established document processing system, most popular on Unix and Unix-like systems. Originally implemented as roff (short for run off) on the original Unix 1st Edition at Bell Labs, the program was updated to nroff (new roff) in Unix 2nd Edition and later as troff (typesetter roff) after Bell Labs purchased a phototypesetter. In 1990, the GNU project released a compatible version called groff (GNU roff) which is the most common implementation today.

While nroff and troff were created for text documents such as patent applications, articles, books, and memos, the system is extensible using preprocessors that generate output suitable for troff. In 1975, Lorinda Cherry and Brian Kernighan introduced the eqn preprocessor which recognizes special instructions to format math and equations within documents. The eqn program is implemented as geqn in GNU groff, but is available on most systems as just eqn.

Learning how to enter equations may seem difficult due to the flexibility within eqn. To get you started, we have shared this sample groff -me document that you can use as a quick-reference guide of the most common equation formatting:

.\" macros to show verbatim text using font 6 (courier)
.de (V
.ft 6
.ps -1
..
.de )V
.ft
.ps
..
.lp
To write equations in a
.b groff
document, you need to use the
.b eqn
preprocessor. This program interprets any instructions between
.(V
\&.EQ
.)V
and
.(V
\&.EN
.)V
in a source file, and inserts the typesetter markup to generate
the equation.
.pp
The
.b eqn
syntax mimics how real people might read an equation out loud,
using keywords to indicate how to display the equation.
For example, to indicate a superscript, write
.(V
sup
.)V
followed by the superscript value.
.EQ
A = pi r sup 2
.EN
.pp
Or
.(V
sub
.)V
to indicate a subscript value:
.EQ
x sub 0 = 0
.EN
.pp
You can indicate sums, square roots, and other symbols with
similar keywords, like this:
.EQ
x(t) = x sub 0 + v sub 0 t + 1 over 2 a t sup 2
.EN
.pp
If you need to group elements in an equation, use
.(V
{
.)V
and
.(V
}
.)V
.q "curly braces"
around the terms that need to go together. For example:
.EQ
t = sqrt{ {2x} over a }
.EN
.pp
Use the
.(V
from
.)V
and
.(V
to
.)V
keywords for equations that use sums or integrals:
.EQ
sum from {n=1} to {10} n = 55
.EN
.pp
To write equations inline with your paragraph text, you need to
specify a pair of delimeters. For example, using
.(V
delim $$
.)V
will recognize the first
.(V
$
.)V
as the start of an inline equation, terminated with another
.(V
$
.)V
character.
You can also set different delimeters for the start and end of
an inline equation.
.EQ
delim $%
.EN
This allows you to write simple math statements like $n = 1% and
$A = pi r sup 2% in the body of a paragraph.
.pp
.b eqn
also recognizes Greek symbols as keywords, such as these:
.EQ
alpha beta gamma delta ... Alpha Beta Gamma Delta
.EN
.pp
Engineers and scientists can also use combinations of characters
like
.EQ
delim $$
.EN
$a bar <= 0$ and $b bar >= 2$ and $pi approx 3.141$ and
$t = 1.2 +- 0.1$ and $x -> 0$ and $z != 0$
to represent special symbols.
Or use these keywords for other symbols:
.EQ
inf partial half prime approx nothing cdot times del grad
sum int prod union inter
.EN
.pp
Certain function names are automatically recognized and entered in
.q roman
style:
.EQ
sin theta ... cos theta ... tan theta ...
sinh x ... cosh x ... tanh x
.EN

Save this source file as math.me and run this command to turn it into a printable PostScript document:

$ groff -e -Tps -me math.me > math.ps

For more information about how to use eqn to create equations, refer to the eqn(1) manual page on your system. The GNU website also has a GNU Troff Manual that includes some information about eqn. O'Reilly Media has an excellent chapter about Typesetting Equations with eqn, from Unix Text Processing. (This book is no longer in print, but is available for free via the O'Reilly website.)