roff - concepts and history of roff typesetting
is the general name for a set of text formatting programs, known
under names like troff
etc. A roff
system consists of an extensible text formatting language
and a set of programs for printing and converting to other text formats.
Unix-like operating systems distribute a roff
system as a core package.
The most common roff
system today is the free software implementation GNU
implements the look-and-feel and
functionality of its ancestors, with many extensions.
The ancestry of roff
is described in section HISTORY
. In this
document, the term roff
always refers to the general class of roff
programs, not to the roff
command provided in early UNIX systems.
In spite of its age, roff
is in wide use today, for example, the manual
pages on UNIX systems (man pages
), many software books, system
documentation, standards, and corporate documents are written in roff. The
output for text devices is still unmatched, and its graphical
output has the same quality as other free type-setting programs and is better
than some of the commercial systems.
is used to format UNIX manual pages
, (or man pages
the standard documentation system on many UNIX-derived operating systems.
This document describes the history of the development of the roff
; some usage aspects common to all roff
versions, details on
pipeline, which is usually hidden behind front-ends like
; a general overview of the formatting language; some tips for
files; and many pointers to further readings.
Document formatting by computer dates back to the 1960s. The roff
itself is intimately connected to the Unix operating system, but its roots go
back to the earlier operating systems CTSS and Multics.
The Predecessor RUNOFF¶
's ancestor RUNOFF
was written in the MAD language by Jerry
for the Compatible Time Sharing System (CTSS)
, a project of
the Massachusetts Institute of Technology (MIT), in 1963 and 1964 –
note that CTSS commands were all uppercase.
In 1965, MIT's Project MAC teamed with Bell Telephone Laboratories (BTL) and
General Electric to begin the
A command called runoff
was written for Multics in the late
60s in the BCPL language, by Bob Morris
, Doug McIlroy
, and other
members of the Multics team.
Like its CTSS ancestor, Multics runoff
formatted an input file consisting
of text and command lines; commands began with a period and were two letters.
Output from these commands was to terminal devices such as IBM Selectric
terminals. Multics runoff
had additional features added, such as the
ability to do two-pass formatting; it became the main format for Multics
documentation and text processing.
BCPL and runoff
were ported to the GCOS system at Bell Labs when BTL left
the development of Multics.
The Classical nroff/troff System¶
At BTL, there was a need to drive the Graphic Systems CAT
graphical output device from a PDP-11 computer running Unix. As runoff
was too limited for this task it was further developed into a more powerful
text formatting system by Joseph F. Ossanna
, who already programmed
several runoff ports.
The name runoff
was shortened to roff
. The greatly enlarged
language of Ossanna's version already included all elements of a full roff
. All modern roff
systems try to implement compatibility to
this system. So Joe Ossanna can be called the father of all roff
This first roff system
had three formatter programs.
- (typesetter roff) generated a graphical output for the CAT
typesetter as its only device.
- produced text output suitable for terminals and line printers.
- was the reimplementation of the former runoff program with its
limited features; this program was abandoned in later versions. Today, the
name roff is used to refer to a troff/nroff system as a
Ossanna's first version was written in the PDP-11 assembly language and released
in 1973. Brian Kernighan
joined the roff
rewriting it in the C programming language. The C version was
released in 1975.
The syntax of the formatting language of the nroff
was documented in the famous Troff User's Manual [CSTR #54]
first published in 1976, with further revisions up to 1992 by Brian Kernighan.
This document is the specification of the classical troff
. All later
systems tried to establish compatibility with this specification.
After Ossanna's death in 1977, Kernighan went on with developing troff
In the late 1970s, Kernighan equipped troff
with a general interface to
support more devices, the intermediate output format, and the postprocessor
system. This completed the structure of a roff system
as it is still in
use today; see section USING ROFF
. In 1979, these novelties were
described in the paper [CSTR #97]
. This new troff
is the basis for all existing newer troff systems, including groff
some systems, this device independent troff
got a binary of its own,
. All modern troff
programs already provide the
The source code of both the ancient Unix and classical troff
available for two decades. Meanwhile, it is accessible again (on-line) for
non-commercial use, cf. section SEE ALSO
The most important free roff
project was the GNU implementation of
, written from scratch by James Clark
and put under the
It was called groff
). See groff(1)
for an overview.
system is still actively developed. It is compatible to the
, but many extensions were added. It is the first
system that is available on almost all operating systems –
and it is free. This makes groff
the de-facto roff
An alternative is Gunnar Ritter
project, started in 2005, which provides enhanced versions of the
various roff tools found in the OpenSolaris and Plan 9 operating
systems, now available under free licenses.
Most people won't even notice that they are actually using roff
. When you
read a system manual page (man page) roff
is working in the background.
documents can be viewed with a native viewer called
(1x), a standard program of the X window distribution, see
(7x). But using roff
explicitly isn't difficult either.
implementations provide wrapper programs that make it easy to
use the roff
system on the shell command line. For example, the GNU
provides command line options to
avoid the long command pipes of classical troff
; a program
tries to guess from the document which arguments should be used
for a run of groff
; people who do not like specifying command line
options should try the groffer(1)
program for graphically displaying
files and man pages.
The roff Pipe¶
system consists of preprocessors, roff
programs, and a set of device postprocessors. This concept makes heavy use of
mechanism, that is, a series of programs is called one after
the other, where the output of each program in the queue is taken as the input
for the next program.
| ... | preproc
| ... | troff options
The preprocessors generate roff
code that is fed into a roff
formatter (e.g. troff
), which in turn generates intermediate
that is fed into a device postprocessor program for printing or
All of these parts use programming languages of their own; each language is
totally unrelated to the other parts. Moreover, roff
that were tailored for special purposes can be included.
documents use the macros of some package, intermixed with code
for one or more preprocessors, spiced with some elements from the plain
language. The full power of the roff
formatting language is
seldom needed by users; only programmers of macro packages need to know about
the gory details.
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
classical preprocessors are
||for mathematical formulæ.
||for drawing diagrams.
||for bibliographic references.
||for including macro files from standard locations.
||for drawing chemical formulæ.
Other known preprocessors that are not available on all systems include
||for constructing graphical elements.
||for including gremlin(1) pictures.
A roff formatter
is a program that parses documents written in the
formatting language or uses some of the roff
packages. It generates intermediate output
, which is intended to be fed
into a single device postprocessor that must be specified by a command-line
option to the formatter program. The documents must have been run through all
necessary preprocessors before.
The output produced by a roff
formatter is represented in yet another
language, the intermediate output format
or troff output
language was first specified in [CSTR #97]
; its GNU extension is
documented in groff_out(5)
. The intermediate output language is a kind
of assembly language compared to the high-level roff
generated intermediate output is optimized for a special device, but the
language is the same for every device.
formatter is the heart of the roff
had two formatters, nroff
for text devices and
for graphical devices.
Often, the name troff
is used as a general term to refer to both
Devices and Postprocessors¶
Devices are hardware interfaces like printers, text or graphical terminals,
etc., or software interfaces such as a conversion into a different text or
postprocessor is a program that transforms troff
into a form suitable for a special device. The roff
like device drivers for the output target.
For each device there is a postprocessor program that fits the device optimally.
The postprocessor parses the generated intermediate output and generates
device-specific code that is sent directly to the device.
The names of the devices and the postprocessor programs are not fixed because
they greatly depend on the software and hardware abilities of the actual
computer. For example, the classical devices mentioned in
have greatly changed since the classical times. The
old hardware doesn't exist any longer and the old graphical conversions were
quite imprecise when compared to their modern counterparts.
For example, the Postscript device post
in classical troff
resolution of 720 units per inch, while groff
72000, a refinement of factor 100.
Today the operating systems provide device drivers for most printer-like
hardware, so it isn't necessary to write a special hardware postprocessor for
Documents using roff
are normal text files decorated by roff
formatting elements. The roff
formatting language is quite powerful; it
is almost a full programming language and provides elements to enlarge the
language. With these, it became possible to develop macro packages that are
tailored for special applications. Such macro packages are much handier than
. So most people will choose a macro package without worrying
about the internals of the roff
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
. The macro definitions of a package are kept in a file called
). All tmac files
are stored in one or more directories at standardized positions. Details on
the naming of macro packages and their placement is found in
A macro package that is to be used in a document can be announced to the
formatter by the command line option -m
, see troff(1)
, or it can
be specified within a document using the file inclusion requests of the
language, see groff(7)
Famous classical macro packages are man
for traditional man pages,
for BSD-style manual pages; the macro sets for books, articles,
and letters are me
(probably from the first name of its creator
(from Manuscript Macros
), and mm
(from Memorandum Macros
The roff Formatting Language¶
The classical roff
formatting language is documented in the Troff
User's Manual [CSTR #54]
. The roff
language is a full
programming language providing requests, definition of macros, escape
sequences, string variables, number or size registers, and flow controls.
are the predefined basic formatting commands similar to the
commands at the shell prompt. The user can define request-like elements using
elements. These are then called macros
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.
elements starting with a backslash They
can be inserted anywhere, also in the midst of text in a line. They are used
to implement various features, including the insertion of non-ASCII characters
with font changes with in-line comments with the escaping of special control
characters like and many other features.
are variables that can store a string. A string is stored by the
request. The stored string can be retrieved later by the \*
store numbers and sizes. A register can be set with the request
and its value can be retrieved by the escape sequence \n
FILE NAME EXTENSIONS¶
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.
for a document using the me
But there is no general naming scheme for roff
for troff file
is seen now and then. Maybe there
should be a standardization for the filename extensions of roff
File name extensions can be very handy in conjunction with the less(1)
pager. It provides the possibility to feed all input into a command-line pipe
that is specified in the shell environment variable LESSOPEN
process is not well documented, so here an example:
is either a system supplied command or a shell script of
The best program for editing a roff
document is Emacs (or Xemacs), see
. It provides an nroff
mode that is suitable for all
kinds of roff
dialects. This mode can be activated by the following
When editing a file within Emacs the mode can be changed by typing `M-x
', where M-x
means to hold down the Meta
) and hitting the x
key at the same time.
But it is also possible to have the mode automatically selected when the file is
loaded into the editor.
- The most general method is to include the following 3 comment lines at the
end of the file.
.\" Local Variables:
.\" mode: nroff
- There is a set of file name extensions, e.g. the man pages that trigger
the automatic activation of the nroff mode.
- Theoretically, it is possible to write the sequence
- as the first line of a file to have it started in nroff mode when
loaded. Unfortunately, some applications such as the man program
are confused by this; so this is deprecated.
formatters provide automated line breaks and horizontal and
vertical spacing. In order to not disturb this, the following tips can be
- Never include empty or blank lines in a roff document. Instead, use
the empty request (a line consisting of a dot only) or a line comment
.\" if a structuring element is needed.
- Never start a line with whitespace because this can lead to unexpected
behavior. Indented paragraphs can be constructed in a controlled way by
- Start each sentence on a line of its own, for the spacing after a dot is
handled differently depending on whether it terminates an abbreviation or
a sentence. To distinguish both cases, do a line break after each
- To additionally use the auto-fill mode in Emacs, it is best to insert an
empty roff request (a line consisting of a dot only) after each
The following example shows how optimal roff
editing could look.
This is an example for a
This is the next sentence in the same paragraph.
This is a longer sentence stretching over several
lines; abbreviations like `cf.' are easily
identified because the dot is not followed by a
In the output, this will still go to the same
Besides Emacs, some other editors provide nroff
style files too, e.g.
, an extension of the vi(1)
There is a lot of documentation on roff
. The original papers on classical
are still available, and all aspects of groff
documented in great detail.
The historical troff
provides an overview and pointers to all historical aspects of
The Multics site
contains a lot of information on the MIT projects, CTSS, Multics, early Unix,
; especially useful are a glossary and the many links
to ancient documents.
The Ancient Unixes
- Unix Archive
provides the source code and some binaries of the ancient Unixes
(including the source code of troff
and its documentation) that were
made public by Caldera since 2001, e.g. of the famous Unix version 7
for PDP-11 at the
Bell Labs Computing
and Mathematical Sciences Research
- Developers at AT&T Bell Labs
provides a search facility for tracking
information on the early developers.
The Plan 9
- Plan 9
by AT&T Bell Labs.
Saltzer's home page
stores some documents using the ancient RUNOFF
Labs CSTR site
- CSTR Papers
stores the original troff
manuals (CSTR #54, #97,
#114, #116, #122) and famous historical documents on programming.
The groff web
- GNU roff
provides the free roff
, the actual
Historical roff Documentation¶
Many classical troff
documents are still available on-line. The two main
manuals of the troff
- [CSTR #54]
- J. F. Ossanna,
Bell Labs, 1976; revised by Brian Kernighan, 1992.
- [CSTR #97]
- Brian Kernighan,
Bell Labs, 1981, revised March 1982.
The “little language” roff
– A Language for Typesetting Graphs
- [CSTR #114]
- Jon L. Bentley and Brian W. Kernighan,
Bell Labs, August 1984.
– A Graphics Language for Typesetting
- [CSTR #116]
- Brian W. Kernighan,
Bell Labs, December 1984.
– A Program for Typesetting Chemical Structure Diagrams,
Computers and Chemistry
- [CSTR #122]
- J. L. Bentley, L. W. Jelinski, and B. W. Kernighan,
Bell Labs, April 1986.
Due to its complex structure, a full roff
system has many man pages, each
describing a single aspect of roff
. Unfortunately, there is no general
naming scheme for the documentation among the different roff
, the man page groff(1)
contains a survey of all
documentation available in groff
On other systems, you are on your own, but troff(1)
might be a good
Copyright (C) 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009 Free Software
This document is distributed under the terms of the FDL (GNU Free Documentation
License) version 1.3 or later. You should have received a copy of the FDL on
your system, it is also available on-line at the
This document is part of groff
, the GNU roff
distribution. It was
it is maintained by