18.2. Overview of nrofftroff

18.2. Overview of nroff/troff

This section is condensed from the material on troff from the third edition of this book. It covers features available in all versions of nroff and troff, and focuses on those features necessary for writing manual pages.

18.2.1. Command-Line Invocation

nroff and troff are invoked from the command line as follows:

     nroff  [options]  [files]     troff  [options]  [files]

Although both formatters support a plethora of options, the following two are the most important for everyday use.

-mname

Prepend a macro file to input files. Historically, one of /usr/lib/tmac/tmac.name or /usr/share/lib/tmac/tmac.name were the locations of the macros for name. Solaris uses /usr/share/lib/tmac/name. GNU troff uses something like /usr/local/share/groff/x.y.z/tmac/name.tmac. The actual location and filename(s) vary among different Unix systems.

-Tname

Prepare output designed for printer or typesetter name. For device names, see your specific documentation or a local expert. GNU troff provides both PostScript and T_EX DVI output.

18.2.1.1. Example

Format a manual page for printing using groff:

     $ groff -man /usr/share/man/man1/awk.1 | lpr

18.2.2. Conceptual Overview

This section provides a brief overview of how to prepare input for nroff and troff. It presents the following topics:

• Requests and macros

• Common requests

• Specifying measurements

• Requests that cause a line break

• Embedded formatting controls

18.2.2.1. Requests and macros

Formatting is specified by embedding brief codes (called requests) into the text source file. These codes act as directives to nroff and troff when they run. For example, to center a line of text, type the following code in a file:

     .ce     This text should be centered.

When formatted, the output appears centered:

                     This text should be centered.

There are two types of formatting codes:

• Requests, which provide the most elementary instructions

• Macros, which are predefined combinations of requests

Requests, also known as primitives, allow direct control of almost any feature of page layout and formatting. Macros combine requests to create a total effect. In a sense, requests are like statements, and macros are like functions.

All nroff/troff requests are two-letter lowercase names. Macros are usually upper- or mixed-case names. GNU troff removes the two-character restriction on the length of names.

18.2.2.2. Specifying measurements

With some requests, the numeric argument can be followed by a scale indicator that specifies a unit of measurement. The valid indicators and their meanings are listed in the following table. Note that all measurements are internally converted to basic units (this conversion is shown in the last column). A basic unit is the smallest possible size on the printer device. The device resolution (e.g., 600 dots per inch) determines the size of a basic unit. Also, T specifies the current point size, and R specifies the device resolution.

Scale indicator	Meaning	Equivalent unit	# of basic units
c	Centimeter	0.394 inches	R / 2.54
i	Inch	6 picas or 72 points	R
m	Em	T points	R x T / 72
n	En	0.5 em	R x T / 144
p	Point	1/72 inch	R / 72
P	Pica	1/6 inch	R / 6
u	Basic unit		1
v	Vertical line space		(Current value of line spacing in basic units)
None	Default

It is worth noting that all numbers in nroff/troff are stored internally using integers. This applies even to apparently fractional values in commands such as:

     .sp .5

which spaces down one-half of the current vertical spacing.

An "em" is the width of the letter "m" in the current font and point size. An "en" is the width of the letter "n" in the current font and point size. Note that in nroff, an "em" and an "en" are the same the width of one character.

18.2.2.3. Requests that cause a line break

A line break occurs when nroff/troff writes the current output line, even if it is not completely filled. Most requests can be interspersed with text without causing a line break in the output. The following requests cause a break:

     .bp   .ce   .fi   .in   .sp     .br   .cf   .fl   .nf   .ti

If you need to prevent these requests from causing a break, begin them with the "no break" control character (normally ') instead of a dot (.). For example, .bp flushes the current output line and starts a new page immediately. However, 'bp starts a new page, with the current output line not being written until it is full.

18.2.2.4. Embedded formatting controls

In addition to requests and macros, which are written on their own separate lines, you may also have formatting controls embedded within your text lines. These typically provide the following capabilities:

General formatting

Considerable formatting control is available, such as switching fonts (\f), changing point sizes (\s), computing widths (\w), and many other things. For example:

     This text is in \fIitalic\fR, but this is in roman.     This text is \s-2VERY SMALL\s0 but this text is not. 

Special characters

Predefined special typesetting characters, such as the bullet symbol \(bu (·), the left hand \(lh ( ), and the right hand \(rh ( ).

Strings

User-defined sequences of characters, like macros, but usable inline. For example:

     .\" define a shorthand for UNIX     .ds UX  the \s-1UNIX\s0 Operating System     ...     Welcome to \*(UX.     While \*(UX may appear daunting at first,     it is immensely powerful. ...

Number registers

Like variables in programming languages, number registers store numeric values that can be printed in a range of formats (decimal, roman, etc.). Number registers hold integer values; fractional values are converted into the corresponding number of basic units. Number registers can be set to auto-increment or auto-decrement, and are particularly useful when writing macro packages, for managing automatic numbering of headings, footnotes, figures, and so on. For example:

     .nr Cl 0 1  \" Chapter Level     .de CH     .bp     \\n+(Cl. \\$1 \\$2 \\$3     ..

This creates a macro that uses register Cl as the "chapter level." The first three arguments to the macro (represented in the macro body by \\$1 etc.) become the chapter title. The extra backslashes are needed inside the macro definition to prevent too-early evaluation.

Comments in nroff/troff begin with \". Lines beginning with . that contain an unknown request are ignored. In general, don't put leading whitespace on your text lines. This causes a break, and nroff and troff honor the leading whitespace literally.

18.2.3. Outline of Useful Requests

The following is a list of the requests that you may see in manual pages, or that were mentioned earlier in the chapter.

.ad	Adjust margins.	.ls	Line spacing (e.g., single-spaced).
.bp	Begin a new page.	.na	Don't adjust margins.
.br	Break the output line.	.ne	Keep lines on same page if there's room.
.ce	Center lines.	.nf	Don't fill lines.
.cf	Copy raw file to output.	.nr	Define a number register.
.de	Define a macro.	.po	Change page offset.
.ds	Define a string.	.ps	Set point size.
.fi	Fill lines.	.so	Go to a file, then return.
.fl	Flush output buffer.	.sp	Output blank spacing.
.ft	Set font.	.ta	Define tab settings.
.in	Indent.	.ti	Indent next line (temporary indent).
.ll	Set line length.	.vs	Set vertical spacing for lines.

18.2.4. Useful Escape Sequences

This partial list of troff escape sequences provides those that are most useful.

Sequence	Effect
\\	Prevent or delay the interpretation of \.
\e	Printable version of the current escape character (usually \).
\-	- (minus sign in the current font).
\.	Period (dot).
\space	Unpaddable space-size space character.
\newline	Concealed (ignored) newline.
\|	1/6-em narrow space character (zero width in nroff).
\^	1/12-em half-narrow space character (zero width in nroff).
\&	Nonprinting, zero-width character.
\"	Beginning of comment.
\$n	Interpolate macro argument 1 9.
\(xx	Character named xx. See the following section "Special Characters."
\*x or \*(xx	Interpolate string x or xx.
\fx or \f(xx or \fn	Change to font named x or xx or to position n. If x is P, return to the previous font.
\nx, \n(xx	Interpolate number register x or xx.
\n+x, \n+(xx	Interpolate number register x or xx, applying auto-increment.
\n-x, \n-(xx	Interpolate number register x or xx, applying auto-decrement.
\sn, \s±n	Change point size to n or increment by n. For example, \s0 returns to previous point size.
\s(nn, \s±(nn	Just like \s, but allow unambiguous two-character point sizes (ditroff only).
\w'string'	Interpolate width of string in basic units.

18.2.5. Special Characters

Table 18-1 lists the special characters that reside in the standard fonts. troff includes a large number of other characters that we have not described here, since they are mostly for typesetting mathematics.

Table 18-1. Characters in the standard fonts

Input	Char	Character name
'	'	Close quote
'	'	Open quote
\(em		Em-dash (width of "m")
\(en		En-dash (width of "n")
\-	-	Minus in current font
-	-	Hyphen
\(hy	-	Hyphen
\(bu	·	Bullet
\(sq		Square
\(rg	®	Registered
\(co	©	Copyright