Typing Documents on the UNIX System:
Using the -ms Macros with Troff and Nroff
M. E. Lesk
ABSTRACT
This document describes a set of easy-to-use
macros for preparing documents on the UNIX system.
Documents may be produced on either the photo-
typesetter or on a computer terminal, without
changing the input.
The macros provide facilities for paragraphs,
sections (optionally with automatic numbering),
page titles, footnotes, equations, tables, two-
column format, and cover pages for papers.
This memo includes, as an appendix, the text
of the ``Guide to Preparing Documents with -ms''
which contains additional examples of features of
-ms.
This manual is a revision of, and replaces,
``Typing Documents on UNIX,'' dated November 22,
1974.
Introduction. This memorandum describes a package of
commands to produce papers using the troff and nroff format-
ting programs on the UNIX system. As with other roff-derived
programs, text is prepared interspersed with formatting com-
mands. However, this package, which itself is written in
troff commands, provides higher-level commands than those
provided with the basic troff program. The commands avail-
able in this package are listed in Appendix A.
Text. Type normally, except that instead of indenting
for paragraphs, place a line reading ``.PP'' before each
paragraph. This will produce indenting and extra space.
Alternatively, the command .LP that was used here will pro-
duce a left-aligned (block) paragraph. The paragraph spacing
can be changed: see below under ``Registers.''
Beginning. For a document with a paper-type cover
sheet, the input should start as follows:
December 24, 2022
USD:17-2 Using the -ms Macros with Troff and Nroff
[optional overall format .RP - see below]
.TL
Title of document (one or more lines)
.AU
Author(s) (may also be several lines)
.AI
Author's institution(s)
.AB
Abstract; to be placed on the cover sheet of a paper.
Line length is 5/6 of normal; use .ll here to change.
.AE (abstract end)
text ... (begins with .PP, which see)
To omit some of the standard headings (e.g. no abstract, or
no author's institution) just omit the corresponding fields
and command lines. The word ABSTRACT can be suppressed by
writing ``.AB no'' for ``.AB''. Several interspersed .AU and
.AI lines can be used for multiple authors. The headings are
not compulsory: beginning with a .PP command is perfectly OK
and will just start printing an ordinary paragraph. Warning:
You can't just begin a document with a line of text. Some
-ms command must precede any text input. When in doubt, use
.LP to get proper initialization, although any of the com-
mands .PP, .LP, .TL, .SH, .NH is good enough. Figure 1 shows
the legal arrangement of commands at the start of a docu-
ment.
Cover Sheets and First Pages. The first line of a docu-
ment signals the general format of the first page. In par-
ticular, if it is ".RP" a cover sheet with title and
abstract is prepared. The default format is useful for scan-
ning drafts.
In general -ms is arranged so that only one form of a
document need be stored, containing all information; the
first command gives the format, and unnecessary items for
that format are ignored.
Warning: don't put extraneous material between the .TL
and .AE commands. Processing of the titling items is spe-
cial, and other data placed in them may not behave as you
expect. Don't forget that some -ms command must precede any
input text.
Page headings. The -ms macros, by default, will print a
page heading containing a page number (if greater than 1). A
default page footer is provided only in nroff, where the
date is used. The user can make minor adjustments to the
page headings/footings by redefining the strings LH, CH, and
RH which are the left, center and right portions of the page
headings, respectively; and the strings LF, CF, and RF,
which are the left, center and right portions of the page
footer. For more complex formats, the user can redefine the
December 24, 2022
Using the -ms Macros with Troff and Nroff USD:17-3
macros PT and BT, which are invoked respectively at the top
and bottom of each page. The margins (taken from registers
HM and FM for the top and bottom margin respectively) are
normally 1 inch; the page header/footer are in the middle of
that space. The user who redefines these macros should be
careful not to change parameters such as point size or font
without resetting them to default values.
Multi-column formats. If you place the command ``.2C''
in your document, the document will be printed in double
column format beginning at that point. This feature is not
too useful in computer terminal output, but is often desir-
able on the typesetter. The command ``.1C'' will go back to
one-column format and also skip to a new page. The ``.2C''
command is actually a special case of the command
.MC [column width [gutter width]]
which makes multiple columns with the specified column and
gutter width; as many columns as will fit across the page
are used. Thus triple, quadruple, ... column pages can be
printed. Whenever the number of columns is changed (except
going from full width to some larger number of columns) a
new page is started.
Headings. To produce a special heading, there are two
commands. If you type
.NH
type section heading here
may be several lines
you will get automatically numbered section headings (1, 2,
3, ...), in boldface. For example,
.NH
Care and Feeding of Department Heads
produces
1. Care and Feeding of Department Heads
Alternatively,
.SH
Care and Feeding of Directors
will print the heading with no number added:
Care and Feeding of Directors
Every section heading, of either type, should be fol-
lowed by a paragraph beginning with .PP or .LP, indicating
the end of the heading. Headings may contain more than one
December 24, 2022
USD:17-4 Using the -ms Macros with Troff and Nroff
line of text.
The .NH command also supports more complex numbering
schemes. If a numerical argument is given, it is taken to be
a ``level'' number and an appropriate sub-section number is
generated. Larger level numbers indicate deeper sub-
sections, as in this example:
.NH
Erie-Lackawanna
.NH 2
Morris and Essex Division
.NH 3
Gladstone Branch
.NH 3
Montclair Branch
.NH 2
Boonton Line
generates:
2. Erie-Lackawanna
2.1. Morris and Essex Division
2.1.1. Gladstone Branch
2.1.2. Montclair Branch
2.2. Boonton Line
An explicit ``.NH 0'' will reset the numbering of level
1 to one, as here:
.NH 0
Penn Central
1. Penn Central
Indented paragraphs. (Paragraphs with hanging numbers,
e.g. references.) The sequence
.IP [1]
Text for first paragraph, typed
normally for as long as you would
like on as many lines as needed.
.IP [2]
Text for second paragraph, ...
produces
[1] Text for first paragraph, typed normally for as long as
you would like on as many lines as needed.
December 24, 2022
Using the -ms Macros with Troff and Nroff USD:17-5
[2] Text for second paragraph, ...
A series of indented paragraphs may be followed by an ordi-
nary paragraph beginning with .PP or .LP, depending on
whether you wish indenting or not. The command .LP was used
here.
More sophisticated uses of .IP are also possible. If
the label is omitted, for example, a plain block indent is
produced.
.IP
This material will
just be turned into a
block indent suitable for quotations or
such matter.
.LP
will produce
This material will just be turned into a block indent
suitable for quotations or such matter.
If a non-standard amount of indenting is required, it may be
specified after the label (in character positions) and will
remain in effect until the next .PP or .LP. Thus, the gen-
eral form of the .IP command contains two additional fields:
the label and the indenting length. For example,
.IP first: 9
Notice the longer label, requiring larger
indenting for these paragraphs.
.IP second:
And so forth.
.LP
produces this:
first: Notice the longer label, requiring larger indenting
for these paragraphs.
second: And so forth.
It is also possible to produce multiple nested indents; the
command .RS indicates that the next .IP starts from the
current indentation level. Each .RE will eat up one level of
indenting so you should balance .RS and .RE commands. The
.RS command should be thought of as ``move right'' and the
.RE command as ``move left''. As an example
December 24, 2022
USD:17-6 Using the -ms Macros with Troff and Nroff
.IP 1.
Bell Laboratories
.RS
.IP 1.1
Murray Hill
.IP 1.2
Holmdel
.IP 1.3
Whippany
.RS
.IP 1.3.1
Madison
.RE
.IP 1.4
Chester
.RE
.LP
will result in
1. Bell Laboratories
1.1 Murray Hill
1.2 Holmdel
1.3 Whippany
1.3.1Madison
1.4 Chester
All of these variations on .LP leave the right margin
untouched. Sometimes, for purposes such as setting off a
quotation, a paragraph indented on both right and left is
required.
A single paragraph like this is obtained by
preceding it with .QP. More complicated material
(several paragraphs) should be bracketed with .QS
and .QE.
Emphasis. To get italics (on the typesetter) or underlining
(on the terminal) say
.I
as much text as you want
can be typed here
.R
as was done for these three words. The .R command restores
the normal (usually Roman) font. If only one word is to be
italicized, it may be just given on the line with the .I
December 24, 2022
Using the -ms Macros with Troff and Nroff USD:17-7
command,
.I word
and in this case no .R is needed to restore the previous
font. Boldface can be produced by
.B
Text to be set in boldface
goes here
.R
and also will be underlined on the terminal or line printer.
As with .I, a single word can be placed in boldface by plac-
ing it on the same line as the .B command.
A few size changes can be specified similarly with the
commands .LG (make larger), .SM (make smaller), and .NL
(return to normal size). The size change is two points; the
commands may be repeated for increased effect (here one .NL
canceled two .SM commands).
If actual underlining as opposed to italicizing is
required on the typesetter, the command
.UL word
will underline a word. There is no way to underline multi-
ple words on the typesetter.
Footnotes. Material placed between lines with the com-
mands .FS (footnote) and .FE (footnote end) will be col-
lected, remembered, and finally placed at the bottom of the
current page*. By default, footnotes are 11/12th the length
of normal text, but this can be changed using the FL regis-
ter (see below).
Displays and Tables. To prepare displays of lines, such
as tables, in which the lines should not be re-arranged,
enclose them in the commands .DS and .DE
.DS
table lines, like the
examples here, are placed
between .DS and .DE
.DE
By default, lines between .DS and .DE are indented and left-
adjusted. You can also center lines, or retain the left mar-
gin. Lines bracketed by .DS C and .DE commands are centered
(and not re-arranged); lines bracketed by .DS L and .DE are
_________________________
* Like this.
December 24, 2022
USD:17-8 Using the -ms Macros with Troff and Nroff
left-adjusted, not indented, and not re-arranged. A plain
.DS is equivalent to .DS I, which indents and left-adjusts.
Thus,
these lines were preceded
by .DS C and followed by
a .DE command;
whereas
these lines were preceded
by .DS L and followed by
a .DE command.
Note that .DS C centers each line; there is a variant .DS B
that makes the display into a left-adjusted block of text,
and then centers that entire block. Normally a display is
kept together, on one page. If you wish to have a long
display which may be split across page boundaries, use .CD,
.LD, or .ID in place of the commands .DS C, .DS L, or .DS I
respectively. An extra argument to the .DS I or .DS command
is taken as an amount to indent. Note: it is tempting to
assume that .DS R will right adjust lines, but it doesn't
work.
Boxing words or lines. To draw rectangular boxes around
words the command
.BX word
____
will print |_o__d_|as shown. The boxes will not be neat on a
terminal, and this should not be used as a substitute for
italics.
Longer pieces of text may be boxed by enclosing them with
file, you can print it on a terminal with the command*
nroff -ms file
and you can print it on the typesetter with the command
troff -ms file
(many options are possible). In each case, if your document
is stored in several files, just list all the filenames
where we have used ``file''. If equations or tables are
used, eqn and/or tbl must be invoked as preprocessors.
References and further study. If you have to do Greek
or mathematics, see eqn [1] for equation setting. To aid eqn
users, -ms provides definitions of .EQ and .EN which
_________________________
* If .2C was used, pipe the nroff output through col;
make the first line of the input ``.pi /usr/bin/col.''
December 24, 2022
Using the -ms Macros with Troff and Nroff USD:17-9
normally center the equation and set it off slightly. An
argument on .EQ is taken to be an equation number and placed
in the right margin near the equation. In addition, there
are three special arguments to EQ: the letters C, I, and L
indicate centered (default), indented, and left adjusted
equations, respectively. If there is both a format argument
and an equation number, give the format argument first, as
in
.EQ L (1.3a)
for a left-adjusted equation numbered (1.3a).
Similarly, the macros .TS and .TE are defined to
separate tables (see [2]) from text with a little space. A
very long table with a heading may be broken across pages by
beginning it with .TS H instead of .TS, and placing the line
.TH in the table data after the heading. If the table has
no heading repeated from page to page, just use the ordinary
.TS and .TE macros.
To learn more about troff see [3] for a general intro-
duction, and [4] for the full details (experts only). Infor-
mation on related UNIX commands is in [5]. For jobs that do
not seem well-adapted to -ms, consider other macro packages.
It is often far easier to write a specific macro packages
for such tasks as imitating particular journals than to try
to adapt -ms.
Acknowledgment. Many thanks are due to Brian Kernighan
for his help in the design and implementation of this pack-
age, and for his assistance in preparing this manual.
References
[1] B. W. Kernighan and L. L. Cherry, Typesetting Mathemat-
ics - Users Guide (2nd edition), Bell Laboratories Com-
puting Science Report no. 17.
[2] M. E. Lesk, Tbl - A Program to Format Tables, Bell
Laboratories Computing Science Report no. 45.
[3] B. W. Kernighan, A Troff Tutorial, Bell Laboratories,
1976.
[4] J. F. Ossanna, Nroff/Troff Reference Manual, Bell
Laboratories Computing Science Report no. 51.
[5] K. Thompson and D. M. Ritchie, UNIX Programmer's
Manual, Bell Laboratories, 1978.
December 24, 2022
USD:17-10 Using the -ms Macros with Troff and Nroff
Appendix A
List of Commands
1CReturn to single column format. LGIncrease type size.
2CStart double column format. LPLeft aligned block paragraph.
ABBegin abstract.
AEEnd abstract.
AISpecify author's institution.
AUSpecify author. NDChange or cancel date.
B Begin boldface. NHSpecify numbered heading.
DAProvide the date on each page. NLReturn to normal type size.
DEEnd display. PPBegin paragraph.
DSStart display (also CD, LD, ID).
ENEnd equation. R Return to regular font (usually Roman).
EQBegin equation. REEnd one level of relative indenting.
FEEnd footnote. RPUse released paper format.
FSBegin footnote. RSRelative indent increased one level.
I Begin italics. SHSpecify section heading.
SMChange to smaller type size.
IPBegin indented paragraph. TLSpecify title.
KERelease keep.
KFBegin floating keep. ULUnderline one word.
KSStart keep.
Register Names
The following register names are used by -ms inter-
nally. Independent use of these names in one's own macros
may produce incorrect output. Note that no lower case
letters are used in any -ms internal name.
Number registers used in -ms
: DW GW HM IQ LL NA OJ PO T. TV
#T EF H1 HT IR LT NC PD PQ TB VS
.T FC H2 IF IT MF ND PE PS TC WF
1T FL H3 IK KI MM NF PF PX TD YE
AV FM H4 IM L1 MN NS PI RO TN YY
CW FP H5 IP LE MO OI PN ST TQ ZN
String registers used in -ms
' A5 CB DW EZ I KF MR R1 RT TL
` AB CC DY FA I1 KQ ND R2 S0 TM
^ AE CD E1 FE I2 KS NH R3 S1 TQ
~ AI CF E2 FJ I3 LB NL R4 S2 TS
: AU CH E3 FK I4 LD NP R5 SG TT
, B CM E4 FN I5 LG OD RC SH UL
1C BG CS E5 FO ID LP OK RE SM WB
2C BT CT EE FQ IE ME PP RF SN WH
A1 C D EL FS IM MF PT RH SY WT
A2 C1 DA EM FV IP MH PY RP TA XD
A3 C2 DE EN FY IZ MN QF RQ TE XF
December 24, 2022
Using the -ms Macros with Troff and Nroff USD:17-11
A4 CA DS EQ HO KE MO R RS TH XK
Figure 1: Order of Commands in Input
line from 5.612,3.388 to
5.612,2.888 line from
4.237,4.888 to 4.237,4.763 to
5.612,4.763 line from
3.175,5.700 to 3.175,5.513 to
5.612,5.513 line from
3.237,9.700 to 3.237,9.512 to
2.425,9.512 line from
4.237,6.825 to 4.237,5.138
line from 4.212,5.237 to
4.237,5.138 to 4.263,5.237
line from 2.425,6.950 to
2.425,6.825 to 5.612,6.825 to
5.612,4.638 line from
5.587,4.737 to 5.612,4.638 to
5.638,4.737 line from
2.425,9.387 to 3.175,9.387 to
3.175,6.700 line from
3.150,6.800 to 3.175,6.700 to
3.200,6.800 line from
2.425,10.200 to 3.237,10.200
to 3.237,9.950 line from
3.212,10.050 to 3.237,9.950 to
3.262,10.050 line from
5.612,4.388 to 5.612,3.575
line from 5.587,3.675 to
5.612,3.575 to 5.638,3.675
line from 3.175,6.388 to
3.175,5.825 line from
3.150,5.925 to 3.175,5.825 to
3.200,5.925 line from
2.425,7.950 to 2.425,7.200
line from 2.400,7.300 to
2.425,7.200 to 2.450,7.300
line from 2.425,8.950 to
2.425,8.137 line from
2.400,8.237 to 2.425,8.137 to
2.450,8.237 line from
2.425,10.387 to 2.425,9.200
line from 2.400,9.300 to
2.425,9.200 to 2.450,9.300
"RP" at 3.175,9.796 ljust
"text..." at 5.487,3.483 ljust
"PP, LP" at 5.425,4.483 ljust
"NH, SH" at 3.987,4.983 ljust
"AE" at 3.112,5.733 ljust "AB"
at 3.112,6.546 ljust "AI" at
2.362,7.046 ljust "AU" at
2.362,7.983 ljust "TL" at
2.362,9.046 ljust
December 24, 2022