.so utp.mac
.utp
.\" Chapter 5
.chapter 1 "The \f(CWms\fP Macros
.LP
The
.UX
shell is a user interface for the kernel,
the actual heart of the operating system.
You can choose the C shell or Korn shell instead of the
Bourne shell, without worrying about its effects on the
low-level operations of the kernel.
Likewise, a macro package is a user interface for accessing the 
capabilities of the
.CW nroff /\c
.CW troff
formatter.
Users can select either the
.CW ms
or
.CW mm
macro packages (as well as other packages that are available on some 
systems) to use with
.CW nroff /\c
.CW troff .
.PP
The
.CW ms
package was the original Bell labs macro package,
and is available on many
.UX
systems, but it is no longer officially supported by
AT&T.
Our main reason for giving
.CW ms
equal time is that many Berkeley
.UX
systems ship
.CW ms
instead of
.CW mm .
In addition, it is a less complex package,
so it is much easier to learn 
the principles of macro design by studying
.CW ms
than by studying
.CW mm .
.PP
A third general-purpose package, called
.CW me ,
is also distributed with Berkeley
.UX
systems.
It was written by Eric Allman and is comparable to
.CW ms
and
.CW mm .
(Mark Horton writes us:
I think of
.CW ms
as the
FORTRAN
of
.CW nroff ,
.CW mm
as the
.CW PL/I ,
and
.CW me
as the Pascal.)
The
.CW me
package is not described in this book.
.PP
In addition, there are specialized packages \(em
.CW mv ,
for formatting viewgraphs,
.CW mptx ,
for formatting the permuted index found in the
.I "UNIX Reference Manual" ,
and
.CW man ,
for formatting the reference pages in that same manual.
These packages are simple and are covered in the standard
.UX
documentation.
.PP
Regardless of which macro package you choose,
the formatter knows only to 
replace each call of a macro with its definition.
The macro definition contains the set of requests that the
formatter executes.
Whether a definition is supplied with
the text in the input file or found 
in a macro package is irrelevant to
.CW nroff /\c
.CW troff .
The formatter can be said to be oblivious
to the idea of a macro package.
.PP
You might not expect this rather freely structured
arrangement between a macro package and
.CW nroff /\c
.CW troff .
Macros are application programs of sorts.
They organize the types of functions that you need to be able to do.
However, the actual work is accomplished by
.CW nroff /\c
.CW troff
requests.
.PP
In other words, the basic formatting capabilities are inherent in
.CW nroff
and
.CW troff ;
the user implementation of these capabilities to achieve particular 
formats is accomplished with a macro package.
If a macro doesn't work the way you expect,
its definition may have been modified.
It doesn't mean that
.CW nroff /\c
.CW troff
works differently on your system.
It is one thing to say
.CW nroff/troff "" ``
won't let me do it,'' and another to say,
"I don't have the macro to do it 
(but I could do it, perhaps)."
.PP
A general-purpose macro package like
.CW ms
provides a way of describing the format of various kinds of documents.
Each document presents its own specific problems, and macros help to 
provide a simple and flexible solution.
The
.CW ms
macro package is designed to help you format letters, proposals, memos, 
technical papers, and reports.
.PP
For simple documents such as letters,
.CW ms
offers few advantages to the basic format requests
described in Chapter 4.
But as you begin to format more complex documents,
you will quickly see the advantage of working with a macro package,
which provides specialized 
tools for so many of the formatting tasks you will encounter.
.PP
A text file that contains
.CW ms
macros can be processed by either
.CW nroff
or
.CW troff ,
and the output can be displayed on a terminal screen or printed on a line 
printer, a laser printer, or a typesetter.

.Ah "Formatting a Text File with \f(CWms\fP
.LP
If you want to format an
.CW ms
document for a line printer or for a terminal screen,
enter this command line:
.Ps
$ nroff -ms \fIfile(s)\fP
.Pe
.LP
To format for a laser printer or typesetter, enter this command line:
.Ps
$ troff -ms \fIfile(s)\fP | \fIdevice postprocessor\fP
.Pe
.LP
Be sure to redirect the output file or pipe it to the printer;
if you do not, the output will be sent to your terminal screen.

.Bh "Problems in Getting Formatted Output
.LP
There are two ways for a program to handle errors.
One is to have the program terminate and issue an error message.
The other way is to have it keep going in hopes that the problems won't 
affect the rest of the output.
The
.CW ms
macros take this second approach.
.PP
In general,
.CW ms
does its best to carry on no matter how scrambled the output looks.
Sometimes the problems do get corrected within a page or two;
other times the problem continues, making the remaining pages worthless.
Usually, this is because the formatter had a problem
executing the codes as they were entered in the input file.
Most of the time input errors are caused by not including one of the 
macros that must be used in pairs.
.PP
Because
.CW ms
allows formatting to continue unless the error is a "fatal" one,
error correction is characteristic of the
.CW ms
macro definitions.
Apart from the main function of the macro, some of them, such as the 
paragraph macro, also invoke another macro called
.CW \&.RT
to restore certain default values.
.PP
Thus, if you forget to reset the point size or indentation, you might 
notice that the problem continues for a while and then stops.

.Ah "Page Layout
.LP
As suggested in the last chapter,
one of the most important functions of a 
macro package is that it provides basic page layout defaults.
This feature makes it worthwhile to use a macro package
even if you don't 
enter a single macro into your source file.
.PP
At the beginning of Chapter 4, we showed how
.CW nroff
alone formatted a sample letter.
If we format the same letter with
.CW ms ,
the text will be adjusted on a page that has a default top and bottom 
margin of 1 inch, a default left margin, or page offset,
of about 1 inch, and a default line length of 6 inches.
.PP
All of these default values are stored in
number registers so that you can 
easily change them:
.TS
center;
lf(CW) l .
LL	Line Length
HM	Header (top) Margin
FM	Footer (bottom) Margin
PO	Page Offset (left margin)
.TE
.PP
For example, if you like larger top and bottom margins,
all you need to do 
is insert the following requests at the top of your file:
.Ps
\&.nr HM 1.5i
\&.nr FM 1.5i
.Pe
.PP
Registers such as these are used internally by a number of
.CW ms
macros to reset the formatter to its default state.
They will not take effect until one of those "reset" macros is 
encountered.
In the case of
.CW HM
and
.CW FM ,
they will not take effect until the
next page unless they are specified at 
the very beginning of the file.\**
.FS
These "reset" macros (those that call the internal macro
.CW .RT )
include
.CW .LP ,
.CW .PP ,
.CW .IP ,
.CW .QP ,
.CW .SH ,
.CW .NH ,
.CW .RS ,
.CW .RE ,
.CW .TS ,
and
.CW .TE .
The very first reset macro calls a special initialization macro called
.CW \&.BG
that is used only once, on the first page.
This macro prints the cover sheet, if any
(see "Cover Sheet Macros" later 
in this chapter), as well as performing some special first-page 
initialization.
.FE
.Ah Paragraphs
.LP
As we saw in the last chapter, paragraph transitions are natural 
candidates for macros because each paragraph generally will require 
several requests (spacing, indentation) for proper formatting.
.PP
There are four paragraph macros in
.CW ms :
.TS
center;
lf(CW) l .
\&.LP	Block paragraph
\&.PP	First line of paragraph indented
\&.QP	Paragraph indented from both margins
\&.IP	Paragraph with hanging indent (list item)
.TE
.PP
The
.CW .LP
macro produces a justified, block paragraph.
This is the type of paragraph used for most technical documentation.
The
.CW .PP
macro produces a paragraph with a temporary indent for the first line.
This paragraph type is commonly used in
published books and magazines, as 
well as in typewritten correspondence.
.PP
Let's use the same letter to illustrate the use of these macros.
In the original example (in Chapter 4), we left blank lines between 
paragraphs, producing an effect similar to that produced by the
.CW .LP
macro.
.PP
In contrast,
.CW .PP
produces a standard blank paragraph.
Let's code the letter using
.CW .PP
macros.
Because this is a letter, let's also disable justification with an
.CW .na
request.
And of course, we want to print the address block in no-fill mode, as 
shown in Chapter 4.
Figure 5.1 shows the coded letter and Figure 5.2 shows the formatted 
output.

.Bh "Spacing between Paragraphs
.LP
With
.CW nroff ,
all of the paragraph macros produce a full space between paragraphs.
However, with
.CW troff ,
the paragraph macros output a blank space of 0.3v.
Basically, this means that a blank line will output
one full space and the 
paragraph macros will output about a third of that space.
.PP
The amount of spacing between paragraphs is contained in the number 
register
.CW PD
.I "paragraph distance" ). (
If you want to change the amount of space generated by any of the 
paragraph macros, simply change the contents of this register.
.PP
For example, if you don't want to leave any space between paragraphs in 
the letter, you could put the following line at the start of your file:
.Ps
\&.nr PD 0
.Pe
.LP
This flexibility afforded by macro packages is a major advantage.
It is often possible to completely change the appearance of a coded 
document by resetting only a few
number registers at the start of a file.
(As we'll see, this statement is even more true of
.CW mm
than of
.CW ms ).

.Bh "Quoted Paragraphs
.LP
A paragraph that is indented equally from the left and right margins is 
typically used to display quoted material.
It is produced by
.CW .QP .
For example:
.KF
.Fs
.Ps
\&.QP
In the next couple of days, I'll be putting together a ...
\&.ad r
April 1, 1987
\&.sp 2
\&.ad
\&.nf
Mr. John Fust
Vice President, Research and Development
Gutenberg Galaxy Software
Waltham, Massachusetts 02159
\&.fi
\&.sp
\&.na
Dear Mr. Fust:
\&.PP
In our conversation last Thursday, we discussed a
documentation project that would produce a user's manual on
the Alcuin product.
Yesterday, I received the product demo and other materials
that you sent me.
\&.PP
Going through a demo session gave me a much better
understanding of the product.
I confess to being amazed by Alcuin.
Some people around here, looking over my shoulder, were
also astounded by the illustrated manuscript I produced
with Alcuin.
One person, a student of calligraphy, was really impressed.
\&.PP
In the next couple of days, I'll be putting together a
written plan that presents different strategies for
documenting the Alcuin product.
After I submit this plan, and you have had time to review,
it, let's arrande a meeting at your company to discuss
these strategies.
\&.PP
Thanks again for giving us the opportunity to bid on this
documentation project.
I hope we can decide upon a strategy and get started as
soon as possible in order to have the manual ready in time
for the first customer shipment.
I look forward to meeting with you towards the end of next
week.
\&.sp
Sincerely,
\&.sp 3
Fred Caslon
.Pe
.Fe "Letter Coded with \f(CWms\fP Macros
.KE

.Fs
.SS
.sp 2
.RS
.ad r
April 1, 1987
.sp 2
.ad
.nf
Mr. John Fust
Vice President, Research and Development
Gutenberg Galaxy Software
Waltham, Massachusetts 02159
.fi
.sp
.na
Dear Mr. Fust:
.PP
In our conversation last Thursday, we discussed a
documentation project that would produce a user's manual on
the Alcuin product.
Yesterday, I received the product demo and other materials
that you sent me.
.PP
Going through a demo session gave me a much better
understanding of the product.
I confess to being amazed by Alcuin.
Some people around here, looking over my shoulder, were
also astounded by the illustrated manuscript I produced
with Alcuin.
One person, a student of calligraphy, was really impressed.
.PP
In the next couple of days, I'll be putting together a
written plan that presents different strategies for
documenting the Alcuin product.
After I submit this plan, and you have had time to review,
it, let's arrange a meeting at your company to discuss
these strategies.
.PP
Thanks again for giving us the opportunity to bid on this
documentation project.
I hope we can decide upon a strategy and get started as
soon as possible in order to have the manual ready in time
for the first customer shipment.
I look forward to meeting with you towards the end of next
week.
.in +4i
.sp
Sincerely,
.sp 3
Fred Caslon
.in -4i
.RE
.sp 2
.SE
.Fe "Formatted Output
.LP
The
.CW .QP
macro produces a paragraph indented on both sides.
The pair of macros
.CW .QS
and
.CW .QE
can be used to mark a section longer than one paragraph
that is indented.
This is useful in reports and proposals that quote a length
from another source.
.Ps
\&.LP
I was particularly interested in the following comment
found in the product specification:
\&.QS
Users first need a brief introduction to what
the product does.
Sometimes this is more for the benefit of people
who haven't yet bought the product, and are just
looking at the manual.
However, it also serves to put the rest of the manual,
and the product itself, in the proper context.
\&.QE
.Pe
.LP
The result of formatting is:
.SS
.sp
.RS
I was particularly interested in the following comment
found in the product specification:
.QS
Users first need a brief introduction to what
the product does.
Sometimes this is more for the benefit of people
who haven't yet bought the product, and are just
looking at the manual.
However, it also serves to put the rest of the manual,
and the product itself, in the proper context.
.QE
.RE
.SE
.LP
Use the
.CW .QP
macro inside a
.CW .QS /\c
.CW .QE
block to break up paragraphs.

.Bh "Indented Paragraphs
.LP
The
.CW .IP
macro produces an entire paragraph indented from the left margin.
This is especially useful for constructing lists, in which
a mark of some kind
(e.g., a letter or number)
extends into the left margin.
We call these
.I "labeled item lists" .
.PP
The
.CW .IP
macro takes three arguments.
The first argument is a text label; if the label contains
spaces, it should be enclosed within quotation marks.
The second argument is optional and specifies the amount of
indentation; a default of 5 is used if the second argument
is not specified.
A third argument of 0 inhibits spacing before the indented
paragraph.
.PP
Item lists are useful in preparing command reference pages
that describe various syntax items, and in glossaries that
present a term in one column and its definition in the
other.
The following example shows a portion of the input file for
a reference page:
.\" page 111
.Ps
\&.IP figure 10
is the name of a cataloged figure.
If a figure has not been cataloged, you need
to use the LOCATE command.
\&.IP f:p 10
is the scale of the figure in relation to
the page.
\&.IP font 10
is the two-character abbreviation or full name
of one of the available fonts from the Alcuin
library.
.Pe
.LP
The following item list is produced:
.SS
.RS
.IP figure 10
is the name of a cataloged figure.
If a figure has not been cataloged, you need
to use the LOCATE command.
.IP f:p 10
is the scale of the figure in relation to
the page.
.IP font 10
is the two-character abbreviation or full name
of one of the available fonts from the Alcuin
library.
.RE
.SE
.LP
An
.CW .LP
or
.CW .PP
should be specified after the last item so that the text
following the list is not also indented.
.PP
If you want to indent the label as well as the paragraph,
you can use the
.CW .in
request around the list.
The following example:
.Ps
\&.in 10
\&.IP figure 10
is the name of a cataloged figure.
If a figure has not been cataloged, you need
to use the LOCATE command.
\&.in 0
.Pe
.LP
will produce:
.SS
.in 10
.IP figure 10
is the name of a cataloged figure.
If a figure has not been cataloged, you need
to use the LOCATE command.
.in 0
.SE
.LP
You can specify an absolute or relative indent.
To achieve the effect of a nested list, you can use the
.CW .RS
(you can think of this as either
.I "relative start"
or
.I "right shift" )
and
.CW .RE
.I "relative end" "" (
or
.I retreat )
macros:
.\" page 112
.Ps
\&.IP font 10
is the two-character abbreviation or full name
of one of the available fonts from the Alcuin
library.
\&.RS
\&.IP CU
Cursive
\&.IP RS
Slanted
\&.RS
\&.IP LH 5 0
Left handed
\&.IP RH 5 0
Right handed
\&.RE
\&.IP BL
Block
\&.RE
.Pe
.LP
The labels on the second level are aligned with with the
indented left margin of paragraphs on the first level.
.SS
.RS
.IP font 10
is the two-character abbreviation or full name
of one of the available fonts from the Alcuin
library.
.RS
.IP CU
Cursive
.IP RS
Slanted
.RS
.IP LH 5 0
Left handed
.IP RH 5 0
Right handed
.RE
.IP BL
Block
.RE
.RE
.SE
.LP
One thing you need to watch out for in using the
.CW .IP
macro is not to include space in the label argument.
Because of the way the macro is coded, the space may be
expanded when the finished line is adjusted.
The first line will not be aligned with the rest.
For example:
.Ps
\&.IP "font name" 10
is the two-character abbreviation or full name . . .
.Pe
.LP
might produce the following:
.SS
.RS
.IP "font name" 10
is the two-character abbreviation or full name
of one of the available fonts from the Alcuin
library.
.RE
.SE
.\" page 113
.LP
To avoid this problem, always use an unpaddable space
(a backslash followed by a space) to separate words in the
label argument to
.CW .IP .
This caution applies to many other formatting situations as
well.
.PP
Automatically numbered and alphabetized lists are not
provided for in
.CW ms .
(Chapter 16 shows how to write your own macros for this.)
However, by specifying the number or letter as a label, you
can make do with the
.CW .IP
macro.
For example:
.Ps
User-oriented documentation recognizes three things:
\&.in +3n
\&.IP 1) 5n
that a new user needs
to learn the system in stages, getting a sense of the
system as a whole while becoming proficient in performing
particular tasks;
\&.IP 2) 5n
that there are different levels of users, and not every
user needs to learn all the capabilities of the system in
order to be productive;
\&.IP 3) 5n
that an experienced user must be able to rely on the
documentation for accurate and thorough reference
information.
\&.in -3n
.Pe
.LP
This produces:
.SS
.RS
.LP
User-oriented documentation recognizes three things:
.in +3n
.IP 1) 5n
that a new user needs
to learn the system in stages, getting a sense of the
system as a whole while becoming proficient in performing
particular tasks;
.IP 2) 5n
that there are different levels of users, and not every
user needs to learn all the capabilities of the system in
order to be productive;
.IP 3) 5n
that an experienced user must be able to rely on the
documentation for accurate and thorough reference
information.
.in -3n
.RE
.SE
.LP
The number is indented three ens and the text is indented
five more ens.
(Note: If you are using
.CW nroff ,
you don't need to specify units on the indents.
However, if you are using
.CW troff ,
the default scaling for both the
.CW .IP
and the
.CW .in
requests shown in the previous example is ems.
Remember that you can append a scaling indicator to the
numeric arguments of most macros and
.CW troff
requests.)

.\" page 114
.Ah "Changing Font and Point Size
.LP
When you format with
.CW nroff
and print on a line printer, you can put emphasis on
individual words or phrases by underlining or overstriking.
When you are using
.CW troff
and send your output to a laser printer or typesetter, you
can specify variations of type, font, and point size based
on the capabilities of the output devices.

.Bh "Roman, Italic, and Bold Fonts
.LP
Most typefaces have at least three fonts available:
roman,
.B bold ,
and
.I italic .
Normal body copy is printed in the roman font.
You can change temporarily to a bold or italic font for
emphasis.
In Chapter 4, you learned how to specify font changed using
the
.CW .ft
request and inline
.CW \ef
requests.
The
.CW ms
package provides a set of mnemonic macros for changing fonts:
.TS
center;
lf(CW) l .
\&.B	bold
\&.I	italic
\&.R	roman
.TE
.LP
Each macro prints a single argument in a particular font.
You might code a single sentence as follows:
.Ps
\&.B Alcuin
revitalizes an
\&.I age-old
tradition.
.Pe
.LP
The printed sentence has one word in bold and one in italic.
.SS
.B Alcuin
revitalizes an
.I age-old
tradition.
.SE
.LP
If no argument is specified, the selected font is current
until it is explicitly changed:
.Ps
The art of
\&.B
calligraphy
\&.R
is, quite simply,
\&.I
beautiful
\&.R
handwriting;
.Pe
.LP
The example produces:
.SS
The art of
.B
calligraphy
.R
is, quite simply,
.I
beautiful
.R
handwriting;
.SE
.PP
You've already seen that the first argument is changed
to the selected font.
If you supply a second argument, it is printed in the previous font.
(You are limited to two arguments, set off by a space;
a phrase must be enclosed within quotation marks to be
taken as a single argument.)
A good use for the alternate argument is to supply punctuation,
especially because of the restriction that you cannot
begin a line with a period.
.Ps
its opposite is
\&.B cacography .
.Pe
.LP
This example produces:
.SS
its opposite is
.B cacography .
.SE
.LP
If the second argument is a word or phrase, you must
supply the spacing:
.Ps
The ink pen has been replaced by a
\&.I light " pen."
.Pe
.LP
This produces:
.SS
The ink pen has been replaced by a
.I light " pen."
.SE
.LP
If you are using
.CW nroff ,
specifying a bold font results in character overstrike;
specifying an italic font results in an underline
for each character (not a continuous rule).
Overstriking and underlining can cause problems on
some printers and terminals.
.PP
The chief advantage of these macros over the corresponding
.CW troff
constructs is the ease of entry.
It is easier to type:
.Ps
\&.B calligraphy
.Pe
.LP
than:
.Ps
\\fBcalligraphy\\fP
.Pe
.LP
However, you'll notice that using these macros
changes the style of your input considerably.
As shown in the examples on the preceding pages,
these macros require you to code your input file
using short lines that do not resemble the resulting
filled output text.
.PP
This style, which clearly divorces the form of the input
from the form of the output, is recommended by many
.CW nroff
and
.CW troff
users.
They recommend that you use macros like these rather
than inline codes, and that you begin each sentence
or clause on a new line.
There are advantages in speed of editing.
However, there are others (one of the authors included)
who find this style of input unreadable on the screen,
and prefer to use inline codes, and to keep the input
file as readable as possible.
(There is no difference in the output file.)

.Bh Underlining
.LP
If you want to underline a single word,
regardless of whether you are using
.CW nroff
or
.CW troff ,
use the
.CW .UL
macro:
.Ps
the
\&.UL art
of calligraphy.
.Pe
.LP
It will print a continuous rule beneath the word.
you cannot specify more than a single word with this macro.

.Bh "Changing Point Size
.LP
As discussed in Chapter 4,
you can change the point size and vertical spacing with the
.CW .ps
and
.CW .vs
requests.
However, if you do this in
.CW ms ,
you will find that the point size and vertical
spacing revert to 10 and 12 points,
respectively, after the next paragraph macro.
This is because the paragraph macro,
in addition to other tasks,
resets the point size and vertical spacing
(along with various other values) to 
default values stored in number registers.
.PP
The default point size and vertical spacing
for a document are kept in the registers
.CW PS
and
.CW VS ,
respectively.
If you want to change the overall point size or vertical spacing,
change the value in these registers.
(The default values are 10 and 12, respectively.)
For example, to change the body type to
8 points and the spacing to 10 points,
enter the following requests at the top of your document:
.Ps
\&.nr PS 8
\&.nr VS 12
.Pe
.LP
At the top of a document,
these settings will take effect immediately.
Otherwise, you must wait for the
next paragraph macro for the new values 
to be recognized.
If you need both immediate and long-lasting effects,
you may need a construct like:
.Ps
\&.ps 8
\&.nr PS 8
\&.vs 12
\&.nr VS 12
.Pe
.LP
There are also several macros for making local point size changes.
The
.CW .LG
macro increases the current point size by 2 points; the
.CW .SM
macro decreases the point size by 2 points.
The new point size remains in effect until you change it.
The
.CW .NL
macro changes the point size back to its default or normal setting.
For example:
.Ps
\&.LG
Alcuin
\&.NL
is a graphic arts product for
\&.SM
UNIX
\&.NL
systems.
.Pe
.\" page 117
.LP
The following line is produced:
.SS
.LG
Alcuin
.NL
is a graphic arts product for
.SM
UNIX
.NL
systems.
.SE
.PP
The
.CW .LG
and
.CW .SM
macros simply increment or decrement the current point size by 2 
points.
Because you change the point size relative to the current setting, 
repeating a macro adds or subtracts 2 more points.
If you are going to change the point size by more than 2,
it makes more sense to use the
.CW .ps
request.
The
.CW .NL
macro uses the value of the number register
.CW PS
to reset the normal point size.
Its default value is 10.
.PP
In the following example, the
.CW .ps
request changes the point size to 12.
The
.CW .LG
and
.CW .SM
macros increase and decrease the point size relative to 12 points.
The
.CW .NL
macro is not used until the end
because it changes the point size back to 10.
.Ps
\&.ps 12
\&.LG
Alcuin
\&.SM
is a graphic arts product for
\&.SM
UNIX
\&.LG
systems.
\&.NL
.Pe
.LP
It produces the following line:
.SS
.ps 12
.LG
Alcuin
.SM
is a graphic arts product for
.SM
UNIX
.LG
systems.
.NL
.SE
.LP
A change in the point size affects how much
vertical space is needed for the larger or smaller characters.
Vertical spacing is usually 2 points larger than the point size
(10 on 12).
Use the vertical spacing request to temporarily change the vertical 
spacing, if necessary.

.Ah Displays
.LP
A document often includes material \(em such as tables, figures, or 
equations \(em that are not part of the running text,
and must be kept together on the page.
In
.CW ms
and
.CW mm ,
such document elements are referred to generically as
.I displays .
.PP
The macros
.CW .DS ,
.CW .DE ,
.CW .ID ,
.CW .CD ,
and
.CW .LD
are used to handle displays in
.CW ms .
The display macros can be relied upon to provide
.Ls B
.Li
adequate spacing before and after the display;
.Li
horizontal positioning of the display as a left-justified, indented, or 
centered block;
.Li
proper page breaks, keeping the entire display together.
.Le
.\" page 118
.LP
The default action of the
.CW .DS
macro is to indent the block of text without filling lines:
.Ps
Some of the typefaces that are currently available are:
\&.DS
Roman
Caslon
Baskerville
Helvetica
\&.DE
.Pe
.LP
This produces:
.SS
.LP
Some of the typefaces that are currently available are:
.DS
Roman
Caslon
Baskerville
Helvetica
.DE
.SE
.PP
You can select a different format for a display by specifying a 
left-justified or centered display with one of
the following arguments:
.TS
center;
lf(CW) l .
I	Indented (default)
L	Left-justified
C	Center each line
B	Block (center entire display)
.TE
.PP
The
.CW L
argument can be used for formatting an address block in a letter:
.Ps
\&.DS L
Mr. John Fust
Vice President, Research and Development
Gutenberg Galaxy Software
Waltham, Massachusetts 02154
\&.DE
.Pe
.LP
The display macro prevents these lines from being filled;
it "protects" 
the carriage returns as they were entered in the file.
.PP
A display can be centered in two ways:
either each individual line in the display is centered
.CW C ), (
or the entire display is centered as a block
.CW B ) (
based on the longest line of the display.
.PP
The use of tabs often presents a problem outside of displays.
Material that has been entered with tabs in the input file should be 
formatted in no-fill mode, the default setting of the display macros.
The following table was designed using tabs to provide the spacing.

.\" page 119
.Ps
\&.DS L
Dates           Description of Task

June 30         Submit audience analysis
July 2          Meeting to review audience analysis
July 15         Submit detailed outline
August 1        Submit first draft
August 5        Return of first draft
August 8        Meeting to review documents
                and establish revisions
\&.DE
.Pe
.LP
This table appears in the output just as it looks in the file.
If this material had not been processed inside a display,
the columns would be improperly aligned.

.Bh "Static and Floating Displays
.LP
One of the basic functions of a display
is to make sure the displayed 
material stays together on one page.
If the display is longer than the
distance to the bottom of the page, 
there is a page break.
.PP
If the display is large,
causing a page break can leave a large bock of 
white space at the bottom of the page.
To avoid this problem,
.CW ms
provides a set of macros for
.I "floating displays" ,
as well as macros for the
.I "static displays"
we've already discussed.
If a floating display doesn't fit on the page,
the formatter doesn't force a page break.
Instead, it simply holds the displayed text in reserve
while it fills up 
the remainder of the page with the text following the display.
It prints the display at the top of the next page,
then continues where it left off.
.PP
We have already used
.CW .DS
and
.CW .DE
to mark the beginning and end of a static display.
To specify a floating display, the closing mark is the same but the 
beginning is marked by a different macro:
.TS
center;
lf(CW) l .
\&.ID	Same as \f(CW.DS I\fP (indented) but floating
\&.LD	Same as \f(CW.DS L\fP (left justified) but floating
\&.CD	Same as \f(CW.DS C\fP (center each line) but floating
\&.BD	Same as \f(CW.DS B\fP (center display) but floating
.TE
.PP
In the following example of an input file,
numbers are used instead of actual lines of text
to make the placement of the display more obvious:
.Ps
1
2
3
4
5
\&.LD
.I "Long Display"
\&.DE
6
.\" page 120
7
8
9
10
.Pe
.LP
The following two formatted pages might be produced,
assuming that there 
are a sufficient number of lines to cause a page break:
.sp
.nf
.nr my_wid (u;\n[.ll]/4u)
.mk
.po +(u;\n[my_wid]/2)
.ll \n[my_wid]u
.B1
.ce
- 1 -
1
2
3
4
5
6
.B2
.rt
.po +(u;\n[my_wid]*2)
.B1
.ce
- 2 -
\fILong Display\fP
7
8
9
10

.B2
.fi
.po \n(POu
.sp
.LP
If there had been room on page 1 to fit the display,
it would have been placed there,
and lines 6 and 7 would have followed the display,
as they did in the input file.
.PP
If a static display had been specified in the previous example,
the display would have been placed in the same position
on the second page, and lines 6 and 7 would have followed it,
leaving extra space at the bottom of page 1.
A floating display attempts to make the
best use of the available space on a page.
.PP
The formatter maintains a queue to hold
floating displays that it has not yet output.
When the top of a page is encountered,
the next display in the queue is output.
The queue is emptied in the order
in which it was filled (first in, first out).
.PP
The macros called by the display macros to
control output of a block of text are available for other uses.
They are known as "keep and release" macros.
The pair
.CW .KS /\c
.CW .KE
keep a block together and output it on the next available page.
The pair
.CW .KF /\c
.CW .KE
specify a floating keep;
the block saved by the keep can float and lines 
of text following the block may appear before it in the text.

.Ah Headings
.LP
In
.CW ms ,
you can have numbered and unnumbered headings.
There are two heading macros:
.CW .NH
for numbered headings and
.CW .SH
for unnumbered section headings.
.PP
Let's first look at how to produce numbered headings.
The syntax for the
.CW .NH
macro is:
.Ps
\&.NH [\fIlevel\fP]
[\fIheading text\fP]
\&.LP
.Pe
.\" page 121
.LP
(The brackets indicate optional arguments.)
You can supply a numerical value indicating the
.I level
of the heading.
If no value is provided for
.I level ,
then a top-level heading is assumed.
The
.I "heading text"
begins on the line following the macro
and can extend over several lines.
You have to use one of the paragraph macros, either
.CW .LP
or
.CW .PP ,
after the last line of the heading.
For example:
.Ps
\&.NH
Quick Tour of Alcuin
\&.LP
.Pe
.LP
The result is a heading preceded by a first-level heading number:
.SS
1.  Quick Tour of Alcuin
.SE
.LP
The next time you use this macro
the heading number will be incremented to 2,
and after that, to 3.
.PP
You can add levels by specifying a numeric argument.
A second-level heading is indicated by 2:
.Ps
\&.NH 2
Introduction to Calligraphy
\&.LP
.Pe
.LP
The first second-level heading number is printed:
.Ps
1.1 Introduction to Calligraphy
.Pe
.LP
When another heading is specified at the same level,
the heading number is automatically incremented.
If the next heading is at the second level:
.Ps
\&.NH 2
Digest of Alcuin Commands
\&.LP
.Pe
.LP
.CW ms
produces:
.SS
1.2  Digest of Alcuin Commands
.SE
Each time you go to a new level, .1 is
appended to the number representing the existing level.
That number is incremented for each call at the same level.
When you back out of a level
(for instance, when you go from level 5 to level 4)
the counter for the level (in this case level 5) is reset to 0.
.PP
The macro for unnumbered headings is
.CW .SH :
.Ps
\&.SH
Introduction to Calligraphy
\&.LP
.Pe
.LP
Unnumbered heading and numbered headings can be intermixed without 
affecting the numbering scheme:
.\" page 122
.SS
1.  Quick Tour of Alcuin
.LP
Introduction to Calligraphy
.LP
1.1  Digest of Alcuin Commands
.SE
.PP
Headings are visible keys to your document's structure.
Their appearance can contribute significantly
to a reader recognizing that organization.
If you are using unnumbered headings,
it becomes even more important to make headings stand out.
A simple thing you can do is use uppercase letters for a first-level 
heading.

.Ah "Cover Sheet Macros
.LP
In their original incarnation at Bell Laboratories, the
.CW ms
macros were called on to format many internal AT&T documents.
Accordingly, it is not surprising that there were
quite a few macros that 
controlled the format of specific internal document types.
What is surprising is that these macros are
still present in copies of the
.CW ms
macros distributed outside of AT&T.
.PP
You have the option of specifying that your document contains
Engineer's Notes
.CW .EG ), (
an Internal Memorandum
.CW .IM ), (
a Memorandum for Record
.CW .MR ), (
a Memorandum for File
.CW .MF ), (
a Released Paper
.CW .RP ), (
a Technical Report
.CW .TR ), (
or a letter
.CW .LT ). (
.PP
Many of these formats are quite useless outside of AT&T, unless you 
customize them heavily for other institutions.
We prefer simply to ignore them.
.PP
In general, what these document type macros control is
the appearance of the document's cover sheet.
The contents of that cover sheet is specified
using the following macros:
.TS
center;
lf(CW) l .
\&.TL	Title
\&.AU	Author
\&.AI	Author's Institution
\&.AB	Abstract Start
\&.AE	Abstract End
.TE
.LP
These macros are general enough that
you can still use them even if you 
aren't from Bell Laboratories.
.PP
Each macro takes its data from the following line(s)
rather than from an argument.
They are typically used together.
For example:
.Ps
\&.TL
UNIX Text Processing
\&.AU
Dale Dougherty
\&.AU
Tim O'Reilly
.\" page 123
\&.AI
O'Reilly & Associates, Inc.
\&.AB
This book provides a comprehensive introduction to the major
UNIX text-processing tools.
It includes a discussion of vi, ex, nroff, and troff, as
well as many other text-processing programs.
\&.AE
\&.LP
.Pe
.LP
Exactly how the output will look
depends on which document type you have selected.
If you don't specify any of the formats,
you will get something like this:
.SS
.RS
.sp
.ce 99
.LG
.B "UNIX Text Processing"
.NL
.sp
.I
Dale Dougherty
.sp 0.5v
Tim O'Reilly
.R
.sp 0.5v
O'Reilly & Associates, Inc.
.sp 2
.I ABSTRACT
.ce 0
.sp 0.5v
.RS
This book provides a comprehensive introduction to the major
UNIX text-processing tools.
It includes a discussion of
.CW vi ,
.CW ex ,
.CW nroff ,
and
.CW troff ,
as well as many other text-processing programs.
.RE
.RE
.sp
.SE
.LP
You can specify as many title lines as you want following
.CW .TL .
The macro will be terminated by
any of the other cover sheet macros,
or by any paragraph macro.
For multiple authors,
.CW .AU
and
.CW .AI
can be repeated up to nine times.
.PP
The cover sheet isn't actually printed until a reset
(such as that caused by any of the paragraph macros)
is encountered, so if you want to print only a cover page,
you should conclude it with a paragraph macro even if 
there is no following text.
.PP
In addition, if you use these macros
without one of the overall document 
type macros like
.CW .RP ,
the cover sheet will not be printed separately.
Instead, the text will immediately follow.
Insert a
.CW .bp
if you want a separate cover sheet.

.Ah "Miscellaneous Features

.Bh "Putting Information in a Box
.LP
Another way of handling special information is to place it in a box.
Individual words can be boxed for emphasis using the
.CW .BX
command:

.\" page 124
.Ps
To move to the next menu, press the
\&.BX RETURN
key.
.Pe
.LP
This draws a box around the word RETURN.
.Ps
To move to the next menu, press the
.BX RETURN
key.
.Pe
As you can see,
it might be a good idea to reduce the point size of the 
boxed word.
.PP
You can enclose a block of material within a box
by using the pair of macros
.CW .B1
and
.CW .B2 :
.Ps
\&.B1
\&.H
\&.ce
Note to Reviewers
\&.R
\&.LP
Can you get a copy of a manuscript without annotations?
It seems to me that you should be able to mark up a
page with comments or 
other scribbles while in Annotation Mode and still
obtain a printed copy without these marks.
Any ideas?
\&.sp
\&.B2
.Pe
.LP
This example produces the following boxed section in
troff :

.B1
.H
.ce
Note to Reviewers
.R
.LP
Can you get a copy of a manuscript without annotations?
It seems to me that you should be able to mark up a
page with comments or 
other scribbles while in Annotation Mode and still
obtain a printed copy without these marks.
Any ideas?
.sp
.B2
.LP
You may want to place boxed information
inside a pair of keep or display macros.
This will prevent the box macro from breaking
if it crosses a page boundary.
If you use these macros with
.CW nroff ,
you must also pipe your output through the
.CW col
postprocessor as described in Chapter 4.

.Bh Footnotes

Footnotes present special problems \(em
the main is printing the text at 
the bottom of the page.
The
.CW .FS
macro indicates the start of the text for the footnote, and
.CW .FE
indicates the end of the text for the footnote.
These macros surround the footnote text that
will appear at the bottom of the page.
The
.CW .FS
macro is put on the line immediately following some kind of marker,
such as an asterisk, that you supply in the text and in the footnote.

.\" page 125
.Ps
\&... in an article on desktop publishing.*
\&.FS
* "Publish or Perish: Start-up grabs early page language
lead," Computerworld, April 21, 1986, p. 1.
\&.FE
.Pe
.LP
All the footnotes are collected and output
at the bottom of each page underneath a short rule.
The footnote text is printed in small type,
with a slightly shorter line length than the body text.
However, you can change these if you want.
.PP
Footnotes in
.CW ms
use an
.CW nroff /\c
.CW troff
feature called
.I environments
(see Chapter 14),
so that parameters like line length or font that are set 
inside a footnote are saved independently of the body text.
So, for example, if you issued the requests:
.Ps
\&.FS
\&.ft B
\&.ll -5n
\&.in +5n
Some text
~
~
~
\&.FE
.Pe
.LP
the text within the footnote would be printed in boldface,
with a 5-en indent, and the line length would be shortened by 5 ens.
The text following the footnote would be
unaffected by those formatting requests.
However, the next time a footnote was called,
that special formatting would again be in effect.
.SS
.RS
\l'3i'
.br
.B
* "Publish or Perish: Start-up grabs early page language lead,"
.br
.I Computerworld ,
April 21, 1986, p. 1.
.R
.RE
.SE
.LP
If a footnote is too long to fit on one page,
it will be continued at the bottom of the next page.

.Bh "Two-Column Processing
.LP
One of the nice features of the
.CW ms
macros is the ease with which you can create
multiple columns and format documents,
such as newsletters or data sheets, that are best suited to a 
multicolumn format.
.PP
To switch to two-column mode, simply insert the
.CW .2C
macro.
To return to single-column mode, use
.CW .1C .
Because of the way two-column processing works in
.CW ms ,
you can switch to two-column mode in the middle of a page,
but switching back to a single column forces a page break.
(You'll understand the reason for this when we return to two-column 
processing in Chapter 16.)
.PP
The default column width for two-column processing is
7/15th of the line length.
It is stored in the register
.CW CW
.I "column width" ). (
The gutter between the columns is
.\" page 126
1/15th of the line length, and is stored in the register
.CW GW
.I "gutter width" ). (
By changing the values in these registers,
you can change the column and gutter width.
.PP
For more than two columns, you can use the
.CW .MC
macro.
This macro takes two arguments,
the column width and the gutter width, and 
creates as many columns as will fit in the line length.
For example, if the line lengths are 7 inches, the request:
.Ps
\&.MC 2i .3i
.Pe
.LP
would create three columns 2 inches wide, with a gutter of .3 inches 
between the columns.
.PP
Again,
.CW .1C
can be used to return to single-column mode.
In some versions of
.CW ms ,
the
.CW .RC
macro can be used to break columns.
If you are in the left column,
following text will go to the top of the next column.
If you are in the right column,
.CW .RC
will start a new page.

.Ah "Page Headers and Footers
.LP
When you format a page with
.CW ms ,
the formatter is instructed to provide several lines
at the top and the bottom of the page for a header and a footer.
Beginning with the second page,
a page number appears on a single line in 
the header and only blank lines are printed for the footer.
.PP
The
.CW ms
package allows you to define strings that appear
in the header or footer.
You can place text in three locations in the header or footer:
left justified,
centered,
and right justified.
For example, we could place the name of the client,
the title of the document, and the date in the page header
and we could place the page number in the footer.
.SS
.DS
\&.ds LH GGS
\&.ds CH Alcuin Project Proposal
\&.ds RH \\*(DY
\&.ds CF Page %
.DE
.SE
You may notice that we use the string
.CW DY
to supply today's date in the header.
In the footer, we use a special symbol
.CW % ) (
to access the current page number.
Here are the resulting header and footer:
.SS
.nf
.ta 0.5i \n[.ll]u/2uC \n[.ll]u-0.5iR
	GGS	Alcuin Project Proposal	April 26, 1987
		\&.
		\&.
		\&.
		Page  2
.TA
.fi
.SE
.LP
Normally, you would define the
header and footer strings at the start of 
the document, so they would take effect throughout.
However, note that there is nothing to prevent you
from changing one or more of them from page to page.
(Changes to a footer string
.\" page 127
will take effect on the same page;
changes to a header string will take 
effect at the top of the next page.)

.Ah "Problems on the First Page
.LP
Because
.CW ms
was originally designed to work with the cover sheet macros
and one of the standard Bell document types,
there are a number of problems that can 
occur on the first page of a document that
doesn't use these macros.\**
.FS
This problem actually can occur on any page, but is most frequently 
encountered on the first page.
.FE
.PP
First, headers are not printed on the page,
nor is it apparent how to get 
them printed there if you want them.
The trick is to invoke the internal
.CW .NP
.I "new page" ) (
macro at the top of your text.
This will not actually start a new page,
but will execute the various 
internal goings-on that normally take place at the top of a page.
.PP
Second, it is not evident how to space down
from the top if you want to 
start your text at some distance down the page.
For example, if you want to create your own title page, the sequence:
.Ps
\&.sp 3i
\&.ce
\\s16The Invention of Movable Type\\s0
.Pe
.LP
will not work.
.PP
The page top macro includes an
.CW .ns
request, designed to ensure that all
leftover space from the bottom of one 
page doesn't carry over to the next, so that all pages start evenly.
To circumvent this on all pages after the first one,
precede your spacing request with an
.CW .rs
.I "restore spacing" ) (
request.
On the first page, a
.CW .fl
request must precede a
.CW .rs
request.

.Ah "Extensions to ms
.LP
In many ways,
.CW ms
can be used to give you a head start on defining your own macro 
package.
Many of the features that are missing in
.CW ms
can be supplied by user-defined macros.
Many of these features are covered in Chapters 14 through 18,
where, for example, we show macros for formatting numbered lists.
.\" end of chapter 5