NROFF/TROFF User's Manual
Joseph F. Ossanna
(updated for 4.3BSD by Mark Seiden)
Bell Laboratories
Murray Hill, New Jersey 07974
Introduction
NROFF and TROFF are text processors under the UNIX Time-Sharing
System that format text for typewriter-like terminals and for a
Graphic Systems phototypesetter, respectively. (Device-
independent TROFF, part of the Documenter's Workbench, supports
additional output devices.) They accept lines of text inter-
spersed with lines of format control information and format the
text into a printable, paginated document having a user-designed
style. NROFF and TROFF offer unusual freedom in document styling,
including: arbitrary style headers and footers; arbitrary style
footnotes; multiple automatic sequence numbering for paragraphs,
sections, etc; multiple column output; dynamic font and point-
size control; arbitrary horizontal and vertical local motions at
any point; and a family of automatic overstriking, bracket con-
struction, and line drawing functions.
NROFF and TROFF are highly compatible with each other and it is
almost always possible to prepare input acceptable to both. Con-
ditional input is provided that enables the user to embed input
expressly destined for either program. NROFF can prepare output
directly for a variety of terminal types and is capable of util-
izing the full resolution of each terminal.
Usage
The general form of invoking NROFF (or TROFF) at UNIX command
level is
nroff options files(or troff options files)
where options represents any of a number of option arguments and
files represents the list of files containing the document to be
formatted. An argument consisting of a single minus (-) is taken
to be a file name corresponding to the standard input. If no file
names are given input is taken from the standard input. The
options, which may appear in any order so long as they appear
before the files, are:
Option Effect
-i Read standard input after the input files are
exhausted.
-mname Prepends the macro file /usr/lib/tmac.name to the
input files.
-nN Number first generated page N.
-olist Print only pages whose page numbers appear in list,
which consists of comma-separated numbers and number
ranges. A number range has the form N-M and means
pages N through M; a initial -N means from the
beginning to page N; and a final N- means from N to
the end.
USD:24-2 NROFF/TROFF User's Manual
-q Invoke the simultaneous input-output mode of the rd
request.
-raN Number register a (one-character) is set to N.
-sN Stop every N pages. NROFF will halt prior to every N
pages (default N=1) to allow paper loading or chang-
ing, and will resume upon receipt of a newline.
TROFF will stop the phototypesetter every N pages,
produce a trailer to allow changing cassettes, and
will resume after the phototypesetter START button
is pressed.
-z Efficiently suppress formatted output. Only produce
output to standard error (from tm requests or diag-
nostics).
NROFF Only
-Tname Specifies the name of the output terminal type.
Currently defined names are 37 for the (default)
Model 37 Teletype(R), tn300 for the GE TermiNet 300
(or any terminal without half-line capabilities),
300S for the DASI-300S, 300 for the DASI-300, and
450 for the DASI-450 (Diablo Hyterm).
-e Produce equally-spaced words in adjusted lines,
using full terminal resolution.
-h On output, use tabs during horizontal spacing to
increase speed. Device tabs setting are assumed to
be (and input tabs are initially set to) every 8
character widths.
TROFF Only
-a Send a printable (ASCII) approximation of the
results to the standard output.
-b TROFF will report whether the phototypesetter is
busy or available. No text processing is done.
-f Refrain from feeding out paper and stopping photo-
typesetter at the end of the run.
-t Direct output to the standard output instead of the
phototypesetter.
-w Wait until phototypesetter is available, if
currently busy.
Each option is invoked as a separate argument; for example,
nroff -o4,8-10 -T300S -mabc file1 file2
requests formatting of pages 4, 8, 9, and 10 of a document con-
tained in the files named file1 and file2, specifies the output
terminal as a DASI-300S, and invokes the macro package abc.
Various pre- and post-processors are available for use with NROFF
and TROFF. These include the equation preprocessors NEQN and EQN1
(for NROFF and TROFF respectively), and the table-construction
preprocessor TBL2. A reverse-line postprocessor COL3 is available
for multiple-column NROFF output on terminals without reverse-
line ability; COL expects the Model 37 Teletype escape sequences
that NROFF produces by default. TK3 is a 37 Teletype simulator
postprocessor for printing NROFF output on a Tektronix 4014. TC5
is a phototypesetter-simulator postprocessor for TROFF that pro-
duces an approximation of phototypesetter output on a Tektronix
4014. For example, in
NROFF/TROFF User's Manual USD:24-3
tbl files | eqn | troff -t options | tc
the first | indicates the piping of TBL's output to EQN's input;
the second the piping of EQN's output to TROFF's input; and the
third indicates the piping of TROFF's output to TC.
The remainder of this manual consists of: a Summary and outline;
a Reference Manual keyed to the outline; and a set of Tutorial
Examples. Another tutorial is [5].
References
[1]B. W. Kernighan, L. L. Cherry, Typesetting Mathematics -
User's Guide (Second Edition), Bell Laboratories.
[2]M. E. Lesk, Tbl - A Program to Format Tables, Bell Labora-
tories internal memorandum.
[3]Internal on-line documentation (man pages) on UNIX.
[4]B. W. Kernighan, A TROFF Tutorial, Bell Laboratories.
[5]Your site may have similar programs for more modern displays.
USD:24-4 NROFF/TROFF User's Manual
NROFF/TROFF User's Manual USD:24-3
SUMMARY OF REQUESTS AND OUTLINE OF THIS MANUAL
Request Initial If No
Form Value* Argument Notes#Explanation
1. General Explanation
2. Font and Character Size Control
.ps±N 10point previous E Point size; also \s±N.-
.fz F ±N off - E font F to point size ±N.
.fz S F ±N off - E Special Font characters to point
size ±N.
.ss N 12/36em ignored E Space-character size set to N/36em.-
.cs FNM off - P Constant character space (width)
mode (font F).-
.bd F N off - P Embolden font F by N-1 units.-
.bd S F N off - P Embolden Special Font when current
font is F.-
.ft F Roman previous E Change to font F = x, xx, or 1-4.
Also \fx,\f(xx,\fN.
.fp N F R,I,B,S ignored - Font named F mounted on physical
position 1≤N≤4.
3. Page Control
.pl ±N 11in 11in v Page length.
.bp ±N N=1 - B=,v Eject current page; next page number
N.
.pn ±N N=1 ignored - Next page number N.
.po ±N 0; 26/27in previousvPage offset.
.ne N - N=1V D,v Need N vertical space (V = vertical
spacing).
.mk R none internal D Mark current vertical place in
register R.
.rt ±N none internal D,vReturn (upward only) to marked
vertical place.
4. Text Filling, Adjusting, and Centering
.br - - B Break.
.fi fill - B,E Fill output lines.
.nf fill - B,E No filling or adjusting of output
lines.
.ad c adj,both adjust EAdjust output lines with mode c.
.na adjust - E No output line adjusting.
.ce N off N=1 B,E Center following N input text lines.
5. Vertical Spacing
.vs N 1/6in;12pts previousE,pVertical base line spacing
(V).
.ls N N=1 previous E Output N-1 Vs after each text out-
put line.
.sp N - N=1V B,v Space vertical distance N in either
direction.
.sv N - N=1V v Save vertical distance N.
.os - - - Output saved vertical distance.
.ns space - D Turn no-space mode on.
__________
*Values separated by ";" are for NROFF and TROFF respectively.
#Notes are explained at the end of this Summary and Index
-No effect in NROFF.
=The use of " ' " as control character (instead of ".")
suppresses the break function.
USD:24-4 NROFF/TROFF User's Manual
Request Initial If No
Form Value Argument NotesExplanation
.rs - - D Restore spacing; turn no-space mode
off.
6. Line Length and Indenting
.ll ±N 6.5in previous E,mLine length.
.in ±N N=0 previous B,E,mIndent.
.ti ±N - ignored B,E,m Temporary indent.
7. Macros, Strings, Diversion, and Position Traps
.de xx yy - .yy=.. -Define or redefine macro xx; end
at call of yy.
.am xx yy - .yy=.. -Append to a macro.
.ds xx string - ignored-Define a string xx containing
string.
.as xx string - ignored-Append string to string xx.
.rm xx - ignored - Remove request, macro, or string.
.rn xx yy - ignored-Rename request, macro, or string
xx to yy.
.di xx - end D Divert output to macro xx.
.da xx - end D Divert and append to xx.
.wh N xx - - v Set location trap; negative is
w.r.t. page bottom.
.ch xx N - - v Change trap location.
.dt N xx - off D,vSet a diversion trap.
.it N xx - off E Set an input-line count trap.
.em xx none none - End macro is xx.
8. Number Registers
.nr R ±N M - - u Define and set number register R;
auto-increment by M.
.af R c arabic - - Assign format to register R (c=1, i,
I, a, A).
.rr R - - - Remove register R.
9. Tabs, Leaders, and Fields
.ta Nt ... 0.8; 0.5in noneE,mTab settings; left type,
unless t=R(right), C(centered).
.tc c none none E Tab repetition character.
.lc c . none E Leader repetition character.
.fc a b off off - Set field delimiter a and pad char-
acter b.
10. Input and Output Conventions and Character Translations
.ec c \ \ - Set escape character.
.eo on - - Turn off escape character mechanism.
.lg N -;on on - Ligature mode on if N>0.
.ul N off N=1 E Underline (italicize in TROFF) N
input lines.
.cu N off N=1 E Continuous underline in NROFF; like
ul in TROFF.
.uf F Italic Italic - Underline font set to F (to be
switched to by ul).
.cc c . . E Set control character to c.
.c2 c ' ' E Set nobreak control character to c.
.tr abcd.... none - O Translate a to b, etc. on output.
11. Local Horizontal and Vertical Motions, and the Width Function
NROFF/TROFF User's Manual USD:24-5
Request Initial If No
Form Value Argument NotesExplanation
12. Overstrike, Bracket, Line-drawing, and Zero-width Functions
13. Hyphenation.
.nh hyphenate - E No hyphenation.
.hy N hyphenate hyphenateEHyphenate; N = mode.
.hc c \% \% E Hyphenation indicator character c.
.hw word1 ... ignored-Exception words.
14. Three Part Titles.
.tl 'left'center'right' - - Three part title.
.pc c % off - Page number character.
.lt ±N 6.5in previous E,mLength of title.
15. Output Line Numbering.
.nm ±N M S I off E Number mode on or off, set parame-
ters.
.nn N - N=1 E Do not number next N lines.
16. Conditional Acceptance of Input
.if c anything - - If condition c true, accept anything
as input,
for multi-line use \{anything\}.
.if !c anything - - If condition c false, accept any-
thing.
.if N anything - u If expression N > 0, accept any-
thing.
.if !N anything - u If expression N ≤ 0, accept any-
thing.
.if 'string1'string2' anything -If string1 identical to string2,
accept anything.
.if !'string1'string2' anything-If string1 not identical to
string2, accept anything.
.ie c anything - u If portion of if-else; all above
forms (like if).
.el anything - - Else portion of if-else.
17. Environment Switching.
.ev N N=0 previous - Environment switched (push down).
18. Insertions from the Standard Input
.rd prompt - prompt=BELRead insertion.
.ex - - - Exit from NROFF/TROFF.
19. Input/Output File Switching
.so filename - - Switch source file (push down).
.nx filename end-of-file-Next file.
.pi program - - Pipe output to program (NROFF
only).
20. Miscellaneous
.mc c N - off E,m Set margin character c and separa-
tion N.
.tm string - newline-Print string on terminal (UNIX
standard error output).
.ig yy - .yy=.. - Ignore till call of yy.
.pm t - all - Print macro names and sizes;
if t present, print only total of
sizes.
.ab string - - - Print a message and abort.
.fl - - B Flush output buffer.
USD:24-6 NROFF/TROFF User's Manual
Request Initial If No
Form Value Argument NotesExplanation
21. Output and Error Messages
_________________________________________________________________
Notes-
B Request normally causes a break.
D Mode or relevant parameters associated with current diversion level.
E Relevant parameters are a part of the current environment.
O Must stay in effect until logical output.
P Mode must be still or again in effect at the time of physical output.
v,p,m,uDefault scale indicator; if not specified, scale indicators are ignored.
Alphabetical Request and Section Number Cross Reference
a20 c10 di7 e18 h13 l10 ne3 os5 r18 ss2 u10
ad4 c10 ds7 fc9 h13 l10 nf4 p14 rm7 sv5 u10
af8 ce4 dt7 fi4 i16 ll6 n13 p19 rn7 ta9 vs5
am7 ch7 e10 f20 i16 ls5 n15 pl3 rr8 tc9 wh7
as7 cs2 e16 fp2 i20 l14 n15 p20 rs5 ti6
bd2 c10 em7 ft2 in6 m20 nr8 pn3 rt3 t14
bp3 da7 e10 fz2 it7 mk3 ns5 po3 s19 t20
br4 de7 e17 h13 lc9 na4 n19 ps2 sp5 t10
NROFF/TROFF User's Manual USD:24-7
Escape Sequences for Characters, Indicators, and Functions
Section Escape
Reference Sequence Meaning
10.1 \\ \ (to prevent or delay the interpretation of \)
10.1 \e Printable version of the current escape character.
2.1 \' ' (acute accent); equivalent to \(aa
2.1 \` ` (grave accent); equivalent to \(ga
2.1 \- - Minus sign in the current font
7 \. Period (dot) (see de)
11.1 \(space) Unpaddable space-size space character
11.1 \0 Digit width space
11.1 \| 1/6em narrow space character (zero width in NROFF)
11.1 \^ 1/12em half-narrow space character (zero width in NROFF)
4.1 \& Non-printing, zero width character
10.6 \! Transparent line indicator
10.7 \" Beginning of comment
7.3 \$N Interpolate argument 1≤N≤9
13 \% Default optional hyphenation character
2.1 \(xx Character named xx
7.1 \*x, \*(xx Interpolate string x or xx
9.1 \a Non-interpreted leader character
12.3 \b'abc...' Bracket building function
4.2 \c Interrupt text processing
11.1 \d Forward (down) 1/2em vertical motion (1/2 line in NROFF)
2.2 \fx,\f(xx,\fN Change to font named x or xx, or position N
11.1 \h'N ' Local horizontal motion; move right N (negative left)
11.3 \kx Mark horizontal input place in register x
12.4 \l'Nc' Horizontal line drawing function (optionally with c)
12.4 \L'Nc' Vertical line drawing function (optionally with c)
8 \nx,\n(xx Interpolate number register x or xx
12.1 \o'abc...' Overstrike characters a, b, c, ...
4.1 \p Break and spread output line
11.1 \r Reverse 1em vertical motion (reverse line in NROFF)
2.3 \sN,\s±N Point-size change function
9.1 \t Non-interpreted horizontal tab
11.1 \u Reverse (up) 1/2em vertical motion (1/2 line in NROFF)
11.1 \v'N' Local vertical motion; move down N (negative up)
11.2 \w'string' Interpolate width of string
5.2 \x'N' Extra line-space function (negative before, positive after)
12.2 \zc Print c with zero width (without spacing)
16 \{ Begin conditional input
16 \} End conditional input
10.7 \(newline) Concealed (ignored) newline
- \X X, any character not listed above
The escape sequences \\, \., \", \$, \*, \a, \n, \t, and \(new-
line) are interpreted in copy mode (S7.2).
USD:24-8 NROFF/TROFF User's Manual
Predefined General Number Registers
Section Register
Reference Name Description
3 % Current page number.
19 c. Number of lines read from current input file.
11.2 ct Character type (set by width function).
7.4 dl Width (maximum) of last completed diversion.
7.4 dn Height (vertical size) of last completed diversion.
- dw Current day of the week (1-7).
- dy Current day of the month (1-31).
11.3 hp Current horizontal place on input line (not in ditroff)
15 ln Output line number.
- mo Current month (1-12).
4.1 nl Vertical position of last printed text base-line.
11.2 sb Depth of string below base line (generated by width function).
11.2 st Height of string above base line (generated by width function).
- yr Last two digits of current year.
Predefined Read-Only Number Registers
Section Register
Reference Name Description
7.3 .$ Number of arguments available at the current macro level.
- .A Set to 1 in TROFF, if -a option used; always 1 in NROFF.
11.1 .H Available horizontal resolution in basic units.
5.3 .L Set to current line-spacing (ls) parameter
- .P Set to 1 if the current page is being printed; otherwise 0.
- .T Set to 1 in NROFF, if -T option used; always 0 in TROFF.
11.1 .V Available vertical resolution in basic units.
5.2 .a Post-line extra line-space most recently utilized using \x'N'.
19 .c Number of lines read from current input file.
7.4 .d Current vertical place in current diversion; equal to nl, if no diversion.
2.2 .f Current font as physical quadrant (1-4).
4 .h Text base-line high-water mark on current page or diversion.
6 .i Current indent.
4.2 .j Current adjustment mode and type.
4.1 .k Length of text portion on current partial output line.
6 .l Current line length.
4 .n Length of text portion on previous output line.
3 .o Current page offset.
3 .p Current page length.
2.3 .s Current point size.
7.5 .t Distance to the next trap.
4.1 .u Equal to 1 in fill mode and 0 in nofill mode.
5.1 .v Current vertical line spacing.
11.2 .w Width of previous character.
- .x Reserved version-dependent register.
- .y Reserved version-dependent register.
7.4 .z Name of current diversion.
NROFF/TROFF User's Manual USD:24-9
USD:24-8 NROFF/TROFF User's Manual
REFERENCE MANUAL
1. General Explanation
1.1.Form of input. Input consists of text lines, which are des-
tined to be printed, interspersed with control lines, which set
parameters or otherwise control subsequent processing. Control
lines begin with a control character-normally . (period) or '
(acute accent)-followed by a one or two character name that
specifies a basic request or the substitution of a user-defined
macro in place of the control line. The control character '
suppresses the break function-the forced output of a partially
filled line-caused by certain requests. The control character may
be separated from the request/macro name by white space (spaces
and/or tabs) for sthetic reasons. Names must be followed by
either space or newline. Control lines with unrecognized names
are ignored.
Various special functions may be introduced anywhere in the input
by means of an escape character, normally \. For example, the
function \nR causes the interpolation (insertion in place) of the
contents of the number register R in place of the function; here
R is either a single character name as in \nx, or left-
parenthesis-introduced, two-character name as in \n(xx.
1.2.Formatter and device resolution. TROFF internally uses 432
units/inch, (for historical reasons, corresponding to the Graphic
Systems phototypesetter which had a horizontal resolution of
1/432 inch and a vertical resolution of 1/144 inch.) NROFF inter-
nally uses 240 units/inch, corresponding to the least common mul-
tiple of the horizontal and vertical resolutions of various
typewriter-like output devices. TROFF rounds horizontal/vertical
numerical parameter input to its own internal horizontal/vertical
resolution. NROFF similarly rounds numerical input to the actual
resolution of the output device indicated by the -T option
(default Model 37 Teletype).
1.3.Numerical parameter input. Both NROFF and TROFF accept numer-
ical input with the scale indicator suffixes shown in the follow-
ing table, where S is the current type size in points, V is the
current vertical line spacing in basic units, and C is a nominal
character width in basic units.
______________________________________________________________
| Scale | | Number of basic units |
| Indicator| Meaning | TROFF NROFF |
|__________|_____________________|____________|_______________|
| i | Inch | 432 | 240 |
| c | Centimeter | 432x50/127| 240x50/127 |
| P | Pica = 1/6 inch | 72 | 240/6 |
| m | Em = S points | 6xS | C |
| n | En = Em/2 | 3xS | C, same as Em|
| p | Point = 1/72 inch | 6 | 240/72 |
| u | Basic unit | 1 | 1 |
| v | Vertical line space| V | V |
| none | Default, see below | | |
|__________|_____________________|____________|_______________|
In NROFF, both the em and the en are taken to be equal to the C,
NROFF/TROFF User's Manual USD:24-9
which is output-device dependent; common values are 1/10 and 1/12
inch. Actual character widths in NROFF need not be all the same
and constructed characters such as -> (->) are often extra wide.
The default scaling is ems for the horizontally-oriented requests
and functions ll, in, ti, ta, lt, po, mc, \h, and \l; Vs for the
vertically-oriented requests and functions pl, wh, ch, dt, sp,
sv, ne, rt, \v, \x, and \L; p for the vs request; and u for the
requests nr, if, and ie. All other requests ignore any scale
indicators. When a number register containing an already
appropriately scaled number is interpolated to provide numerical
input, the unit scale indicator u may need to be appended to
prevent an additional inappropriate default scaling. The number,
N, may be specified in decimal-fraction form but the parameter
finally stored is rounded to an integer number of basic units.
The absolute position indicator | may be prefixed to a number N
to generate the distance to the vertical or horizontal place N.
For vertically-oriented requests and functions, |N becomes the
distance in basic units from the current vertical place on the
page or in a diversion (S7.4) to the vertical place N. For all
other requests and functions, |N becomes the distance from the
current horizontal place on the input line to the horizontal
place N. For example,
.sp |3.2c
will space in the required direction to 3.2 centimeters from the
top of the page.
1.4.Numerical expressions. Wherever numerical input is expected,
an expression involving parentheses, the arithmetic operators +,
-, /, *, % (mod), and the logical operators <, >, <=, >=, = (or
==), & (and), : (or) may be used. Except where controlled by
parentheses, evaluation of expressions is left-to-right; there is
no operator precedence. In the case of certain requests, an ini-
tial + or - is stripped and interpreted as an increment or decre-
ment indicator respectively. In the presence of default scaling,
the desired scale indicator must be attached to every number in
an expression for which the desired and default scaling differ.
For example, if the number register x contains 2 and the current
point size is 10, then
.ll (4.25i+\nxP+3)/2u
will set the line length to 1/2 the sum of 4.25 inches + 2 picas
+ 30 points.
1.5.Notation. Numerical parameters are indicated in this manual
in two ways. ±N means that the argument may take the forms N, +N,
or -N and that the corresponding effect is to set the affected
parameter to N, to increment it by N, or to decrement it by N
respectively. Plain N means that an initial algebraic sign is not
an increment indicator, but merely the sign of N. Generally,
unreasonable numerical input is either ignored or truncated to a
reasonable value. For example, most requests expect to set param-
eters to non-negative values; exceptions are sp, wh, ch, nr, and
if. The requests ps, ft, po, vs, ls, ll, in, and lt restore the
previous parameter value in the absence of an argument.
Single character arguments are indicated by single lower case
letters and one/two character arguments are indicated by a pair
of lower case letters. Character string arguments are indicated
by multi-character mnemonics.
USD:24-10 NROFF/TROFF User's Manual
2. Font and Character Size Control
2.1.Character set. The TROFF character set consists of a
typesetter-dependent basic character set plus a Special Mathemat-
ical Font character set-each having 102 characters. An example of
these character sets is shown in the Appendix Table I. All print-
able ASCII characters are included, with some on the Special
Font. With three exceptions, these ASCII characters are input as
themselves, and non-ASCII characters are input in the form \(xx
where xx is a two-character name given in the Appendix Table II.
The three ASCII exceptions are mapped as follows:
____________________________________________________
| ASCII Input | Printed by TROFF |
| Character Name | Character Name |
|_________________________|_________________________|
| ' acute accent| ' close quote|
| ` grave accent| ` open quote |
| - minus | - hyphen |
|_________________________|_________________________|
The characters ', `, and - may be input by \', \`, and \- respec-
tively or by their names (Table II). The ASCII characters @, #,
", ', `, <, >, \, {, }, ~, ^, and _ exist only on the Special
Font and are printed as a 1-em space if that font is not mounted.
NROFF understands the entire TROFF character set, but can in gen-
eral print only ASCII characters, additional characters as may be
available on the output device, such characters as may be able to
be constructed by overstriking or other combination, and those
that can reasonably be mapped into other printable characters.
The exact behavior is determined by a driving table prepared for
each device. The characters ', `, and _ print as themselves.
2.2.Fonts. The default mounted fonts are Times Roman (R), Times
Italic (I), Times Bold (B), and the Special Mathematical Font (S)
on physical typesetter positions 1, 2, 3, and 4 respectively.
These fonts are used in this document. The current font, ini-
tially Roman, may be changed (among the mounted fonts) by use of
the ft request, or by imbedding at any desired point either \fx,
\f(xx, or \fN where x and xx are the name of a mounted font and N
is a numerical font position. It is not necessary to change to
the Special Font; characters on that font are automatically han-
dled. A request for a named but not-mounted font is ignored.
TROFF can be informed that any particular font is mounted by use
of the fp request. The list of known fonts is installation depen-
dent. In the subsequent discussion of font-related requests, F
represents either a one/two-character font name or the numerical
font position, 1-4. The current font is available (as numerical
position) in the read-only number register .f.
NROFF understands font control and normally underlines Italic
characters (see S10.5).
2.3.Character size. Character point sizes available are
typesetter dependent, but often include 6, 7, 8, 9, 10, 11, 12,
14, 16, 18, 20, 22, 24, 28, and 36. This is a range of 1/12 inch
to 1/2 inch. The ps request is used to change or restore the
point size. Alternatively the point size may be changed between
any two characters by imbedding a \sN at the desired point to set
NROFF/TROFF User's Manual USD:24-11
the size to N, or a \s±N (1≤N≤9) to increment/decrement the size
by N; \s0 restores the previous size. Requested point size values
that are between two valid sizes yield the larger of the two. The
current size is available in the .s register. NROFF ignores type
size control.
Request Initial If No
Form Value Argument Notes*Explanation
.ps ±N 10point previous E Point size set to ±N. Alterna-
tively imbed \sN or \s±N. Any posi-
tive size value may be requested; if
invalid, the next larger valid size
will result, with a maximum of 36. A
paired sequence +N,-N will work
because the previous requested value
is also remembered. Ignored in
NROFF.
.fz F ±N off - E The characters in font F will be
adjusted to be in size ±N. Charac-
ters in the Special Font encountered
during the use of font F will have
the same size modification. (Use the
.fz S request if different treatment
of Special Font characters is
required). .fz must follow any .fp
request for the position.
.fz S F ±N off - E The characters in the Special Font
will be in size ±N independent of
previous .fz requests.
.ss N 12/36em ignored E Space-character size is set to
N/36ems. This size is the minimum
word spacing in adjusted text.
Ignored in NROFF.
.cs FNM off - P Constant character space (width)
mode is set on for font F (if
mounted); the width of every charac-
ter will be taken to be N/36 ems. If
M is absent, the em is that of the
character's point size; if M is
given, the em is M-points. All
affected characters are centered in
this space, including those with an
actual width larger than this space.
Special Font characters occurring
while the current font is F are also
so treated. If N is absent, the mode
is turned off. The mode must be
still or again in effect when the
characters are physically printed.
Ignored in NROFF.
.bd F N off - P The characters in font F will be
artificially emboldened by printing
each one twice, separated by N-1
basic units. A reasonable value for
__________
*Notes are explained at the end of the Summary and Index above.
USD:24-12 NROFF/TROFF User's Manual
N is 3 when the character size is in
the vicinity of 10 points. If N is
missing the embolden mode is turned
off. The column heads above were
printed with .bd I 3. The mode must
be still or again in effect when the
characters are physically printed.
Ignored in NROFF.
.bd S F N off - P The characters in the Special Font
will be emboldened whenever the
current font is F. This manual was
printed with .bdSB3. The mode must
be still or again in effect when the
characters are physically printed.
.ft F Roman previous E Font changed to F. Alternatively,
imbed \fF. The font name P is
reserved to mean the previous font.
.fp N F R,I,B,S ignored - Font position. This is a statement
that a font named F is mounted on
position N (1-4). It is a fatal
error if F is not known. The photo-
typesetter has four fonts physically
mounted. Each font consists of a
film strip which can be mounted on a
numbered quadrant of a wheel. The
default mounting sequence assumed by
TROFF is R, I, B, and S on positions
1, 2, 3 and 4.
3. Page control
Top and bottom margins are not automatically provided; it is con-
ventional to define two macros and to set traps for them at vert-
ical positions 0 (top) and -N (N from the bottom). See S7 and
Tutorial Examples ST2. A pseudo-page transition onto the first
page occurs either when the first break occurs or when the first
non-diverted text processing occurs. Arrangements for a trap to
occur at the top of the first page must be completed before this
transition. In the following, references to the current diversion
(S7.4) mean that the mechanism being described works during both
ordinary and diverted output (the former considered as the top
diversion level).
The usable page width on the Graphic Systems phototypesetter was
about 7.54 inches, beginning about 1/27 inch from the left edge
of the 8 inch wide, continuous roll paper, but these characteris-
tics are typesetter- dependent. The physical limitations on NROFF
output are output-device dependent.
Request Initial If No
Form Value Argument NotesExplanation
.pl ±N 11in 11in v Page length set to ±N. The internal
limitation is about 75 inches in
TROFF and about 136 inches in NROFF.
The current page length is available
in the .p register.
.bp ±N N=1 - B*,v Begin page. The current page is
__________
*The use of " ' " as control character (instead of ".")
NROFF/TROFF User's Manual USD:24-13
ejected and a new page is begun. If
±N is given, the new page number
will be ±N. Also see request ns.
.pn ±N N=1 ignored - Page number. The next page (when it
occurs) will have the page number
±N. A pn must occur before the ini-
tial pseudo-page transition to
affect the page number of the first
page. The current page number is in
the % register.
.po ±N 0; 26/27in- previousvPage offset. The current left
margin is set to ±N. The TROFF ini-
tial value provides about 1 inch of
paper margin including the physical
typesetter margin of 1/27 inch. In
TROFF the maximum (line-
length)+(page-offset) is about 7.54
inches. See S6. The current page
offset is available in the .o regis-
ter.
.ne N - N=1V D,v Need N vertical space. If the dis-
tance, D, to the next trap position
(see S7.5) is less than N, a forward
vertical space of size D occurs,
which will spring the trap. If there
are no remaining traps on the page,
D is the distance to the bottom of
the page. If D<V, another line could
still be output and spring the trap.
In a diversion, D is the distance to
the diversion trap, if any, or is
very large.
.mk R none internal D Mark the current vertical place in
an internal register (both associ-
ated with the current diversion
level), or in register R, if given.
See rt request.
.rt ±N none internal D,vReturn upward only to a marked
vertical place in the current diver-
sion. If ±N (w.r.t. current place)
is given, the place is ±N from the
top of the page or diversion or, if
N is absent, to a place marked by a
previous mk. Note that the sp
request (S5.3) may be used in all
cases instead of rt by spacing to
the absolute place stored in a
explicit register; e. g. using the
sequence .mk R ... .sp |\nRu.
4. Text Filling, Adjusting, and Centering
4.1.Filling and adjusting. Normally, words are collected from
input text lines and assembled into a output text line until some
__________
suppresses the break function.
-Values separated by ";" are for NROFF and TROFF respectively.
USD:24-14 NROFF/TROFF User's Manual
word doesn't fit. An attempt is then made to hyphenate the word
to assemble a part of it into the output line. The spaces between
the words on the output line are then increased to spread out the
line to the current line length minus any current indent. A word
is any string of characters delimited by the space character or
the beginning/end of the input line. Any adjacent pair of words
that must be kept together (neither split across output lines nor
spread apart in the adjustment process) can be tied together by
separating them with the unpaddable space character "\ "
(backslash-space). The adjusted word spacings are uniform in
TROFF and the minimum interword spacing can be controlled with
the ss request (S2). In NROFF, they are normally nonuniform
because of quantization to character-size spaces; however, the
command line option -e causes uniform spacing with full output
device resolution. Filling, adjustment, and hyphenation (S13) can
all be prevented or controlled. The text length on the last line
output is available in the .n register, and text base-line posi-
tion on the page for this line is in the nl register. The text
base-line high-water mark (lowest place) on the current page is
in the .h register. The .k register (read-only) contains the hor-
izontal size of the text portion (without indent) of the current
partially-collected output line (if any) in the current environ-
ment.
An input text line ending with ., ?, or ! is taken to be the end
of a sentence, and an additional space character is automatically
provided during filling. Multiple inter-word space characters
found in the input are retained, except for trailing spaces; ini-
tial spaces also cause a break.
When filling is in effect, a \p may be imbedded or attached to a
word to cause a break at the end of the word and have the result-
ing output line spread out to fill the current line length.
A text input line that happens to begin with a control character
(S10.4) can be made to not look like a control line by preceding
it by the non-printing, zero-width filler character \&. Still
another way is to specify output translation of some convenient
character into the control character using tr (S10.5).
4.2.Interrupted text. The copying of a input line in nofill
(non-fill) mode can be interrupted by terminating the partial
line with a \c. The next encountered input text line will be con-
sidered to be a continuation of the same line of input text.
Similarly, a word within filled text may be interrupted by ter-
minating the word (and line) with \c; the next encountered text
will be taken as a continuation of the interrupted word. If the
intervening control lines cause a break, any partial line will be
forced out along with any partial word.
Request Initial If No
Form Value Argument NotesExplanation
.br - - B Break. The filling of the line
currently being collected is stopped
and the line is output without
adjustment. Text lines beginning
with space characters and empty text
lines (blank lines) also cause a
break.
.fi fill on - B,E Fill subsequent output lines. The
NROFF/TROFF User's Manual USD:24-15
register .u is 1 in fill mode and 0
in nofill mode.
.nf fill on - B,E Nofill. Subsequent output lines are
neither filled nor adjusted. Input
text lines are copied directly to
output lines without regard for the
current line length.
.ad c adj,both adjust ELine adjustment is begun. If fill
mode is not on, adjustment will be
deferred until fill mode is back on.
If the type indicator c is present,
the adjustment type is changed as
shown in the following table. The
type indicator can also be a value
saved from the read-only .j number
register, which is set to contain
the current adjustment mode and
type.
______________________________________
| Indicator| Adjust Type |
|__________|__________________________|
| l | adjust left margin only |
| r | adjust right margin only|
| c | center |
| b or n | adjust both margins |
| absent | unchanged |
|__________|__________________________|
.na adjust - E Noadjust. Adjustment is turned off;
the right margin will be ragged. The
adjustment type for ad is not
changed. Output line filling still
occurs if fill mode is on.
.ce N off N=1 B,E Center the next N input text lines
within the current (line-length
minus indent). If N=0, any residual
count is cleared. A break occurs
after each of the N input lines. If
the input line is too long, it will
be left adjusted.
5. Vertical Spacing
5.1.Base-line spacing. The vertical spacing (V) between the
base-lines of successive output lines can be set using the vs
request with a resolution of 1/144inch=1/2 point in TROFF, and to
the output device resolution in NROFF. V must be large enough to
accommodate the character sizes on the affected output lines. For
the common type sizes (9-12 points), usual typesetting practice
is to set V to 2 points greater than the point size; TROFF
default is 10-point type on a 12-point spacing (as in this docu-
ment). The current V is available in the .v register. Multiple-V
line separation (e.g. double spacing) may be requested with ls.
5.2.Extra line-space. If a word contains a vertically tall con-
struct requiring the output line containing it to have extra
vertical space before and/or after it, the extra-line-space
USD:24-16 NROFF/TROFF User's Manual
function \x'N' can be imbedded in or attached to that word. In
this and other functions having a pair of delimiters around their
parameter (here '), the delimiter choice is arbitrary, except
that it can't look like the continuation of a number expression
for N. If N is negative, the output line containing the word will
be preceded by N extra vertical space; if N is positive, the out-
put line containing the word will be followed by N extra vertical
space. If successive requests for extra space apply to the same
line, the maximum values are used. The most recently utilized
post-line extra line-space is available in the .a register.
5.3.Blocks of vertical space. A block of vertical space is ordi-
narily requested using sp, which honors the no-space mode and
which does not space past a trap. A contiguous block of vertical
space may be reserved using sv.
Request Initial If No
Form Value Argument NotesExplanation
.vs N 1/6in;12pts previousE,pSet vertical base-line spacing
size V. Transient extra vertical
space available with \x'N' (see
above).
.ls N N=1 previous E Line spacing set to ±N. N-1 Vs
(blank lines) are appended to each
output text line. The (read-only)
number register .L is set to contain
the current line-spacing value.
Appended blank lines are omitted, if
the text or previous appended blank
line reached a trap position.
.sp N - N=1V B,v Space vertically in either direc-
tion. If N is negative, the motion
is backward (upward) and is limited
to the distance to the top of the
page. Forward (downward) motion is
truncated to the distance to the
nearest trap. If the no-space mode
is on, no spacing occurs (see ns,
and rs below).
.sv N - N=1V v Save a contiguous vertical block of
size N. If the distance to the next
trap is greater than N, N vertical
space is output. No-space mode has
no effect. If this distance is less
than N, no vertical space is immedi-
ately output, but N is remembered
for later output (see os). Subse-
quent sv requests will overwrite any
still remembered N.
.os - - - Output saved vertical space. No-
space mode has no effect. Used to
finally output a block of vertical
space requested by an earlier sv
request.
.ns space - D No-space mode turned on. When on,
the no-space mode inhibits sp
requests and bp requests without a
NROFF/TROFF User's Manual USD:24-17
next page number. The no-space mode
is turned off when a line of output
occurs, or with rs.
.rs space - D Restore spacing. The no-space mode
is turned off.
Blank text line. - B Causes a break and outputs a blank
line just like sp 1.
6. Line Length and Indenting
The maximum line length for fill mode may be set with ll. The
indent may be set with in; an indent applicable to only the next
output line may be set with ti. The line length includes indent
space but not page offset space. The line-length minus the indent
is the basis for centering with ce. The effect of ll, in, or ti
is delayed, if a partially collected line exists, until after
that line is output. In fill mode the length of text on an output
line is less than or equal to the line length minus the indent.
The current line length and indent are available in registers .l
and .i respectively. The length of three-part titles produced by
tl (see S14) is independently set by lt.
Request Initial If No
Form Value Argument NotesExplanation
.ll ±N 6.5in previous E,mLine length is set to ±N. In
TROFF the maximum (line-
length)+(page-offset) is about 7.54
inches.
.in ±N N=0 previous B,E,mIndent is set to ±N. The indent
is prepended to each output line.
.ti ±N - ignored B,E,m Temporary indent. The next output
text line will be indented a dis-
tance ±N with respect to the current
indent. The resulting total indent
may not be negative. The current
indent is not changed.
7. Macros, Strings, Diversion, and Position Traps
7.1.Macros and strings. A macro is a named set of arbitrary lines
that may be invoked by name or with a trap. A string is a named
string of characters, not including a newline character, that may
be interpolated by name at any point. Request, macro, and string
names share the same name list. Macro and string names may be one
or two characters long and may usurp previously defined request,
macro, or string names. Any of these entities may be renamed with
rn or removed with rm. Macros are created by de and di, and
appended to by am and da; di and da cause normal output to be
stored in a macro. Strings are created by ds and appended to by
as. A macro is invoked in the same way as a request; a control
line beginning .xx will interpolate the contents of macro xx. The
remainder of the line may contain up to nine arguments. The
strings x and xx are interpolated at any desired point with \*x
and \*(xx respectively. String references and macro invocations
may be nested.
7.2.Copy mode input interpretation. During the definition and
extension of strings and macros (not by diversion) the input is
read in copy mode. The input is copied without interpretation
except that:
+ The contents of number registers indicated by \n are interpolated.
USD:24-18 NROFF/TROFF User's Manual
+ Strings indicated by \* are interpolated.
+ Arguments indicated by \$ are interpolated.
+ Concealed newlines indicated by \(newline) are eliminated.
+ Comments indicated by \" are eliminated.
+ \t and \a are interpreted as ASCII horizontal tab and SOH respectively (S9).
+ \\ is interpreted as \.
+ \. is interpreted as ".".
These interpretations can be suppressed by prepending a \. For
example, since \\ maps into a \, \\n will copy as \n which will
be interpreted as a number register indicator when the macro or
string is reread.
7.3.Arguments. When a macro is invoked by name, the remainder of
the line is taken to contain up to nine arguments. The argument
separator is the space character, and arguments may be surrounded
by double-quotes to permit imbedded space characters. Pairs of
double-quotes may be imbedded in double-quoted arguments to
represent a single double-quote. If the desired arguments won't
fit on a line, a concealed newline may be used to continue on the
next line.
When a macro is invoked the input level is pushed down and any
arguments available at the previous level become unavailable
until the macro is completely read and the previous level is
restored. A macro's own arguments can be interpolated at any
point within the macro with \$N, which interpolates the Nth argu-
ment (1≤N≤9). If an invoked argument doesn't exist, a null string
results. For example, the macro xx may be defined by
.de xx \"begin definition
Today is \\$1 the \\$2.
.. \"end definition
and called by
.xx Monday 14th
to produce the text
Today is Monday the 14th.
Note that the \$ was concealed in the definition with a prepended
\. The number of currently available arguments is in the .$
register.
No arguments are available at the top (non-macro) level in this
implementation. Because string referencing is implemented as a
input-level push down, no arguments are available from within a
string. No arguments are available within a trap-invoked macro.
Arguments are copied in copy mode onto a stack where they are
available for reference. The mechanism does not allow an argument
to contain a direct reference to a long string (interpolated at
copy time) and it is advisable to conceal string references (with
an extra \) to delay interpolation until argument reference time.
7.4.Diversions. Processed output may be diverted into a macro for
purposes such as footnote processing (see Tutorial ST5) or deter-
mining the horizontal and vertical size of some text for condi-
tional changing of pages or columns. A single diversion trap may
be set at a specified vertical position. The number registers dn
and dl respectively contain the vertical and horizontal size of
the most recently ended diversion. Processed text that is
diverted into a macro retains the vertical size of each of its
lines when reread in nofill mode regardless of the current V.
Constant-spaced (cs) or emboldened (bd) text that is diverted can
NROFF/TROFF User's Manual USD:24-19
be reread correctly only if these modes are again or still in
effect at reread time. One way to do this is to imbed in the
diversion the appropriate cs or bd requests with the transparent
mechanism described in S10.6.
Diversions may be nested and certain parameters and registers are
associated with the current diversion level (the top non-
diversion level may be thought of as the 0th diversion level).
These are the diversion trap and associated macro, no-space mode,
the internally-saved marked place (see mk and rt), the current
vertical place (.d register), the current high-water text base-
line (.h register), and the current diversion name (.z register).
7.5.Traps. Three types of trap mechanisms are available-page
traps, a diversion trap, and an input-line-count trap. Macro-
invocation traps may be planted using wh at any page position
including the top. This trap position may be changed using ch.
Trap positions at or below the bottom of the page have no effect
unless or until moved to within the page or rendered effective by
an increase in page length. Two traps may be planted at the same
position only by first planting them at different positions and
then moving one of the traps; the first planted trap will conceal
the second unless and until the first one is moved (see Tutorial
Examples ST5). If the first one is moved back, it again conceals
the second trap. The macro associated with a page trap is
automatically invoked when a line of text is output whose verti-
cal size reaches or sweeps past the trap position. Reaching the
bottom of a page springs the top-of-page trap, if any, provided
there is a next page. The distance to the next trap position is
available in the .t register; if there are no traps between the
current position and the bottom of the page, the distance
returned is the distance to the page bottom.
A macro-invocation trap effective in the current diversion may be
planted using dt. The .t register works in a diversion; if there
is no subsequent trap a large distance is returned. For a
description of input-line-count traps, see the it request below.
Request Initial If No
Form Value Argument NotesExplanation
.de xx yy - .yy=.. -Define or redefine the macro xx.
The contents of the macro begin on
the next input line. Input lines are
copied in copy mode until the defin-
ition is terminated by a line begin-
ning with .yy, whereupon the macro
yy is called. In the absence of yy,
the definition is terminated by a
line beginning with "..". A macro
may contain de requests provided the
terminating macros differ or the
contained definition terminator is
concealed. ".." can be concealed as
\\.. which will copy as \.. and be
reread as "..".
.am xx yy - .yy=.. -Append to macro (append version
of de).
.ds xx string - ignored-Define a string xx containing
string. Any initial double-quote in
USD:24-20 NROFF/TROFF User's Manual
string is stripped off to permit
initial blanks.
.as xx string - ignored-Append string to string xx
(append version of ds).
.rm xx - ignored - Remove request, macro, or string.
The name xx is removed from the name
list and any related storage space
is freed. Subsequent references will
have no effect.
.rn xx yy - ignored-Rename request, macro, or string
xx to yy. If yy exists, it is first
removed.
.di xx - end D Divert output to macro xx. Normal
text processing occurs during diver-
sion except that page offsetting is
not done. The diversion ends when
the request di or da is encountered
without an argument; extraneous
requests of this type should not
appear when nested diversions are
being used.
.da xx - end D Divert, appending to xx (append ver-
sion of di).
.wh N xx - - v Install a trap to invoke xx at
page position N; a negative N will
be interpreted with respect to the
page bottom. Any macro previously
planted at N is replaced by xx. A
zero N refers to the top of a page.
In the absence of xx, the first
found trap at N, if any, is removed.
.ch xx N - - v Change the trap position for macro
xx to be N. In the absence of N, the
trap, if any, is removed.
.dt N xx - off D,vInstall a diversion trap at posi-
tion N in the current diversion to
invoke macro xx. Another dt will
redefine the diversion trap. If no
arguments are given, the diversion
trap is removed.
.it N xx - off E Set an input-line-count trap to
invoke the macro xx after N lines of
text input have been read (control
or request lines don't count). The
text may be in-line text or text
interpolated by inline or trap-
invoked macros.
.em xx none none - The macro xx will be invoked when
all input has ended. The effect is
the same as if the contents of xx
had been at the end of the last file
processed.
8. Number Registers
A variety of parameters are available to the user as predefined,
named number registers (see Summary and Index, page 7). In
NROFF/TROFF User's Manual USD:24-21
addition, the user may define his own named registers. Register
names are one or two characters long and do not conflict with
request, macro, or string names. Except for certain predefined
read-only registers, a number register can be read, written,
automatically incremented or decremented, and interpolated into
the input in a variety of formats. One common use of user-defined
registers is to automatically number sections, paragraphs, lines,
etc. A number register may be used any time numerical input is
expected or desired and may be used in numerical expressions
(S1.4).
Number registers are created and modified using nr, which speci-
fies the name, numerical value, and the auto-increment size.
Registers are also modified, if accessed with an auto-
incrementing sequence. If the registers x and xx both contain N
and have the auto-increment size M, the following access
sequences have the effect shown:
_____________________________________________
| | Effect on | Value |
| Sequence| Register | Interpolated|
|_________|____________________|_____________|
| \nx | none | N |
| \n(xx | none | N |
| \n+x | x incremented by M | N+M |
| \n-x | x decremented by M | N-M |
| \n+(xx | xx incremented by M| N+M |
| \n-(xx | xx decremented by M| N-M |
|_________|____________________|_____________|
When interpolated, a number register is converted to decimal
(default), decimal with leading zeros, lower-case Roman, upper-
case Roman, lower-case sequential alphabetic, or upper-case
sequential alphabetic according to the format specified by af.
Request Initial If No
Form Value Argument NotesExplanation
.nr R ±N M - - u The number register R is assigned
the value ±N with respect to the
previous value, if any. The incre-
ment for auto-incrementing is set to
M.
.af R c arabic - - Assign format c to register R. The
available formats are:
____________________________________________
| | Numbering |
| Format| Sequence |
|_______|___________________________________|
| 1 | 0,1,2,3,4,5,... |
| 001 | 000,001,002,003,004,005,... |
| i | 0,i,ii,iii,iv,v,... |
| I | 0,I,II,III,IV,V,... |
| a | 0,a,b,c,...,z,aa,ab,...,zz,aaa,...|
| A | 0,A,B,C,...,Z,AA,AB,...,ZZ,AAA,...|
|_______|___________________________________|
USD:24-22 NROFF/TROFF User's Manual
An arabic format having N digits
specifies a field width of N digits
(example 2 above). The read-only
registers and the width function
(S11.2) are always arabic.
.rr R - ignored - Remove register R. If many registers
are being created dynamically, it
may become necessary to remove no
longer used registers to recapture
internal storage space for newer
registers.
9. Tabs, Leaders, and Fields
9.1.Tabs and leaders. The ASCII horizontal tab character and the
ASCII SOH (hereafter known as the leader character) can both be
used to generate either horizontal motion or a string of repeated
characters. The length of the generated entity is governed by
internal tab stops specifiable with ta. The default difference is
that tabs generate motion and leaders generate a string of
periods; tc and lc offer the choice of repeated character or
motion. There are three types of internal tab stops-left adjust-
ing, right adjusting, and centering. In the following table: D is
the distance from the current position on the input line (where a
tab or leader was found) to the next tab stop; next-string con-
sists of the input characters following the tab (or leader) up to
the next tab (or leader) or end of line; and W is the width of
next-string.
___________________________________________________________
| Tab | Length of motion or| Location of |
| type | repeated characters| next-string |
|_________|____________________|___________________________|
| Left | D | Following D |
| Right | D-W | Right adjusted within D |
| Centered| D-W/2 | Centered on right end of D|
|_________|____________________|___________________________|
The length of generated motion is allowed to be negative, but
that of a repeated character string cannot be. Repeated character
strings contain an integer number of characters, and any residual
distance is prepended as motion. Tabs or leaders found after the
last tab stop are ignored, but may be used as next-string termi-
nators.
Tabs and leaders are not interpreted in copy mode. \t and \a
always generate a non-interpreted tab and leader respectively,
and are equivalent to actual tabs and leaders in copy mode.
9.2.Fields. A field is contained between a pair of field delim-
iter characters, and consists of sub-strings separated by padding
indicator characters. The field length is the distance on the
input line from the position where the field begins to the next
tab stop. The difference between the total length of all the
sub-strings and the field length is incorporated as horizontal
padding space that is divided among the indicated padding places.
The incorporated padding is allowed to be negative. For example,
if the field delimiter is # and the padding indicator is ^,
#^xxx^right# specifies a right-adjusted string with the string
NROFF/TROFF User's Manual USD:24-23
xxx centered in the remaining space.
Request Initial If No
Form Value Argument NotesExplanation
.ta Nt ... 8n; 0.5in noneE,mSet tab stops and types. t=R,
right adjusting; t=C, centering; t
absent, left adjusting. TROFF tab
stops are preset every 0.5in.; NROFF
every 8 character widths. The stop
values are separated by spaces, and
a value preceded by + is treated as
an increment to the previous stop
value.
.tc c none none E The tab repetition character becomes
c, or is removed specifying motion.
.lc c . none E The leader repetition character
becomes c, or is removed specifying
motion.
.fc a b off off - The field delimiter is set to a; the
padding indicator is set to the
space character or to b, if given.
In the absence of arguments the
field mechanism is turned off.
10. Input and Output Conventions and Character Translations
10.1.Input character translations. Ways of inputting the graphic
character set were discussed in S2.1. The ASCII control charac-
ters horizontal tab (S9.1), SOH (S9.1), and backspace (S10.3) are
discussed elsewhere. The newline delimits input lines. In addi-
tion, STX, ETX, ENQ, ACK, and BEL are accepted, and may be used
as delimiters or translated into a graphic with tr (S10.5). All
others are ignored.
The escape character \ introduces escape sequences-causes the
following character to mean another character, or to indicate
some function. A complete list of such sequences is given in the
Summary and Index on page 6. \ should not be confused with the
ASCII control character ESC of the same name. The escape charac-
ter \ can be input with the sequence \\. The escape character can
be changed with ec, and all that has been said about the default
\ becomes true for the new escape character. \e can be used to
print whatever the current escape character is. If necessary or
convenient, the escape mechanism may be turned off with eo, and
restored with ec.
Request Initial If No
Form Value Argument NotesExplanation
.ec c \ \ - Set escape character to \, or to c,
if given.
.eo on - - Turn escape mechanism off.
10.2.Ligatures. Five ligatures are available in the current TROFF
character set - fi, fl, ff, ffi, and ffl. They may be input (even
in NROFF) by \(fi, \(fl, \(ff, \(Fi, and \(Fl respectively. The
ligature mode is normally on in TROFF, and automatically invokes
ligatures during input.
USD:24-24 NROFF/TROFF User's Manual
Request Initial If No
Form Value Argument NotesExplanation
.lg N off; on on - Ligature mode is turned on if N is
absent or non-zero, and turned off
if N=0. If N=2, only the two-
character ligatures are automati-
cally invoked. Ligature mode is
inhibited for request, macro,
string, register, or file names, and
in copy mode. No effect in NROFF.
10.3.Backspacing, underlining, overstriking, etc. Unless in copy
mode, the ASCII backspace character is replaced by a backward
horizontal motion having the width of the space character. Under-
lining as a form of line-drawing is discussed in S12.4. A gen-
eralized overstriking function is described in S12.1.
NROFF automatically underlines characters in the underline font,
specifiable with uf, normally Times Italic on font position 2
(see S2.2). In addition to ft and \fF, the underline font may be
selected by ul and cu. Underlining is restricted to an output-
device-dependent subset of reasonable characters.
Request Initial If No
Form Value Argument NotesExplanation
.ul N off N=1 E Underline in NROFF (italicize in
TROFF) the next N input text lines.
Actually, switch to underline font,
saving the current font for later
restoration; other font changes
within the span of a ul will take
effect, but the restoration will
undo the last change. Output gen-
erated by tl (S14) is affected by
the font change, but does not decre-
ment N. If N>1, there is the risk
that a trap interpolated macro may
provide text lines within the span;
environment switching can prevent
this.
.cu N off N=1 E A variant of ul that causes every
character to be underlined in NROFF.
Identical to ul in TROFF.
.uf F Italic Italic - Underline font set to F. In NROFF, F
may not be on position 1 (initially
Times Roman).
10.4.Control characters. Both the control character . and the
no-break control character ' may be changed, if desired. Such a
change must be compatible with the design of any macros used in
the span of the change, and particularly of any trap-invoked mac-
ros.
Request Initial If No
Form Value Argument NotesExplanation
.cc c . . E The basic control character is set
to c, or reset to ".".
.c2 c ' ' E The nobreak control character is set
to c, or reset to "'".
10.5.Output translation. One character can be made a stand-in for
NROFF/TROFF User's Manual USD:24-25
another character using tr. All text processing (e. g. character
comparisons) takes place with the input (stand-in) character
which appears to have the width of the final character. The
graphic translation occurs at the moment of output (including
diversion).
Request Initial If No
Form Value Argument NotesExplanation
.tr abcd.... none - O Translate a into b, c into d, etc.
If an odd number of characters is
given, the last one will be mapped
into the space character. To be con-
sistent, a particular translation
must stay in effect from input to
output time.
10.6.Transparent throughput. An input line beginning with a \! is
read in copy mode and transparently output (without the initial
\!); the text processor is otherwise unaware of the line's pres-
ence. This mechanism may be used to pass control information to a
post-processor or to imbed control lines in a macro created by a
diversion.
10.7.Comments and concealed newlines. An uncomfortably long input
line that must stay one line (e. g. a string definition, or
nofilled text) can be split into many physical lines by ending
all but the last one with the escape \. The sequence \(newline)
is always ignored-except in a comment. Comments may be imbedded
at the end of any line by prefacing them with \". The newline at
the end of a comment cannot be concealed. A line beginning with
\" will appear as a blank line and behave like .sp 1; a comment
can be on a line by itself by beginning the line with .\".
11. Local Horizontal and Vertical Motions, and the Width Function
11.1.Local Motions. The functions \v'N' and \h'N' can be used for
local vertical and horizontal motion respectively. The distance N
may be negative; the positive directions are rightward and down-
ward. A local motion is one contained within a line. To avoid
unexpected vertical dislocations, it is necessary that the net
vertical local motion within a word in filled text and otherwise
within a line balance to zero. The above and certain other escape
sequences providing local motion are summarized in the following
table.
______________________________________________________________________________________
| Vertical | Effect in | Horizontal | Effect in |
| Local Motion| TROFF NROFF | Local Motion| TROFF NROFF |
|_____________|___________________________|_____________|_____________________________|
| \v'N' | Move distance N | \h'N' | Move distance N |
|_____________|___________________________| \(space) | Unpaddable space-size space |
| \u | 1/2 em up | 1/2 line up | \0 | Digit-size space |
| \d | 1/2 em down| 1/2 line down|_____________|_____________________________|
| \r | 1 em up | 1 line up | \| | 1/6 em space | ignored |
| | | | \^ | 1/12 em space| ignored |
|_____________|____________|______________|_____________|______________|______________|
As an example, E2 could be generated by the sequence
E\s-2\v'-0.4m'2\v'0.4m'\s+2; it should be noted in this example
that the 0.4 em vertical motions are at the smaller size.
USD:24-26 NROFF/TROFF User's Manual
11.2.Width Function. The width function \w'string' generates the
numerical width of string (in basic units). Size and font changes
may be safely imbedded in string, and will not affect the current
environment. For example, .ti -\w'1. 'u could be used to tem-
porarily indent leftward a distance equal to the size of the
string "1. ".
The width function also sets three number registers. The regis-
ters st and sb are set respectively to the highest and lowest
extent of string relative to the baseline; then, for example, the
total height of the string is \n(stu-\n(sbu. In TROFF the number
register ct is set to a value between 0 and 3: 0 means that all
of the characters in string were short lower case characters
without descenders (like e); 1 means that at least one character
has a descender (like y); 2 means that at least one character is
tall (like H); and 3 means that both tall characters and charac-
ters with descenders are present.
11.3.Mark horizontal place. The escape sequence \kx will cause
the current horizontal position in the input line to be stored in
register x. As an example, the construction
\kxword\h'|\nxu+2u'word will embolden word by backing up to
almost its beginning and overprinting it, resulting in word.
12. Overstrike, Bracket, Line-drawing, and Zero-width Functions
12.1.Overstriking. Automatically centered overstriking of up to
nine characters is provided by the overstrike function
\o'string'. The characters in string are overprinted with centers
aligned; the total width is that of the widest character. string
should not contain local vertical motion. As examples, \o'e\''
produces e', and \o'\(mo\(sl' produces <-/.
12.2.Zero-width characters. The function \zc will output c
without spacing over it, and can be used to produce left-aligned
overstruck combinations. As examples, \z\(ci\(pl will produce •,
and \(br\z\(rn\(ul\(br will produce the smallest possible con-
structed box |~_|.
12.3.Large Brackets. The Special Mathematical Font contains a
number of bracket construction pieces (|||||||||||) that can be
combined into various bracket styles. The function \b'string' may
be used to pile up vertically the characters in string (the first
character on top and the last at the bottom); the characters are
vertically separated by 1 em and the total pile is centered 1/2em
above the current baseline (1/2 line in NROFF). For example,
\b'\(lc\(lf'E\|\b'\(rc\(rf'\x'-0.5m'\x'0.5m' produces |
|E|
|.
12.4.Line drawing. The function \l'Nc' will draw a string of
repeated c's towards the right for a distance N. (\l is \(lower
case L). If c looks like a continuation of an expression for N,
it may insulated from N with a \&. If c is not specified, the _
(baseline rule) is used (underline character in NROFF). If N is
negative, a backward horizontal motion of size N is made before
drawing the string. Any space resulting from N/(size of c) having
a remainder is put at the beginning (left end) of the string. In
the case of characters that are designed to be connected such as
baseline-rule _, underrule _, and root-en ~, the remainder space
is covered by over-lapping. If N is less than the width of c, a
single c is centered on a distance N. As an example, a macro to
underscore a string can be written
NROFF/TROFF User's Manual USD:24-27
.de us
\\$1\l'|0\(ul'
..
or one to draw a box around a string
.de bx
\(br\|\\$1\|\(br\l'|0\(rn'\l'|0\(ul'
..
such that
.us "underlined words"
and
.bx "words in a box"
yield _n__e__l__n__d___o__d__ and _̅wo̅r̅d̅s̅_̅ _̅n_̅ _̅ ̅_̅ox̅|̅.̅
The function \L'Nc' will draw a vertical line consisting of the
(optional) character c stacked vertically apart 1em (1 line in
NROFF), with the first two characters overlapped, if necessary,
to form a continuous line. The default character is the box rule
| (\(br); the other suitable character is the bold vertical |
(\(bv). The line is begun without any initial motion relative to
the current base line. A positive N specifies a line drawn down-
ward and a negative N specifies a line drawn upward. After the
line is drawn no compensating motions are made; the instantaneous
b_s__l__n____s___t___h___e_n_d___f___h____i__e__________________________________
|he horizontal and vertical line drawing functions may be used in |
|ombination to produce large boxes. The zero-width box-rule and |
|he 1/2-em wide underrule were designed to form corners when |
|sing 1-em vertical spacings. For example the macro |
| .de eb |
| .sp -1 \"compensate for next automatic base-line spacing |
| .nf \"avoid possibly overflowing word buffer |
| \h'-.5n'\L'|\\nau-1'\l'\\n(.lu+1n\(ul'\L'-|\\nau+1'\l'|0u-.5n\(|ul' \"draw box
| .fi |
| .. |
|ill draw a box around some text whose beginning vertical place |
|as saved in number register a (e. g. using .mk a) as done for |
|__i____a__a__r__p__.______________________________________________________|
13. Hyphenation.
The automatic hyphenation may be switched off and on. When
switched on with hy, several variants may be set. A hyphenation
indicator character may be imbedded in a word to specify desired
hyphenation points, or may be prepended to suppress hyphenation.
In addition, the user may specify a small exception word list.
Only words that consist of a central alphabetic string surrounded
by (usually null) non-alphabetic strings are considered candi-
dates for automatic hyphenation. Words that were input containing
hyphens (minus), em-dashes (\(em), or hyphenation indicator
characters-such as mother-in-law-are always subject to splitting
after those characters, whether or not automatic hyphenation is
on or off.
Request Initial If No
Form Value Argument NotesExplanation
.nh hyphenate - E Automatic hyphenation is turned
off.
.hyN on,N=1 on,N=1 E Automatic hyphenation is turned on
for N≥1, or off for N=0. If N=2,
last lines (ones that will cause a
USD:24-28 NROFF/TROFF User's Manual
trap) are not hyphenated. For N=4
and 8, the last and first two char-
acters respectively of a word are
not split off. These values are
additive; i. e. N=14 will invoke all
three restrictions.
.hc c \% \% E Hyphenation indicator character is
set to c or to the default \%. The
indicator does not appear in the
output.
.hw word1 ... ignored-Specify hyphenation points in
words with imbedded minus signs.
Versions of a word with terminal s
are implied; i. e. dig-it implies
dig-its. This list is examined ini-
tially and after each suffix strip-
ping. The space available is small-
about 128 characters.
14. Three Part Titles.
The titling function tl provides for automatic placement of three
fields at the left, center, and right of a line with a title-
length specifiable with lt. tl may be used anywhere, and is
independent of the normal text collecting process. A common use
is in header and footer macros.
Request Initial If No
Form Value Argument NotesExplanation
.tl 'left'center'right' - - The strings left, center, and
right are respectively left-
adjusted, centered, and right-
adjusted in the current title-
length. Any of the strings may be
empty, and overlapping is permitted.
If the page-number character (ini-
tially %) is found within any of the
fields it is replaced by the current
page number having the format
assigned to register %. Any charac-
ter may be used as the string delim-
iter.
.pc c % off - The page number character is set to
c, or removed. The page-number
register remains %.
.lt ±N 6.5in previous E,mLength of title set to ±N. The
line-length and the title-length are
independent. Indents do not apply to
titles; page-offsets do.
15. Output Line Numbering.
Automatic sequence numbering of output lines may be requested
with nm. When in effect, a three-digit, arabic number plus a
3 digit-space is prepended to output text lines. The text lines
are thus offset by four digit-spaces, and otherwise retain
their line length; a reduction in line length may be desired
6 to keep the right margin aligned with an earlier margin.
Blank lines, other vertical spaces, and lines generated by tl
are not numbered. Numbering can be temporarily suspended with
NROFF/TROFF User's Manual USD:24-29
9 nn, or with an .nm followed by a later .nm +0. In addition, a
line number indent I, and the number-text separation S may be
specified in digit-spaces. Further, it can be specified that
12 only those line numbers that are multiples of some number M
are to be printed (the others will appear as blank number
fields).
Request Initial If No
Form Value Argument NotesExplanation
.nm ±N M S I off E Line number mode. If ±N is given,
line numbering is turned on, and the
next output line numbered is num-
bered ±N. Default values are M=1,
S=1, and I=0. Parameters correspond-
ing to missing arguments are unaf-
fected; a non-numeric argument is
considered missing. In the absence
of all arguments, numbering is
turned off; the next line number is
preserved for possible further use
in number register ln.
.nn N - N=1 E The next N text output lines are not
numbered.
15 As an example, the paragraph portions of this section are
numbered with M=3: .nm 1 3 was placed at the beginning; .nm
was placed at the end of the first paragraph; and .nm +0 was
18 placed in front of this paragraph; and .nm finally placed at
the end. Line lengths were also changed (by \w'0000'u) to
keep the right side aligned. Another example is .nm +5 5 x 3
21 which turns on numbering with the line number of the next
line to be 5 greater than the last numbered line, with M=5,
with spacing S untouched, and with the indent I set to 3.
16. Conditional Acceptance of Input
In the following, c is a one-character, built-in condition name,
! signifies not, N is a numerical expression, string1 and string2
are strings delimited by any non-blank, non-numeric character not
in the strings, and anything represents what is conditionally
accepted.
Request Initial If No
Form Value Argument NotesExplanation
.if c anything - - If condition c true, accept anything
as input; in multi-line case use
\{anything\}.
.if !c anything - - If condition c false, accept any-
thing.
.if N anything - u If expression N > 0, accept any-
thing.
.if !N anything - u If expression N ≤ 0, accept any-
thing.
.if 'string1'string2' anything -If string1 identical to string2,
accept anything.
.if !'string1'string2' anything-If string1 not identical to
string2, accept anything.
.ie c anything - u If portion of if-else; all above
forms (like if).
.el anything - - Else portion of if-else.
USD:24-30 NROFF/TROFF User's Manual
The built-in condition names are:
________________________________________
| Condition| |
| Name | True If |
|__________|____________________________|
| o | Current page number is odd |
| e | Current page number is even|
| t | Formatter is TROFF |
| n | Formatter is NROFF |
|__________|____________________________|
If the condition c is true, or if the number N is greater than
zero, or if the strings compare identically (including motions
and character size and font), anything is accepted as input. If a
! precedes the condition, number, or string comparison, the sense
of the acceptance is reversed.
Any spaces between the condition and the beginning of anything
are skipped over. The anything can be either a single input line
(text, macro, or whatever) or a number of input lines. In the
multi-line case, the first line must begin with a left delimiter
\{ and the last line must end with a right delimiter \}.
The request ie (if-else) is identical to if except that the
acceptance state is remembered. A subsequent and matching el
(else) request then uses the reverse sense of that state. ie - el
pairs may be nested.
Some examples are:
.if e .tl 'Even Page %'''
which outputs a title if the page number is even; and
.ie \n%>1 \{\
'sp 0.5i
.tl 'Page %'''
'sp |1.2i \}
.el .sp |2.5i
which treats page 1 differently from other pages.
17. Environment Switching.
A number of the parameters that control the text processing are
gathered together into an environment, which can be switched by
the user. The environment parameters are those associated with
requests noting E in their Notes column; in addition, partially
collected lines and words are in the environment. Everything else
is global; examples are page-oriented parameters, diversion-
oriented parameters, number registers, and macro and string
definitions. All environments are initialized with default param-
eter values.
Request Initial If No
Form Value Argument NotesExplanation
.ev N N=0 previous - Environment switched to environ-
ment 0≤N≤2. Switching is done in
push-down fashion so that restoring
a previous environment must be done
with .ev rather than specific refer-
ence.
18. Insertions from the Standard Input
The input can be temporarily switched to the system standard
NROFF/TROFF User's Manual USD:24-31
input with rd, which will switch back when two newlines in a row
are found (the extra blank line is not used). This mechanism is
intended for insertions in form-letter-like documentation. On
UNIX, the standard input can be the user's keyboard, a pipe, or a
file.
Request Initial If No
Form Value Argument NotesExplanation
.rd prompt - prompt=BELRead insertion from the stan-
dard input until two newlines in a
row are found. If the standard input
is the user's keyboard, prompt (or a
BEL) is written onto the user's ter-
minal. rd behaves like a macro, and
arguments may be placed after
prompt.
.ex - - - Exit from NROFF/TROFF. Text process-
ing is terminated exactly as if all
input had ended.
If insertions are to be taken from the terminal keyboard while
output is being printed on the terminal, the command line option
-q will turn off the echoing of keyboard input and prompt only
with BEL. The regular input and insertion input cannot simultane-
ously come from the standard input.
As an example, multiple copies of a form letter may be prepared
by entering the insertions for all the copies in one file to be
used as the standard input, and causing the file containing the
letter to reinvoke itself using nx (S19); the process would ulti-
mately be ended by an ex in the insertion file.
19. Input/Output File Switching
The (read-only) number register .c contains the input line number
in the current input file. The number register c. is a general
register serving the same purpose.
Request Initial If No
Form Value Argument NotesExplanation
.so filename - - Switch source file. The top input
(file reading) level is switched to
filename. The effect of an so
encountered in a macro occurs
immediately. When the new file ends,
input is again taken from the origi-
nal file. so's may be nested.
.nx filename end-of-file-Next file is filename. The
current file is considered ended,
and the input is immediately
switched to filename.
.pi program - - Pipe output to program (NROFF
only). This request must occur
before any printing occurs. No argu-
ments are transmitted to program.
20. Miscellaneous
Request Initial If No
Form Value Argument NotesExplanation
.mc c N - off E,m Specifies that a margin character c |
appear a distance N to the right of |
the right margin after each non- |
USD:24-32 NROFF/TROFF User's Manual
empty text line (except those pro- |
duced by tl). If the output line is |
too-long (as can happen in nofill |
mode) the character will be appended |
to the line. If N is not given, the |
previous N is used; the initial N is |
0.2 inches in NROFF and 1em in |
TROFF. The margin character used |
with this paragraph was a 12-point |
box-rule. |
.tm string - newline-After skipping initial blanks,
string (rest of the line) is read in
copy mode and written on the user's
terminal. (see S21).
.ig yy - .yy=.. - Ignore input lines. ig behaves
exactly like de (S7) except that the
input is discarded. The input is
read in copy mode, and any auto-
incremented registers will be
affected.
.pm t - all - Print macros. The names and sizes of
all of the defined macros and
strings are printed on the user's
terminal; if t is given, only the
total of the sizes is printed. The
sizes is given in blocks of 128
characters.
.ab string - - - Print string on standard error and
terminate immediately. The default
string is "User Abort". Does not
cause a break. Only output preced-
ing the last break is written.
.fl - - B Flush output buffer. Used in
interactive debugging to force out-
put.
21. Output and Error Messages.
The output from tm, pm, ab and the prompt from rd, as well as
various error messages are written onto UNIX's standard error
output. The latter is different from the standard output, where
NROFF formatted output goes. By default, both are written onto
the user's terminal, but they can be independently redirected.
Various error conditions may occur during the operation of NROFF
and TROFF. Certain less serious errors having only local impact
do not cause processing to terminate. Two examples are word over-
flow, caused by a word that is too large to fit into the word
buffer (in fill mode), and line overflow, caused by an output
line that grew too large to fit in the line buffer; in both
cases, a message is printed, the offending excess is discarded,
and the affected word or line is marked at the point of trunca-
tion with a * in NROFF and a <= in TROFF. The philosophy is to
continue processing, if possible, on the grounds that output use-
ful for debugging may be produced. If a serious error occurs,
processing terminates, and an appropriate message is printed.
Examples are the inability to create, read, or write files, and
the exceeding of certain internal limits that make future output
NROFF/TROFF User's Manual USD:24-33
unlikely to be useful.
USD:24-34 NROFF/TROFF User's Manual
USD:24-28 NROFF/TROFF User's Manual
TUTORIAL EXAMPLES
T1. Introduction respectively. A trap is planted
Although NROFF and TROFF have at page position 0 for the
by design a syntax reminiscent header, and at -N (N from the
of earlier text processors* page bottom) for the footer.
with the intent of easing their The simplest such definitions
use, it is almost always neces- might be
sary to prepare at least a .de hd \"define header
small set of macro definitions 'sp 1i
to describe most documents. .. \"end definition
Such common formatting needs as .de fo \"define footer
page margins and footnotes are 'bp
deliberately not built into .. \"end definition
NROFF and TROFF. Instead, the .wh 0 hd
macro and string definition, .wh -1i fo
number register, diversion, which provide blank 1 inch top
environment switching, page- and bottom margins. The header
position trap, and conditional will occur on the first page,
input mechanisms provide the only if the definition and trap
basis for user-defined imple- exist prior to the initial
mentations. pseudo-page transition (S3). In
The examples to be discussed fill mode, the output line that
are intended to be useful and springs the footer trap was
somewhat realistic, but won't typically forced out because
necessarily cover all relevant some part or whole word didn't
contingencies. Explicit numeri- fit on it. If anything in the
cal parameters are used in the footer and header that follows
examples to make them easier to causes a break, that word or
read and to illustrate typical part word will be forced out.
values. In many cases, number In this and other examples,
registers would really be used requests like bp and sp that
to reduce the number of places normally cause breaks are
where numerical information is invoked using the no-break con-
kept, and to concentrate condi- trol character ' to avoid this.
tional parameter initialization When the header/footer design
like that which depends on contains material requiring
whether TROFF or NROFF is being independent text processing,
used. the environment may be
T2. Page Margins switched, avoiding most
As discussed in S3, header and interaction with the running
footer macros are usually text.
defined to describe the top and A more realistic example would
bottom page margin areas be
__________ .de hd \"header
*For example: P. A. Crisman, .if t .tl '\(rn''\(rn' \"troff cut mark
Ed., The Compatible Time- .if \\n%>1 \{\
Sharing System, MIT Press, 'sp |0.5i-1\"tl base at 0.5i
1965, Section AH9.01 (Descrip- .tl ''- % -''\"centered page number
tion of RUNOFF program on MIT's .ps \"restore size
CTSS system). .ft \"restore font
NROFF/TROFF User's Manual USD:24-29
.vs \} \"restore vs . --- \"header stuff
'sp |1.0i \"space to 1.0i .ps \\n(s2\"restore previous size
.ns \"turn on no-space mode .ps \\n(s1\"restore current size
.. ..
.de fo \"footer Page numbers may be printed in
.ps 10 \"set footer/header siztehe bottom margin by a separate
.ft R \"set font macro triggered during the
.vs 12p \"set base-line spacingfooter's page ejection:
.if \\n%=1 \{\ .de bn \"bottom number
'sp |\\n(.pu-0.5i-1 \"tl base 0.5i.tulp''- % -''\"centered page number
.tl ''- % -'' \} \"first page numb.e.r
'bp .wh -0.5i-1v bn \"tl base 0.5i up
.. T3. Paragraphs and Headings
.wh 0 hd The housekeeping associated
.wh -1i fo with starting a new paragraph
which sets the size, font, and should be collected in a para-
base-line spacing for the graph macro that, for example,
header/footer material, and does the desired preparagraph
ultimately restores them. The spacing, forces the correct
material in this case is a page font, size, base-line spacing,
number at the bottom of the and indent, checks that enough
first page and at the top of space remains for more than one
the remaining pages. If TROFF line, and requests a temporary
is used, a cut mark is drawn in indent.
the form of root-en's at each .de pg \"paragraph
margin. The sp's refer to abso- .br \"break
lute positions to avoid depen- .ft R \"force font,
dence on the base-line spacing. .ps 10 \"size,
Another reason for this in the .vs 12p \"spacing,
footer is that the footer is .in 0 \"and indent
invoked by printing a line .sp 0.4 \"prespace
whose vertical spacing swept .ne 1+\\n(.Vu\"want more than 1 line
past the trap position by pos- .ti 0.2i \"temp indent
sibly as much as the base-line ..
spacing. The no-space mode is The first break in pg will
turned on at the end of hd to force out any previous partial
render ineffective accidental lines, and must occur before
occurrences of sp at the top of the vs. The forcing of font,
the running text. etc. is partly a defense
The above method of restoring against prior error and partly
size, font, etc. presupposes to permit things like section
that such requests (that set heading macros to set parame-
previous value) are not used in ters only once. The prespacing
the running text. A better parameter is suitable for
scheme is save and restore both TROFF; a larger space, at least
the current and previous values as big as the output device
as shown for size in the fol- vertical resolution, would be
lowing: more suitable in NROFF. The
.de fo choice of remaining space to
.nr s1 \\n(.s\"current size test for in the ne is the smal-
.ps lest amount greater than one
.nr s2 \\n(.s\"previous size line (the .V is the available
. --- \"rest of footer vertical resolution).
.. A macro to automatically number
.de hd section headings might look
USD:24-30 NROFF/TROFF User's Manual
like: columns, but is easily modified
.de sc \"section for more.
. --- \"force font, etc. .de hd \"header
.sp 0.4 \"prespace . ---
.ne 2.4+\\n(.Vu \"want 2.4+ lines .nr cl 0 1\"init column count
.fi .mk \"mark top of text
\\n+S. ..
.. .de fo \"footer
.nr S 0 1 \"init S .ie \\n+(cl<2 \{\
The usage is .sc, followed by .po +3.4i \"next column; 3.1+0.3
the section heading text, fol- .rt \"back to mark
lowed by .pg. The ne test value .ns \} \"no-space mode
includes one line of heading, .el \{\
0.4 line in the following pg, .po \\nMu \"restore left margin
and one line of the paragraph . ---
text. A word consisting of the 'bp \}
next section number and a ..
period is produced to begin the .ll 3.1i \"column width
heading line. The format of the .nr M \\n(.o\"save left margin
number may be set by af (S8). Typically a portion of the top
Another common form is the of the first page contains full
labeled, indented paragraph, width text; the request for the
where the label protrudes left narrower line length, as well
into the indent space. as another .mk would be made
.de lp \"labeled paragraph where the two column output was
.pg to begin.
.in 0.5i \"paragraph indent T5. Footnote Processing
.ta 0.2i 0.5i\"label, paragraph The footnote mechanism to be
.ti 0 described is used by imbedding
\t\\$1\t\c\"flow into paragraph the footnotes in the input text
.. at the point of reference,
The intended usage is ".lp demarcated by an initial .fn
label"; label will begin at and a terminal .ef:
0.2inch, and cannot exceed a .fn
length of 0.3inch without Footnote text and control lines...
intruding into the paragraph. .ef
The label could be right In the following, footnotes are
adjusted against 0.4inch by processed in a separate
setting the tabs instead with environment and diverted for
.ta 0.4iR 0.5i. The last line later printing in the space
of lp ends with \c so that it immediately prior to the bottom
will become a part of the first margin. There is provision for
line of the text that follows. the case where the last col-
T4. Multiple Column Output lected footnote doesn't com-
The production of multiple pletely fit in the available
column pages requires the space.
footer macro to decide whether .de hd \"header
it was invoked by other than . ---
the last column, so that it .nr x 0 1 \"init footnote count
will begin a new column rather .nr y 0-\\nb\"current footer place
than produce the bottom margin. .ch fo -\\nbu\"reset footer trap
The header can initialize a .if \\n(dn .fz\"leftover footnote
column register that the footer ..
will increment and test. The .de fo \"footer
following is arranged for two .nr dn 0 \"zero last diversion size
NROFF/TROFF User's Manual USD:24-31
.if \\nx \{\ leftover footnote, fz is
.ev 1 \"expand footnotes in eivn1voked to reprocess it. The
.nf \"retain vertical sizefootnote start macro fn begins
.FN \"footnotes a diversion (append) in
.rm FN \"delete it environment 1, and increments
.if "\\n(.z"fy" .di \"end overflotwhedivceorusnitonx; if the count is
.nr x 0 \"disable fx one, the footnote separator fs
.ev \} \"pop environment is interpolated. The separator
. --- is kept in a separate macro to
'bp permit user redefinition. The
.. footnote end macro ef restores
.de fx \"process footnote overtfhleowprevious environment and
.if \\nx .di fy\"divert overflowends the diversion after saving
.. the spacing size in register z.
.de fn \"start footnote y is then decremented by the
.da FN \"divert (append) footnsoitzee of the footnote, available
.ev 1 \"in environment 1 in dn; then on the first foot-
.if \\n+x=1 .fs \"if first, inclundoetes,epayraitsorfurther decremented
.fi \"fill mode by the difference in vertical
.. base-line spacings of the two
.de ef \"end footnote environments, to prevent the
.br \"finish output late triggering the footer trap
.nr z \\n(.v\"save spacing from causing the last line of
.ev \"pop ev the combined footnotes to over-
.di \"end diversion flow. The footer trap is then
.nr y -\\n(dn\"new footer positiosne,t to the lower (on the page)
.if \\nx=1 .nr y -(\\n(.v-\\nz) \of y or the current page posi-
\"uncertainty correctiotnion (nl) plus one line, to
.ch fo \\nyu\"y is negative allow for printing the refer-
.if (\\n(nl+1v)>(\\n(.p+\\ny) \ ence line. If indicated by x,
.ch fo \\n(nlu+1v \"it didn't fitthe footer fo rereads the foot-
.. notes from FN in nofill mode in
.de fs \"separator environment 1, and deletes FN.
\l'1i' \"1 inch rule If the footnotes were too large
.br to fit, the macro fx will be
.. trap-invoked to redivert the
.de fz \"get leftover footnoteoverflow into fy, and the
.fn register dn will later indicate
.nf \"retain vertical sizeto the header whether fy is
.fy \"where fx put it empty. Both fo and fx are
.ef planted in the nominal footer
.. trap position in an order that
.nr b 1.0i\"bottom margin size causes fx to be concealed
.wh 0 hd \"header trap unless the fo trap is moved.
.wh 12i fo\"footer trap, temp posTihteiofnooter then terminates the
.wh -\\nbu fx\"fx at footer positoivoenrflow diversion, if neces-
.ch fo -\\nbu\"conceal fx with fosary, and zeros x to disable
The header hd initializes a fx, because the uncertainty
footnote count register x, and correction together with a
sets both the current footer not-too-late triggering of the
trap position register y and footer can result in the foot-
the footer trap itself to a note rereading finishing before
nominal position specified in reaching the fx trap.
register b. In addition, if the A good exercise for the student
register dn indicates a is to combine the multiple-
USD:24-32 NROFF/TROFF User's Manual
column and footnote mechanisms.
T6. The Last Page
After the last input file has
ended, NROFF and TROFF invoke
the end macro (S7), if any, and
when it finishes, eject the
remainder of the page. During
the eject, any traps encoun-
tered are processed normally.
At the end of this last page,
processing terminates unless a
partial line, word, or partial
word remains. If it is desired
that another page be started,
the end-macro
.de en \"end-macro
\c
'bp
..
.em en
will deposit a null partial
word, and effect another last
page.
NROFF/TROFF User's Manual USD:24-33
USD:24-32 NROFF/TROFF User's Manual
Table I
Font Style Examples
The following fonts are printed in 12-point, with a vertical
spacing of 14-point, and with non-alphanumeric characters
separated by 1/4em space (all measurements on 8.5 x 11 inch paper
prior to photoreduction). This font sample is printed on an APS-5
phototypesetter at University of California, Berkeley.
Times Roman
abcdefghijklmnopqrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ
1234567890
! $ % & ( ) ` ' * + - . , / : ; = ? [ ] |
+ [] - - _ 1/4 1/2 3/4 fi fl ff ffi ffl - ' / (R) (C)
Times Italic
abcdefghijklmnopqrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ
1234567890
! $ % & ( ) ` ' * + - . , / : ; = ? [ ] |
+ [] - - _ 1/4 1/2 3/4 fi fl ff ffi ffl - ' / (R) (C)
Times Bold
abcdefghijklmnopqrstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ
1234567890
! $ % & ( ) ` ' * + - . , / : ; = ? [ ] |
• [] - - _ 1/4 1/2 3/4 fi fl ff ffi ffl |- ' c/ (R) (C)
Special Mathematical Font
" ' \ ^ _ ` ~ / < > { } # @ + - = *
( | / ` - n - i k \ u v o i̅i̅ p o̅ i̅ u | x | w
I̅ _\_ - /\ _ TT ≥̅ Y | | _O
/ ~ ≥ ≤ _ ~ ̅ / -> <- ^ v x - ± (̅)̅ _)_ (= =) (_ _)
oo `
S \̅/̅ oc / - = => <= | O | | | | | | | | | | | |
NROFF/TROFF User's Manual USD:24-33
NROFF/TROFF User's Manual USD:24-33
Table II
Input Naming Conventions for ', `, and -
and for Non-ASCII Special Characters
Non-ASCII characters and minus on the standard fonts.
Input Character InputCharacter
Char Name Name CharNameName
' ' close quote 3/4 \(34 3/4
` ` open quote fi \(fi fi
- \(em 3/4 Eflda\(fl fl
- - hyphen or ff \(ff ff
- \(hy hffien\(Fi ffi
- \- current font minus ffl \(Fl ffl
+ \(bu bullet\(de degree
[] \(sq sq|-are\(dg dagger
_ \(ru r'le \(fm foot mark
1/4 \(14 1c/4 \(ct cent sign
1/2 \(12 (R) \(rg registered
(C) \(co copyright
Non-ASCII characters and ', `, _, +, -, =, and * on the special
font.
The ASCII characters @, #, ", ', `, <, >, \, {, }, ~, ^, and _
exist only on the special font and are printed as a 1-em space if
that font is not mounted. The following characters exist only on
the special font except for the upper case Greek letter names
followed by - which are mapped into upper case English letters in
whatever font is mounted on font position one (default Times
Roman). The special math plus, minus, and equals are provided to
insulate the appearance of equations from the choice of standard
fonts.
Input Character InputCharacter
Char Name Name CharNameName
+ \(pl mathnplu\(*y eta
- \(mi math-min\(*h theta
= \(eq math iqua\(*i iota
* \(** mathksta\(*k kappa
S \(sc sec,\ion\(*l lambda
' \(aa acuteuacc\(*m mu
` \(ga gravevacc\(*n nu
_ \(ul underrul\(*c xi
/ \(sl slash (matchong \(*oslash) omicron
( \(*a ali̅i̅a \(*p pi
| \(*b bpta \(*r rho
/ \(*g gao̅ma \(*s sigma
` \(*d delta \(ts terminal sigma
- \(*e epsi̅lon\(*t tau
\(*z zuta \(*u upsilon
USD:24-34 NROFF/TROFF User's Manual
Input Character InputCharacter
Char Name Name CharNameName
r | \(*f phi \(no not
x \(*x chi \(is integral sign
| \(*q poc \(pt proportional to
w \(*w omO/ga \(es empty set
A \(*A Al<-ha-\(mo member of
B \(*B Be|a- \(br box vertical rule
I̅ \(*G Ga|=ma \(dd double dagger
_\_ \(*D De=>a \(rh right hand
E \(*E Eps<=on-\(lh left hand
Z \(*Z Zeta- \(bs Bell System logo (typesetter-dependent)
H \(*Y E|a- \(or or
- \(*H ThOta \(ci circle
I \(*I Io|a- \(lt left top of big curly bracket
K \(*K Ka|pa-\(lb left bottom
/\ \(*L La|bda\(rt right top
M \(*M M|- \(rb right bot
N \(*N N|- \(lk left center of big curly bracket
_ \(*C |i \(rk right center of big curly bracket
O \(*O Omi|ron-\(bv bold vertical
TT \(*P |i \(lf left floor (left bottom of big
P \(*R Rho- square bracket)
≥̅ \(*S Si|ma \(rf right floor (right bottom)
T \(*T T|u- \(lc left ceiling (left top)
Y \(*U Ups|lon\(rc right ceiling (right top)
| \(*F Phi
X \(*X Chi-
| \(*Q Psi
_ \(*W Omega
/ \(sr square root
~ \(rn root en extender
≥ \(>= >=
≤ \(<= <=
_ \(== identically equal
̅ \(~= approx =
~ \(ap approximates
/ \(!= not equal
-> \(-> right arrow
<- \(<- left arrow
^ \(ua up arrow
v \(da down arrow
x \(mu multiply
- \(di divide
± \(+- plus-minus
(̅)̅ \(cu cup (union)
_)_ \(ca cap (intersection)
(= \(sb subset of
=) \(sp superset of
(_ \(ib improper subset
_) \(ip improper superset
oo \(if infinity
` \(pd partial derivative
\̅/̅ \(gr gradient
NROFF/TROFF User's Manual USD:24-35
Input Character InputCharacter
Char Name Name CharNameName
May 15, 1977
Summary of Changes to N/TROFF Since October 1976 Manual
Options
-h (Nroff only) Output tabs used during horizontal spacing
to speed output as well as reduce output byte count.
Device tab settings assumed to be every 8 nominal char-
acter widths. The default settings of input (logical)
tabs is also initialized to every 8 nominal character
widths.
-z Efficiently suppresses formatted output. Only message
output will occur (from "tm"s and diagnostics).
Old Requests
.ad c The adjustment type indicator "c" may now also be a
number previously obtained from the ".j" register (see
below).
.so name The contents of file "name" will be interpolated at the
point the "so" is encountered. Previously, the interpo-
lation was done upon return to the file-reading input
level.
New Request
.ab text Prints "text" on the message output and terminates
without further processing. If "text" is missing, "User
Abort." is printed. Does not cause a break. The output
buffer is flushed.
.fz F N forces _ont "F" to be in si_e N. N may have the form N,
+N, or -N. For example,
.fz 3 -2
will cause an implicit \s-2 every time font 3 is
entered, and a corresponding \s+2 when it is left. Spe-
cial font characters occurring during the reign of font
F will have the same size modification. If special
characters are to be treated differently,
.fz S F N
may be used to specify the size treatment of special
characters during font F. For example,
.fz 3 -3
.fz S 3 -0
will cause automatic reduction of font 3 by 3 points
while the special characters would not be affected. Any
``.fp'' request specifying a font on some position must
precede ``.fz'' requests relating to that position.
New Predefined Number Registers.
.k Read-only. Contains the horizontal size of the text
portion (without indent) of the current partially
collected
May 15, 1977
output line, if any, in the current environment.
.j Read-only. A number representing the current adjustment
mode and type. Can be saved and later given to the "ad"
request to restore a previous mode.
.P Read-only. 1 if the current page is being printed, and
zero otherwise.
.L Read-only. Contains the current line-spacing parameter
("ls").
c. General register access to the input line-number in the
current input file. Contains the same value as the
read-only ".c" register.
May 15, 1977
Generated on 2013-04-27 00:20:00 by $MirOS: src/scripts/roff2htm,v 1.77 2013/01/01 20:49:09 tg Exp $
These manual pages and other documentation are copyrighted by their respective writers;
their source is available at our CVSweb,
AnonCVS, and other mirrors. The rest is Copyright © 2002‒2013 The MirOS Project, Germany.
This product includes material
provided by Thorsten Glaser.
This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.