Formatting text using Unix tools: Nroff/Troff

Revised: October 2003.

October 2001 Notice: Nroff and Troff are essentially obsolete. For most purposes they have been replaced by popular wordprocessing applications, such as MicroSoft Word, run on personal computers. This vintage 1985 article is retained to support legacy documents which depend on Nroff/Troff, Eqn, and Tbl.

This article is composed of the following sections:

Instructions that go into nroff/gtroff/troff files
- Sketch of syntax conventions
- Descriptive list of in-file word-processing commands
Obtaining formatted typesetter and laser printer output with gtroff
Obtaining screen and typewriter terminal output with nroff
How to run preprocessors
Command options for nroff/gtroff/lpr/lp commands

Word-processing on UNIX systems is handled differently than it is on most micro-computers. On UNIX there are two stages to the process. First, you type your text into a file using an editor like "vi" (see the vi tutorial). The text is typed in "raw" form -- this means typing it in conveniently short lines, without hyphenating and without much concern for margins or page boundaries. As you type, you imbed some formatting instructions in your text. These guide the formatting program which is run in the second stage of the process.

The formatting program produces your finished document. It reads the raw text file and usually does several routine chores such as cutting and splicing lines to make even margins, hyphenating, shaping paragraphs, and paginating. The format instructions imbedded in the text control the action of the formatting program. Simple layouts can be achieved very easily and with almost no imbedded instructions. Fancy layouts naturally require more instructions.

UNIX text formatting is based on the programs nroff and troff. Nroff formats text primarily for screens and for typewriter-like devices such as Diablo printers. Gtroff (general troff) employs troff and formats text for devices with more sophisticated capabilities such as laser printers and typesetters.

The various devices for printing, in ascending order of quality and capability are: line printer, typewriter terminal, laser printer, and typesetter. Line printer output quality is suitable for some proofreading and record keeping purposes. Typewriter terminals of various kinds (Diablo, Xerox, NEC) offer "letter quality" output with some composition refinements (boxed tables, superscripts). Laser printers and typesetters offer proportionally spaced characters, a variety of type sizes, and the ability to produce sophisticated equations and tables. Typesetting offers high resolution output suitable for publication.

Most nroff/troff/gtroff text formatting is done with the aid of the -ms macro package. The -ms macro package is a set of powerful formatting instructions (macros) built from the more rudimentary instructions inherently recognized by nroff/troff.

For special needs such as foreign language text, dissertations, tables, technical notation, bibliographic listings, etc., there are auxilliary tools.

Diacritical marks (accents) for foreign language text are provided through the -ms macro package. See "help format".

There is a package of macros for thesis preparation. See "help thesis".

There is a program called "eqn" which is used to format mathematics. See "help eqn".

Technical symbols and greek characters are obtained by various means:

Troff (gtroff) has built-in notation for many symbols.

Eqn provides mnemonic names for some of the troff built-in symbols and for additional constructs. See "help eqn" for more information.

Eqn's repertoire is extended by a set of definitions contained in an "eqnchar" file. See "help eqnchar".

"tbl" is a program that is used to make nice tables and boxed items. See "help format".

"refer" is a bibiographic management system which facilitates building, maintaining and extracting from a bibliographic database. See "help refer" [No longer supported].

Instructions that go into nroff/gtroff/troff files

Text formatting done with the UNIX formatting utilities nroff and
troff (gtroff) is guided by instructions that you type in the file
along with the text.  These instructions fall into two classifications:
low-level commands that nroff and troff recognize directly and
higher level instructions called macros that are defined in terms
of the low-level commands.
The set of macros most commonly used are in a package called "-ms".
Note that the names of low-level instructions are lowercase (e.g. bp,
sp, br) while the macros have uppercase names (e.g. PP, LP).
The help menu selections beneath this one sketch the nroff/troff
syntax conventions, and present a list of frequently used in-file
instructions of both flavors: low-level and macro.

Sketch of syntax conventions

Word processing with in-file troff commands and macros is straightforward. These commands are placed in the file to be formatted. Each command refers to a specific action to be taken on the text (e.g., "start a paragraph" or "center the next line").

All in-file troff commands that start with a period `.' must be typed on lines by themselves, while those that begin with a backslash `\' can be imbedded in text. (See the sample input below).

A list, with descriptions and usage, of the most frequently used in-file troff commands accompanies this selection in the help menu.

----------------------- Sample Input and Output -----------------------

The following sample input and output provides a simple illustration of the basic procedure and features of text formatting with nroff/ troff/gtroff. Note that although the sample input is indented here, in the actual file, all commands that start with a period must be placed at the beginning of a line.

Sample Input (before formatting):

.ST This is sample text. This is sample text. This is sample text also. Note that the way the sample text is typed in doesn't matter--it will all be justified in the end. .PP This is sample text to be placed in an indented paragraph. Here is yet more sample text, and yet more, and yet more!

Sample Output (after formatting):

This is sample text. This is sample text. This is sample text also. Note that the way the sample text is typed in doesn't matter--it will all be justified in the end.

This is sample text to be placed in an indented para- graph. Here is yet more sample text, and yet more, and yet more!

--------- Comments: ---------

The `.ST' (start) command is commonly placed at the top of files to be formatted. This command sets up certain default registers, such as the header and footer margins, and the point size to be used.

Note that the `.PP' (indented paragraph) command skips one line and indents the first line of the paragraph 5 spaces.

Note that the formatter (nroff/troff) takes care of filling and adjusting text for you - this means that you can type short lines, even one word to a line, and the formatter will put them together to make normal-length lines. It's a good idea to begin each sentence on a new line, as it makes it easier to edit later.

There are two exceptions to the "filling" rule: if you leave a blank line in the text, it will not be "filled" and the formatter will leave a blank line at this point. If you begin a line with a space or a tab, the formatter will also "break" filling, and space in the indicated amount, even if the previous line ended mid-sentence or mid-line -- and this can be inconvenient. For example, if you typed:

1 This is a story that I would like 2 to tell you.

(the numbers refer to the far left margin of the file) you might want the formatter to translate this to

This is a story that I would like to tell you.

since the two phrases will fit on the same line. But since you began the second line with 3 spaces, the formatter will heed this and output

This is a story that I would like to tell you.

It's worthwhile to keep in mind that when you indent by typing a space or a tab, the formatter will too.

Descriptive list of in-file word-processing commands

This list is presented in alphabetical order and is NOT an exhaustive list of all commands.

.ad Adjust Adjusts text by adding extra space between words to make right margin completely even. See .na .

.af PN i Changes page numbers to Roman Numeral style. (To revert back to Arabic numerals use .af PN 1 .) NOTE: the "i" and "1" DO NOT reset the page number to 1, they simply state the style of numbering to be used; i.e., "1" for arabic or "i" for roman.

.B Boldface Typeset the following text in bold face until another font command (or a paragraph command ) is reached. If you don't give another font command, all your text will be bold face. For troff, gtroff, and typeset this macro actually causes a switch to whatever font is mounted in font position three (3) which is Times bold by default.

.BB Bibliography instruction Needs to be preceded by a ` .in 5 ' . Prints bibliography entries with a non-indented 1st line, then indents all following lines 5 spaces.

.bp Begin Page Forces printing to begin a new page, regardless of where you are now. Also see .ne instruction.

.br Break Breaks line filling temporarily; in other words, forces the next line to begin on a line by itself, instead of attaching onto the end of the last one.

.BX word Box Puts a box around the next word.

.ce n_ Center Centers the following n_lines. If n_ is not specified, centers the next line.

.de Zz Define Macro Defines macro Zz; definition should end with ``..''

.ds LF string Define String, Left Footer Designates the following string as the left page footer.

.ds LH string Define String, Left Header Designates the following string as the left page header. (You get the idea, right? Just use CH and CF for center headers and footers, and RH and RF for right headers and footers. If you want the page number to appear in your header or footer, put a % character somewhere in your string).

To generate alternate headers or footers for odd and even pages, the following macros can be used:

.OH 'left'center'right' -- odd page header .EH 'left'center'right' -- even page header .OF 'left'center'right' -- odd page footer .EF 'left'center'right' -- even page footer

\*(DY String to insert the current date.

.EQ Equation begin .EN Equation end .EQ marks the beginning of an equation for processing by eqn. When equation is finished, terminate with .EN .

.fi Fill Start filling in text to right margin. This is the default; you only need to do it if you've turned off filling somehow, as with a .nf .

.hy 0 Hyphenation Off Doesn't allow the formatter to break up long words with hyphenation when typing out on output terminal.

.hy 14 Hyphenation On Allows hyphenation.

.I Italics (or underline on typewriter output terminal) Makes everything following it italicized or underlined. Turn this off with a .B (bold), .R (roman, or normal, type), or a paragraph command (see the end of this article). For troff, gtroff, and typeset this macro actually causes a switch to whatever font is mounted in font position two (2) which is Times italic by default.

.in n_ Indent Indents all of the following text n_ (+) (-). You can also specify the number of inches to indent, i.e. .in 2i . Indents are not turned off until you give another indent command, like .in -2i, to set them back. (Yes, negative indentation is permitted!)

.IP Indented paragraph .IP l_a_b_e_l_ .IP l_a_b_e_l_ n_ .IP "" n_ .IP by itself gives you an indented block-style paragraph. .IP l_a_b_e_l_ gives output with an unindented "paragraph label" on the first line of the paragraph. If the label contains spaces, put "quotation marks" around it. .IP l_a_b_e_l_ n_ indents the paragraph part n_ spaces. This is useful especially when you have a long label, i.e. more than 5 characters, so the paragraph won't sit on top of the label. .IP "" n_ indents the paragraph n_ spaces without labeling it. NOTE: the only way to properly terminate the indenting initiated by .IP is by giving one of the other paragraph instructions, .LP or .PP.

.KS .KE Keep Start and Keep End Keeps the enclosed text together, at the point in the manuscript where it now is. If necessary, starts a new page.

.KF .KE Keep Floating Keeps the text together, but lets it float relative to the main text, so no huge gaps of blank space occur. This means that this block of text may be moved onto the next page, while the rest of the text continues into the gap left on the previous page. This is most useful for tables and other such blocks of text whose exact location in the text isn't vital.

.ll 5.5i .nr LL 5.5i Designates line length in inches from the left margin. Both command are required for immediate and lasting effect, see disscussion of .ps below. Left margin is controlled by page offset (see .PO below).

.LP Block paragraph Gives you a block-style paragraph (doesn't indent).

.ls n_ Line-Space Sets line spacing. If you don't adjust it, the default is single-spaced. .ls 1 is single-spaced, .ls 2 is double-spaced. The .ls instruction does not support partial line spacing, e.g. space and a half. See .VS for partial line spacing.

.MC n_i Multiple Columns Divides printout into more than one column, to create output more like magazines or newspapers. The argument refers to the width of a single column; .MC will place as many columns as it can within the current line length ( see .LL )

.na No Adjusting Prevents full-adjusting of lines; allows a ragged right margin. When not used, text will be automatically fully adjusted, so that it will have a completely even right margin. See .ad .

.ne n Need Keeps blocks of n lines of text from being broken up by forcing them onto the next page if there isn't room for them on the current page. Especially useful for fixing up paragraphs; for example, if only one line of a paragraph is appearing at the bottom of a page (which looks funny), use .ne 2 to push it onto the next page. In some situations, such as when you have a .ne right after a paragraph, it makes sense to cause a break (.br) before the .ne, in order to force out the last partial line of the paragraph before advancing to the next page.

.nf No Filling Begins not filling in the lines to the right margin; i.e. prints text line-for-line, just as you typed it. Use .fi to turn on filling again. .nf is especially useful when you want to use tabs, which don't work with filling on.

.nr HM n_i Header Margin Sets the number register HM which contains the header margin size to the specified value. The default header margin size is one inch. You can use this instruction to make the margin larger or smaller. Example:

.nr HM 0.5i

The instruction must be given before the page is started. To apply to the first page the instruction must be given before anything that causes an nroff/troff "break", e.g. before .ST or any paragraph macro. Setting the margin to very small values (approximately 0.25i) may cause text to be clipped due to the physical limits of the printer's imaging area.

.nr FM n_i Footer Margin Similar to header margin setting, see above. Care must be taken when setting the footer margin to values less than one inch to avoid conflicts with the bottom trap, BT. Generally, footer margins as small as 0.75i will be safe. If you set the footer margin any smaller you should probably remove the BT trap (.rm BT). Removing BT means that footer strings defined with instructions such as ".ds LF ..." will not be printed.

.pn n_ Page Number Sets page number n_ for next page. Only necessary if you want to change the page numbering in the middle of a document.

.pl n_i Page length Sets page length n in inches.

.po 1.25i .nr PO 1.25i Designates page offset in inches - moves the whole printed image to the right. Both commands are required to have immediate and lasting effect, see discussion of .ps below. If the gtroff command is used to format the file, the offset is measured from the left edge of the paper. If the nroff command is used, the offset is measured from the carriage return position, i.e. where the shell prompt appears. Page offset + Line length should not exceed 8 inches.

.P1 Print header on page 1 This command when place prior to the .ST command allows for headers be printed on the first page. Normally, headers don't print until page two.

.PP Paragraph Gives you a paragraph with first line indented 5 spaces.

.ps 11 .nr PS 11 Set font size in points. It is a characteristic of the standard MS macro package that it takes two commands to change point size so that it has an immediate and lasting effect. The ".ps 11" has immediate effect, but will not last beyond the end of the current paragraph unless accompanied by ".nr PS 11".

.QP Quote Paragraph Gives you a paragraph with every line indented 5 spaces on both sides.

.QS .QE Quote Start and Quote End Useful for starting and ending quotations; automatically sets up an indent of 5 from both margins, so quotation is "suspended" in between.

.R Roman Makes everything following it normal (roman) type. Particularly useful for turning off the effects of a .B or a .I . For troff, gtroff, and typeset this macro actually causes a switch to whatever font is mounted in font position one (1) which is Times regular by default.

.sp n_ Space Inserts n_ blank lines into the output. Stops at bottom of page. Space can be specified in inches (.sp 2.5i). Sometimes the formatter refuses to put blank space at the top of a page, the .rs (restore space mode) instruction is useful in this situation. For example, .bp .rs .sp 2i To leave space for something like an illustration after breaking to a new page with the .br command, use this incantation: .br .ne 2i .rs .sp 2i

.ST Start Always place this command at the beginning of a file.

.SU word superscript Superscript Word is printed normally, then superscript is printed in a raised position (nice for footnote marking). Punctuation can be placed after the superscript like this: .SU magazine 7 , This example would print approximately

7 magazine , on a Diablo typewriter terminal.

.ta n_i Tabsets Sets specific internal system tabs - does not change physical terminal tabs, so they still look the same, but will change the outputted tab size. For example: .ta .5i 1.5i 2.5i sets 3 tabs at 1/2 inch, 1 1/2 inch and 2 1/2 inches, respectively. NOTE: tabs only make sense in no-fill mode; see .nf above.

.TS .TE Table Start and Table End Used when a table to be run through tbl is enclosed in the text. **Note**: When Tbl in either portrait or landscape is run with gtroff, if the table exceeds 7.5i width, the following message will appear:

Table at line # File Filename is too wide - ###units

*********YOU CAN IGNORE THIS ERROR MESSAGE!!*********

.ti n_ Temporary Indent Indents the next line n_ spaces. Only affects one line, unlike .in which will continuously indent until a contrary command is issued.

.UL word Underline Word Underline the following single word in typesetting.

.UL "two words" Place quotation marks to get more than one word underlined.

.vs 18p .nr VS 18p Set the global vertical spacing to 18 points. (This would produce 1-1/2 line spacing when using a point size of 10 or 11.) Both command are required for immediate and lasting effect, see disscussion of .ps above.

\& Not a command Place before any period (.) or apostrophe (') that must begin a line that is not a format instruction, so that the formatter will treat it as printable text.

\ \ \ Controlled spaces When you wish a space between two words to be preserved and not expanded or separated by full-adjusting, for example, between a first and last name, or in a date, type "Mary\ Jones" to preserve that single space.

\% Hyphen control If placed before a word, the word will not be hyphenated. If placed within the word, the word will be hyphenated only at that point, and only when necessary for filling.

Obtaining formatted typesetter and laser printer output with gtroff

The following topics are covered in this selection:

1. The two basic steps to run gtroff 3. Previewing output on the screen

Example commands are given in the companion article to this one.

Using gtroff with ACS printers and the Linotronic typesetter

The printer destination environment variable is set to the name of the printer (e.g., laser2) or typesetter (L300) and the gtroff command is given:

On BSD UNIX: % setenv PRINTER laser2 % gtroff -ms filename | lpr

On HPUX UNIX: % setenv LPDEST laser2 % gtroff -ms filename | lp

Using gtroff with a LaserWriter attached to the LAN

If you are using a departmental LaserWriter attached to the Local Area Network the printer destination environment variable should be set to `psc' and the appropriate option to the print command (lpr or lp) should be used to designate the printer.

(the printer's designation is deptlw)

On BSD UNIX: % setenv PRINTER psc % gtroff -ms filename | lpr -Pdeptlw

On HPUX UNIX: % setenv LPDEST psc % gtroff -ms filename | lp -ddeptlw

Using gtroff with a LaserWriter attached to a terminal

If you are using a LaserWriter attached to a terminal, you can set the printer environment variable to "psc", run gtroff with any necessary preprocessors (like tbl or eqn), catch the output in a temporary file, and pass that temporary file to the attached printer using the pt command.

On BSD UNIX: % setenv PRINTER psc % gtroff -ms filename > output % pt output

On HPUX UNIX: % setenv LPDEST psc % gtroff -ms filename > output % pt output

Obtaining screen and typewriter terminal output with nroff

The ``nroff'' formatting command is used for simple devices like screen
terminals, line printers, and typewriter terminals.  Unlike
``gtroff'' it is not necessary to set a printer destination
environment variable when using nroff.  See the companion articles
to this one for example commands.

Using nroff with the terminal screen

To format a file containing in-file nroff/troff commands and macros for the screen, give one of the following commands:

% nroff -ms filename | col | more

The ``more'' program displays the formatted output on the screen, one screenful at a time.

Note that equations and tables do not print well on screens, because of the screen's limited capabilities.

Using nroff with line printers

To format a file containing in-file nroff/troff commands and macros and send the output to a lineprinter (say, to the site printer), give one of the following commands:

On BSD UNIX: % nroff -ms -Tlpr filename | lpr -Psite

On HPUX UNIX % nroff -ms -Tlp filename | lp -dsite

Replace ``site'' with the lineprinter designation of your choice. Note that equations and tables do not print well on lineprinters, because of the lineprinter's limited capabilities.

Using nroff with typewriter-type terminals

To format a file containing in-file nroff/troff commands and macros and print the output on a Diablo/Xerox typewriter-type terminal, give one of the following commands:

On BSD UNIX: % nroff -ms -T450 filename | dbfast

On HPUX UNIX % nroff -ms -T450 filename

Replace -T450 with -T450-12 to obtain elite type.

It is possible to format your file at a terminal other than the typewriter terminal, place the results in a file, and then print the results on the typewriter terminal as follows:

On BSD UNIX: % nroff -ms -T450 filename > output

(log into the typewriter terminal)

% dbfast output

On HPUX UNIX: % nroff -ms filename | col > output

(log into the typewriter terminal)

% cat output

How to run preprocessors

Eqn (neqn) for mathematics

Command examples:

On BSD UNIX:

% setenv PRINTER laser1 % eqn file | gtroff -ms | lpr

On HPUX UNIX:

% setenv LPDEST laser1 % eqn file | gtroff -ms | lp

Commands which run neqn with nroff have a similar structure to the ones above.

% neqn file | nroff -ms -T450

See "help eqn" for additional information.

Tbl for tables

Command examples:

On BSD UNIX:

% setenv PRINTER laser1 % tbl file | gtroff -ms | lpr

On HPUX UNIX:

$ setenv LPDEST laser1 $ tbl file | gtroff -ms | lp

Commands which run tbl with nroff have a similar structure to the ones above.

% tbl file | nroff -ms -T450

See "help format" for additional information.

Refer for bibliographic references

Command examples:

On BSD UNIX:

% setenv PRINTER laser1 % refer -p bib file | gtroff -ms | lpr

On HPUX UNIX:

"refer" is not available on HPUX.

Commands which run "refer" with nroff have a similar structure to the one above.

% refer -p bib file | nroff -ms -T450

See "help refer" [No longer supported].

Combining preprocessors

When formatting a document that requires more than one of the
preprocessors (refer, tbl, eqn), follow these guidelines:
1.  Run "refer" before tbl or eqn.  Run tbl before eqn.
	% tbl file | eqn | gtroff -ms | lpr
	% refer -p bib file | eqn | gtroff -ms | lpr
	% refer -p bib file | tbl | eqn | gtroff -ms | lpr
2.  Put all input filenames in the list presented to the first preprocessor,
    do not put filenames later in the pipe.
    RIGHT:	% tbl /public/eqnchar.ps file | eqn | gtroff -ms | lpr
    WRONG:	% tbl file | eqn /public/eqnchar.ps | gtroff -ms | lpr
Commands which run preprocessors with nroff have a similar structure
to the ones above.
	% refer -p bib file | tbl | neqn | nroff -ms -T450

Command options for nroff/gtroff/lpr/lp commands

Listed below are some of the options most frequently used with nroff, gtroff, lpr (BSD UNIX) and lp (HPUX UNIX). More can be found in the manual pages for these commands (e.g. "man lp", "man nroff"). Options for a particular command can be placed in any order after the command; spaces should separate the options from the command and from each other.

Available NROFF options include:

-olist Print only pages whose page numbers appear in list, which consists of comma-separated numbers and number ranges. Examples: -o3 page 3 -o3,7 pages 3 and 7 -o3-7 pages 3, 4, 5, 6, and 7 -o-3,7-11,14- beginning to page 3, 7 thru 11, and 14 to the end

-nN Numbers the first page in the file N.

-s Stops for single sheet paper loading on typewriter terminals.

-T450 Use with Diablo terminals with pica printwheels.

-T450-12 Use with Diablo terminals with elite printwheels.

Here's an example of the placement of these (command-options) in a command: nroff -ms -T450 -s -n26 -o27-29 filename This example means: type on a Diablo/Xerox, stop between pages, number the first page generated 26, print only pages 27, 28, and 29 (that is the second, third, and fourth pages generated).

Available TROFF or GTROFF options include:

-olist Only the pages contained in list will be output. List contains page numbers separated by commas or hyphens. Examples: -o4,7,9-11,22- will print pages 4, 7, 9 thru 11, and 22 to the end; -o-5 will print from the beginning thru page 5.

-n# The first page of the file will be numbered #.

-ms The document will be formatted with the ms macros. This is necessary for many formatting instructions such as .LL, .IP, .PP, etc. to be effective. (Note: -ms may be replaced by calls for other macro packages if desired).

-a Process the text as though for the laser printing device, but produce an approximation that is displayable on common mono-space screen terminals and printers. Type fitting information such as line content, hyphenation, and page breaks can be gleened from this approximation. Other aspects of the layout (indention, tabulation, centering) are NOT depicted.

Available LPR options include:

-Poutprinter Example: -Plaser2 See the "list of printers".

-Jcomment Used to specify a destination for Computer Center delivery service or mailing, or to request "nostaples" in output sent to laser1. Comment should contain no spaces.

-#3 Produce 3 copies of the output.

Available LP options include:

-doutprinter Example: -dlaser2 See the "list of printers".

-tcomment Used to specify a destination for Computer Center delivery service or mailing. Comment should contain no spaces.

-n3 Produce 3 copies of the output.

***Note*** Landscape mode with the new gtroff processor can now be invoked by including at the top of a text file:

.so /public/landscape