Computing ServicesLibrary, 218 Evans HallUniversity of CaliforniaBerkeley, California 94720415-642-5205
UNX 4.3.2 May 1984
Abstract
This document describes the supported commands used
for producing formatted papers,
such as dissertations and journal articles,
on the UNIX system. (UNIX is a trademark of Bell Laboratories.)
It is intended to be the main source of
information on formatting documents with
nroff or troff
and the -ms macro package at the UC Berkeley Computer Center.
The reader is assumed to have basic familiarity
with UNIX and with a text editor such as
edit, ex, or vi.
Credits
The first edition of this paper,
written by Joel Kies,
was based on the Bell Laboratories manual
Typing Documents on the UNIX System:
Using the -ms Macros with Troff and Nroff,
by Michael E. Lesk (Murry Hill, 1978),
and it replaces that document for
UC Berkeley UNIX users.
The following people contributed substantially to the first edition
by their suggestions and criticism:
Ricki Blau, John Kunze, Bob Levinson, Gail Moyer,
Betty Nelson, Cindy Nelson, and Ken Wahl.
This second edition describes the state of the -ms macros
after they were revised by Bill Tuthill in 1982.
These revisions allow the macros to be read by the computer
in half the time formerly required.
Bugs have been fixed, and there are extensions
such as numbered footnotes, a table of contents apparatus,
improved accent marks, and even/odd page titles.
As much as possible, the revised macros produce
exactly the same output as before.
However, macros specific to Bell Laboratories have been eliminated.
Karen Borst-Rothe and Dorothy Heydt
edited this second edition.
Cover design by Dorothy Heydt.
HTML translation by
Jan Pardoe (aka jrp) 3/95.
Table of Contents
1. Introduction
1.1. Filling, Adjusting, and Hyphenating
1.2. Purposes of a Macro Package
1.3. Typing an Input File
2. Commands and Features of -ms
2.1. Paragraphs
2.2. Section Headings
2.3. Changes in Indentation
2.4. Footnotes and Endnotes
2.5. Emphasis
2.6. Type Size Changes
2.7. Boxes Around Text
2.8. Title Pages and Cover Sheets
2.9. Dates
2.10. Tables of Contents
2.11. Multi-Column Formats
2.12. Keeping Text Together
2.13. Displays
2.14. Modifying Default Features
2.15. Dimensions
2.16. Page Headers and Footers
2.17. Set-Up Commands
2.18. Accent Marks
3. Using Nroff/Troff Commands
4. Including Tables and Equations
5. Producing Output
6. Sample Input Files
7. For More Information
Appendix A: Command Descriptions
Appendix B: The Order of Things
Appendix C: Names of -ms Macros, String Registers, and Number Registers
Note on Typographical Conventions
In the body of this document, boldface is used to
represent the names of programs and macro
packages (nroff, -ms),
individual macros (.PP),
number and string registers (LL, \*(SN),
and specific examples (\f3bold\f1).
Italic text is used for arguments and options
to commands
(.IP[label] [indentation]), and
in the ordinary way for emphasis: most technical terms
(points, initializing macro) will be italicized
for emphasis the first time they appear.
Boldface and italics, not surprisingly, also represent themselves
in the section on Emphasis.
In Appendices A and B, boldface and italics are used slightly
differently, as explained at the beginning of Appendix A.
This document describes a package of commands
used in producing formatted papers,
such as reports,
dissertations, and journal articles,
on the UNIX system.
The package, called the
-ms macros,
provides commands for paragraphs,
section headings,
running page titles, footnotes, multi-column format,
cover sheets, and other features.
To use the facilities described in this document,
you need to have a general familiarity
with UNIX and with a text editor
such as ex, edit, or vi.
UNIX offers several related formatting programs,
suited to handling tables and
mathematics as well as ordinary text.
A number of separate writeups on these programs
are available;
an annotated list is included later in this document
(see section 7).
This document should be read first, however,
since it provides both a description of the most
commonly-used formatting commands and an overview of the related programs.
The main formatting programs, called
nroff and troff,
are both able to interpret commands from one or more UNIX files
that specify how the output of any text should look.
This document, for example, is a text that has been typed in
with the appropriate commands to produce titles, section headers,
paragraphs, double columns, etc.
The nroff program is used for typewriter-like terminals,
the troff program for a phototypesetter.
Although they are separate programs,
nroff and troff are very compatible.
They share the same command language and
work in such a way that it is possible to use
nroff for typewriter or lineprinter output (usually for early
drafts of papers) and then to use
troff for final phototypesetter
output-both from the same input file.
For convenience, we will refer usually to nroff, but
it should be understood that what is said
applies also to troff unless stated otherwise.
Normally, the text of a document is typed on lines
of varying length even though lines of uniform length
are desired in the finished document.
One of nroff’s most important functions is
filling,
the process of collecting words from the input
file and placing them on an output line until no more
will fit within a given
line length.
Hyphenation
is also provided, so that a line may be
completed with part of a word
to obtain a line of the right length.
Unfortunately, hyphenation with nroff is only about
95 percent accurate,
but there are ways of correcting problems.
After the line has been filled,
adjustment
inserts spaces between words as necessary to
bring the text exactly to the right margin.
(It is also possible to obtain a ragged right margin
(explained in section 3, below),
as used in this document.)
Filling, hyphenating, and adjusting
are illustrated by the following examples.
Text that is not filled:
The Caterpillar and Alice
looked at each other
for some time in silence:
at last
the Caterpillar took the hookah
out of its mouth,
and addressed her in a sleepy,
languid voice.
Filled but not adjusted:
The Caterpillar and Alice looked at each
other for some time in silence: at last
the Caterpillar took the hookah out of
its mouth, and addressed her in a
sleepy, languid voice.
Filled and adjusted:
The Caterpillar and Alice looked at each
other for some time in silence: at last
the Caterpillar took the hookah out of
its mouth, and addressed her in a
sleepy, languid voice.
Given a file of input consisting only of lines of text
without any formatting commands,
nroff would produce simply a continuous stream of
filled, adjusted and hyphenated output.
Additional operations such as producing paragraphs,
providing margins at tops and bottoms of pages,
and saving footnotes to be printed at the bottoms of
pages, must be requested by means of formatting commands.
Nroff provides a flexible, sophisticated command language
for requesting operations of the sort just mentioned.
Largely because of its high degree of flexibility,
however, this language can be very difficult to use.
Even a relatively simple formatting task like
beginning a paragraph is a multi-step process
in the nroff language.
For most documents, it is advantageous to use
instead the commands provided by a macro package.
A macro is simply a
predefined sequence of nroff commands and/or text
which you can invoke by including just one command in your
input file.
This makes it possible to handle repetitious tasks,
such as starting paragraphs,
by typing one command each time instead of several.
The -ms macro package has simple commands for a large number of
common formatting tasks.
The macro package has other kinds of functions as well,
some of which are less visible
but equally important.
Although nroff provides commands and mechanisms for arranging
page layouts with top and bottom
margins, page numbers, and running titles
automatically placed on every page,
it doesn’t do any of these things on its own without instructions.
The -ms macro package supplies such instructions
“behind the scenes” by taking care of some of the more difficult
programming problems involved in handling
footnotes and page transitions.
For example, when the macro package is used, a page layout style is set
up automatically.
On the other hand, should you wish to change the formatting style, the macro
package also leaves you a great deal of flexibility to alter the page layout.
In general, the commands of -ms, rather than
the more numerous building-blocks of the nroff language,
are the only instructions needed to format a text.
(There are some exceptions to this rule
discussed in section 3.)
Thus, although the macro package offers a limited subset
of the wide range of formatting possibilities afforded
by nroff,
these are usually sufficient for formatting most texts, and the
ease of use is a convenient feature.
An input file for nroff, containing
text and formatting commands,
is created with the text editor.
Here is a small example of an input file:
.TL
Simple Sample Document
.PP
These are a few lines of sample text.
It doesn’t matter that there is no initial
indentation or that the lines are both
long and short,
because nroff or troff
will take care of that later.
Notice that in this file,
some lines contain nothing but text
while the others, beginning with a period,
contain formatting commands.
This example illustrates several rules
to be observed when typing an input file.
First, some rules with regard to the text:

• A line of text should normally end with the end of a word,
  along with any trailing punctuation,
  because by default nroff always inserts a space
  between whatever ends one line of input text
  and whatever begins the next.
  Breaking a word, even a compound word that is normally
  hyphenated, at the end of a line
  will create an extra, unwanted space in the output.
• Lines in the input file
  should always start with characters other than a space,
  since that would cause a
  break
  at that point in the output, and nroff would
  skip immediately to a new output line,
  interrupting the process of filling and adjusting.
  Do not be concerned that the input text paragraph does not
  look like an indented, typed paragraph in your input file.
• Although text lines can vary in length,
  it is a good idea to
  keep them fairly short and
  type the RETURN key at ends of phrases
  and ends of sentences.
  There are two reasons for this.
  First, it makes the input file easy to modify later.
  Second, whenever sentence-ending punctuation
  (period, question mark, or exclamation point)
  occurs at the end of an input line,
  nroff leaves two spaces following the sentence.
  To obtain this effect consistently,
  always go to a new input line when starting a new sentence.

Second, some rules governing commands:

• A period or an apostrophe (‘) as
  the first character on a line indicates to nroff
  that the line contains a formatting command.
  (The two control characters have slightly different meanings
  in a few cases;
  it is preferable to use the period except in rare instances when
  the alternate effect is needed.
  This point is explained in A Troff Tutorial.
  See “For More Information,” section 7.)
  To type either of these
  control characters at the beginning of a line of text
  would be an error;
  nroff would try to interpret the line as a command,
  and the result, at best, would
  be the disappearance of that text from
  the formatted output.
• The control character, the period, is always followed
  by a one- or two-character
  name
  of a formatting command.
  In the -ms macro package, these
  commands usually consist of one
  or two capital letters;
  some are one capital letter and a numerical digit.
  In contrast, the nroff language, which allows
  single-step processes,
  has commands in lower-case letters alone or in combination with a digit.
• Some commands occur by themselves on a line such as title or paragraph
  designations (.TL or .PP).
  Other commands, however, can take one or more additional
  pieces of information on the same command line.
  These extra pieces of information are called
  arguments,
  and can be either a word or a number upon which
  the command is to operate,
  but they must be separated from the command itself
  (and from each other if there are more than one) by a space.
  Sometimes an argument is a piece of text
  on which the command operates;
  alternatively, it can simply be some additional information
  about what the command is to do.
  For example:
  .sp 3
  shows an nroff command with one argument.
  The command requests vertical space;
  the argument indicates the number of blank lines desired (three).
• Finally, there is an important rule about the order
  in which things should appear in an input file
  to be processed using the -ms macros:
  the file should never begin immediately with a line of text.
  Instead, one of the following -ms macros must
  precede the first line of text:
  .TL .SH .NH .PP .LP
  Such a command placed before the beginning of text
  is called the
  initializing or beginning macro
  in the file.
  These commands are described in the following pages.
  (This point is discussed more fully below,
  and sample beginnings of input files are shown
  in section 6.)
  If none of them seems to be exactly what you want, use
  .LP.
  The beginning macro must appear before any break
  generated by blank lines, leading spaces, or
  .sp, .br,
  and .ce requests.
  A blank line at the beginning of a text is often hard to see,
  but will result in various kinds of unpredictable behavior.

A left-block paragraph is produced by the command
.LP,
followed on subsequent lines by the text of the paragraph.
In the output, the paragraph is set off by vertical space from
whatever preceded it.
This particular paragraph, for example, was produced by
.LP.
     Another type of paragraph produced
by the command .PP
is the indented paragraph,
which is also preceded by vertical space
when printed, and has its first line indented.
This paragraph was produced by
.PP.
As part of the automatic page layout style mentioned in
section 1.2,
the amount of vertical spacing before paragraphs
and the width of the indentation normally have pre-defined
standard or default values.
These numbers can be modified from their default value
to suit the needs of each paper.
They are stored in memory spaces called number registers,
This is discussed at length in Section 2.14,
“Modifying Default Features,”
but one number register should be mentioned now:
the value of register PI (paragraph indent)
controls the amount of indentation for several macros,
including .PP, .XP (exdented paragraph),
.DS (display), and .RS (block indent).
For a completely indented or offset paragraph, a third paragraph
command, .IP, is available.
Here are some ways .IP
might be used in an input file:
.IP
The first example is simple.
This text will be set in a block
and the entire block will be indented
from the left margin.
.IP (2)
The second instance shows how to put
a hanging label on an indented paragraph.
The identification you want for
the label is typed as an
argument to the .IP command.
The label will be aligned at the left
margin of the paper, while the
paragraph will be indented
a standard amount.
.IP “Example 3” 12
A complication arises if the label
is too long to fit in the standard
indentation provided by the command.
In this case, you must request a non-standard
indentation as a second argument
on the command line.
Now let’s look at the way troff formats these paragraphs:
The first example is simple. This text will
be set in a block and the entire block will
be indented from the left margin.
(2) The second instance shows how to put a
hanging label on an indented paragraph.
The identification you want for the label is
typed as an argument to the .IP command.
The label will be aligned at the left margin
of the paper, while the paragraph will be
indented a standard amount.
Example 3 A complication arises if the label is
too long to fit in the standard
indentation provided by the
command. In this case, you must
request a non-standard indentation
as a second argument on the
command line.
The new indentation in Example 3 is requested by the number
which follows the label after a space and indicates the
ens
of distance.
(This term is a unit of dimension used frequently in typesetting,
and will be discussed in section 2.15 in relation
to nroff and troff.)
After an indented paragraph with non-standard indentation,
that indentation stays in effect for a series
of consecutive .IPs, until the next
.LP or .PP is used.
At this point, it is reset back to the standard indentation.
Note also that the label “Example 3,” because it
contains a space, must be marked
off as a single unit in one of two ways-otherwise “Example”
would be read as the label and “3” as the length,
with visually unpleasant results.
One way to mark the label is to enclose it in double quotes ” “,
as shown above.
(You will find, as you do more with UNIX, that the arguments to
many other commands are enclosed within double quotes, particularly
if they contain spaces.)
The other way would be to precede the space with a backslash,
making it a fixed or unpaddable space which will
not be read as the boundary between the label and the length:
Example\ 3
A fourth macro, .QP, produces a block-quote
paragraph that is centered and indented on
both left and right:
One could use this macro, for instance, for direct quotations
of prose that need to be offset because of length but do not need special
formatting display like that in poetry.
This paragraph was produced by .QP.
If you are producing a paper with double-spaced text and
single-spaced indented quotations, add the line .vs 12p
between the .QP and the beginning of text.
Do this for each quoted paragraph:
.QP
.vs 12p
(Text)
The next .LP or .PP will restore the double spacing.
There is a new macro especially useful for bibliographic entries.
An .XP stands for “exdented paragraph,”
and produces a first line that extends
beyond the rest of an indented entry.
The following examples illustrate how these paragraphs look:
Lumley, Lyle S., Sex in Crustaceans: Shell Fish Habits, Harbinger
Press, Tampa Bay and San Diego, October 1979. 243 pages. The
pioneering work in this field.
Leffadinger, Harry A., “Mollusk Mating Season: 52 Weeks, or All
Year?” in Acta Biologica, vol. 42, no. 11, November 1980. A
provocative thesis, but the conclusions are wrong.
Of course, you will have to italicize the book title and journal
and quote the title of the journal article yourself;
these commands are covered in section 2.5.
This macro only sets up a standard format for a bibliography entry.
The indentation level can be changed if you wish;
sections 2.14 and 2.15 explain
how to go about doing this.
Two varieties of section headings are available with -ms:
unnumbered with .SH,
and automatically numbered with .NH.
In either case, the text of the section heading
is typed on one or more lines following the command,
and the output heading, which is preceded by one line of vertical space,
begins at the left margin.
(To end a section heading and begin normal text,
use a paragraph command such as .PP or .LP.)
Note that nroff underlines the heading,
while troff sets it in boldface type.
The following example shows how the section headings
in this document were produced:
.NH
Introduction
.NH 2
Filling, Adjusting, and Hyphenating
.NH 2
Purposes of a Macro Package
.NH 2
Typing an Input File
.NH
Commands and Features of -ms
The input shown above generates the following output:
1. Introduction
1.1. Filling, Adjusting, and Hyphenating
1.2. Purposes of a Macro Package
1.3. Typing an Input File
2. Commands and Features of -ms
To extend the section header to a third level (to get 1.1.1 and
1.1.2, for instance) the .NH 2
command and text would be followed by .NH 3
and the appropriate third level section header title.
Most texts, however,
would require only a two-level designation for numbering.
More complicated divisions would probably be better represented
by some form of outline, which is covered in the next section.
Using .NH 0
cancels the numbering sequence in effect
and produces a section heading numbered 1.
The position of a paper’s left margin is determined by
two page-layout dimensions, the
page offset and the indentation.
The page offset represents an absolute limit for the left margin
and usually is not changed at any point in the paper.
The indentation, on the other hand, controls the
current left margin (the place where a section heading or an
.LP
paragraph begins), and this may be varied from one
part of the paper to another.
Indentation is expressed as a distance to the right of
the page offset.
The indentation is set by default to zero, that is,
the same point at which the page offset is placed.
It cannot be moved to the left of the page offset.
Two macros, .RS and .RE,
allow you to shift the indentation
of a paper to the right and back to the left, respectively.
The amount shifted is, by default, 5 ens.
More than one .RS may be used to shift the indentation a
larger amount;
to get back to the original margin, each
.RS must be balanced by an .RE.
For example, this input:
.IP I.
Branches of Government
.RS
.IP A.
Executive
.IP B.
Legislative
.RS
.IP 1.
House
.IP 2.
Senate
.RE
.IP C.
Judicial
.RE
produces this output:
I. Branches of Government
A. Executive
B. Legislative
1. House
2. Senate
C. Judicial
The macros .FS and .FE
indicate the beginning and end of material to be
saved and printed at the bottom of the page as a footnote.
The commands would appear in the following way in the input file,
and the footnote would be printed at the bottom of this column:
[Can’t find a way to do footnotes with HTML–jrp.]
This sentence is in the
main body of text.*
.FS *
This is the footnote.
.FE
Continuation of the text . . .
By default, footnotes are given a line length
slightly shorter than the normal text, and, when typeset,
appear in smaller size type.
The commands only save a passage of text
for printing at the bottom of the page;
they do not mark the footnote reference in any way.
Thus, in the example above, the asterisk had to be
included as part of the text preceding the footnote,
and again just before the footnote text, as an argument
to the .FS macro.
Any character may be used as a footnote marker.
After arabic numerals and lower-case letters,
the most common footnote markers are the asterisk,
the dagger, represented as \(dg,
and the double dagger, represented as \(dd.
One important feature is automatically numbered footnotes.
Footnote numbers are printed by means of a pre-defined string
(\**), which is typed into the text where you would normally
have a footnote number or other designation.
Each time it is used,
this string increases the footnote number by one,
whether you use .FS
and .FE
in your text to make the footnotes appear at the bottom of the page,
or whether you have the notes appear at the end of the paper.
On the phototypesetter and on daisy-wheel terminals,
footnote numbers will be superscripted,
but on low-resolution devices (such as the lineprinter or video
display terminal), they will be bracketed.
If you use \** to indicate numbered footnotes,
then the .FS
macro will automatically include
the footnote number at the bottom of the page.
This footnote, for example, was produced as follows:
[Sorry, still no footnotes in HTML–jrp.]
This footnote, for example,
was produced as follows:\**
.FS
This is the footnote.
.FE
If you never use the “\**” string,
no footnote numbers will appear anywhere in the text,
including down in the footnote.
But if one time you neglect to use it,
the footnote number will remain the same
as that of the previous reference.
Do not forget the .FE
to mark the end of a footnote in the text.
Failure to include it causes the rest of your text to be
processed as if it were part of the footnote,
causing an error called a “macro/diversion overflow.”
Endnotes may be produced with the endnote program,
which takes normal -ms footnotes described above,
and moves them to the end of your output.
It should be used with numbered footnotes only,
or else it will not be clear which endnotes are which.
Before using the endnote program,
you must copy it into your own directory and make it executable.
This needs to be done only once:
% cp /usr/lib/ms/endnote endnote
% chmod +x endnote
When you want to produce numbered endnotes instead of footnotes,
you can run the program as follows:
% endnote filename | nroff -ms
The endnote program creates the file “endnotes”
in the current working directory;
this file is removed after endnote finishes.
If the “endnotes” file already exists,
the program exits with an error message.
Emphasis in typewritten material is usually indicated
by underlining.
In typesetting the convention is different;
the usual way to emphasize words is to set them
in a different typeface such as
italic or boldface.
In keeping with the design of compatibility between
nroff and troff,
-ms provides commands which emphasize text
in a manner appropriate to the type of output.
The macro .I
produces italics on the typesetter (using troff), and
underlining on typewriter output (using nroff).
The command .B
gives boldface typesetting and underlined typewriting.
A third macro, .R,
restores the roman typeface or non-underlined typewriting.
The commands are used this way:
.I
Either this text will appear in italics,
or it will be underlined (if nroffed).
.B
This text will be set in boldface
or it will be underlined (if nroffed).
.R
This text will be printed in normal style.
If only one word is needed in italics or boldface,
it may be given as an argument on the command line,
like the following:
.I word
or
.B word
Since the remainder of the text does not begin until the line following
the command and argument, no .R
is needed to restore normal printing for the following text.
Also, when .I or .B
is used with a word as an argument,
it can take as a second argument any trailing punctuation
to be printed immediately after the word,
but set in normal typeface.
For example:
.B word )
will print the word in boldface while the closing parenthesis will appear
in the normal typeface, directly adjacent to the word.
Another method that produces italics in
troff for more than one word–
whole sections of text if necessary–
is changing the font by using backslash-f with the letters
I (for italic), B (for bold), and R (for roman).
For example, this word italic was produced by typing
\fIitalic\fR in the input file.
The same could be done for any amount of text you want to set off.
(You do not need to begin and end a font change in the same
input line, though checknr
will complain if you don’t.)
This method not only reduces the number of lines in your input file,
but also gives you a better idea of what the output lines will look like.
In some cases, such as tables or displays, in-line font change commands
are the only kind that will work.
With nroff, changing to “italics”
will produce underlining, but changing to “boldface” will
not show at all on many printers.
On the typesetter, actual
underlining
is available only in a limited way
for a single word at a time, by means of the
.UL command.
It is used like this:
.UL word
Unlike italicizing, there is no shortcut for underlining more than one
word at a time on the typesetter.
The .UL
command must be repeated for each word to be underlined.
Three macros control the size of type used for troff output.
The command .LG
increases the type size by two points
(A point
is another unit of dimension used commonly in typesetting;
its precise meaning is discussed later
(see section 2.15)),
while .SM
decreases it by two points.
Either command may be repeated
for added effect, like this. [Sorry, no size change in HTML–jrp.]
The macro .NL
restores the normal point size,
canceling all accumulated changes.
These commands are useful primarily for
temporary size changes for a small number of words.
They do not affect vertical spacing of lines of text.
Other techniques are available for changing
the type size and vertical spacing of longer passages.
(See “Modifying Default Features,”
section 2.14.)
Commands for changing type size are always ignored by nroff.
A box can be drawn around a single word with the
.BX macro, which is used as follows:
This
.BX word
will appear in a box.
The output looks like this:
This word will appear in a box.
[Sorry, no boxes in HTML–jrp.]
To get several lines of text enclosed in
a box, precede the text with
.B1 and follow it with
.B2:
.B1
These boxes are designed to look good
when typeset, but aren’t as pleasing
in typewriter output.
.B2
The output looks like this:
These boxes are designed to look good when typeset,
but aren’t as pleasing in typewriter output.
[Sorry, no boxes in HTML–jrp.]
A group of macros is available to format items
that typically appear on the cover sheet and/or
title page of a paper.
These commands generate
a formally laid-out cover sheet and title page.
It is possible to use them selectively
(you might use the .TL
command without the others);
but if several are used,
they should appear in the order shown below,
normally at or near the beginning of the input file:
.RP (requests a separate cover sheet)
.TL
The title of the paper goes here;
it may occupy one or more lines.
.AU
One or more author’s names,
arranged on one or more lines,
as you would like them to appear.
.AI
The author’s institution,
arranged on one or more lines.
.AB
Abstract of the paper: a brief
description of its contents.
.AE (marks the end of the abstract)
If the macro .RP
precedes .TL,
the title, author, author’s institution, and abstract material
will be printed separately on a cover sheet.
(If .RP is to be used, .TL
and the title must follow it.)
The title and author information, but not the abstract
will be repeated on page one of the paper,
without having to be typed again in the input file.
To suppress this repetition, use the command
.RP no
instead of just .RP.
In the absence of .RP,
all of this material appears on page one,
followed on the same page by the main text of the paper.
The abstract is preceded by a centered heading of
the word ABSTRACT.
To suppress this heading, use the command
.AB no instead of
.AB.
If there are several authors from
different institutions, the names and institutions
may be interleaved, with alternating
.AUs and .AIs.
The use of the cover sheet and title page commands is entirely optional;
if you do not want these, you may begin a paper
simply with a section heading or paragraph command.
When cover sheet/title page material does precede the
text, however, include a paragraph or section heading command
between the last title page command and the beginning
of the main text.
Otherwise, the cover sheet will never come out.
(Some sample beginnings of input files are
shown in section 6,
to help clarify the proper sequence of commands and text.)
With the -ms program,
nroff normally prints the current date at the bottom center
of every page starting with page one;
troff does not.
Both nroff and troff print
it on the cover sheet
if you have requested one with
.RP.
There are various ways of changing these defaults.
To eliminate the date from nroff output,
use the command
.ND
at the beginning of your input file.
To make troff print the date centered
at the foot of the page, use .DA.
To make nroff or troff print
some date other than the actual current date, use
.DA as follows:
.DA December 10, 1953
If you want a specified date to appear on the cover sheet and
nowhere else, use an .ND
command in the following way:
.ND May 1, 1787
Be sure that .ND or
.DA is placed before the .RP.
Notice that in the two examples above,
no double-quote marks were placed around the dates.
These two commands represent exceptions to the
rule that an argument containing spaces must be
enclosed within double-quote marks.
There are five new macros to help produce a table of contents.
All entries intended for the table of contents
must be enclosed in .XS
and .XE
pairs, with optional .XA
macros for additional entries.
The first argument to .XS or
.XA specifies the page number,
to be printed after a line of dots.
If this first argument is no, no page
number will be printed, as when a chapter and its
first subsection begin on the same page.
The second argument specifies the indentation level;
if this argument is missing,
the current indentation stays in effect.
Finally, the .PX
macro prints out the table of contents.
If you forget it, nothing will happen.
Here is a sample of typical input and output text:
.XS ii (Start)
Introduction
.XA 1
Chapter 1: History
.XA no
Chapter 2: Evidence
.XA 24 5 (indent 5 ens)
Heuristic Assumptions
.XA 35
Experimental Data
.XA 56 0 (go back to original indentation)
Conclusions
.XE (End)
.PX (Print out)Table of Contents
Introduction ………………… ii
Chapter 1: History …………… 1
Chapter 2: Evidence
Heuristic Assumptions …….. 24
Experimental Data ………… 35
Conclusions …………………. 56
The .XS and .XE
pairs may also be used throughout the body of a text
to collect a table of contents automatically,
including automatically generated page numbers.
For example, you might want to index each section header,
in which case you would do this:
.SH
Antecedents of Capitalism
.XS
Antecedents of Capitalism
.XE
If you are using numbered headings produced with the
.NH macro, and you want the heading
numbers included in the
table of contents, use this format:
.NH
Phylum Protozoa
.XS
\*(SN Phylum Protozoa
.XE
The \*(SN string will be replaced with
the number of the heading when the table of contents is output,
for example:
Table of Contents
1. Phylum Protozoa ………………. 1
2. Phylum Porifera ………………. 6
3. Phylum Coelenterata …………… 10
Or you can use the .TC
macro (rather than .PX)
at the end of the paper to print out the table of contents.
If you forget it, nothing will happen.
The two macros are almost identical, but
.TC causes a page break and resets the
page number to i (lower case Roman numeral one).
(Page i will thus appear after the last page of the
document, but nothing prevents you from shuffling it
up to the front.)
Note that this automatic indexing method will only
work correctly within a single run.
On the typesetter, a single run is limited to 35 pages.
If you do not request otherwise,
nroff produces output in single-column format.
By placing the command .2C
in your input file, the output
is printed in double-column format beginning
at that point.
Each column will have a width 7/15 that of the
text line length in single-column
format, and the “gutter,” or gap between columns,
will be 1/15 of the full line length.
To return to single-column, use the command
.1C.
Switching from double to single-column always causes
a skip to a new page.
To obtain formats of more than two columns,
use the command .MC
as follows:
.MC column-width
This will cause output to be formatted in as many columns
of the specified width as will fit on the page.
The column-width may be specified in any unit
of scale, but if no unit is indicated
the setting will be understood as a number of ens.
(Units of scale are discussed in section 2.15.)
An .MC
without any column-width specification means the same thing as
.2C. Any change in the number of columns,
except from one to a larger number,
causes a skip to a new page.
The -ms package provides macros for keeping
a block of text all together on one page.
There are two ways of doing this.
The standard “keep” is begun with the macro
.KS and ended with
.KE.
If there is enough room on the current page for the
material contained between these two macros,
nroff prints it there; if not,
it skips to the next page and prints it there instead.
The other type, called a “floating keep,”
is begun with .KF
and ended with .KE.
If it is necessary to skip to a new page to
print this material,
nroff first fills the current page with the
ordinary text that follows the keep in the input file.
This avoids leaving blank space at the bottom of the page
preceding the kept material.
A floating keep is most often used for positioning
a table or some other type of material not part
of the strict logical sequence of text.
Whichever style of keep you use,
it is essential to end each one with
.KE to complete the pair.
Otherwise, the remainder of your text will be processed as a keep,
and you will get a “macro/diversion overflow.”
In double- or multi-column formats, the keep macros
attempt to place all the kept material in the same column.
If the material enclosed within a keep turns
out to require more than a page of space,
or more than a column in multi-column format,
it will start on a new page or column and simply
run over onto the following page or column.
Occasionally it is desirable to format some text without
filling and adjusting it-for example,
a list of items or a stanza of poetry.
To turn off filling so that each output line
will correspond exactly to one line of input,
use the command
.DS to start the material and
.DE to end it.
By default, this material is indented from the left margin
by the value of PI.
Here is some sample input:
.DS
Display
text
lines
The resulting output is:
Display
text
lines
If you don’t want the indentation, use
.DS L to begin and
.DE to end:
you’ll get
something
like this.
A centered display begins with
.DS C:
this is an
example
of a centered display.
Note that in the example above,
each line is centered individually.
To produce a left-adjusted block that is
centered as a piece on the page,
use .DS B to start:
Something approximately
like this
will be the result.
Another possibility is .DS I,
which means the same thing as plain .DS.
You can specify the amount of indentation by including
another argument after either of these constructions;
.DS I 3 or .DS 3
begins a display to be indented 3 ens from the margin.
Any of the displays described above
is automatically put into a standard keep.
As with ordinary blocks of kept text, if there is not
enough room for the display on the current page,
the entire display will be saved and put onto the next page.
If you do not want to keep displays on a single page,
and want to avoid unsightly gaps in the text,
or if you have displays that are longer than a page,
use the display commands .BD,
.CD, .ID, or
.LD, instead of
.DS B, .DS C,
.DS I, or .DS L,
respectively.
These commands also have to be turned off with
.DE to end any type of display.
Failure to include the ending command causes problems
similar to those caused by failure to close a footnote or a keep.
One of the things -ms does to expedite
document formatting is to establish a standard
page layout style.
In papers produced with -ms,
the text line has a default length of six inches;
the indentation of the first line of a paragraph is
five ens; the page number is printed at the top center
of every page after page one;
and the header and footer margins are an inch wide.
Many of these features are controlled by values
stored by -ms as variables in the computer’s memory.
This makes it possible to alter the default format
characteristics by changing the values that control them.
The memory locations where these values are stored
are called number registers
and string registers.
The former hold numeric values; the latter hold strings of characters.
Number and string registers have names like those of commands,
one or two characters long.
For instance, the value of the line length is
stored in a number register named LL.
Unless you give a command to change the value stored
in register LL,
it will contain the standard or default
value (6 inches) assigned to it by -ms.
In order to change a dimension such as the line length
from its default value,
you can reset the associated number register.
To do this, use the nroff command
.nr as follows:
.nr LL 5i
The first argument is the name of a number
register, and the second is the value being assigned to it.
The value may be expressed as an integer
or may contain a decimal fraction.
When setting the value of a number register,
it is almost always necessary to include a unit of scale
immediately after the value.
In the example above,
the “i” as the unit of scale lets nroff
know you mean five inches
and not five of some other unit of distance.
But the point size (PS) and vertical spacing (VS)
registers are exceptions to this rule:
ordinarily they should be assigned a value as a number of points
without indicating the unit of scale.
For example, to change the vertical spacing from 12 points
(single spacing) to 24 points (double spacing),
use the command:
.nr VS 24
In the unusual case where you want to set the vertical
spacing to more than half an inch (more than 36 points),
include a unit of scale in setting the VS register.
Table 1 explains the units of
measurement available with nroff and troff.
+———————————————————–+
| Table 1 |
| Units of Measurement in Nroff and Troff |
+———————————————————–+
| __Meaning For__ |
| Unit Abbr Nroff Troff |
| point p 1/72 inch 1/72 inch |
| pica P 1/6 inch 1/6 inch |
| em m width of one distance equal |
| character to number of |
| points in the |
| current typesize |
| en n width of one half an em |
| character |
| vertical v amount of space in which each |
| space line of text is set, measured |
| baseline to baseline |
| inch i inch inch |
| centimeter c centimeter centimeter |
| machine u 1/240 inch 1/432 inch |
| unit |
+———————————————————–+
The units point, pica, em,
and en are units of measurement used traditionally in typesetting.
The vertical space
unit also corresponds to the typesetting term “leading,”
referring to the distance from the baseline
of one line of type to the baseline of the next.
Em and en are particularly interesting
in that they are proportional to the type size currently in use
(normally expressed as a number of points).
An em is the distance equal to
the number of points in the type size
(roughly the width of the letter “m” in that point size),
while an en is half that (about the width of the letter “n”).
These units are convenient for specifying dimensions
such as indentation.
In troff, em and en have their traditional meanings–
one em of distance is equal to two ens.
For nroff, on the other hand,
em and en both mean the same quantity of distance,
the width of one typewritten character.
The machine unit
is a special unit to which almost all dimensions are converted by
nroff and troff internally
when storing them in memory.
Although such a unit of measurement exists, it would never be used
to modify default dimensions.
One important aspect of number registers to remember is that
a change to a register such as LL
does not immediately change the related dimension
at that point in the output.
Instead, in the case of the line length,
the change takes place at the beginning of
the next paragraph, where -ms resets
various dimensions to the current values of the
related number registers.
Table 2 lists, for each register, the place
at which a change to the register actually takes effect.
If the effect is needed immediately–if, for instance,
you need to change the vertical spacing in the middle of a paragraph–
you must use the nroff command
.vs,
which controls the vertical spacing directly.
It takes effect at the place where it occurs
in your input file.
Since it does not change the VS
register, however,
its effect lasts only until the beginning of the
next paragraph.
As a general rule:
to make a permanent change, or one that will last
for several paragraphs until you want to change it again,
alter the value of the -ms register.
If the change must happen immediately, somewhere
other than the point shown in Table 2,
use the nroff command.
(See “For More Information,” section 7.)
If you want the change to be both immediate and lasting,
do both.
+———————————————————–+
| Table 2 |
| Summary of -ms Number Registers |
+———————————————————–+
| Reg. Takes |
| Name Controls Effect Default |
| PS point size next para. 10 |
| VS vertical spacing next para. 12 |
| LL line length next para. 6i |
| of text |
| LT line length next page same as LL |
| of page titles |
| FL line length next FS 5.5i |
| of footnotes |
| PD vertical distance next para. .3v (troff) |
| 1v (nroff) |
| DD vertical distance next DS .5v (troff) |
| around displays 1v (nroff) |
| PI para. indent next para. 5n |
| QI left and right next QP 5n |
| indent for QP |
| FI footnote indent next FS 5n |
| PO page offset next page ~1i (troff) |
| 0 (nroff) |
| HM header margin next page 1i |
| FM footer margin next page 1i |
| M1 space before page next page HM/2 |
| titles |
| M4 space after bottom next page FM/2 |
| titles |
+———————————————————–+
In setting up the default page layout,
-ms provides for six
string registers
to store the running titles to be printed at tops and
bottoms of pages.
Like number registers, string registers are
storage locations in the computer’s memory;
they differ in that their contents
are strings of characters rather than numeric values.
The three -ms string register names
for the top of every page other than the first,
which presumably has a title, are
LH, CH,
and RH.
They indicate the printed positions of left, center, and
right.
The string registers for the bottom of the page, including the first, are
LF, CF,
and RF,
For nroff output, the default value of
CH
is the current page number
surrounded on either side by hyphens;
CF
contains the current date as supplied by the computer.
For troff, CH
also contains the page number but CF
is empty.
The other four registers are empty by default
for both nroff and troff.
You can use the command
.ds
(“define string”) to assign a value to a string register.
For example:
.ds RF Not for publication
This causes the character string “Not for publication”
to be printed at the bottom right of every page.
No double-quote marks are needed to enclose the argument;
this is another exception to the rule about spaces within arguments.
In order to remove a string register,
simply use the .rm command.
For instance, to clear string register
CH,
making the center header blank on following pages,
use the command:
.rm CH
To put the page number in the right header, use this command:
.ds RH %
In page titles, both headers and footers, “%” is
a special symbol referring to nroff’s automatic page counter.
If you want hyphens on either side of the page number,
place them on either side of the % in the command.
It is also possible to produce custom headers and footers
that are different on even and odd pages.
The .OH and
.EH macros define odd and even headers, while
.OF and .EF
define odd and even footers.
Arguments to these four macros must be enclosed
within a set of four apostrophes.
For example:
.OH ‘\fISecrets of the Oyster Bed”%\fP’
.EH ‘\fI%”Chapter Five\fP’
In this example the title (for the italicizing here, see
section 2.4)
is printed on the left side of odd pages by being enclosed between
the first and second apostrophe.
The center area is left blank because nothing
is to be printed in the center header area.
Note that these two marks are single apostrophe marks,
not double quotation marks.
The page number designation
(italicized because it is within the font changes)
appears on the right side between the third and fourth apostrophes.
Any variations of the left, center, and right positions can be
made by adjusting the parts of a title within areas
delimited by the four apostrophes.
It is important not to use an apostrophe in the header text,
unless you use a different delimiter
around the left, center, and right portions of the title.
You can use any character as a delimiter,
provided it doesn’t appear elsewhere in the argument to
.OH, .EH, .OF,
or .EF.
The default limit to title length is nine words.
If you need more, enclose the entire title argument
in double quotation marks, also including the four apostrophes.
Another new feature that involves page headers and footers
is the .TM
macro for printing theses according to Berkeley standards.
(This thesis mode is much like the .th
macro in -me).
It will automatically put page numbers
in the upper right-hand corner of every page,
and number the first page.
In addition it suppresses the date in the center footer,
and doublespaces everything except quotes, displays, and keeps.
It should be used at the top of each file making up your thesis.
As a by-product, the invocation of .TM
defines the .CT
macro for chapter titles.
Using this macro whenever a new chapter begins will
move the page number from the right header to the center footer.
In a similar way the .P1
(P one) macro,
which can be used even without thesis mode,
prints the header (including page number) on page 1.
If you
want roman numeral page numbering,
put this line at the beginning of the file:
.af PN i
And in any line referring to the page number-where
in the header or footer to put it, for example-use
\\n(PN rather than %.
To go back to arabic numerals
and start a new section with page 1, insert the lines:
.af PN 1
.bp 1
If commands that set the values of string and number registers
are meant to take effect as of the first page of output,
they should be placed at or near the beginning of the input file,
before the beginning macro
(which, in turn, must precede the first line of text).
(The initializing or beginning macro can be the
title macro
or one of the paragraph or section heading macros.
This point is discussed in section 1.3.
Sample beginnings of input files are shown in section 6.)
Since the beginning macro causes what is called
a “pseudo page break” onto page one of the paper,
including the top-of-page processing for that page,
it is particularly important that commands
changing the value of the page offset, top and bottom margins, the
PO, HM,
and FM
number registers, and the page header string registers,
be placed before the transition onto the page
where they are intended to take effect.
Appendix B gives a list of
possible commands that can set up
a file and those that can start a file.
Certain foreign-language accent marks
have been predefined as strings in the -ms package.
Use them by placing a reference to the accent string
before the letter being accented.
The string reference
\*’
placed immediately before the letter “e” in input text,
as in:
t\*’el\*’ephone
causes an acute accent
to be placed over the “e” in the output:
téléphone
Here is a list of the seven accent strings provided by default
with examples of their printed form:
Input Output Input Output
\*’e é \*~a ã
\*`e è \*:u ü
\*,c ç \*Ce [sorry, can’t do in HTML–jrp]
\*.e ê
There are now a large number of additional foreign accent marks
as well as better definitions of the seven diacritical marks
above available for use.
To use them, the command .AM
must be included at the beginning of your document.
Unlike the default -ms accent marks,
the new accent strings should be placed
after the letter being accented.
Certain foreign-language constructs, however,
are entirely made up of the accent string.
Be careful to distinguish which is which in the following list:
[Sorry, some of these aren’t available in HTML–jrp.]
accent mark input output
—————————————————————–
acute accent e\*’ é
grave accent e\*` è
circumflex o\*^ ô
cedilla c\*, ç
tilde n\*~ ñ
question \*?
exclamation \*!
umlaut u\*: ü
digraph s \*8 ß
hacek c\*v
macron a\*_
underdot s\*.
o-slash o\*/ ø
angstrom a\*o å
yogh kni\*3t
Thorn \*(Th Þ
thorn \*(th þ
Eth \*(D- Ð
eth \*(d- ð
hooked o \*q
ae ligature \*(ae æ
AE ligature \*(Ae Æ
oe ligature \*(oe
OE ligature \*(Oe
These new diacritical marks will not appear or will be
placed on the wrong letter if
.AM
is not at the top of your file.
If .AM is at the top of your file,
the default -ms accent marks will be placed
on the wrong letter.
Choose one set or the other and use it consistently.
As an aid in producing text that will format correctly
with both nroff and troff,
there are some new string definitions that define dashes
and quotation marks for each of these two formatting programs.
The \(*- string will yield two hyphens in nroff,
but in troff it will produce an em dash–like this one.
The \*Q and \(*U strings
will produce open and close quotes in troff,
but straight double quotes in nroff.
(In typesetting, the double quote character
is traditionally considered bad form.)
The -ms macros make up a package in the sense that
they are designed to meet most formatting needs,
and to make it unnecessary to learn a large amount of detail
about the more complex nroff command language.
You can, however, use a small subset of nroff commands
without losing too much of the macro package’s simplicity.
It is necessary to use the nroff commands
.nr and .ds
to manipulate the -ms number and string registers,
as discussed previously.
In addition, the following nroff commands
may be used in a file to be processed using -ms.
The first three requests may be used anywhere,
while the remaining should not appear until after the beginning macro:
.ls n
Line spacing is set to n.
If n equals 2, then doublespace;
if n equals 1, return to singlespacing (the default).
.na
No adjust; turn off justification of right margin (ragged right).
.ad
Adjust both margins; this is the default adjust mode.
.pl n
Page length is set to n,
which may be specified in any unit: 9i produces pages nine inches long.
.bp
Begin a new page; spacing is turned off at the top of a page,
and does not begin until text starts coming out.
.sp n
Space: provide n blank lines
at this point in the output. If n is omitted,
the command requests one blank line
(the current value of the unit v).
You can attach a unit of dimension to n
to specify the quantity in units other than
a number of blank lines.
.br
Break line: start a new output line
whether or not the current one has been completely filled with text.
.ce n
Center the following n input text lines
individually in the output. If n is omitted,
only the next line of text is centered.
There is a reason for caution in using nroff commands
in a file also containing -ms macros.
The macro package executes
sequences of nroff commands on its own,
in a manner invisible to users.
By inserting your own nroff commands you run the risk
of introducing errors.
The most likely unintended result
is simply for your nroff commands to be ignored,
but in some cases the results can include
fatal nroff errors and expensive,
garbled typesetter output.
For a very mild example,
if you tried to produce a centered section heading
with the input:
.ce
.SH
Text of section heading
you would discover that the heading came out left-adjusted:
the .SH macro, appearing after the
.ce command,
overrules it and forces left-adjusting.
On the other hand, the sequence:
.sp
.ce
.B
Line of text
would successfully produce a centered,
boldface heading preceded by one line of vertical space.
(However, it would be better to use the .TL
macro.)
Because it is not possible to document in a simple way
which tricks like this work and which don’t,
it is suggested that adaptations of more sophisticated features
of the nroff language to files being
processed with -ms not be used
by new or casual users of the document formatting programs.
UNIX provides special programs to make formatting of tables
and mathematics relatively easy.
These programs are tbl to format tables,
and eqn and neqn to handle mathematics
for typesetter and typewriter output, respectively.
They each have their own command languages,
documented in separate writeups.
(See “For More Information,” section 7.)
Tables and equations are produced by “preprocessing”
an nroff input file:
the table and equation formatters convert material
entered in their command languages to straight nroff input,
and then nroff produces the tables or mathematics.
You can include tbl material
in your nroff input file along with ordinary text
(as was done in this paper to produce the tables on
pages 13 and 14).
The way to identify this material is to precede
each table with the command
.TS
and follow it with
.TE.
These have special meaning to the tbl preprocessor,
signaling the beginning and end of material
intended for it.
If you are using the -ms package, the commands
have additional significance as -ms macros.
In a file processed with -ms, tables are set off by
extra vertical space both before and after.
Also, -ms offers a variant
.TS H
for beginning a table.
This has a corresponding command,
.TH,
which is placed within the table data.
All table text up to the
.TH
is used as a continuation heading
if the table runs over onto more than one page.
For mathematics the situation is analogous.
.EQ
and
.EN
signal the beginning and end of material
to be processed by eqn or neqn.
When used with -ms, the
.EQ
and
.EN
commands cause the equation material to be formatted specially.
.EQ
can take one or two arguments.
One is a format indicator: use
.EQ I
for an indented equation,
.EQ L
for left-adjusted, and
.EQ C
for centered (the same thing you get with just
.EQ).
The other possible argument is an equation number,
which will be printed in the right margin
alongside the equation.
You can use either of these arguments without the other,
but if both are used, the format indicator should come first:
.EQ 3.1
specifies a centered equation numbered 3.1, while
.EQ L 3.2
specifies a left-adjusted equation numbered 3.2.
When you have finished preparing the input file for a document,
you are ready to produce the formatted output.
This is done by means of the UNIX commands
nroff
or troff.
To catch typographical errors and mistakes in formatting,
you might wish to preview the output.
There are ways to preview either
nroff or troff on crt (video screen)
terminals, typewriter terminals, or the lineprinter,
whichever is most convenient and appropriate.
In addition, troff output can be previewed on a
Tektronix 4015 graphics terminal,
providing a reasonable facsimile of phototypesetter output.
The general form of the command to produce output is:
% nroff options filename …
or
% troff options filename …
The options
are described fully in the description
of nroff and troff in section 1 of the
UNIX Programmer’s Manual.
We can only touch on them here, although
one should get special mention.
In the command:
% nroff -ms filename …
the -ms option has the effect of
informing nroff that you are using the
-ms macro package.
If you forget this option, you get continuous, unpaginated output
in which -ms macro commands are ignored.
More than one input file can be named on the command line
(as indicated by the ellipses after filename),
in which case nroff simply processes all of them,
in the order they appear, as if they were all one file.
Following are some examples of commands
you might use to get preview and final output of
various sorts.
Send nroff output to lineprinter:
% nroff -ms -Tlpr filename … | lpr
Produce nroff output on a Diablo or Xerox printer
with a 10 pitch (pica) daisy wheel:
% nroff -ms -Txerox filename …
There are many other kinds of printers besides the Diablo/Xerox;
if you have another brand, see
“For More Information,” section 7,
for a reference on this.
To produce a file with tables preprocess with tbl
and then pipe it to the regular command:
% tbl filename … | nroff -ms -Txerox
The same is true for producing a file with equations;
preprocess with neqn and follow the order
in the example below:
% neqn filename … | nroff -ms -Txerox
To produce a file with both tables and equations
the order is important, as shown below:
% tbl filename … | neqn | nroff -ms -Txerox
Typesetting produces high quality output text,
but is relatively expensive.
To put a job in the phototypesetter queue use:
% troff -Q -ms filename …
Typesetting a file with both tables and equations
(note that eqn is used with troff,
whereas neqn is used with nroff)
follows a command sequence similar to those above:
% tbl filename … | eqn | troff -ms -Q
Since the cost is high for this kind of output,
two ways of previewing are available.
To preview a troff approximation on the terminal,
you may use tbl and/or eqn as above,
and send output to the lineprinter:
% troff -a -ms filename … | lpr
To preview a troff approximation on the
Versatec V80 printer/plotter,
you may use tbl and/or eqn as above,
with a command of this form:
% troff -V -ms filename …
The output will allow you to preview what the
finished troff output will look like.
Since the Versatec uses a different typeface,
some of the characters and spacing may look
a trifle bizarre.
Paper charges for troff previewing on the Versatec are
about one-sixth as much as for phototypesetting;
processing charges, however, are a little higher.
Or, you may wish to use the Versatec to produce your final output,
lower in quality than the phototypesetter but
usually higher in quality than a lineprinter.
In this case you will use vroff rather than
troff -V, to provide a more attractive
typeface and more even spacing:
% vroff -ms filename …
% tbl filename … | eqn | vroff -ms
For more information on the Versatec printer/plotter,
see UNIX Text Formatting on the Versatec (UNX 4.3.4, $1.75
at the Computing Service Library),
or type help versatec while logged on to UNIX.
If you are unable to format text because of fatal
nroff errors,
then the
program may pinpoint your errors.
Some users even invoke
checknr
before trying to format a file for the first time:
% checknr filename …
Error diagnostics are given, along with an indication of the line number
where specific errors occur.
Following are three sample files of input for nroff or troff.
They are short, and are not meant to show the
usage of all of the features covered in the previous sections.
Rather, they focus on how to begin an input file.
The order of occurrence of
commands and text at the beginning of the file is important,
and a number of problems can arise from
errors at this point.
After each example are some comments.
No output from these samples is included here,
but as an exercise you might try creating input files
identical to the ones shown and then
using nroff to produce output from them.
The first example is a fairly simple one:
.ND
.nr LL 5.5i
.ds CH Hard Times – Chapter I
.ds CF – % –
.TL
Chapter I:
The One Thing Needful
.LP
Now, what I want is, Facts.
Teach these boys and girls nothing
but Facts.
Facts alone are wanted in life.
Plant nothing else, and root out
everything else.
You can only form the minds
of reasoning animals upon Facts:
nothing else will ever be of any
service to them.
When the file contains commands that set
values of number and string registers,
and the effect is wanted at the beginning of the output,
those commands should come first.
Their order relative to each other is not important.
The commands .ND
or .DA,
if used, should also be in this group appearing first.
Next comes the initializing macro,
which in this case is the
.TL command.
The paragraph command, .LP,
signifies the end of the title and the beginning
of the main text of the paper.
The second example is a bit more complex:
.ND
.nr LL 5.5i
.nr QI 10n
.ds LH Gulliver’s Travels
.ds CH
.ds RH Lilliput
.ds CF – % –
.LP
.ce
.B
.LG
Chapter VIII
.NL
.QP
.I
The author, by a lucky accident,
finds means to leave Blefuscu;
and, after some difficulties,
returns safe to his native country.
.R
.LP
Three days after my arrival, walking
out of curiosity to the north-east coast
of the Island I observed, about half
a league off, in the sea, somewhat that
looked like a boat overturned.
This example shows a typical way of specifying
a title by means other than the
.TL command.
The reason for using an alternate method is to
avoid the standard vertical placement of the
title provided by .TL,
and simply center it at the top of the page.
The subtlety here is that, because
.TL
is not being used, there must be another macro
to perform initialization.
In this case it is .LP,
included solely for this purpose,
even though the following line of text is
a title and not the beginning of a paragraph.
Finally, the third example shows the usage
of the cover sheet macros at the beginning of a file:
.ND
.ds CH
.ds CF – % –
.nr PS 9
.nr VS 11
.nr LL 5i
.nr PI 3n
.RP
.TL
Confessions of an
English Opium-Eater
.AU
Thomas De Quincey
.AB no
I here present you, courteous reader,
with the record of a
remarkable period of my life;
and according to my application of it,
I trust that it will prove,
not merely an interesting record, but
in a considerable degree, instructive.
.AE
.MC 2.3i
.PP
I have often been asked how it was,
and through what series of steps,
that I became an opium-eater.
Was it gradually,
tentatively, mistrustingly,
as one goes down a shelving beach into
a deepening sea, and
with knowledge from the first of the
dangers lying on that path;
half-courting those dangers, in fact,
whilst seeming to defy them?
When cover sheet/title page macros are used,
there are more things to keep in proper order.
The commands that change number and string registers
still come first.
Next should be the .RP
command, if a cover sheet is desired.
Following this are the commands and text
for the elements of the cover sheet and title page.
It is not necessary to include all of them,
but any that you use should be in the order
shown in section 2.7.
If an abstract is included,
don’t forget the .AE
to end the abstract.
After the cover sheet or title page material
there must be a section heading or paragraph macro,
after which begins the main body of text.
If multi-column format is wanted for the main text,
a .2C
or .MC
command may be placed between title page material
and the paragraph or section-heading command.
This document is intended to be the main
written source of information on formatting
ordinary text with nroff or troff
and the -ms macro package.
Other documents contain information not covered here.
If your text contains tables or mathematics,
you should consult the separate manuals describing
the programs that work in conjunction
with nroff and troff
to format that material:
Tbl-A Program to Format Tables
by M. E. Lesk,
and Typesetting Mathematics-User’s Guide
by Brian W. Kernighan and Lorinda L. Cherry.
A Troff Tutorial
by Brian W. Kernighan provides very useful supplementary
information on the nroff and
troff command language,
though it covers many features of these programs that should be used
only with caution in a file to be processed with -ms.
The comprehensive reference source, the
Nroff/Troff User’s Manual
by Joseph F. Ossanna,
is difficult to read and recommended mainly for prospective experts.
When you are ready to produce formatted
output, consult the
UNIX Programmer’s Manual
pages on nroff and troff
for details on command usage
and the various command-line options.
The manual writeup on eqn(1)
should also be consulted by users of eqn.
Writeups from the Programmer’s Manual
are available online by means of the
man command; the whole Manual is available
in printed form as well.
A one-page document entitled
Using Hardcopy Terminals with Nroff
contains tips for producing nroff output on
typewriter terminals such as the DTC 302, IPSI 1622, Xerox 1730, and others.
This includes instructions on how to set up the terminal,
and a list of identifiers for various terminal types.
Already mentioned was UNIX Text Formatting on the Versatec
(UNX 4.3.4, $1.75).
Other writeups are available online by means of the
help command.
Type help topics
for a list of topics.
All of the printed documentation mentioned here
is available at the Computing Services Library, 218 Evans Hall.
For further information, please drop by the Consulting Office
in 262 Evans Hall,
or phone the Consulting Office at 642-4072.
[For the current availability of these or other publications, see the
Workstation Support Services Documentation page.–jrp]
Jan Pardoejanp@eecs.berkeley.edu3/15/95