1.  Introduction

      troff [1] is a text-formatting program, written by J. F. Ossanna, for producing high-quality printed output from the phototypesetter on the UNIX and GCOS operating systems. This document is an example of troff output.

      The single most important rule of using troff is not to use it directly, but through some intermediary. In many ways, troff resembles an assembly language _ a remarkably powerful and flexible one _ but nonetheless such that many operations must be specified at a level of detail and in a form that is too hard for most people to use effectively.

      For two special applications, there are programs that provide an interface to troff for the majority of users. eqn [2] provides an easy to learn language for typesetting mathematics; the eqn user need know no troff whatsoever to typeset mathematics. tbl [3] provides the same convenience for producing tables of arbitrary complexity.

      For producing straight text (which may well contain mathematics or tables), there are a number of `macro packages' that define formatting rules and operations for specific styles of documents, and reduce the amount of direct contact with troff. In particular, the `-ms' [4] and PWB/MM [5] packages for Bell Labs internal memoranda and external papers provide most of the facilities needed for a wide range of document preparation. (This memo was prepared with `-ms'.) There are also packages for viewgraphs, for simulating the older roff formatters on UNIX and GCOS, and for other special applications. Typically you will find these packages easier to use than troff once you get beyond the most trivial operations; you should always consider them first.

      In the few cases where existing packages don't do the whole job, the solution is not to write an entirely new set of troff instructions from scratch, but to make small changes to adapt packages that already exist.

      In accordance with this philosophy of letting someone else do the work, the part of troff described here is only a small part of the whole, although it tries to concentrate on the more useful parts. In any case, there is no attempt to be complete. Rather, the emphasis is on showing how to do simple things, and how to make incremental changes to what already exists. The contents of the remaining sections are:

2. Point sizes and line spacing
3. Fonts and special characters
4. Indents and line length
5. Tabs
6. Local motions: Drawing lines and characters
7. Strings
8. Introduction to macros
9. Titles, pages and numbering
10. Number registers and arithmetic
11. Macros with arguments
12. Conditionals
13. Environments
14. Diversions
Appendix: Typesetter character set

The troff described here is the C-language version running on UNIX at Murray Hill, as documented in [1].

      To use troff you have to prepare not only the actual text you want printed, but some information that tells how you want it printed. (Readers who use roff will find the approach familiar.) For troff the text and the formatting information are often intertwined quite intimately. Most commands to troff are placed on a line separate from the text itself, beginning with a period (one command per line). For example, Some text.
^ps 14
Some more text.
will change the `point size',
that is,
the size of the letters being printed,
to `14 point' (one point is 1/72 inch) like this:
Some text. Some more text.

      Occasionally, though, something special occurs in the middle of a line _ to produce Area = r2
you have to type
Area = \(*p\fIr\fR\|\s8\u2\d\s0
(which we will explain shortly).
The backslash character
\is used
to introduce
troff
commands and special characters within a line of text.