UNIX Text Formatting Using the -ms Macros

Computing Services
Library, 218 Evans Hall
University of California
Berkeley, California 94720
415-642-5205

UNX 4.3.2 May 1984

Abstract

Credits

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.

1. Introduction

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.

1.1 Filling, Adjusting, and Hyphenating

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.

1.2 Purposes of a Macro Package

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.

1.3 Typing an Input File

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.

2. Commands and Features of -ms

2.1 Paragraphs

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.

    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.

Example\ 3

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.

.QP
.vs 12p
(Text)

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.

2.2 Section Headings

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

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.3 Changes in Indentation

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

I.  Branches of Government
    A.  Executive
    B.  Legislative
        1.  House
        2.  Senate
    C.  Judicial

2.4 Footnotes and Endnotes

This sentence is in the
main body of text.*
.FS  *
This is the footnote.
.FE
Continuation of the text . . .

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

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

   % endnote filename | nroff -ms

2.5 Emphasis

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.

.I word

.B word

.B 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

2.6 Type Size Changes

2.7 Boxes Around Text

This
.BX  word
will appear in a box.

This word will appear in a box.

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

These boxes are designed to look good when typeset,
but aren't as pleasing in typewriter output.

2.8 Title Pages and Cover Sheets

.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)

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.)

2.9 Dates

.DA  December 10, 1953

.ND  May 1, 1787

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.

2.10 Tables of Contents

.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

.SH
Antecedents of Capitalism
.XS
Antecedents of Capitalism
.XE

.NH
Phylum Protozoa
.XS
\*(SN Phylum Protozoa
.XE

    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.

2.11 Multi-Column Formats

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.

2.12 Keeping Text Together

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.

2.13 Displays

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.

2.14 Modifying Default Features

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.

2.15 Dimensions

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                                            |
          +-----------------------------------------------------------+

2.16 Page Headers and Footers

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

2.17 Set-up Commands

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.

2.18 Accent Marks

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.)

3. Using Nroff/Troff Commands

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.

4. Including Tables and Equations

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.

5. Producing Output

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 checknr 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.

6. Sample Input Files

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.

7. For More Information

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]

Appendix A: Command Descriptions

Appendix B: The Order of Things

Appendix C: Names of -ms Macros, String Registers, and Number Registers