18.1. Introduction

The standard Unix text-processing tools are nroff and troff. They are not What You See Is What You Get (WYSIWYG) word-processors. Rather, they are text processing programs, where the input consists of a mixture of text to be formatted and special commands that instruct the programs how to format the text.

troff is for output devices such as typesetters and high resolution laser printers that can handle variable-width fonts and different character sizes. nroff is for simpler devices where all characters have the same width, such as terminals or line printers. Both programs accept the same set of commands; thus, carefully prepared input may be used with both programs to produce reasonable results. The original troff program worked for only one specific typesetter. The modern version, known as "device independent troff," or ditroff, can be tuned via specific drivers to work on multiple output devices.

Different commercial versions of Unix come with different versions of the troff suite. GNU/Linux and BSD systems all use GNU troff (groff), which is an excellent, full-featured implementation of ditroff and all the troff preprocessors. The Internet starting point for groff is http://www.gnu.org/software/groff/groff.html. We recommend downloading and building it if you intend to do serious troff-based typesetting work.^[*]

^[*] groff is written in C++, so you may need a C++ compiler. In this case, you may first need to bootstrap g++, the GNU C++ compiler from GCC (the GNU Compiler Collection).

Knowledge of nroff and troff was once an integral part of a Unix wizard's claims to Unix mastery. Over time though, they have been superseded for daily document preparation, either by WYSIWYG programs, or by T_EX and L^AT_EX. More information about troff in general is available from http://www.troff.org/.

However, one important task where knowledge of troff is still handy is the writing of manual pages (for the man command) to accompany software. This chapter introduces the subset of the troff command and feature set that is useful for writing manual pages, and then describes the man macros, concluding with a sample manual page. See also the Writing Manual Pages appendix in Classic Shell Scripting, cited in the Bibliography.

The canonical reference for nroff/troff is Bell Labs Computing Science Technical Report #54, Troff User's Manual, by J.F. Ossanna and B.W. Kernighan. It is available in PostScript from http://cm.bell-labs.com/cm/cs/cstr/54.ps.gz. You should read it if you plan to do any serious work in nroff/troff (such as writing or modifying macro packages). This document explains the ideas of diversions, environments, fields, registers, strings, and traps. The online Info documentation for groff explains the GNU-specific extensions that it supplies.