mm
MacrosA macro package 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 mm
macro package is designed to help you format letters, proposals, memos, technical papers, and reports. A text file that contains mm
macros can be processed by either nroff
or troff
, the two text formatting programs in UNIX. The output from these programs can be displayed on a terminal screen or printed on a line printer, a laser printer, or a typesetter.
Some users of the mm
macro package learn only a few macros and work productively. Others choose from a variety of macros to produce a number of different formats. More advanced users modify the macro definitions and extend the capabilities of the package by defining their own special-purpose macros.
Macros are the words that make up a format description language. Like words, the result of a macro is often determined by context. That is, you may not always understand your output by looking up an individual macro, just like you may not understand the meaning of an entire sentence by looking up a particular word. Without examining the macro definition, you may find it hard to figure out which macro is causing a particular result. Macros are interrelated; some macros call other macros, like a subroutine in a program, to perform a particular function.
After finding out what the macro package allows you to do, you will probably decide upon a particular format that you like (or one that has evolved according to the decisions of a group of people). To describe that format, you are likely to use only a few of the macros, those that do the job. In everyday use, you want to minimize the number of codes you need to format documents in a consistent manner.
To figure out the role of a macro package such as mm
, it may help to consider the distinction between formatting and format. Formatting is an operation, a process of supplying and executing instructions. You can achieve a variety of results, some pleasing, some not, by any combination of formatting instructions. A format is a consistent product, achieved by a selected set of formatting instructions. A macro package makes it possible for a format to be recreated again and again with minimal difficulty. It encourages the user to concentrate more on the requirements of a document and less on the operations of the text formatter.
Working with a macro package will help reduce the number of formatting instructions you need to supply. This means that a macro package will take care of many things automatically. However, you should gradually become familiar with the operations of the nroff
/troff
formatter and the additional flexibility it offers to define new formats. If you have a basic understanding of how the formatter works, as described in Chapter 4, you will find it easier to learn the intricacies of a macro package.
nroff
/troff
with mm
The mm
command is a shell script that invokes the nroff
formatter and reads in the files that contain the mm
macro definitions before processing the text file(s) specified on the command line.
$ mm
option(s) filename(s)
If more than one file is specified on the command line, the files are concatenated before processing. There are a variety of options for invoking preprocessors and postprocessors, naming an output device, and setting various number registers to alter default values for a document. Using the mm
command is the same as invoking nroff
explicitly with the -mm
option.
Unless you specify otherwise, the mm
command sets nroff
’s -T
option to the terminal type set in your login environment. By default, output is sent to the terminal screen. If you have problems viewing your output, or if you have a graphics terminal, you may want to specify another device name using the -T
option. For a list of available devices, see Appendix B. The mm
command also has a -c
option, which invokes the col
filter to remove reverse linefeeds, and options to invoke tbl(-t)
and eqn(-e)
.
When you format a file to the screen, the output usually streams by too swiftly to read, just as when you cat
a file to the screen. Pipe the output of the mm
command through either of the paging programs, pg
or more
, to view one screenful at a time. This will give you a general indication that the formatting commands achieved the results you had expected. To print a file formatted with mm
, simply pipe the output to the print spooler (e.g., lp
) instead of to a screen paging program.
Many of the actions that a text formatter performs are dependent upon how the document is going to be printed. If you want your document to be formatted with troff
instead of nroff
, use the mmt
command (another shell script) or invoke troff
directly, using the -mm
option. The mmt
command prepares output for laser printers and typesetters. The formatted output should be piped directly to the print spooler (e.g., lp
) or directed to a file and printed separately. You will probably need to check at your site for the proper invocation of mmt
if your site supports more than one type of laser printer or typesetter.
If you are using otroff
, be sure you don’t let troff
send the output to your terminal because, in all probability, it will cause your terminal to hang, or at least to scream and holler.
In this chapter, we will generally show the results of the mm
command, rather than mmt
—that is, we’ll be showing nroff
rather than troff
. Where the subject under discussion is better demonstrated by troff
, we will show troff
output instead. We assume that by now, you will be able to tell which of the programs has been used, without our mentioning the actual commands.
When you format an mm
-coded document, you may only get a portion of your formatted document. Or you may get none of it. Usually, this is because the formatter has had a problem executing the codes as they were entered in the input file. Most of the time it is caused by omitting one of the macros that must be used in pairs.
When formatting stops like this, one or more error messages might appear on your screen, helping you to diagnose the problems. These messages refer to the line numbers in the input file where the problems appear to be, and try to tell you what is missing:
ERROR
:(filename) line numberSometimes, you won’t get error messages, but your output will break midway. Generally, you have to go in the file at the point where it broke, or before that point, and examine the macros or a sequence of macros. You can also run a program on the input file to examine the code you have entered. This program, available at most sites, is called checkmm
.
In Chapter 4, we looked at a sample letter formatted by nroff
. It might be interesting, before putting any macros in the file, to see what happens if we format letter
as it is, this time using the mm
command to read in the mm
macro package.
Refer to Figure 6-1 and note that
nroff;
When you format a page with mm
, the formatter is instructed to provide several lines at the top and the bottom of the page for a header and a footer. By default, a page number appears on a single line in the header and only blank lines are printed for the footer.
There are basically two different ways to change the default header and footer. The first way is to specify a command-line parameter with the mm
or mmt
commands to set the number register N
. This allows you to affect how pages are numbered and where the page number appears. The second way is to specify in the input file a macro that places text in the header or footer. Let’s look at both of these techniques.
When you format a document, pages are numbered in sequence up to the end of the document. This page number is usually printed in the header, set off by dashes.
-1-
Another style of page numbering, used in documents such as technical manuals, numbers pages specific to a section. The first page of the second section would be printed as:
2-1
The other type of change affects whether or not the page number is printed in the header at the top of the first page.
The number register N
controls these actions. This register has a default setting of 0 and can take values from 0 through 5. Table 6-1 shows the effect of these values.
The register N
can be set from the command line using the -r
option. If we set it to 2, no page number will appear at the top of page 1 when we print the sample letter:
$ mm -rN2 letter | lp
The mm
package has a pair of macros for defining what should appear in a page header (.PH
) and a page footer (.PF
). There is also a set of related macros for specifying page headers and footers for odd-numbered pages (.OH
and .OF
) or for even-numbered pages (.EH
and .EF
). All of these macros have the same form, allowing you to place text in three places in the header or footer: left justified, centered, and right justified. This is specified as a single argument in double quotation marks, consisting of three parts delimited by single quotation marks.
’left’center’right’
For example, we could place the name of a client, the
title of the document, and the date in the page header,
and we could place the page number in the footer:
.PH "’GGS’Alcuin Project Proposal’*(DT’"
.PF "’’Page % ’’"
You may notice that we use the string DT
to supply today’s date in the header. The following header appears at the top of the page.
GGS Alcuin Project Proposal April 26, 1987
In the footer, we use a special symbol (%
) to access the current page number. Only text to be centered was specified; however, the four delimiters were still required to place the text correctly. This footer appears at the bottom of the page:
The header and footer macros override the default header and footer.
The mm
package uses number registers to supply the values that control line length, page offset, point size, and page length, as shown in Table 6-2.
These registers must be defined before the mm
macro package is read by nroff
or troff
. Thus, they can be set from the command line using the -r
option, as we showed when we gave a new value for register N
. Values of registers O
and W
for nroff
must be given in character positions (depending on the character size of the output device for nroff
, .5i might translate as either 5 or 6 character positions), but troff
can accept any of the units descibed in Chapter 4. For example:
$ mm -rN2 -rW65 -r10
file
but:
$ mmt -rN2 -rW6.5i -rOli
file
Or the page control registers can be set at the top of your file, using the .so
request to read in the mm
macro package, as follows:
.nr N 2
.nr W 65
.nr O 10
.so /usr/lib/tmac/tmac.m
If you do it this way, you cannot use the mm
command. Use nroff
or troff
without the -mm
option. Specifying -mm
would cause the mm
macro package to be read twice; mm
would trap that error and bail out.
The .P
macro marks the beginning of a paragraph.
.P
In our conversation last Thursday, we discussed a
This macro produces a left-justified, block paragraph. A blank line in the input file also results in a left-justified, block paragraph, as you saw when we formatted an uncoded file.
However, the paragraph macro controls a number of actions in the formatter, many of which can be changed by overriding the default values of several number registers. The .P
macro takes a numeric argument that overrides the default paragraph type, which is a block paragraph. Specifying 1 results in an indented paragraph:
.P 1
Going through a demo session gave me a much better
The first three paragraphs formatted for the screen follow:
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.
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.
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.
The first line of the second paragraph is indented five spaces. (In troff
the default indent is three ens.) Notice that the paragraph type specification changes only the second paragraph. The third paragraph, which is preceded in the input file by .P
without an argument, is a block paragraph.
If you want to create a document in which all the paragraphs are indented, you can change the number register that specifies the default paragraph type. The value of Pt
is 0 by default, producing block paragraphs. For indented paragraphs, set the value of Pt
to 1. Now the .P
macro will produce indented paragraphs.
.nr Pt 1
If you want to obtain a block paragraph after you have changed the default type, specify an argument of 0:
When you specify a type argument, it overrides whatever paragraph type is in effect.
There is a third paragraph type that produces an indented paragraph with some exceptions. If Pt
is set to 2, paragraphs are indented except those following section headings, lists, and displays. It is the paragraph type used in this book.
The following list summarizes the three default paragraph types:
0
Block1
Indented2
Indented with exceptions
The paragraph macro also controls the spacing between paragraphs. The amount of space is specified in the number register Ps
. This amount differs between nroff
and troff
.
With nroff
, the .P
macro has the same effect as a blank line, producing a full space between paragraphs. However, with troff
, the .P
macro outputs a blank space that is equal to one-half of the current vertical spacing setting. Basically, this means that a blank line will cause one full space to be output, and the .P
macro will output half that space.
The .P
macro invokes the .SP
macro for vertical spacing. This macro take a numeric argument requesting that many lines of space.
Sincerely,
.SP 3
Fred Caslon
Three lines of space will be provided between the salutation and the signature lines.
You do not achieve the same effect if you enter .SP
macros on three consecutive lines. The vertical space does not accumulate and one line of space is output, not three.
Two or more consecutive .SP
macros with numeric arguments results in the spacing specified by the greatest argument. The other arguments are ignored.
.SP 5
.SP
.SP 2
In this example, five lines are output, not eight.
Because the .P
macro calls the .SP
macro, it means that two or more consecutive paragraph macros will have the same effect as one.
.SP
Macro versus the .sp
RequestThere are several differences between the .SP
macro and the .sp
request. A series of .sp
requests does cause vertical spacing to accumulate. The following three requests produce eight blank lines:
.sp 5
.sp
.sp 2
The argument specified with the .SP
macro cannot be scaled nor can it be a negative number. The .SP
macro automatically works in the scale (v
) of the current vertical spacing. However, both .SP
and .sp
accept fractions, so that each of the following codes has the same result:
.sp .3v .SP .3 .sp .3
A document formatted by nroff
with mm
produces, by default, unjustified text (an uneven or ragged-right margin). When formatted by troff
, the same document is automatically justified (the right margin is even).
If you are using both nroff
and troff
, it is probably a good idea to explicitly set justification on or off rather than depend upon the default chosen by the formatter. Use the .SA
macro (set adjustment) to set document-wide justification. An argument of 0 specifies no justification; 1 specifies justification.
If you insert this macro at the top of your file:
.SA 1
both nroff
and troff
will produce right-justified paragraphs like the following:
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.
One way to achieve better line breaks and more evenly filled lines is to instruct the formatter to perform word hyphenation.
Hyphenation is turned off in the mm
macro package. This means that the formatter does not try to hyphenate words to make them fit on a line unless you request it by setting the number register Hy
to 1. If you want the formatter to automatically hyphenate words, insert the following line at the top of your file:
Most of the time, the formatter breaks up a word correctly when hyphenating. Sometimes, however, it does not and you have to explicitly tell the formatter either how to split a word (using the .hy
request) or not to hyphenate at all (using the .nh
request).
When we format a text file, the line breaks caused by carriage returns are ignored by nroff/troff
. How text is entered on lines in the input file does not affect how lines are formed in the output. It doesn’t really matter whether information is typed on three lines or four; it appears the same after formatting.
You probably noticed that the name and address at the beginning of our sample file did not come out in block form. The four lines of input ran together and produced two filled lines of output:
Mr. John Fust Vice President, Research and Development
Gutenberg Galaxy Software Waltham, Massachusetts 02159
The formatter, instead of paying attention to carriage returns, acts on specific macros or requests that cause a break, such as .P
, .SP
, or a blank line. The formatter request .br
is probably the simplest way to break a line:
Mr. John Fust
.br
Vice President, Research and Development
The .br
request is most appropriate when you are forcing a break of a single line. For larger blocks of text, the mm
macro package provides a pair of macros for indicating that a block of text should be output just as it was entered in the input file. The .DS
(display start) macro is placed at the start of the text, and the .DE
(display end) macro is placed at the end:
.DS
Mr. John Fust
Vice President, Research and Development
Gutenberg Galaxy Software
Waltham, Massachusetts 02159
.DE
The formatter does not fill these lines, so the address block is output on four lines, just as it was typed. In addition, the .DE
macro provides a line of space following the display.
We have pretty much exhausted what we can do using the sample letter. Before going on to larger documents, you may want to compare the coded file in Figure 6-2 with the nroff
-formatted output in Figure 6-3. Look them over and make sure you understand what the different macros are accomplishing.
We have worked through some of the problems presented by a very simple one-page letter. As we move on, we will be describing specialized macros that address the problems of multiple page documents, such as proposals and reports. In many ways, the macros for more complex documents are the feature performers in a macro package, the ones that really convince you that a markup language is worth learning.
When you format with nroff
and print on a line printer, you can put emphasis on individual words or phrases by underlining or overstriking. When you are using 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 device.
Most typefaces have at least three fonts available: roman, bold, and 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 changes using the .ft
request and inline f
requests. The mm
package provides a set of mnemonic macros for changing fonts:
.B
Bold.I
Italic.R
Roman
Each macro prints a single argument in a particular font. You might code a single sentence as follows:
.B Alcuin
revitalizes an
.I age-old
tradition.
The printed sentence has a word in bold and one in italic. (In nroff
, bold space is simulated by overstriking, and italics by underlining.)
Alcuin revitalizes an age-old tradition.
If no argument is specified, the selected font is current until it is explicitly changed:
The art of
.B
calligraphy
.R
is, quite simply,
.I
beautifu1
.R
handwriting;
The previous example produces:
The art of calligraphy is, quite simply, beautiful handwriting;
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. Each macro takes up to six arguments for alternating font changes. (An argument is 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 an input line with a period.
its opposite is
.B cacography .
This example produces:
its opposite is cacography.
If you specify alternate arguments consisting of words or phrases, you must supply the spacing:
The ink pen has been replaced by a
.I light " pen."
This produces:
The ink pen has been replaced by a light pen.
Here’s an example using all six arguments:
Alcuin uses three input devices, a
.B "light pen" ", a " "mouse" ", and a " "graphics tablet."
This produces:
Alcuin uses three input devices, a light pen, a mouse, and a graphics tablet.
There are additional macros for selecting other main and alternate fonts. These macros also take up to six arguments, displayed in alternate fonts:
.BR
Alternate bold and roman.IB
Alternate italic and bold.RI
Alternate roman and italic.BI
Alternate bold and italic.IR
Alternate italic and roman.RB
Alternate roman and bold
If you are using 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.
When formatting with troff
, you can request a larger or smaller point size for the type. A change in the point size affects how much vertical space is needed for the larger or smaller characters. Normal body copy is set in 10-point type with the vertical spacing 2 points larger.
You learned about the .ps
(point size) and .vs
(vertical spacing) requests in Chapter 4. These will work in mm
; however, mm
also has a single macro for changing both the point size and vertical space:
.S
[point size] [vertical spacing]
The values for point size and vertical spacing can be set in relation to the current setting: + increments and − decrements the current value. For example, you could specify relative point size changes:
.S +2 +2
or absolute ones:
.S 12 14
By default, if you don’t specify vertical spacing, a relation of 2 points greater than the point size will be maintained. A null value (""
) does not change the current setting.
The new point size and vertical spacing remain in effect until you change them. Simply entering the .S
macro without arguments restores the previous settings:
.S
The mm
package keeps track of the default, previous, and current values, making it easy to switch between different settings using one of these three arguments:
D
DefaultP
PreviousC
Current
To restore the default values, enter:
.S D
The point size returns to 10 points and the vertical spacing is automatically reset to 12 points. To increase the vertical space to 16 points while keeping the point size the same, enter:
.S C 16
In the following example for a letterhead, the company name is specified in 18-point type and a tag line in 12-point type; then the default settings are restored:
.S 18
Caslon Inc.
.S 12
Communicating Expertise
.S D
The result is:
Caslon Inc.
Communicating Expertise
You can also change the font along with the point size, using the .I
macro described previously. Following is the tag line in 12-point italic.
Communicating Expertise
A special-purpose macro in mm
reduces by 1 point the point size of a specified string. The .SM
macro can be followed by one, two, or three strings. Only one argument is reduced; which one depends upon how many arguments are given. If you specify one or two arguments, the first argument will be reduced by 1 point:
using
.SM UNIX ,
you will find
The second argument is concatenated to the first argument, so that the comma immediately follows the word UNIX:
using UNIX, you will find
If you specify three arguments:
.SM [ UNIX ]
The second argument is reduced by one point, but the first and third arguments are printed in the current point size, and all three are concatenated:
Broadly speaking, a display is any kind of information in the body of a document that cannot be set as a normal paragraph. Displays can be figures, quotations, examples, tables, lists, equations, or diagrams.
The display macros position the display on the page. Inside the display, you might use other macros or preprocessors such as tbl
or eqn
. You might simply have a block of text that deserves special treatment.
The display macros can be relied upon to provide
The default action of the .DS
macro is to left justify the text block in no-fill mode. It provides no indentation from the current margins.
You can specify a different format for a display by specifying up to three arguments with the .DS
macro. The syntax is:
.DS
[format] [fill mode] [right indent]
The format argument allows you to specify an indented or centered display. The argument can be set by a numeric value or a letter corresponding to the following options:
0 L
No indent (default)1 I
Indented2 C
Center each line3 CB
Center entire display
For consistency, the indent of displays is initially set to be the same as indented paragraphs (five spaces in nroff
and three ens in troff
), although these values are maintained independently in two different number registers, Pi
and Si
. (To change the defaults, simply use the .nr
request to put the desired value in the appropriate register.)
A display can be centered in two ways: either each individual line in the display is centered (C
) or the entire display is centered as a block based on the longest line of the display (CB
).
For instance, the preceding list was formatted using tbl
, but its placement was controlled by the display macro.
.DS CB
.TS
.TE
.DE
0
N
No-fill mode (default)1
F
Fill mode
The right indent argument is a numeric value that is subtracted from the right margin. In nroff
, this value is automatically scaled in ens. In troff
, you can specify a scaled number; otherwise, the default is ems.
The use of fill mode, along with other indented display options, can provide a paragraph indented on both sides. This is often used in reports and proposals that quote at length from another source. For example:
.P
I was particularly interested in the following comment
found in the product specification:
.DS I F 5
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.
.DE
The result of formatting is:
I was particularly interested in the following comment
found in the the product specification:
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.
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:
.DF I
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 comments
.DE
This table appears in the output just as it looks in the file. If this material had not been processed inside a display in no-fill mode, the columns would be improperly aligned.
There are two types of displays, static and floating. The difference between them has to do with what happens when a display cannot fit in its entirety on the current page. Both the static and the floating display output the block at the top of the next page if it doesn’t fit on the current page; however, only the floating display allows text that follows the display to be used to fill up the preceding page. A static display maintains the order in which a display was placed in the input file.
We have already used .DS
and .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 the .DF
macro. The options are the same as for the .DS
macro.
In the following example of an input file, numbers are used instead of actual lines of text:
1
2
3
4
5
.DF
.DE
6
7
8
9
10
The following two formatted pages might be produced, assuming that there are a sufficient number of lines in the display to cause a page break:
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.
If a static display had been specified, the display would be placed in the same position on page 2, and lines 6 and 7 would have to follow 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.
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). Two number registers, De
and Df
, allow you to control when displays are removed from the queue and placed in position.
At the end of a section, as indicated by the section macros .H
and .HU
(which we will see shortly), or at the end of the input file, any floating displays that remain in the queue will be placed in the document.
You can provide a title or caption for tables, equations, exhibits, and figures. In addition, the display can be labeled and numbered in sequence, as well as printed in a table of contents at the end of the file. The following group of macros are available:
.EC
Equation.EX
Exhibit.FG
Figure
All of these macros work the same way and are usually specified within a pair of .DS/.DE
macros, so that the title and the display appear on the same page. Each macro can be followed by a title. If the title contains spaces, it should be enclosed within quotation marks. The title of a table usually appears at the top of a table, so it must be specified before the .TS
macro that signals to tbl
the presence of a table (see Chapter 8).
The label is centered:
Table 1. List of Required Resources
If the title exceeds the line length, then it will be broken onto several lines. Additional lines are indented and begin at the first character of the title.
Table 1. List of Required
Resources Provided by Gutenberg Galaxy Software
The label for equations, exhibits, and figures usually follows the display. The following:
.FG "Drawing with a Light Pen"
produces a centered line:
Figure 1. Drawing with a Light Pen
The default format of the label can be changed slightly by setting the number register Of
to 1. This replaces the period with a dash.
Figure 1 — Drawing with a Light Pen
Second and third arguments, specified with the label macros, can be used to modify or override the default numbering of displays. Basically, the second argument is a literal and the third argument a numeric value that specifies what the literal means.
If the third argument is
0
then the second argument will be treated as a prefix;1
then the second argument will be treated as a suffix;2
then the second argument replaces the normal table number.
Thus, a pair of related tables could be specified as la
and lb
using the following labels:
.TB "Estimated Hours: June, July, and August" a 1
.TB "Estimated Hours: September and November," lb 2
(These labels show two different uses of the third argument. Usually, you would consistently use one technique or the other for a given set of tables.)
For tbl
, the delimiters for tables are .TS/.TE
. For eqn
, the delimiters for equations are .EQ/.EN
. For pic
, the delimiters for pictures or diagrams are .PS/.PE
. These pairs of delimiters indicate a block to be processed by a specific preprocessor. You will find the information about each of the preprocessors in Chapters 8 through 10. As mentioned, the preprocessor creates the display, the display macros position it, and the label macros add titles and a number.
Although it may seem a minor point, each of these steps is independent, and because they are not fully integrated, there is some overlap.
The label macros, being independent of the preprocessors, do not make sure that a display exists or check whether a table has been created with tbl
. You can create a two-column table using tabs or create a figure using character symbols and still give it a label. Or you can create a table heading as the first line of your table and let tbl
process it (tbl
won’t provide a number and the table won’t be collected for the table of contents).
In tbl
, you can specify a centered table and not use the .DS/.DE
macros. But, as a consequence, nroff/troff
won’t make a very good attempt at keeping the table together on one page, and you may have to manually break the page. It is recommended that you use the display macros throughout a document, regardless of whether you can get the same effect another way, because if nothing else you will achieve consistency.
Occasionally, you may want to force a page break, whether to ensure that a block of related material is kept together or to allow several pages for material that will be manually pasted in, such as a figure. The .SK
(skip) macro forces a page break. The text following this macro is output at the top of the next page. If supplied with an argument greater than 0, it causes that number of pages to be skipped before resuming the output of text. The “blank” pages are printed, and they have the normal header and footer.
On the next page, you will find a sample page from an
Alcuin manuscript printed with a 16-color plotter.
.SK 1
The mm
macro package provides a variety of different formats for presenting a list of items. You can select from four standard list types:
In addition, you have the flexibility to create lists with nonstandard marks or text labels. The list macros can also be used to produce paragraphs with a hanging indent.
Each list item consists of a special mark, letter, number, or label in a left-hand column with a paragraph of text indented in a right-hand column.
The list macros help to simplify what could be a much larger and tedious formatting task. Here’s the coding for the bulleted list just shown:
.BL
.LI
bulleted
.LI
dashed
.LI
numbered
.LI
alphabetized
.LE
The structure of text in the input file has three parts: a list-initialization macro (.BL
), an item-mark macro (.LI
), and a list-end macro (.LE
).
First, you initialize the list, specifying the particular macro for the type of list that you want. For instance, BL
initializes a bulleted list.
You can specify arguments with the list-initialization macro that change the indentation of the text and turn off the automatic spacing between items in the list. We will examine these arguments when we look at the list-initialization macros in more detail later.
Next, you specify each of the items in the list. The item-mark macro, .LI
, is placed before each item. You can enter one or more lines of text following the macro.
.BL
.LI
Item 1
.LI
Item 2
.LI
Item 3
When the list is formatted, the .LI
macro provides a line of space before each item. (This line can be omitted through an argument to the list-initialization macro if you want to produce a more compact list. We’ll be talking more about this in a moment.)
The .LI
macro can also be used to override or prefix the current mark. If a mark is supplied as the only argument, it replaces the current mark. For example:
If a mark is supplied as the first argument, followed by a second argument of 1, then the specified mark is prefixed to the current mark. The following:
.LI - 1
Item 5
would produce:
• Item 5
A text label can also be supplied in place of the mark, but it presents some additional problems for the proper alignment of the list. We will look at text labels for variable-item lists.
The .LI
macro does not automatically provide spacing after each list item. An argument of 1 can be specified if a line of space is desired.
The end of the list is marked by the list-end macro .LE
. It restores page formatting settings that were in effect prior to the invocation of the last list-initialization macro. The .LE
macro does not output any space following the list unless you specify an argument of 1. (Don’t specify this argument when the list is immediately followed by a macro that outputs space, such as the paragraph macro.)
Be sure you are familiar with the basic structure of a list. A common problem is not closing the list with .LE
. Most of the time, this error causes the formatter to quit at this point in the file. A less serious, but nonetheless frequent, oversight is omitting the first .LI
between the list-initialization macro and the first item in the list. The list is output but the first item will be askew.
Here is a sample list:
.BL
.LI
Item 1
.LI
.Item 2
.LI
.Item 3
.LI o
Item 4
.LI - 1
Item 5
.LE
The troff
output produced by the sample list is:
• Item 1
• Item 2
• Item 3
• Item 4
• Item 5
Complete list structures can be nested within other lists up to six levels. Different types of lists can be nested, making it possible to produce indented outline structures. But, like nested if-then structures in a program, make sure you know which level you are at and remember to close each list.
For instance, we could nest the bulleted list inside a numbered list. The list-initialization macro .AL
generates alphabetized and numbered lists.
.AL
.LI
Don’t worry, we’ll get to the list-initialization macro .AL.
You can specify five different variations of
alphabetic and numbered lists.
.BL
.LI
Item 1
.LI
Item 2
.LI
Item 3
.LE
.LI
We’ll also look at variable-item lists.
.LE
This input produces the following formatted list from troff
:
1. Don’t worry, we’ll get to the list-initialization macro .AL
. You can specify five different variations of alphabetic and numbered lists.
• Item 1
• Item 2
• Item 3
2. We’ll also look at variable-item lists.
You may already realize the ease with which you can make changes to a list. The items in a list can be easily put in a new order. New items can be added to a numbered list without readjusting the numbering scheme. A bulleted list can be changed to an alphabetized list by simply changing the list-initialization macro. And you normally don’t have to be concerned with a variety of specific formatting requests, such as setting indentation levels or specifying spacing between items.
On the other hand, because the structure of the list is not as easy to recognize in the input file as it is in the formatted output, you may find it difficult to interpret complicated lists, in particular ones that have been nested to several levels. The code-checking program, checkmm
, can help; in addition, you may want to format and print repeatedly to examine and correct problems with lists.
Long a standby of technical documents, a marked list clearly organizes a group of related items and sets them apart for easy reading. A list of items marked by a bullet (•) is perhaps the most common type of list. Another type of marked list uses a dash (—). A third type of list allows the user to specify a mark, such as a square (). The list-initialization macros for these lists are:
.BL
[text indent][1
].DL
[text indent][1
].ML
[mark][text indent][1
]
With the .BL
macro, the text is indented the same amount as the first line of an indented paragraph. A single space is maintained between the bullet and the text. The bullet is right justified, causing an indent of several spaces from the left margin.
As you can see from this nroff
-formatted output, the bullet is simulated in nroff
by a +
overstriking an o
:
Currently, the following internal documentation is available on the Alcuin product:
⊕ GGS Technical Memo 3200
⊕ GGS Product Marketing Spec
⊕ Alcuin/UNIX interface definition
⊕ Programmer’s documentation for Alcuin
If you specify a text indent, the first character of the text will start at that position. The position of the bullet is relative to the text, always one space to its left.
If the last argument is 1, the blank line of space separating items is omitted. If you want to specify only this argument, you must specify either a value or a null value (""
) for a text indent.
.BL "" 1
It produces a much more compact list:
⊕ GGS Technical Memo 3200
⊕ GGS Product Marketing Spec
⊕ Alcuin/UNIX interface definition
⊕ Programmer’s documentation for Alcuin
Because the bullets produced by nroff
are not always appropriate due to the overstriking, a dashed list provides a suitable alternative. With the .DL
macro, the dash is placed in the same position as a bullet in a bulleted list. A single space is maintained between the dash and the text, which, like the text with a bulleted list, is indented by the amount specified in the number register for indented paragraphs (Pi
).
The nroff
formatter supplies a dash that is a single hyphen, and troff
supplies an em dash. Because the em dash is longer, and the dash is right justified, the alignment with the left margin is noticeably different. It appears left justified in troff
; in nroff
, the dash appears indented several spaces because it is smaller.
The third chapter on the principles of computerized font design should cover the following topics:
- Building a Font Dictionary
- Loading a Font
- Scaling a Font
You can specify a text indent and a second argument of 1 to inhibit spacing between items.
With the .ML
macro, you have to supply the mark for the list. Some possible candidates are the square (enter (sq
to get ), the square root (enter (sr
to get √), which resembles a check mark, and the gradient symbol (enter (gr
to get ∇). The user-specified mark is the first argument.
.ML (sq
Not all of the characters or symbols that you can use in troff
will have the same effect in nroff
.
Unlike bulleted and dashed lists, text is not automatically indented after a user-specified mark. However, a space is added after the mark. The following example of an indented paragraph and a list, which specifies a square as a mark, has been formatted using nroff
. The square appears as a pair of brackets.
[ ] Remove old initialization files.
[ ] Run install program.
[ ] Exit to main menu and choose selection 3.
The user-supplied mark can be followed by a second argument that specifies a text indent and a third argument of 1 to omit spacing between items.
The following example was produced using the list-initialization command:
.ML (sq 5 1
The specified indent of 5 aligns the text with an indented paragraph:
Check to see that you have completed the following steps:
[ ] Remove old initialization files.
[ ] Run install program.
[ ] Exit to main menu and choose selection 3.
The .AL
macro is used to initialize automatically numbered or alphabetized lists. The syntax for this macro is:
.AL
[type] [text indent] [1
]
If no arguments are specified, the .AL
macro produces a numbered list. For instance, we can code the following paragraph with the list-initialization macro .AL
:
User-oriented documentation recognizes three things:
.AL
.LI
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;
.LI
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;
.LI
that an experienced user must be able to rely on the
documentation for accurate and thorough reference
information.
.LE
to produce a numbered list:
User-oriented documentation recognizes three things:
1. 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;
2. 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;
3. that an experienced user must be able to rely on the documentation for accurate and thorough reference information.
The number is followed by a period, and two spaces are maintained between the period and the first character of text.
The level of text indent, specified in the number register Li
, is 6 in nroff
and 5 in troff
. This value is added to the current indent. If a text indent is specified, that value is added to the current indent, but it does not change the value of Li
.
The third argument inhibits spacing between items in the list. Additionally, the number register LS
can be set to a value from 0 to 6 indicating a nesting level. Lists after this level will not have spacing between items. The default is 6, the maximum nesting depth. If Ls
were set to 2, lists only up to the second level would have a blank line of space between items.
Other types of lists can be specified with .AL
, using the first argument to specify the list type, as follows:
1
1, 2, 3 NumberedA
A, B, C Alphabetic (uppercase)a
a, b, c Alphabetic (lowercase)I
I, II, III Roman numerals (uppercase)i
i, ii, iii Roman numerals (lowercase)
You can produce various list types by simply changing the type argument. You can create a very useful outline format by nesting different types of lists. The example we show of such an outline is one that is nested to four levels using I
, A
, 1
, and a
, in that order. The rather complicated looking input file is shown in Figure 6-4 (indented for easier viewing of each list, although it could not be formatted this way), and the nroff
-formatted output is shown in Figure 6-5.
Another list-initialization macro that produces a numbered list is .RL
(reference list). The only difference is that the reference number is surrounded by brackets ([]
).
.RL
[text indent][1
]
The arguments have the same effect as those specified with the .AL
macro. To initialize a reference list with no spacing between items, use:
.RL "" 1
It produces the following reference list:
[1] The Main Menu
[2] Menus or Commands?
[3] Error Handling
[4] Getting Help
[5] Escaping to UNIX
With a variable-item list, you do not supply a mark; instead, you specify a text label with each .LI
. One or more lines of text following .LI
are used to form a block paragraph indented from the label. If no label is specified, a paragraph with a hanging indent is produced. The syntax is:
.VL
text indent [label indent][1
]
Unlike the other list-initialization macros, a text indent is required. By default, the label is left justified, unless a label indent is given. If you specify both a text indent and a label indent, the indent for the text will be added to the label indent.
Variable-item lists are useful in preparing command reference pages, which describe various syntax items, and glossaries, which present a term in one column and its definition in the other. The text label should be a single word or phrase. The following example shows a portion of the input file for a reference page:
.VL 15 5
.LI figure
is the name of a cataloged figure. If
a figure has not been cataloged, you need to use
the LOCATE command.
.LI f:p
is the scale of the
figure in relation to the page.
.LI font
is the two-character abbreviation or
full name of one of the available fonts
from the Alcuin library.
.LE
The following variable-item list is produced:
figure is the name of a cataloged figure. If a
figure has not been cataloged, you need to
use the LOCATE command.
f:p is the scale of the figure in relation to
the page.
font is the two-character abbreviation or full
name of one of the available fonts from the
Alcuin library.
If you don’t provide a text label with .LI
or give a null argument (""
), you will get a paragraph with a hanging indent. If you want to print an item without a label, specify a backslash followed by a space ( ) or