roff - a survey of the roff typesetting system
roff is the general name for a set of type-setting programs,
known under names like troff, nroff, groff, etc.
The roff type-setting system consists of a formatting language,
macro packages, preprocessors, postprocessors for
output devices, user front-end programs, and conversion
tools.
The most common roff system today is the free software
implementation groff (from `GNU roff'). The pre-groff
implementations are referred to as `classical' (dating
back as long as 1973).
groff is backward-compatible to its classical ancestors,
but has many extensions, and is still evolving. As it is
available for almost every computer system it is the defacto
roff standard today.
In spite of its age, roff is in wide use today, e.g., the
manual pages on UNIX systems (man-pages) are written in
roff. The roff output for text devices is still
unmatched, and its graphical output has the same quality
as the other free type-setting programs and is better than
some of the commercial systems.
This document gives only an overview and provides pointers
to further documentation.
This document is not maintained and might be out of date.
For the real documentation refer to the groff info file
that contains the detailed, actual and concise reference
information.
There are three terms that refer to the language of the
roff system. The term troff language is used when the
classical aspects of roff are stressed, the term groff
language includes the GNU extensions, whereas roff lan-
guage is the general term.
The main source of documentation for all aspects of the
groff language is the groff info file. The manual page
groff(7) gives a short description of all predefined language
elements.
Documents using roff are normal text files decorated by
formatting elements. It is very easy to write high-quality
documents by using one of the macro packages. These
are like high-level programming languages, while the bare
roff language compares to a low-level language like C or
assembler.
The roff language is a full programming language providing
low-level requests, definition of macros, escape
sequences, string variables, number or size registers, and
C-like flow controls.
Some clarification on the language elements seems to be
wanted. Requests are basic formatting commands defined by
programming languages like C, C++, etc., whereas macros
are formatting commands that are written in the roff language.
A document writer will not note any difference in
usage for requests or macros, both are written on a line
on their own starting with a dot `.'. But the user may
define her own macros if desired.
Escape sequences are in-line elements starting with a
backslash `\'. They are used to implement various features,
including the insertion of non-ASCII characters
with \(, the content of strings with \* and register variables
with \n, font changes with \f, in-line comments with
\", the escaping of special control characters like \\,
and many other features.
Formatters are the front-end programs that analyze a groff
document and translate it into a form that is suitable for
a special device. The traditional roff had two formatters,
nroff for text devices and troff for graphical
devices.
These programs still exist in the groff implementation,
but usually they are accessed through a program called
groff. This combined and extended the old functionality
into a single program. It has many command-line options,
most of them herited from troff. To ease the option jungle,
the user-friendly utility grog (from `groff guess')
was created. It tries to guess from the document which
arguments should be used and displays a suitable command
line. Though not being perfect, it is a good starting
point.
The classical preprocessors that are still available in
groff.
eqn for including mathematical equations.
grap for constructing graphical elements (this
preprocessor doesn't come with groff; it is
an extra package).
grn for including gremlin pictures.
pic for creating diagrams.
refer for bibliographic references.
soelim for including other roff files.
tbl for rectangular tables.
Each of these preprocessors defines its own language that
is translated into roff code when run through the preprocessor
program. So parts written in these languages may
be included within a roff document. Such an enhanced document
is run through one or more corresponding preprocessors
before it is fed into the actual formatter.
The preprocessor programs extract and transform the document
parts determined for them. They can be called either
in a UNIX pipeline with their program name or automatically
with a groff option.
+-------------+--------------+
|preprocessor | groff option |
+-------------+--------------+
| eqn | -e |
| grap | -G |
| grn | -g |
| pic | -p |
| refer | -R |
| tbl | -r |
| soelim | -s |
+-------------+--------------+
Macro packages are collections of macros that are suitable
to format a special kind of documents in a convenient way.
This greatly eases the usage of roff. The macro definitions
of a package are kept in a file called tmac.name
where name is the internal roff name for this package.
All tmac files are stored in a single or few directories
at standard positions.
A macro package that is used in a document is specified by
the command line option -m for the formatter like troff -m
name or groff -m name. General details on the naming of
macro packages and their placement is found in tmac(5).
Famous classical macro packages are man, mandoc, and mdoc
for manual pages and me, ms, and mm for books, articles,
and letters. Besides these collections, groff provides an
increasing number of new macro packages for various applications,
for example integration of or conversion into
other file formats.
Manual pages (man-pages) take the section number as a file
name extension, e.g., the filename for this document is
roff.7, i.e., it is kept in section 7 of the man-pages.
The classical macro packages take the package name as an
extension, e.g. file.me for a document using the me macro
package, file.mm for mm, file.ms for ms, file.pic for pic
files, etc.
Most text editors provide support for editing documents
using roff. Especially useful is the nroff-mode in all
flavors of the Emacs editor.
GROFF_TMAC_PATH
A colon separated list of directories in which to
search for macro files, see tmac(5).
GROFF_TYPESETTER [Toc] [Back]
Default device.
GROFF_FONT_PATH [Toc] [Back]
A colon separated list of directories in which to
search for the devname directory. troff will
search in directories given in the -F option before
these, and in standard directories
(.:/usr/local/share/groff/font:/usr/lib/font) after
these.
By default, groff installs all of its library files in a
directory tree under /usr/local/share/groff. This location
might vary for different systems. In the following,
this directory is referred to as <groff_dir>.
<groff_dir>/tmac/troffrc
Initialization file for troff.
<groff_dir>/tmac/tmac.name
Macro files.
<groff_dir>/font/devname/DESC
Device description file for device name.
<groff_dir>/font/devname/F
Font file for font F of device name.
The groff documentation is in evolution at the moment. It
is possible that small inconsistencies between different
documents exist temporarily.
This document is part of groff, the GNU roff distribution.
It was written by Bernd Warken <[email protected]>.
It is distributed under the terms of the FDL (GNU Free
Documentation License) version 1.1 or later. You should
have received a copy of the FDL on your system, it is also
available on-line under
<http://www.gnu.org/copyleft/fdl.html>.
The main source of information is the groff info(1) file.
The predefined elements of the groff language are also
documented in the manual page groff(7).
Formatters and their wrappers: groff(1), grog(1),
nroff(1), and troff(1).
Postprocessors for the output devices: grodvi(1), gro-
html(1), grolbp(1), grolj4(1), grops(1), and grotty(1).
Standard preprocessors: eqn(1), grn(1), grap(1), pic(1),
refer(1), soelim(1), and tbl(1).
The man pages for macro packages include groff_tmac(5),
groff_man(7), groff_markup(7), groff_mdoc(7),
groff_mdoc.samples(7), groff_me(7), groff_mm(7),
groff_mmroff(7), groff_ms(7), and groff_msafer(7).
The following utilities are available: addftinfo(1), afm-
todif(1), hpftodit(1), indxbib(1), lookbib(1), pfbtops(1),
tfmtodit(1), and gxditview(1).
For details on the GNU implementation of the roff system
see groff_char(7), groff_font(7), groff_out(7), and the
file README in the main directory of the groff source distribution.
These also give details on how to contact or
join the groff developer group.
Many classical documents are still available on-line.
Especially informative are the original Bell Labs proceedings
for the old, free UNIX 7 found at http://cm.bell-
labs.com/cm/cs/cstr.html and the collection of the late
Richard S. Stevens at http://www.kohala.com/start/troff/.
Groff Version 1.16.1 April 8, 2001 ROFF(7)
[ Back ] |
