Many people use roff frequently without knowing it. When you
read a system manual page (man page), it is often a roff working
in the background to render it. But using a roff explicitly
isn't difficult.
Some roff implementations provide wrapper programs that make it
easy to use the roff system from the shell's command line. These
can be specific to a macro package, like mmroff(1), or more
general. groff(1) provides command-line options sparing the user
from constructing the long, order-dependent pipelines familiar to
AT&T troff users. Further, a heuristic program, grog(1), is
available to infer from a document's contents which groff
arguments should be used to process it.
The roff pipeline
Each roff system consists of preprocessors, one or more roff
formatter programs, and a set of output drivers (or 'device
postprocessors'). This arrangement is designed to take advantage
of a landmark Unix innovation in inter-process communication: the
pipe. That is, a series of programs termed a 'pipeline' is
called together where the output of each program in the sequence
is taken as the input for the next program, without (necessarily)
passing through temporary files on a disk. (On non-Unix systems,
pipelines may have to be simulated.)
$ preproc1 < input-file | preproc2 | ... | troff [option ...] \
| output-driver
One all preprocessors have run, they deliver a pure roff document
to the formatter, which in turn generates intermediate output
that is fed into an output driver for viewing, printing, or
further processing.
All of these parts use programming languages of their own; each
language is totally unrelated to the other parts. Moreover, roff
macro packages that are tailored for special purposes can be
included.
Most roff input files use the macros of a document formatting
package, intermixed with instructions for one or more
preprocessors, seasoned with escape sequences and requests
directly from the roff language. Some documents are simpler
still, since their formatting packages discourage direct use of
roff requests; man pages are a prominent example. The full power
of the roff formatting language is seldom needed by users; only
programmers of macro packages need a substantial command of it.
Preprocessors
A roff preprocessor is any program that generates output that
syntactically obeys the rules of the roff formatting language.
Each preprocessor defines a language of its own that is
translated into roff code when run through the preprocessor
program. Parts written in these languages may be included within
a roff document; they are identified by special roff requests or
macros. Each document that is enhanced by preprocessor code must
be run through all corresponding preprocessors before it is fed
into the actual roff formatter program, for the formatter just
ignores all alien code. The preprocessor programs extract and
transform only the document parts that are determined for them.
There are a lot of free and commercial roff preprocessors. Some
of them aren't available on each system, but there is a small set
of preprocessors that are considered as an integral part of each
roff system. The classical preprocessors are
tbl for tables.
eqn for mathematical formulae.
pic for drawing diagrams.
refer for bibliographic references.
soelim for including macro files from standard locations.
chem for drawing chemical formulæ.
Other known preprocessors that are not available on all systems
include
grap for constructing graphical elements.
grn for including gremlin(1) pictures.
Formatter programs
In the context of roff systems, the formatter is the program that
parses documents written in the roff language. It generates
intermediate output, which is intended to be fed into an output
driver (also known as a device postprocessor), the identity of
which must be known prior to processing. The documents must
already have been run through all necessary preprocessors to
render correctly.
The output produced by a roff formatter is represented in another
language, termed the 'intermediate output format'. As noted in
section 'History' above, this language was first specified in
CSTR #97; GNU extensions to it are documented in groff_out(5).
Intermediate output is in specialized in its parameters, but not
its syntax, for the output driver used; the format is device-
independent, but not device-agnostic.
The formatter is the heart of the roff system. AT&T had two
formatters: nroff for terminals, and troff for typesetters.
Often, the name troff is used as a general term to refer to both
formatters. When speaking that generally, groff documentation
prefers the term 'roff'.
Devices and output drivers
To a roff system, a device is a hardware interface like a
printer, a text or graphical terminal, or a standardized file
format that unrelated software can interpret.
A roff output driver is a program that parses the device-
independent intermediate output format of troff and produces
instructions specific to the device or file format it supports.
The names of the devices and their driver programs are not
standardized. Technologies change; the devices used for document
preparation have greatly changed since CSTR #54 was first written
in the 1970s. Such hardware is no longer used in production
environments, and device capabilities (including resolution,
color drawing, and font repertoire) have tended to increase. The
PostScript output driver dpost(1) from an AT&T troff of 1980s
vintage had a resolution of 720 units per inch, whereas groff's
grops(1) uses 72 000.
roff
