home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  

Book HomeBook TitleSearch this book

12.3. Conceptual Overview

This sections 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

12.3.2. Common Requests

The most commonly used requests are:

.ad   .ds   .ll   .nr   .sp
.br   .fi   .na   .po   .ta
.bp   .ft   .ne   .ps   .ti
.ce   .in   .nf   .so   .vs
.de   .ls

For example, a simple macro could be written as follows:

.	        \" Ps macro - show literal text display
.de Ps	        \" Define a macro named "Ps"
.sp .5	        \" Space down half a line
.in 1i	        \" Indent one inch
.ta 10n +10n	\" Set new tabstops
.ps 8	        \" Use 8-point type
.vs 10	        \" Use 10-point vertical spacing
.ft CW	        \" Use constant width font
.br		\" Break line (.ne begins count on next line)
.ne 3	        \" Keep 3 lines together
.nf	        \" No-fill mode (output lines as is)
..	        \" End macro definition

12.3.3. 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


Equivalent Unit

# of Basic Units

cCentimeter2.54 inchesR / 2.54

6 picas or 72 points

mEmT pointsR × T / 72
nEn0.5 emR × T / 144
pPoint1/72 inchR / 72
PPica1/6 inchR / 6

Basic unit


Vertical line space


(Current value in basic units)


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.

You can specify a scale indicator for any of the requests in the following table, except for .ps, which always uses points. If no unit is given, the default unit is used. (The second column lists the scale indicators as described in the previous table.) For horizontally oriented requests, the default unit is ems. For vertically oriented requests, the default is usually vertical lines.

Request Default ScaleRequestDefault Scale
.ch v.plv
.dt v.pov
.ie u.psp
.if u.rtv
.in m.spv
.ll m.svv
.lt m.tam
.mc m.tim
.ne v.vsp
.nr u.whv

12.3.5. 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 (Figure ), the left hand \(lh (Figure ), and the right hand \(rh (Figure ).

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.). They 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
\\n+(Cl. \\$1 \\$2 \\$3

This creates a macro that uses register Cl as the “chapter level.” The first three arguments to the macro become the chapter title. The extra backslashes are needed inside the macro definition.

Later sections in this chapter describe the predefined special characters, strings and number registers, and all of the escape sequences that are available.

Library Navigation Links

Copyright © 2003 O'Reilly & Associates. All rights reserved.