Troff, nroff, groffan overview

Jrgen Grahn <jgrahn@algonet.se>

ABSTRACT
TROFF is a language for typesetting text, available since the
early 1970s in many similarly-named variants and implementations. Today it is mostly known as the language in which
Unix manual pages are written.

This papers ambition is to inspire individuals wanting to

learn TROFF, to provide pointers to the scattered pieces of documentation, tutorials and other information available. Also, to
give advice on how to achieve good typography with TROFF.

March, 2003

Troff, nroff, groffan overview

Jrgen Grahn <jgrahn@algonet.se>
It is clear that TROFF ought to be replaced by something better,
but, as I said above, it is far from clear how to do the job a lot
better. So for better or worse, TROFF is likely to be with us for a
long while.
Brian W. Kernighan: A Typesetter-independent
TROFF (revised March, 1982)
1. On the maturity of this paper
Most of the investigations behind this overview took place in December,
2002. At that time I was not yet subscribed to the groff mailing list, and
focused on mostly two sources of information: the historical AT&T
papers, and my groff 1.17.2 installation.
Since I suspect I wont make any more major rewrites, I would like to
point out a few things here:
The groff documentation is a better source of information than I
assumedespecially if you take into account the changes since the 1.17
series, which dates back to 2001.
Coming from a LaTeX background, I may have overestimated the portability of troff source code between implementations, and the benefits of
trying to maintain such portability. Implementations are different, and
what they have in common is a rather small and poorly defined subset of
their functionality.
2. Rationale
I assume I dont have to argue in favor of text-based document preparation
systemsas opposed to WYSIWYG word processorsin general. The convenience of being able to process the text with ones usual toolsthe text
editor, the revision control system, creating and accepting patches, collaborating on a single documentspeaks for itself.
There are many systems similar to TROFF in that they start with a plaintext description of the finished document, which is generated (typeset)
from the text using a set of tools. TeXincluding LaTeXis the best
known and most widely used (if we disregard HTML and various XMLor SGML-based languages).
TeX admittedly has the advantage here: cleaner syntax, warnings and
error messages, a much larger and more active user base, hundreds of
extensions for different purposes, internationalization support, and so on.
Several books on TeX are available.
In contrast, TROFF is available by default in all Unix installations, and
can easily be installed under Win32 if needed. The installation is small
and needs little maintenance. TROFF is (in comparison with TeX) fast.
Since it uses Times and other normal PostScript fonts by default, typesetting to PostScript and PDF is easy. Typesetting to a terminal-like device is
likewise easy, if the document isnt too complicated.

-2-

Ben Collver <collver@linuxfreemail.com> puts it this way (speaking

about groff):
My personal attraction to groff has two parts. First, even though it isnt
in widespread use, its everywhere. Second, it formats great to both text
and graphic devices. Groff outputs ascii and postscript, and recent versions generate html [but do so poorly my comment].
3. History
The history of TROFF began in the mid-sixties with J. E. Saltzers runoff.
To justify the purchase of their PDP-11, the Unix group at Bell Labs
ported it as roff. This was done by J. F. Ossanna in or around 1971. More
refined versions, named nroff and troff, were successes and may have been
the main reason for Unix usage within AT&T in the mid-seventies.
(I havent investigated this much. For more details, see the groff info
documentation or http://www.troff.org.)
Obviously, TROFF has been in continuous use since then, for example at
Berkeley, where Eric Allman wrote the me macro package which he later
used for the sendmail documentation. When D. E. Knuths TeX was
released (in the early eighties?) it probably took away a chunk of the market otherwise reserved for TROFF, i.e. the scientific reports and literature.
Still, TROFF is in use for typesetting computer literature; for example, the
late W. R. Stevens used it for all his books, and it is involved at least as an
intermediate format in many others, e.g. the Camel Book.
When the World Wide Web was first conceived, the proposed markup
language was troff-inspired, before everyone settled for HTML.
GNU troff (groff) was, as far as I know, the first independent and freely
available port of TROFF. It exists for various operating systems and architectures since the early 1990s.
4. Basic TROFF
If you give TROFF a plain text file without embedded formatting commands, it will typeset it in Times over a number of pages using the default
page size. Empty lines will end up as empty lines in the output, while the
chunks of text between them are reformatted into paragraphs of the default
width. Inter-word spacing is adjusted and words are, if necessary, hyphenated to achieve an even right margin (filling).
TROFF

things are introduced into the text in two ways:

Requests
appear on lines of their own, with a . followed by one or two characters and (sometimes) arguments.
Escape sequences
appear in the text, and are introduced by a \.
Builtin TROFF commands such as .sp, and macros (user-defined or from a
macro package) such as .PP are accessed as requests. Escape sequences
are used to access builtin TROFF commands, special characters, string variables and register variables.
Macro packages provide higher-level commands and a common style:
cover pages, headings, paragraphs, page numbering, footnotes . . . The
most common ones are man for Unix man pages and ms for short technical reports, articles and papers.

-3-

Some things that can be expressed in TROFF but are too cumbersome to
type in are implemented as preprocessors for little languages. For
example, a table is implemented in the tbl language, bracketed in the
TROFF source by the .TS and .TE macros. The user is then responsible for
filtering the source through tbl(1) before typesetting it. tbl replaces the tbl
parts with TROFF source implementing the actual table, and the macro
package provides suitable definitions of the bracketing macros, possibly to
center the table or marking it as a float.
5. Sources of information
TROFF documentation is, unfortunately, scattered and patchy. A user is
practically helpless if all she has is the documentation that came with the
systemeven in the case of groff, which comes with a texinfo manual.

This is an attempt to trace the major sources still widely and freely
available.
5.1. UNIX Text Processing
The 1987 book UNIX Text Processing by Dougherty and OReilly is available for free download these days, and may be the best TROFF documentation available. The re-troffed versions from the UTP Revival Project are
probably the most manageable; see http://www.troff.org for details and
pointers.

5.2. AT&T documentation and reports

The original papers (in some instances dating as far back as 1974) by
Ossanna, Kernighan, Lesk and others are mostly available in PostScript as
the Bell Labs Computer Science Technical Reports (CSTR) series, or simply as tutorials and references.
They cover the core language, as well as various macro packages and
preprocessors.
These papers are generally very well written and easily understandable.
Many of them have been revised by Kernighan during the 1980s and early
1990s.
They are available today from at least two sources: the partial CSTR archive at
http://cm.bell-labs.com/cm/cs/cstr.html
or else from the late W. R. Stevenss home page
http://www.kohala.com/start/.
The problem with these is partially that they are old. TROFF was continuously updated at Bell Labs and elsewhere (e.g. at Berkeley) during this
time, along with the rest of Unix. As an example, features such as
hyphenation and ligatures are not documentednevertheless, they are
used in some of the papers.
5.3. The 4.3BSD documentation
The UNIX Users Supplementary Documents (USD) which came with
4.3BSD are still available. Quoting the introduction:
This volume contains documents which supplement the manual pages in
The Unix Users Reference Manual for the Virtual VAX-11 version of
the system as distributed by U.C. Berkeley, and Volumes 2a and 2b as

-4-

provided by Bell Laboratories.

USD includes many interesting things, among them several pieces of
TROFF-related documentation: variants of many of the AT&T papers and
other reports, references and tutorials having to do with development that
took place at Berkeley. Eric Allmans me papers are available here.
The instance Ive found is dated April, 1986 (i.e. earlier than many of
Kernighans revisions) and is available as TROFF source at
http://www.mit.edu/afs/athena/system/usrdoc/usd/ .
Its unclear to me if these documents appear in more recent versions elsewhere, and if they are part of BSD-derivatives such as FreeBSD.
5.4. The groff distribution
The GNU reimplementation of TROFF comes with lots of documentation,
as over forty man pages and a texinfo manual. The quality of this documentation is partly dubious. The manual aims to be the complete documentation of groff and its preprocessors and macro packages, but large
parts of it are still incomplete. The man pages vary in quality and detail
level. Some just point to classic troffs documentation, while others are
detailed request and escape references. Its often hard to see whats groff
extensions and whats not.
The groff distribution should be easy to find, mirrored at numerous
places. All Linux distributions include it, as does the Cygwin suite of
Unix tools ported to Microsoft Windows.
5.5. Other TROFF distributions
Any Unix system that comes with a TROFF implementation comes with
documentation, at least man pages. I have only been able to check one of
theseSolaris (SunOS 5.8). It contains mildly useful (although frequently more useful than the groff counterparts) man pages on the language, the macro packages and preprocessors. None of them can replace
the full-length documentation available elsewhere.
As explained above, TROFF has been under development at a minimum
of three places: Bell Labs, Berkeley and by the groff team. All three of
these efforts have generated partial documentation.
This poses several crucial questions: Have the various Unix vendors
developed TROFF further? Are all commercial implementations in current use (e.g. Suns) based on the Berkeley revisions? Are all current
implementations supersets of the Berkeley TROFF system?
5.6. Web sites, mailing lists, books . . .
As can be expected, there is a small number of personal web sites dedicated to TROFF or groff. They mostly point to each other and to the original papers and the groff documentation (both of which they sometimes
mirror), but they also provide a great deal of useful non-official information. Ill mention three:
http://www.troff.org
Ralph Corderoys extensive and recent site which, I have to admit,
makes much of this paper superfluous.
history of troff troff and its companion programs macro packages
papers on troff and its companions books covering troff and its
companions publications that use troff source code troff

-5-

community whos who in the world of troff links to troff-related

sites frequently asked questions acknowledgements and miscellaneous
http://tylx.tripod.com/groff-resources.html
Ben Collvers Online Groff Resources. About two dozen links. Mirrors
L. Kollars Using groff with the ms Macro Package.
http://www.kohala.com/start/
W. R. Stevenss web site, home of several of the original papers. Also
contains some stuff on his own experiences of using TROFF to typeset
large technical documents.
For real people discussing TROFF issues, see the groff mailing list and the
gnu.groff.bugs Usenet newsgroup.
Older, out-of-print books that at least partly cover TROFF seem to be
fairly plentiful; http://www.troff.org keeps a long list. UNIX Text Processing is described above.
6. An annotated bibliography
What follows is an overview of the documentation Ive found, sorted more
or less by topic. Manual pages mentioned below belong in the groff
1.17.2 distribution. The other documents are available from the web sites
cited above, unless otherwise noted.
6.1. Language tutorials and introductions
Dougherty & OReilly: UNIX Text Processing
The 1987 book centering on TROFF. Extremely complete, from what
Ive seen so far. Covers all possible of areas in great detail, with the
exception of the me macros. See above for its availability.
Kernighan: A TROFF tutorial (1978)
A walkthrough of TROFFs capabilities. Centers on low-level usage
without macro packages, and avoids the most advanced topics.
introduction point sizes; line spacing fonts and special characters
indents and line lengths tabs local motions: drawing lines and
characters strings introduction to macros titles, pages and
numbering number registers and arithmetic macros with arguments conditionals environments diversions
roff(7) a survey of the roff typesetting system
A good overview of groff and the TROFF language.
description formatting language formatters preprocessors
macro packages file name extensions editing environment
files . . .
Allman: Writing Papers with NROFF using me
See Macro packages below.
6.2. Language reference material
Ossanna & Kernighan: Troff Users Manual (CSTR 54)
The language reference, revised in 1992. Covers all requests, escapes,
registers . . . Terse and not very readable unless youve read A TROFF
tutorial.
groff(7) a short reference for the GNU roff language
Enumerates all requests and escapes known to groff. Discusses compatibility, but does not discern extensions and classic TROFF constructs.

-6-

description groff elements control characters numerical expressions conditions requests request short reference escape
sequences single character escapes special characters registers
(read-only, writable) warnings compatibility . . .
troff(1) format documents
Contains a long chapter describing groff extensions to the language.
groff_char(7) groff character names
Enumerates all characters known to groff, without mentioning which
ones are classic. References the 1989 report An extension to the troff
character set for Europe.
grops(1) PostScript driver for groff
Documents, among other things, which TROFF fonts are available when
groff is typesetting to PostScript. (The font lists for different output
devices are, by the way, very obvious in a groff installationlook in a
directory named /usr/share/groff/1.17.2/font/devps or similarly.)
Kernighan: A Typesetter-independent TROFF (CSTR 97)
Describes changes made to AT&T TROFF in 1979, including language
changes and additions having to do with fonts, graphics et cetera.
(These changes should be reflected in the users manual, since it was
revised later than this paper.)
6.3. Macro packages
Lesk: Typing Documents on the UNIX System: Using the ms macros
with Troff and Nroff
A fairly brief but seemingly complete ms tutorial and reference,
revised in 1978. The ms macros are, aside from the man macros, the
most widely used ones.
introduction text beginning cover sheets and first pages page
headings multi-column formats headings indented paragraphs
emphasis footnotes displays and tables boxing words or
lines keeping blocks together nroff/troff commands date signature line registers accents use references and further study
list of commands number registers used by ms string registers
used by ms order of commands in input
Tuthill: A Revised Version of ms
Describes fixes and additions that went into the BSD version of ms
(and apparently into the groff version): automatically numbered footnotes, exdented paragraphs, better support for references, table of
contents support, even and odd page footers. Available as USD:21.
Allman: Writing Papers with NROFF using me
A longish paper on how to use the me macros, also good for TROFF in
general. Available as USD:22.
basics of text processing paragraphs headers and footers double spacing page layout underlining major quotes lists
keeps fancier displays footnotes delayed text indexes more
paragraphs section headings parts of the basic paper equations
and tables two column output defining macros annotations
inside keeps fonts point sizes quotes acknowledgments
Allman: me Reference Manual
Available as USD:23.
Mashey & Smith: PWB/MM . . .
Supposedly documents the mm macros. Not rediscovered.

-7-

the groff macro package man pages

Document the ms, me, mm man, and mdoc macros to varying
degrees. groff_mm(7) seems fairly complete as a reference, while
groff_me(7) mostly points to Eric Allmans reference manual and to
something called Writing Papers with Groff Using me (a typo for Allmans tutorial?). groff_ms(7) mostly describes the differences to the
4.3BSD version, without further references.
6.4. Preprocessors
Lesk: Tbl A Program to Format Tables
Documents the tbl(1) table preprocessor. Revised in 1977.
introduction options format data additional command lines
usage examples
Kernighan: A System for Typesetting Math (CSTR 17)
Documents the eqn(1) preprocessor for mathematical expressions.
Kernighan: PIC . . . (CSTR 85)
Documents the pic(1) preprocessor for graphics (pictures).
Bentley & Kernighan: Grap A Language for Typesetting Graphs
Documents the grap(1) preprocessor for graphs.
introduction tutorial a collection of examples errors troff
issues alternatives references reference manual
soelim(1), tbl(1), refer(1), eqn(1), pic(1), grap(1), grn(1)
Document the the groff implementations of various TROFF preprocessors: soelim for satisfying .so requests, tbl for tables, refer for references, eqn for equations, pic for graphics, grap for diagrams and plots,
and grn for gremlin pictures. Most document only the groff extensions
and refer vaguely to the Unix documentation for a description of the
complete language. grap(1) is a separate package not part of the groff
distribution.
7. Example TROFF source
Good example source is always a useful tool for learning.
The primary source is, as far as I can see, the UNIX Users Supplementary Documents (USD), where many of the original papers on TROFF and a
wide variety of others (Michael Toys and Ken Arnolds A Guide to the
Dungeons of Doom comes to mind) are available in ms or me format.
See elsewhere in this paper for an URL.
Man pages are available aplenty; however, most people who write them
have no deeper TROFF knowledge, and man pages are a special case, anyways.
The sendmail documentation (op.me) still comes as TROFF source with
the sendmail distribution. Another example is the Nethack guidebook
(formatted with the obscure mn macros).
8. Organizing the TROFF source
A TROFF source text needs to be readable. TROFF makes this harder than it
could be. Some words of advice from a relatively nave user:
Empty lines are significant and have undesirable resultsthey cause a
raw paragraph break. The empty request . can be used to make the
source less compact. The request .\" introduces a comment line, while
.ig makes TROFF ignore many lines.

-8-

Macros and many commands need a newline. Not much to do about

this, Im afraid.
Spacing around escape sequences is significant. For example, mn
reads as m\(emn. You may use \ to introduce a continuation line so that
at least the part after the escape is more readable.

TROFF forces you to use escapes for many national characters, such as
and , making input text in most western-european languages unreadable. Most TROFF implementations silently strip non-ASCII input characters. You could, perhaps, use groff, which accepts the full ISO8859-1.

There are probably a lot of other things you can do. For example, .so can
be used for include statements.
9. Style and typography
No typesetting system can produce excellent printed output without
human intervention. Microsoft Word documents need an expert writer to
look anything like adequate. LaTeX does some of the job, but needs much
help from the writer. And TROFF, I think its fair to say, needs more help
than LaTeX.
Whats good printed style varies somewhat with language and culture.
Theres usually a national organization which codifies and publishes the
rules. Here, Ive used Svenska skrivregler and my understanding of whats
the US norm.
9.1. Line length
The default text width in TROFF is too wide to be readable (60 characters a
line is a good rule), and macro packages dont seem to change this. There
are various solutions to this:
enter two-column mode (but you need a text that is easily rebroken and
you need good hyphenation)
adjust the line length (using the ms macros, you can put something
like .nr LL 60n near the start of the document)
switch to a different font that is wider than the default Times (but these
fonts tend to be harder to read onscreen)
increase the point size and line spacing
9.2. Paragraphs
Paragraphs are usually not separated by vertical space. If they follow
another paragraph, the first line is indented a few millimeters.
You should use your macro packages paragraph macros. Most of them
seem to use vertical spacing by default. The ms macros are pretty OK;
they have little vertical spacing and separate macros (.LP and .PP) for
unindented and indented paragraphs. The default indent is too large;
change it with .nr PI 2n.

Sometimes (more frequently in older texts) a major paragraph break is

also used: a vertical space, often with a centered asterisk or some other
decorative glyph. Its not part of any of the macro packages, as far as I
know. An implementation could look like:
.sp 0.5
.ce

-9-

\(**
.LP
9.3. Ligatures
Well typeset text may, depending on the font, use special glyphs for some
combinations of the letter f and other letters. Compare, for example,
fish and fish.
groff uses these by default (although it can be turned off), and makes
them available as escapes too (\(fi etc). I dont know about the other
TROFF implementations.
9.4. Hyphenation and line breaking
Groff hyphenates by default, using American English rules. Apparently it
can be made to use othersalthough the distribution comes with just
English and the way to add others is undocumented. Its unclear to me
whether all modern TROFFs hyphenate; at least the Solaris version does.
To introduce soft hyphens in problematic words, use \%.
To prevent line breaking on space where its unsuitable (e.g. between
initials in a persons name), escape the space with a \. Other escapes are
available for other spacings. Your style guide is likely to give elaborate
advice on where different spacings should be used, and where line breaking is inappropriate.
9.5. Dashes
A style guide will have detailed advice on various dashes: in which situations they are used and how/if they should be surrounded by spacing.
Tastes seem to vary a lot here. I frequently use the long dash without
spacinglike thisand while that looks appealing to me, others might
find it arcane. (Its up to the reader to blame my fascination by Fitzgerald,
Lovecraft, Salinger and older science fictionor the awfully typeset Word
documents I encounter daily at work.)
At least four different dashes are available in TROFF. They appear in the
input as , \, \(en and \(em.
9.6. Quotation marks
The proper way of quoting differs between cultures. The standard way of
quoting in English is like this, while in Swedish it is like this.
As in TeX, these appears in the source as two characters each: the
ASCII backtick and single quote, respectively.
Other cultures have other quotation marks. The guillemots are used in
Spain, and in older Swedish texts, like this or like this. Its unclear to
me if these are possible to typeset in classic TROFF. In groff, they can be
entered directly (since they are part of ISO8859-1) or using the escapes
\(Fo and \(Fc.
9.7. Ellipsis
My style guide says that ellipsis should be written without any extra spacing ... like this. On the other hand, LaTeX (or is it TeX?) provides the
\ldots macro for properly spaced ellipsis, and at least older US literature
uses something . . . like this, which can be accomplished with a couple of
non-breaking spaces: .\<sp>.\<sp>..

-10-

9.8. Tables of contents

There are ways of getting automatic tables of contents into a TROFF document using the me macro package, the ms macros (post-AT&T) and I
guess mm as well.
Judging from the papers on ms that Ive read these are pretty painful
and force the table to appear at the end of the paper.
9.9. References and citations
The refer(1) preprocessor makes it possible to build large databases of references, and to refer to them in the TROFF source.
By default, a reference ends up as a footnote marker (a numeral by
default) and a footnote at the bottom of the page. Even the original refer
can do things differently, e.g. use more mnemonic labels and collect the
references near the end of the paper, but it is unclear to me where its capabilities end. Style guides often have precise demands in this area . . .