Cover  Paragraphs  Fonts  Headings  Headers and footers  Multicolumn  Footnotes  Keeps  Boxes  Table of contents  Predefined strings  Number registers  Equations and tables  troff  Reserved names

Formatting documents with troff -ms

A quick reference.
Jutta Degener, 1995.

Cover sheet

Generally, the cover sheet commands are optional, but must appear in a fixed order, and some demand each other.

Accent macros

.AM
turns on "new-style" accent marks, which are those you want (see below for a list). If present, it must be the first command in the file. (This probably bears qualification.)

Date or no date

.DA  [date]
Makes troff print the date as the center page footer. (The current date if date is omitted, otherwise whatever the arguments are.)
.ND  [date]
If date is present, it is printed once on a cover sheet in .RP format and nowhere else. If .ND is invoked without arguments, no date is printed.

Thesis mode

.TM
Puts page numbers in the upper right corner, numbers the first page, suppresses the date, and sets everything double-spaced except quotes, displays, and keeps. Defines .CT.

Released paper format

.RP
Causes the title sheet to be printed separately; if present, it immediately precedes the .TL.

Title

.TL
Title
All these fields can contain more than one line, and continue until the next request.

Author and Author's institution

.AU
Authors
.AI
Authors' institution(s)
When formatting for multiple authors, repeat as many pairs of .AU and .AI as necessary.

Abstract

.AB [no]
Abstract as it appears on the cover
.AE
The main text must be preceded by either a paragraph start or a section heading.  If you want a title, but no abstract, use .AB no.

Paragraphs

Normal paragraph

.PP
Lorem ipsum dolor sit amet, consectetuer

Left-aligned paragraph

.LP
Lorem ipsum dolor sit amet, consectetuer
There are default values for the vertical spacing before paragraphs and for their indentation.

Indented paragraph

.IP [tag [indent-in-ens]]
Lorem ipsum dolor sit amet, consectetuer
Indented paragraphs are ended by starting another kind of paragraph.

Relative indent start and end

.IP
This text is indented one step.
.RS
.IP
This text is indented two steps.
.RE

Quoted paragraph

.QP
Lorem ipsum dolor sit amet, consectetuer
In contrast to .IP, .QP indents the right margin as well as the left.

Exdented paragraph

.XP
Lorem ipsum dolor sit amet, consectetuer
Indents everything but the first line of the paragraph. The number register PI says how much.

Font changes

Bold, italic, and underlined text

.I  [word [trailer]]
If word is omitted, the request simply turns on italic font; if the argument is present, only that word is set in intalics. If there is a trailer after the word, that trailer is set in the original font without intervening white space.
.B  [word [trailer]]
Similar for boldface.
.R
Restores the previous font.
.UL  word
Underline word. There's no way to turn on underlining for good, in the way that omitting the argument does it for bold or italics.

Font sizes

.LG
.SM
.NL
make the font larger, smaller, and normal again, respectively; two points by default. They can be iterated. They don't affect the line spacing.

Headings

Section heading

.SH
Lorem ipsum dolor sit amet, consectetuer
Section headings are ended by starting a paragraph or another section heading.

Numbered heading

.NH  depth-level
Lorem ipsum dolor sit amet, consectetuer
The depth ranges from 1 to 5. The default is 1.  A depth of 0 resets the counters and produces a section heading numbered 1.

Chapter title

.CT
Lorem ipsum dolor sit amet, consectetuer
Only defined in thesis mode. Starts a new page.

Running headers and footers

Header and footer variables

To set the left, right, and center parts of the footer and header respectively, set the string variables
.ds  LH left header
.ds  CH center header
.ds  RH right header
.ds  LF left footer
.ds  CF center footer
.ds  RF right footer
The default values for these registers are, for troff,
CH page number
for nroff,
CH - page number -
CF current date
In nroff string definitions, % refers to the current page number. To clear a string register, just assign the null string to it.

If the assignments should take effect before the first page, they have to precede the title macros.

Header and footer macros

.de PT
code that is executed at the top of each page
..
.de FT
code is executed at the bottom of each page.
..
There are separate macros for odd and even pages:
.de OH
odd page header macro
..
.de OF
odd page footer macro
..

.de EH
even page header macro
..
.de EF
even page footer macro
..

These macros get passed the string registers as three arguments, in the order left, center, right, separated by a single apostrophe. (Or whatever else the first character of the string is.) If the separator should appear in the string, it has to be escaped with a backslash.

Page 1 header

.P1
Prints a header on page one. I reckon that it has to be used before that, then, but I don't have time to test it.

Roman page numbering

.af PN i
Makes PN (the ms page number) appear as lower case roman characters. (.af is the troff assign format request.)

Multicolumn layout

Two-column text

.2C
Start two-column output.

Arbitrary multicolumn text

.MC [column-width  [gutter-width]]
Start multicolumn output. The ``gutter'' is the space between the columns. The width can have units, but if they don't, the default unit is ens.

Single-column text

.1C
Returns to single-column format.

Footnotes

.FS [mark]
Incidentally, lorem ipsum dolor sit amet ...
.FE
In the text that invokes the footnote, you produce the mark separately, as one of
\**
automatic counter, incremented each time it is used
\(dg
dagger
\(dd
double dagger
*
simple asterisk
If you use anythin except \**, you can either repeat the mark as an argument to the .FS macro, or simply write it in the text.

The number register FL contains the footnote line's length.

Keeps and displays

Displays

Displays are kept on one page, and (by default) indented a bit.
.DS [code  [indent]]
Lorem ipsum dolor sit amet, consectetuer
.DE
The code determines how the display is placed on its containing page.
I
indented (default)
C
centered
L
flush left
B
flushed left, then centered as a whole
An extra indent argument (in ens) is taken as the amount to indent. There's no way to right-adjust a display.

Displays with page breaks

In place of
.DS code
..
.DE
use
.codeD
..
.DE
for codes I, C, L, or B if you want page breaks in the display.

Keeps

.KS
Lorem ipsum dolor sit amet, consectetuer
.KE
If the text between .KS and .KE doesn't fit on the rest of the page, a new page is started.

Floating keeps

.KF
Lorem ipsum dolor sit amet, consectetuer
.KE
Like regular keeps, but the text is moved past the following text.

Boxes

Boxed word

.BX  text
prints a box around the text.

Boxed text

.B1
Lorem ipsum dolor sit amet, consectetuer
.B2
enclose the text between them in a box.

Table of contents

Defining the table of contents

.XS  [page-number]
Lorem ipsum dolor sit amet, consectetuer
.XA  [page-number]
Lorem ipsum dolor sit amet, consectetuer
...
.XE
If the page numbers are omitted from the XS or XA macros, the page number of the current page is used.

Printing the table

.PX

Special strings

Dash

The string \*- yields -- in nroff, but a single em-dash in troff.

Quotes

The strings \*Q and \*U produce leading and ending quotes, respectively, in troff, and simple double quotes (") in nroff.

Accent marks

Given .AM at the start of the file, you can use the following:
e\*'
e-acute (é)
e\*'
e-grave (è)
o\*^
o-circumflex (ô)
c\*,
c-cedilla
n\*~
n-tilde
\*?
inverted question mark
\*!
inverted exclamation mark
u\*:
umlaut-u
\*8
sharp s
c\*v
hacek (c with v on top)
a\*_
macron (dash over)
o\*/
o-slash
\*3
yogh
a\*o
angstrom (circle on top)
\*(Th
upper case thorn
\*(th
lower case thorn
\*(D-
upper case eth
\*(d-
lower case eth
\*q
hooked o
\*(Ae
upper case ae ligature
\*(ae
lower case ae ligature
\*(Oe
upper case oe ligature
\*(oe
lower case oe ligature

Number registers

The number registers used by the MS macros and their meanings (with the defaults in parentheses) are:
PS
point size (10)
VS
line spacing (12p)
LL
line length (6i)
LT
title length (6i)
PD
paragraph spacing (0.3v)
PI
paragraph indent (5n)
FL
footnote length (11/12 LL)
CW
column width (7/15 LL)
GW
gutter width (1/15 LL)
PO
page offset (26/27i)
HM
top margin (1i)
FM
bottom margin (1i)
MS uses more than just those, but those are the ones the user can change.

Including EQN and TBL output

Equations

.EQ [code]  [equation-number]
eqn commands
.EN
By default, equations are centered and surrounded by a small amount of vertical space. The optional code can be one of C, I, or L to print the equation centered, indented, or flushed left, respectively. Any argument that is not a code is an equation number and is printed on the right margin, near the equation.

Tables

.TS [H
tbl header comands
.TH]
tbl commands
.TE
Similar to the case for equations. If the H option is present, the table header is separated from the body by a .TH. If the table is broken up over multiple pages, the code between .TS and .TH is repeated on the top of each page.

Supplementary troff commands

Number registers

.nr  NN  value
Sets the number register NN to value value.

Units

Except for PS and VS, numbers need to be specified in units. Possible units and their meanings are:
p
point, 1/72 inch, 1/28 cm
P
pica, 1/6 inch, 4.23 mm
m
em, width of an m
n
en, width of an n
v
vertical space, baseline-to-baseline distance
i
inch
c
centimeter
u
machine unit, varying (but very small)

String registers

.ds  SS  value
defines the string register SS as value.

Margins

.ad  b
Adjust both margins, the default.
.na
Turn off adjustment of right margins, producing a "ragged right" look.

Centering text

.ce  [number-of-lines]
Lorem ipsum dolor sit amet, consectetuer
centers the next number-of-lines lines of text, default 1.

Breaking lines and pages

.bp
Begin a new page.
.br
Begin a new line.
.sp  number-of-lines
Insert number-of-lines blank lines into the output.

Reserved names

These troff number and string registers are used internally by the MS macros and shouldn't be used by the application.

Number registers

:	#T	1T	CW	DW	EF	FC
FL	FM	FP	GW	H1	H2	H3
H4	H5	HM	HT	IF	IK	IM
IP	IQ	IR	IT	KI	L1	LE
LL	LT	MF	MM	MN	MO	NA
NC	ND	NF	NS	OI	OJ	PD
PE	PF	PI	PN	PO	PQ	PS
PX	RO	ST	T.	TB	TC	TD
TN	TQ	TV	VS	WF	YE	YY
ZN

String registers

'	`	^	~	:	,	1C
2C	A1	A2	A3	A4	A5	AB
AE	AI	AU	B	BG	BT	C
C1	C2	CA	CB	CC	CD	CF
CH	CM	CS	CT 	D	DA	DE
DS	DW	DY	E1	E2	E3	E4
E5	EE	EL	EM	EN	EQ	EZ
FA	FE	FJ	FK	FN	FO	FQ
FS	FV	FY	HO	I	I1	I2
I3	I4	I5	ID	IE	IM	IP
IZ	KE	KF	KQ	KS	LB	LD
LG	LP	ME	MF	MH	MN	MO
MR	ND	NH	NL	NP	OD	OK
PP	PT	PY	QF	R	R1	R2
R3	R4	R5	RC	RE	RF	RP
RQ	RS	RT	S0	S1	S2	SG
SH	SM	SN	SY	TA	TE	TH
TL	TM	TQ	TS	TT	UL	WB
WH	WT	XD	XF	XK