TOC BACK FORWARD HOME

UNIX Unleashed, Internet Edition

- 9 -

Formatting with Macro Packages

by David B. Horvath, CCP

This chapter introduces macros and macro packages. We will begin with a sample macro, and you'll see how and why it works. You'll then see it evolves from simple to complex.

Macro packages are collections of macros. A macro is a collection of troff primitives or requests. In this chapter, the man macro package (used to format the man, or manual, pages in the UNIX system) is examined and used as an example for other macro packages.

What Is a Macro?

With embedded troff primitives, you can format a page just about any way you want. The trouble is that you have to reinvent the wheel every time you write a new document. For example, every time you format a first-level heading, you have to remember the sequence of primitives you used to produce a centered 14-point Helvetica bold heading. Then you have to type three or four troff requests, the heading itself, and another three or four requests to return to the normal body style. While this may result in many lines, it is not very productive. It is a laborious process that makes it difficult, if not impossible, to maintain consistency over a set of documents.

There is a solution: You can use macros to simplify formatting and ensure consistency. Macros take advantage of one of the UNIX system's distinguishing characteristics: the capability to build complex processes from basic, primitive units. A macro is nothing more than a series of troff requests, specified and named, that perform special formatting tasks.

Chapter 10, "Writing Your Own Macros" explains how to write your own macros. You can use your own macros with the macro packages by embedding the macros in your source document or sourcing them in.

The man Macro Package

The man macro package is used to produce documents in a specific format. The format is used for UNIX system documentation manual pages--man pages, for short. In addition, information entered with the man macros is used to create the formidable permuted indexes so dear to the hearts of UNIX users.

There are only a few macros in the man package. Summary information is provided for the me and ms packages at the end of the chapter.


NOTE: If you are familiar with mm, then man's paragraph style macros and their usage when producing lists will be foreign.

The man macros produce an 8.5 x 11-inch page with a text area of 6.5 x 10 inches. There is a troff--but not an nroff--option for producing a smaller 6 x 9 inch-page with a text area of 4.75 x 8.375 inches. If you choose this option, point size and leading are reduced from 10/12 to 9/10.

Page Layout

The .IN macro sets the indent relative to subheads. The default setting is 7.2 ens in troff and 5 ens in nroff.


NOTE: Space measurements have different scales. When a request needs a distance, you can use the default type or modify the number with an indicator. The measurement types are inches, centimeters, Picas, Ems, Ens, points, units, and vertical line spaces. A Pica is 1/6 of an inch. An em is the width of the letter m and is dependent on the font used in troff. An en is half an em.

The .LL macro sets the line length, which includes the value of IN.

The footer produced by the man macros is an example of making the best of a bad deal. By default, a hard coded date in the macro package is used instead of the current system date. The historical reasons for this behavior are not entirely clear, but it probably was a way of controlling updates to reference manuals.

The system administrator can change the date by modifying the macro package (the .TH macro (table heading) contains a string definition for a string called [5. [5 contains the date printed in the footer. To redefine [5, use the following at the top of your file:

.ds [5 "January 1, 2001


TIP: When you define strings, use an opening quotation mark, but no closing mark. If you forget and put that closing quotation mark, the closing quotation mark will be printed.

Now, what about that "Page 1"? Manpages are not numbered like ordinary document pages. The reason is that reference manuals are lengthy and are updated frequently. Furthermore, Bell Laboratories decided many years ago never to number replacement pages with letters, such as 101a, 101b, and so on. Because it was impractical to reprint a 2,000 page manual just because you had inserted two pages at the beginning, Bell Labs came up with another solution: Number the pages consecutively only for each entry; then start again with "Page 1."

You can change this, but you'll face the same dilemma that Bell Labs faced: What do you do about updates? Assuming this isn't a problem, how do you number reference manual pages consecutively?

You can achieve consecutive page numbering by using the register (-r) option to set the P register to 1 when you print your file:

troff -rP1 filename

Later in this chapter, Table 9.3 details the registers that can be set from the command line.

Headings

The man macros fall into two basic categories: headings and paragraph styles. Using these macros correctly is an art, not a science as it once was. Fonts are no longer as rigidly defined. For example, earlier UNIX reference manuals did not use a monospace--or constant width--font. Today, monospace is routinely used for file and directory names and for "computer voice," which is anything you see on the screen. Sometimes a distinction is made between monospace (\f(CW) and bold monospace (\f(CB). Bold monospace is used to indicate what the user types; it appears in the syntax section of a manpage.

The example in Figure 9.1 represents one way of using the man macros. Type styles are a matter of individual or company preference.

man recognizes three types of headings:

.TH and .SH are mandatory. A manpage must have a .TH and at least one .SH.

.TH takes up to four arguments. These are positional arguments. Therefore, if you don't use the third (and least common) argument but you want the fourth, you must insert a null argument ("") before the fourth argument. The syntax for .TH is

.TH <title> <section number> <commentary> <manual name>

title specifies the title of the manpage. This appears in the page header on the left and the right. It can be more than one word, so enclose it in quotation marks. The title of the manpage shown in Figure 9.1 is namehim.


Caution: Failure to enclose arguments to the .TH macro in quotation marks produces random garbage on the printed page.

section number indicates the section of the reference manual to which the entry belongs. The standard sections are broken down as shown in Table 9.1.

Table 9.1. Manual Section Numbers.

Section Description
1 User commands
1C Basic networking commands
1M Administration commands
2 System calls
3 Other subroutines and functions
3C Standard C library functions
3M Math library functions
3S Standard I/O functions
3X Local and specialized functions
4 File formats
5 Miscellaneous facilities
6 Demonstrations (actually games; not usually included)
7 Special files
8 System maintenance procedures

The section number appears in the header in parentheses after the title. Don't include parentheses; they are supplied automatically. The manpage shown in Figure 9.1 has 0 as the section number, even though 0 is not really a permissible section number.

commentary is an extra comment, such as Local. The argument appears in the header. It must be enclosed in quotation marks if there are embedded blanks. The manpage shown in Figure 9.1 doesn't have any commentary.

Listing 9.1 shows the man macros and text used to produce the sample manual page shown in Figure 9.1 (after processing by troff -man). The use of .HP, .IP, .TP, .RS, and .RE are included.

Figure 9.1.
Sample Manual Page.

Listing 9.1. Basic man source.

.TH namehim 0 "Novelist's Work Bench"
.SH NAME
namehim - supplies one or more names (first, last, or both) for fictional character
.SH SYNTAX
namehim [ -F | -L ]  [ -t type ]  [ -a age ]  [ -y year ] ...
.SH OPTIONS
.IP "-F | -L" 3m
specifies first or last name; if neither F nor L
is specified, both are produced.
.IP -t 3m
Specifies type of name:
select from the following (may be combined):
.RS
.IP a 3m
all
.IP f 3m
fancy
.IP h 3m
hero
.IP l 3m
light
.RE
.TP 3m
-a
Specifies the character's age, the younger the
character, the more likely it will be a nickname.
.TP 3m
-y
Specifies the year or era of the character. The
older names will be more in the Medieval style.


NOTE: Local means that the command described by the manual page is not a standard command. It might be a brand new command created for your particular UNIX system, it might be a standard command that has been modified for your system, or it might be part of a software vendor's package.

manual name is the name of the manual--for example, UNIX System V or Documenter's Workbench. The name of the manual shown in Figure 9.1 is Novelist's Workbench.

.TH is a shared macro name; it has one meaning in the man macro package and another for the tbl preprocessor. The .TH macro for the tbl preprocessor is used to specify column headings on a multiple page table. It is identified by starting and ending macros--.TS and .TE. This presents a potential problem. tbl is described in Chapter 11, "Tools for Writers."

The .TH table heading macro can appear only within a .TS and .TE pair. Supposedly, this insulates the macro and alerts the macro processor to rename the .TH man title macro whenever a .TS is encountered. However, you are not guaranteed that this will happen. Be sure to use tbl before nroff/troff if your document contains tables.


NOTE: The troff primitive .rn renames macros.


Caution: You may want to avoid using the .TH table heading macro on a manpage; the results are unpredictable and depend on your individual system.
If you have a multiple page table, you can always create the column headings manually. It isn't an elegant solution, but it doesn't break anything.

Some implementations of the man macros support automatic preprocessing by tbl and eqn/neqn by inspecting the first line of the file. To force tbl preprocessing, the first line should consist of '\" t.

The .SH macro is a crucial one. With .TH it is mandatory for manpages. It is customarily followed by a keyword, although you can specify any word or words you want. The most common .SH keywords are

NAME

SYNTAX or SYNOPSIS

DESCRIPTION

OPTIONS

EXAMPLE or EXAMPLES

FILES

DIAGNOSTICS

BUGS

SEE ALSO

The .SH macros are used like this:

.SH NAME
namehim - brief description of entry

Text following .SH is indented, as shown in Figure 9.1.

.SH keywords are always printed in all caps, and you don't need to put quotation marks around a two-word keyword. If you do use quotation marks, they won't be printed.

The most crucial .SH is .SH NAME. .SH NAME is mandatory. It is used to produce the permuted index, and its arguments must be entered on a single line, no matter how they are. No period is used at the end of the line. Naturally, it's a good idea to be as terse as possible.

The manpage shown in Figure 9.1 uses .SH OPTIONS after .SH SYNTAX. An alternate style sometimes seen in the reference manuals is the where form, which puts the word where on a line by itself and lists the options and arguments shown in the syntax section.

If a manpage needs headings under the .SHs, use .SS. Text following .SS is indented further.

Paragraph Styles

There are four ordinary paragraph macros:

.PP Begins a paragraph with an indented first line.
.P Synonym for .PP. The only thing it does is call .PP.
.LP Begins left-blocked paragraphs (no indent).
.PD Specifies interparagraph spacing.

To set the indentation for .PP (and .P), use number register PI. The default unit is ens, but you can use any unit you want as long as you specify it. Unlike ms, man provides the .PD macro to change the spacing between paragraphs.


NOTE: This section ("The man Macro Package") shows you how to use number registers that are useful with man macros. If you want to find out what other registers are available in troff, refer to the "Number Registers" section in Chapter 8, "Basic Formatting with troff/nroff" and the "Predefined Number Register" section in Chapter 10, "Writing Your Own Macros."

The .PD macro is nothing more than ms's PD number register turned into a macro. Because the format of manpages is so exacting, writers need more control over spacing. The argument to .PD specifies interparagraph spacing. Remember, when using nroff, this argument is interpreted as whole lines; for troff you can specify .3v or something similar. .PD is most often used to suppress spacing between list items, which are paragraphs in man. This is done very simply: .PD 0. The default spacing for .PD is .4r in troff, one line in nroff.

man has three hanging paragraph styles: .HP, .IP, and .TP. .HP is a simple hanging paragraph. The first line is flush with the margin. All subsequent lines in the paragraph are indented by the amount specified in the argument to .HP. .TP is more complex, and it is described later, following the discussion of .IP.

The .IP macro is similar to the ms .IP macro and is useful for formatting lists. .IP can take two arguments. The first argument is a label, or tag. It can be a word, a number, or even the troff code for a bullet. The second argument specifies how far in from the left margin to indent the rest of the first line and all the rest of the paragraph.

The .RS and .RE pair is used to create relative indents. .RS (relative start) starts a 5-en indent from whatever the current indent is. .RE returns to the indent whatever it was before .RS was called. For every .RS in your file, you need a .RE to undo it. You can use this pair of macros to build nested lists.

.TP is similar to .IP. In fact, .TP produces virtually the same output. However, you specify it a little differently. Whereas .IP takes two arguments, .TP takes only the indentation. The line following the .TP macro call is called the tag. If the tag is wider than the specified indentation, the text following the tag starts on the next line. You can use .IP without a tag (actually, a null tag), .TP requires a tag. That tag can be a blank line.

Fonts and Point Size

man recognizes the .R (roman), .I (italics), and .B (bold) macros--all of which operate exactly as they do in ms and mm. man permits all six permutations of alternating roman, italic, and bold fonts:

.RI

.RB

.IR

.IB

.BR

.BI

You may never have occasion to use these macros, but it's nice to know that they're available.

In addition to the font change macros, there is one macro for changing point size: .SM. man needs .SM more than the other macro packages because manpages contain terms with long names that must be written in capital letters. To make these terms more readable and to conserve space, man includes a macro that produces a smaller point size--two points smaller.

.SM has another special use: printing the word UNIX in capital or small cap letters. Because UNIX is a registered trademark, it should be printed in a way that distinguishes it from ordinary text. Sometimes it appears in all capital letters. Another acceptable way is with a capital U and small capital N, I, and X, as in UNIX.

Preprocessor Macros

The only preprocessor macros recognized by man are the .TS and .TE table macros. The table macro .TH can cause problems.

Predefined Strings

The man package has three predefined strings. They are

\*R Produces the registered trademark symbol
\*(Tm Produces the trademark symbol
\*S Returns to the default point size and vertical spacing

Miscellaneous Macros

.TH resets tab stops whenever it is called. The default settings are every 7.2 ens in troff and every 5 ens in nroff. However, experimenting with various customized indents might affect tab settings. If you want to restore the tab settings and you can't wait for the next .TH, use the .DT macro.

The .PM (proprietary marking) macro is interesting for its history, but unless you change its text, it isn't really useful. It takes two arguments. The first argument identifies the type of marking, such as Proprietary or Restricted. The second argument is the year. If you omit the year, the default is the current year.

Using man Macros with troff and nroff

You can invoke the man macros with the troff or nroff command. Printing man files is covered in detail in the "Printing Files Formatted with man Macros" section in this chapter.

man Macro Summary

Table 9.2 lists the man macros and describes their functions.

Table 9.2. Summary of the man macros.

Macro Description Comments
.B Bold With text, sets text in bold. On a line by itself, changes to bold font.
.BI Bold italic Alternates bold and italic fonts.
.BR Bold roman Alternates bold and roman fonts.
.DT Defines tabs and sets tab stops The default is 7.2 ens in troff and 5 ens in nroff.
.HP Hanging paragraph Begin hanging paragraph.
.I Italics With text, sets text in italics. On a line by itself, changes to italic font.
.IB Italic bold Alternates italic and bold fonts.
.IP Indented paragraph Begin Indented paragraph.
.IR Italic roman Alternates italic and roman fonts.
.LP Block-style paragraph Begin Block-style paragraph.
.P Paragraph Synonym for .PP. .P actually calls .PP.
.PD Sets the distance between paragraphs The default is .4v in troff and 1v in nroff.
.PM Proprietary marking This is an AT&T macro for placing different types of Proprietary notices at the bottom of each page.
.PP Paragraph Begin normal paragraph.
.R Roman With text, sets text in roman type. On a line by itself, changes to roman type.
.RB Roman bold Alternates roman and bold fonts.
.RE Relative Indent End Ends a relative indent begun by .RS
.RI Roman italic Alternates roman and italic fonts.
.RS Begins relative indent Begin indent relative to current.
.SH Subhead .SN NAME is the crucial macro for producing the permuted index
.SM Reduces point size by 2 points Stands for small.
.SS Sub-subhead Heading that is not as important as a subhead
.TE Table end Denote the end of a table
.TH Title head Specify the title heading
.TP Indented paragraph with hanging tag. Begin new paragraph.
.TS Table start Supposedly, the H argument with the .TH macro for continuing table column heads works with the man macros. It's safer, though, to avoid the issue.

Printing Files Formatted with the Standard Macro Packages

You can use either nroff or troff to process files formatted with the standard macro packages, ms, me, and man.


Caution: You cannot use two macro packages to format one file. The urge to do so usually arises when you want to put a manpage in a text file. It can't be done. Make separate files; better yet, put the manpage in an appendix and refer to it in your text.


TIP: You can create a document that uses multiple macro packages but not with them intermixed. By splitting your document into multiple files, each can use a different macro package. Create a shell script that executes nroff or troff with the appropriate command line switch to select the macro. You can pipe the output from the shell script into whichever post-processor you are using or redirect it to a file.

Both nroff and troff expect to find a pointer to the appropriate macro package in the /usr/lib/tmac directory and to find the macro file in the /usr/lib/macros directory. Some versions look to the /usr/ucblib/doctools/tmac directory for the packages and files.

Printing Files Formatted with ms, me, and man

You can use either nroff or troff to process files that use the me, ms, or man macros. All of the options shown in Table 9.7 can be used; however, the -r option has limited use because all predefined number registers in me and ms have two-character names.

Most of man's predefined number registers also have two-character names. You can set register s to 1 to reduce the page size from 8.5 x 11 to 5.5 x 8.

When you use nroff or troff to print files formatted with these macro packages, your command line takes this form:

nroff -ms options filenames
troff -ms options filenames
nroff -me options filenames
troff -me options filenames
nroff -man options filenames
troff -man options filenames

The options must precede the filename(s).

A complete listing of nroff and troff options can be found in Table 9.7.

Setting Number Registers from the Command Line

The -r option to nroff/troff lets you set certain number registers on the command line. This initializes the registers because it is done before the macro package is called. Only registers with one-character names can be initialized this way.


NOTE: To initialize a number register, you must set it before the macro package is called. You can initialize registers with two-character names by doing the following:
1. Set the registers in the first lines of your text file:
.nr XX 0 .nr YY 1 .nr ZZ 3
2. Source in the macros right after you initialize the number registers:
.so /usr/lib/tmac/tmac.s
3. Invoke nroff or troff without the -m option:
troff file

Table 9.3 lists the registers that can be initialized with the -r option to nroff/troff.

Table 9.3. Registers that can be initialized on the nroff/troff command line.

Register Effect
A Modifies the first page for memos and letters. If A is set to any nonzero number, the letterhead block is suppressed to accommodate personal stationery.
C Sets the type of copy as follows:

0 none (default)
1 OFFICIAL FILE COPY
2 DATE FILE COPY
3 DRAFT with single spacing, default paragraph style
4 DRAFT with double spacing, 10 en paragraph indent
5 double spacing with 10 en paragraph indent
D Sets debug mode. (Formatter will continue processing even if errors that would otherwise cause processing to stop are detected.)
E Controls the font of the subject/date/from fields on memos and letters. If D is 1, these fields are emboldened; if D is 0, the fields are printed in normal font.
L Sets the length of the physical page to N (default 11 inches). Specify units with this option because N is scaled.
N Specifies page numbering style as follows:
0 All pages include header
1 Header replaces footer on page 1; all other pages have a header
2 Page 1 has no header; all other pages have a header
3 All pages use section-page as footer
4 No header on page 1; header on other pages only if .PH is defined
5 Same as 3, but section-figure
O Sets page offset (left margin) to N where N is a scaled value
P Specifies that pages are to be numbered starting with N
S Sets point size and vertical spacing for document; by default point size is 10, vertical spacing is 12
W Sets page width to N where N is a scaled value (default 6i)

The -r option is useful if you have a file that will be printed somewhat differently over the course of its life. As an example, assume the first draft of your document has to be double spaced and have the word "DRAFT" at the bottom of every page. Set the C register to 4 on your command line:

troff -ms -rC4 docname

As the document nears completion, you have to print it single spaced, but you still want the word "DRAFT" at the bottom of every page:

troff -ms -rC3 docname

When the document is complete, you can use -rC1 to print "OFFICIAL FILE COPY" at the bottom of each page, or you can use -rC0 to omit that line entirely.

Error Messages

Error messages are largely self explanatory. They can be generated by the system (if you type torff instead of troff), by nroff or troff, by the macro package, or by the preprocessors (the tbl, eqn/neqn, pic, and grap sections of Chapter 11, "Tools for Writers," contain information about preprocessor error messages).

It doesn't really matter whether troff or a macro package generates a message; you have to correct the error. Errors usually fall into one of the following categories:

The one thing to remember is that the line number, helpfully supplied by troff, is the troff output line number. So it's not uncommon to be told that you have an error in line 1500 when your text file is 600 lines long. Macro packages attempt to give you the source file line number. Don't wager a large amount on its accuracy.

me Macro Summary

The me macro package is generally used for formatting technical papers.

Table 9.4 lists the me macros and describes their functions.

Table 9.4. Summary of the me macros.

Macro Description Comments
.(c Begin Centered Block
.(d Begin Delayed Text Printed with .pd
.(f Begin Footnote
.(l Begin List
.(q Begin Major Quote
.(xn Begin Indexed item Stored in index n, printed with .xp
.(z Begin Floating Keep
.)c End Centered Block
.)d End Delayed Text Printed with .pd
.)f End Footnote
.)l End List
.)q End Major Quote
.)x End Indexed Item
.)z End Floating Keep
.++ x H Define Paper Section x can be C for Chapter, A for Appendix, P for Preliminary, and B for Bibliography; H is the heading
.+c T Begin Section Section is defined with .++ macro; T is the title
.1c One Column Format Begins on a new page
.2c Two Column Format Begins on a new page
.EN Space after eqn/neqn equation
.EQ x n Space before eqn/neqn equation x is optional and can be I for indent (default), L for left justify, and C to Center; n is the equation number.
.PE End pic Picture
.PS Begin pic Picture
.TE End tbl Table
.TH tbl Table Heading Defines table formatting
.TS Begin tbl Table
.ac a n Use ACM Style a is the Author's Name, n is the total number of pages
.b Bold Change font to bold
.ba n Base Augment Changes base indent by n; to reduce, use negative number
.bc Begin Column
.bi Bold Italics Changes the font to bold italics
.bu Begin Bulleted Paragraph
.bx x Box Text x is text placed inside box
.ef 'x'y'z Even Page Footer x is left side, y is centered, and z is right side text
.eh 'x'y'z Even Page Header x is left side, y is centered, and z is right side text
.fo 'x'y'z Set Page Footer x is left side, y is centered, and z is right side text
.he 'x'y'z Set Page Header x is left side, y is centered, and z is right side text
.hx Header/Footer Suppress Headers and footers do not print on next page
.hl Horizontal Line
.i Italics Changes the font to italics
.ip x n Begin Indented Paragraph x is hanging tag, n is indentation, defaulting to 5 ens
.lp Begin Left Blocked Paragraph
.lo Read in Local Macros Should be done at top of document
.np Begin Numbered Paragraph
.of 'x'y'z Odd Page Footer x is left side, y is centered, and z is right side text
.oh 'x'y'z Odd Page Header x is left side, y is centered, and z is right side text
.pd Print Delayed Text that was previously defined with .(d and .)d
.pp Begin Paragraph By default, the first line is indented
.r Roman Changes the font to roman
.re Reset Tabs to default values
.sc Read in Special Characters Should be done at top of document
.sh n H Begin Section n is the section level, H is the section heading
.sk Skip Next Page
.sm Small Changes the font to Small
.sz n Font Size Augment Changes Font Size by n; to reduce, use negative number
.th Thesis Format
.tp Begin Title Page
.uh Begin Unnumbered Section Like .sh but no numbers
.xp n Print Index that was previously defined with .(xn and .)xn.

ms Macro Summary

The ms macro package is used for general formatting.

Table 9.5 lists the ms macros and describes their functions.

Table 9.5. Summary of the ms macros.

Macro Description Comments
.1C One Column Format Begins on a new page
.2C Two Column Format Begins on a new page
.AB Begin Abstract
.AE End Abstract With text, sets text in bold
.AI Author's Institution With text, sets text in bold
.AU Author's Name With text, sets text in bold
.B Bold Changes font to bold
.B1 Begin Text in Box Text between this macro and .B2 is enclosed in a box
.B2 End Text in Box
.BD Block Display Centers entire block
.BT Bottom Title Printed at bottom of each page, defaults to the date
.BX Print Text in Box Text following this macro is enclosed in a box; used for words or phrases while .B1 and .B2 are used for larger segments of text
.CD Centered Display
.CT Chapter Title
.DA n Date for Footer Forces date onto page footer, current date is used if n is not specified
.DE End Display
.DS Begin Display with keep Accepts optional indent
.EF "x"y"z Even Footer x is left side text, y is center, and z is right side
.EH "x"y"z Even Header x is left side text, y is center, and z is right side
.EN End eqn/neqn Equation
.EQ x n Begin eqn/neqn Equation x is optional and can be I for indent (default), L for left justify, and C to Center; n is the equation number
.FE End Footnote
.FP Numbered Footnote Paragraph
.FS L Start Footnote L is optional label
.HD Optional Page Header Placed below header margin
.I Italicize Changes the font to italics
.ID n Indent Display, no keep n is the indent
.IP x n Begin Indented Paragraph x is hanging tag, n is indentation, defaulting to 5 ens
.IX a b ... Index Words a, b, ... are up to five levels of words to index
.KE End Keep Ends keep of any kind
.KF Begin Floating Keep Text fills remaining lines on page
.KS Begin Keep Text kept together on single page
.LD Left Display, no keep
.LG Larger Increases font size by 2 points
.LP Left Paragraph (block)
.MC n Multiple Columns n is the column width
.ND No Date Date is not included on page footer
.NH Numbered Header
.NL Normal Sets font size back to normal
.OF "x"y"z Odd Footer x is left side text, y is center, and z is right side
.OH "x"y"z Odd Header x is left side text, y is center, and z is right side
.P1 Print Header on Page 1
.PP Print Paragraph First line indented
.PT Page Title Printed at top of each page
.PX Print Index Prints Index
.QP Quote Paragraph Major quote; indented and smaller font
.R Roman Changes the font to roman
.RE End Relative Indent
.RP Reset Paper Format Return to default format
.RS Right Shift Starts Relative Indent
.SH Section Header Prints header in bold
.SM Smaller Decreases font size by 2 points
.TA Set Tab Positions Defaults are 8n and 16n for nroff, and 5n and 10n for troff
.TC Print Table of Contents
.TE End tbl Table
.TH tbl Table Heading Defines table formatting
.TL Title Prints title in bold and 2 points larger
.TS Begin tbl Table
.UL Underline Underlines text
.UX UNIX Prints the text UNIX with a trademark the first time used
.XA Another Index Entry
.XE End Index Entry Ends .XA or series of .IX
.XP Indented Paragraph Differs from .PP because all lines are indented, not just first
.XS Begin Index Entry
.]- Begin refer Reference Begin reference to be processed by refer
.]n End refer Reference End reference to be processed by refer. n is 0 for unknown, 1 for journal article, 2 for book, 3 for book article, and 4 for report

The ms macro package supports a number of numeric registers and predefined strings. Table 9.6 lists the ms macro package registers and describes their functions. Table 22.7 lists the ms macro package predefined strings and describes their functions.

Table 9.6. Summary of the ms macro package registers.

Register Description
DD Display Distance
FF Footnote Format; 0 is default, 1 suppresses superscripting, 2 suppresses superscripting and first line indentation, 3 produces footnote paragraphs like .IP
FI Footnote Indent
FL Footnote Length
FM Footer Margin
HM Header Margin
LL Line Length
LT Title Length
PD Paragraph Distance
PI Paragraph Indent
PO Page Offset
PS Point Size
QI Quote Indent
VS Vertical Spacing

Table 9.7. Summary of the ms macro package predefined strings.

String Description
\*Q Quote, " in nroff, '' in troff
\*U Unquote, " in nroff, '' in troff
\*- Dash, -- in nroff, -- in troff
\** Footnote, automatically numbered
\*' Acute Accent (use before letter)
\*' Grave Accent (use before letter)
\*^ Circumflex (use before letter)
\*, Cedilla (use before letter)
\*: Umlaut (use before letter)
\*~ Tilde (use before letter)

Summary

Using macro packages such as man, ms, or me, ease the development of documents and standardizes the "look and feel." As you work with a particular package, you learn more about it, but you can start with only the basics and produce good-looking documents.

TOCBACKFORWARDHOME


©Copyright, Macmillan Computer Publishing. All rights reserved.