.ab [text]

Abort and print text as message. If text is not specified, the message User Abort is printed.

.ad [c]

Adjust output lines according to format c. Fill mode must be on (see .fi). With no argument, same as .ad 1. The current adjustment mode is stored in register .j, with the following values: 0=l, 1=b, 3=c, 5=r (see .na).

Values for c

.af r c

Assign format c to register r.

Values for c

Example

Paginate front matter using the ms macros:

.af PN i	Set page number register PN to i

.am xx [yy]

Take the requests (etc.) that follow and append them to the definition of macro xx; end the append at call of .yy (or .., if yy is omitted).

.as xx string

Append string to string register xx. string may contain spaces and is terminated by a newline. An initial quote (") is ignored.

.bd [s] f n

Overstrike characters in font f n times. If s is specified, overstrike characters in special font n times when font f is in effect.

.bp [n]

Begin new page. Number next page n.

.br

Break to a newline (output partial line).

.c2 c

Use c (instead of ') as the no-break control character.

.cc c

Use c (instead of .) as the control character to introduce requests and macros.

.ce [n]

Center next n lines (default is 1); if n is 0, stop centering. n applies only to lines containing output text. Blank lines don't count.

.cf file

Copy contents of file into output and don't interpret (ditroff only).

.ch xx [n]

Change trap position for macro xx to n. If n is absent, remove the trap.

.cs f n m

Use constant spacing for font f. Constant character width is n/36 ems. If m is given, the em is taken to be m points.

Example

.cs CW 18   squeeze spacing of constant-width font

.cu [n]

Continuous underline (including interword spaces) on next n lines. If n is 0, stop underlining. Use .ul to underline visible characters only. Underline font can be switched in troff with .uf request. In troff, .cu and .ul produce italics (you must use a macro to underline).

.da [xx]

Divert following text and append it to macro xx. If no argument, end the diversion.

.de xx [yy]

Define macro xx. End definition at call of .yy (or .., if yy is omitted).

.di [xx]

Divert following text into a newly defined macro xx. If no argument, end the diversion.

.ds xx string

Define xx to contain string. An initial quote (") is ignored.

.dt n xx

Install diversion trap at position n, within diversion, to invoke macro xx.

.ec [c]

Set escape character to c. Default is \.

.el

Else portion of if-else (see .ie below).

.em xx

Set end macro to be xx. xx is executed automatically when all other output complete.

.eo

Turn escape character mechanism off. All escape characters are printed literally.

.ev [n]

Change environment to n. For example, many requests that affect horizontal position, hyphenation, or text adjustment are stored in the current environment. If n is omitted, restore previous environment. The initial value of n is 0, and 0 n 2. You must return to the previous environment by using .ev with no argument, or you will get a stack overflow. (ditroff simply ignores an invalid argument and issues a warning.)

.ex

Exit from the formatter and perform no further text processing. Typically used with .nx for form-letter generation.

.fc a b

Set field delimiter to a and pad character to b.

.fi

Turn on fill mode, the inverse of .nf. Default is on.

.fl

Flush output buffer. Useful for interactive debugging.

.fp n f

Assign font f to position n. n ranges from 1 to 4 in otroff and from 1 to 99 in ditroff.

Examples

.fp 7 CW   \" position 7 is constant width
.fp 8 CI   \" position 8 is constant italic
.fp 9 CB   \" position 9 is constant bold

.ft f

Change font to f, where f is a one- or two-character font name, or a font position assigned with .fp. Similar to escape sequence \f.

.hc [c]

Change input hyphenation-indication character to c. Default is \%.

.hw words

Specify hyphenation points for words (e.g., .hw spe-ci-fy). There is a limit of around 128 total characters for the total list of words.

.hy n

Turn hyphenation on (n 1) or off (n = 0). See also .nh.

Values for n

.ie [!]condition anything

.el anything

If portion of if-else. If condition is true, do anything. Otherwise do anything following .el request. .ie/.el pairs can be nested. Syntax for condition is described under .if.

Example

If first argument isn't 2, columns are 1.8 inches wide; otherwise, columns are 2.5 inches wide:

.ie !'\\$1'2' .MC 1.8i 0.2i
.el .MC 2.5i 0.25i

.if [!]condition anything

If condition is true, do anything. The presence of an ! negates the condition. If anything runs over more than one line, it must be delimited by \{ and \}.

Conditions

Expressions

Expressions typically contain number register interpolations and can use any of the following operators:

Note: expressions are evaluated left to right; there is no operator precedence. Parentheses may be supplied to force a particular evaluation order.

Example

Inside a macro definition, set the spacing and print the second argument. (The extra backslashes are necessary in \\$2. One backslash is stripped off when the macro is first read, so the second one is needed for it to be evaluated correctly when the macro is executed.)

.if t .nr PD 0.5v  \" Set spacing between ms paragraphs
.if !"\\$2"" \{ \" If arg 2 is non null, print it in bold
\fB\\$2\fP\}

.ig [yy]

Ignore following text, up to line beginning with .yy (default is .., as with .de). Useful for commenting out large blocks of text or macro definitions.

.in [[±]n]

Set indent to n or increment indent by ±n. If no argument, restore previous indent. Current indent is stored in register .i. Default scale is ems.

.it n xx

Set trap for input-line count, so as to invoke macro xx after n lines of input text have been read.

.lc c

Set leader repetition character (value for \a) to c instead of . (dot).

.lf n filename

Set the line number and filename for subsequent error messages to n and filename (recent versions of ditroff only). Modifies registers .c and .F.

.lg n

Turn ligature mode on if n is absent or nonzero.

.ll [[±]n]

Set line length to n or increment line length by ±n. If no argument, restore previous line length. Current line length is stored in register .l. Default value is 6.5 inches.

.ls [n]

Set line spacing to n. If no argument, restore previous line spacing. Initial value is 1.

Example

.ls 2      Produce double-spaced output

.lt [n]

Set title length to n (default scale is ems). If no argument, restore previous value.

.mc [c] [n]

Set margin character to c and place it n spaces to the right of margin. If c is missing, turn margin character off. If n is missing, use previous value. Initial value for n is .2 inches in nroff and 1 em in troff.

This command is usually used for producing “change bars” in documents. See diffmk in Chapter 2.

.mk [r]

Mark current vertical place in register r. Return to mark with .rt or .sp|\nr.

.na

Do not adjust margins. Current adjustment mode is stored in register .j. See also .ad.

.ne n

If n lines do not remain on this page, start a new page.

.nf

Do not fill or adjust output lines. See also .ad and .fi.

.nh

Turn hyphenation off. See also .hy.

.nm [n m s i]

Number output lines (if n 0), or turn numbering off (if n = 0). ±n sets initial line number; m sets numbering interval; s sets separation of numbers and text; i sets indent of text. Useful for code segments, poetry, etc. See also .nn.

.nn n

Do not number next n lines, but keep track of numbering sequence, which can be resumed with .nm +0. See also .nm.

.nr r n [m]

Assign value n to number register r and optionally set auto-increment to m.

Examples

Set the “box width” register to line length minus indent:

.nr BW \n(.l-\n(.i

Set page layout values for ms macros:

.nr LL 6i                         Line length
.nr PO ((8.25i-\n(LLu)/2u)        Page offset
.nr VS \n(PS+2                    Vertical spacing

In groff, auto-increment a footnote-counter register:

.nr footcount 0 1                  Reset to zero on each page

Note: inside a macro definition, \n should be \\n.

.ns

Turn on no-space mode. See also .rs.

.nx file

Switch to file and do not return to current file. See also .so.

.os

Output saved space specified in previous .sv request.

.pc c

Use c (instead of %) as the page number character within nroff/troff coding.

.pi command

Pipe the formatter output through a Unix command, instead of placing it on standard output (ditroff and nroff only). Request must occur before any output.

Example

.pi /usr/bin/col     Process nroff output with col

.pl [[±]n]

Set page length to n or increment page length by ±n. If no argument, restore default. Current page length is stored in register .p. Default is 11 inches.

.pm

Print names and sizes of all defined macros.

.pn [[±]n]

Set next page number to n or increment page number by ±n. Current page number is stored in register %.

.po [[±]n]

Offset text a distance of n from left edge of page or else increment the current offset by ±n. If no argument, return to previous offset. Current page offset is stored in register .o.

.ps n

Set point size to n (troff only, accepted but ignored by nroff). Current point size is stored in register .s. Default is 10 points.

.rd [prompt]

Read input from terminal, after printing optional prompt.

.rm xx

Remove request macro or string xx.

.rn xx yy

Rename request, macro, or string xx to yy.

.rr r

Remove register r. See also .nr.

.rs

Restore spacing (disable no-space mode). See .ns.

.rt [±n]

Return (upward only) to marked vertical place, or to ±n from top of page or diversion. See also .mk.

.so file

Switch out to file, then return to current file; that is, read the contents of another file into the current file. See also .nx.

.sp n

Leave n blank lines. Default is 1. You may use any vertical value, with an appropriate unit specifier, for n.

.ss n

Set space-character size to n/36 em (no effect in nroff).

.sv n

Save n lines of space; output saved space with .os.

.sy command [args]

Execute Unix command with optional arguments (ditroff only).

Example

Search for the first argument; accumulate in a temp file:

.sy sed -n 's/\\$1/Note: &/p' list >> /tmp/notesfile

(Note the extra backslash in \\$1. This example occurs inside a macro definition. One backslash is stripped off when the macro is first read, so the second one is needed for it to be evaluated correctly when the macro is executed.)

.ta n[t] [+]m[t] ...

Set tab stops at positions n, m, etc. If t is not given, tab is left-adjusting. Use a + to move relative to the previous tab stop.

Values for t

.tc c

Define tab repetition character as c (instead of whitespace). nroff/troff uses c when expanding tabs. For example, you might use .tc . when formatting a table of contents.

.ti [[±]n]

Temporary indent. Indent the next output line by n or increment the current indent by ±n for the next output line. Default scale is ems.

Example

.in 10
.ti -5
The first line of this paragraph sticks out by 5 ems ...
.in -10

.tl 'l'c'r'

Specify left, centered, or right title. Title length is specified by .lt, not .ll. Use % to get the page number, for example, .tl ''- % -''.

.tm text

Terminal message. Print text on standard error. Useful for debugging, as well for producing indexes and cross references.

.tr ab...

Translate character a (first of a pair) to b (second of pair).

Example

Produce uppercase and later restore. Useful for title macros:

.tr aAbBcCdDeEfFgGhHiIjJkKlLmM     Et cetera
.tr aabbccddeeffgghhiijjkkllmm     Et cetera

.uf f

Set underline font to f (to be switched to by .ul or .cu); default is italics.

.ul [n]

Underline (italicize in troff) next n input lines. Do not underline inter-word spaces. Use .cu for continuous underline. Underline font can be switched in troff with .uf request. However, you must use a macro to actually underline in troff.

.vs [n]

Set vertical line spacing to n. If no argument, restore previous spacing. Current vertical spacing is stored in register .v. Default is 1/6 inch.

.wh n [xx]

The “when” request. When position n is reached, execute macro xx; negative values are calculated with respect to the bottom of the page. If xx is not supplied, remove any trap(s) at that location. (A trap is the position on the page where a given macro is executed.) Two traps can be at the same location if one is moved over the other with .ch. They cannot be placed at the same location with .wh.