Appendix A: Command Descriptions

This appendix serves as a reference manual for the -ms macros; the intention here is to provide a concise but complete description of the operation of each command. Certain typographical conventions are used in presenting command syntax. Command names appear at the left margin, followed where appropriate by the arguments available with the command. Arguments are typed on the same line as the command, separated from the command and from each other by a space. An argument which contains one or more spaces within it must be surrounded by double-quote marks except where noted. A word in boldface indicates what must be typed literally as shown in the syntax statement; thus each command name appears in boldface. A word in italics represents an argument which you supply. The contents of the argument are sometimes entirely your choice (for example, the label after the command .IP can be anything). Sometimes the argument is restricted to a predetermined set of choices (for example, the level-number after the .NH command must be an integer from 0 to 5, or the letter S). Details about what can be supplied as an argument are contained in the description opposite each command.

An argument enclosed in square brackets is optional--the command has meaning either with or without that argument. Conversely, an argument not enclosed in square brackets must be supplied whenever the command is used. An argument enclosed in square brackets and printed in boldface is optional, but, if used, must be typed literally as shown.

Paragraphs

.PP

Begins a standard paragraph, separated vertically from preceding text by the value of number register PD. First line is indented by the value of register PI, and following lines begin at the current main indentation level.

.LP

Begins a left-block paragraph, set off vertically by the value of register PD. No first-line indentation. All lines begin at the main indentation level.

.IP [label] [indentation]

Begins an indented paragraph, set off vertically by the value of register PD. The entire block is left-adjusted and then, by default, indented the value of register PI to the right of the main indentation level. If one argument is given, it is a label to be placed at the main indentation level opposite the first line of the paragraph. If two arguments are given, the second must be numeric and is an amount of indentation (in ens unless indicated otherwise) to supersede the default indentation for the paragraph. Nonstandard indentation must be specified if the label is too wide to fit within the default indentation. This nonstandard indentation persists in subsequent .IPs in a series, disappearing when the series is ended by a return to some other format such as a section heading or a .PP or .LP paragraph.

For nonstandard indentation without any label, the first argument should be simply a pair of double-quote marks with nothing between them.

.QP

Begins a block-quote paragraph. Preceded by vertical space as for other paragraphs. Every line is indented from the main indentation level by the value of register QI. The right margin is moved in toward the left by an equal amount (the line length is shortened). Successive .QPs maintain the same indentation; it does not accumulate.

.XP

Begins an exdented paragraph set off vertically by the value of number register PD. The first line will be flush left, but the remaining lines will be indented by the value of number register PI. This is the command to use for bibliography entries.

Section Headings

.SH

Begins a heading that is left-adjusted at the main indentation level and separated by one vertical space from whatever preceded it. In nroff, the heading is underlined; in troff, it is set in boldface.

.NH [level-number]

Produces a heading similar to .SH except that it is automatically numbered. An optional level number, from 1 to 5, causes the macro to generate the next consecutive section number of that level (1.2.5 is a third-level section number). A level-number 0 (zero) may be used as the argument; this cancels the numbering sequence in effect and generates a heading numbered 1. The header number can be set by specifying "S" and the section number. For example, .NH S 4 2 3 will set the header number to 4.2.3.

Note: when either .SH or .NH is used, all text up to the next paragraph command or section heading command is considered part of the heading.

Changes in Indentation

.RS

Moves the indentation to the right by a value based on register PI. More than one .RS may be used, producing additional indentation.

.RE

Moves the indentation to the left by the same amount as the corresponding .RS moved it to the right. To restore the original indent, each .RS must be balanced by a corresponding .RE.

Note: it is not possible to move the indentation level to the left of the page offset. The value of register PI should not be changed within a series of .RS and .RE commands at any point except after the indentation has been returned to its default starting position.

Footnotes

.FS [label]

Begins text of footnote. This macro, and the accompanying footnote text, should be placed in the input file immediately after the reference to the footnote. Footnote text is automatically saved and printed at the bottom of the current page, separated from the main text by a horizontal rule. Using \** as the footnote indicator just before the .FS will cause automatic footnote numbering to occur. A footnote label may be specified, which will be printed instead of a footnote number. If not enough space remains on the page for all of the footnote, it continues at the bottom of the following page. The line length of footnotes defaults to 5 1/2 inches. In troff output, footnotes are set in type two points smaller than regular text.

.FE

Marks the end of footnote text.

Note: the FF number register controls the footnote format. Setting FF to 1 suppresses footnote superscripting or bracketing; setting it to 2 also suppresses indentation of the first line; and setting it to 3 produces an .IP-like paragraph.

Emphasis and Size Changes

.I [word] [punctuation]

Without an argument, this macro causes a switch to font number 2 (italic) in troff or underlined typing in nroff. If one argument is given, it is one word to be italicized, and the effect of the command is limited to that word. A second argument may consist of trailing punctuation to be printed directly after the word, in the typeface (usually roman) in use for the text prior to the italicized word.

.B [word] [punctuation]

Produces text in font number 3 (boldface) in troff, underlining in nroff. Usage is analogous to that of .I.

.R

Switches back to font number 1 (roman) in troff, non-underlined typing in nroff.

.UL word

Causes the word supplied as the argument to be underlined. This is the only -ms command to produce an underlined word on the typesetter. It works only for one word at a time.

.LG

Increases the type size by two points in troff. (May be repeated for added effect.) Ignored by nroff.

.SM

Reduces the point size by two points. May be repeated for added effect. Ignored by nroff.

.NL

Resets the point size to the normal setting, i.e., the value of the PS register. Ignored by nroff.

Note: if changing the type size by two points results in a non-existent type size on the typesetter, the next larger valid size is chosen. Valid point sizes are 6, 7, 8, 9, 10, 11, 12, 14, 16, 18, 20, 22, 24, 28, and 36.

Boxes Around Text

.BX word

Draws a box around word.

.B1

Begins a longer passage of text to be enclosed in a box.

.B2

Ends passage of text and draws box.

Title Pages and Cover Sheets

.RP [no]

Causes a cover sheet to be generated containing any of the following information, if included with the appropriate macro after .RP: title, authors, authors' institutions, and abstract. The current date is printed on the cover sheet unless suppressed with the command .ND. Ordinarily the title, authors, and authors' institutions are also printed on the first page, unless the argument no is specified to suppress this.

.TL

When used for cover sheet and/or title page (prior to regular text), .TL causes title text to be filled, without hyphenation, on a 5-inch line length. The resulting lines are individually centered when printed. To break lines of title text differently, use the command .br. Troff sets the title in 12-point boldface.

.AU

Centers the author's name, included on the following line of the input file. More than one name can be included, in which case they will be printed on separate lines if entered on separate input lines. Troff sets names in 10-point italic.

.AI

Centers lines of information about the author's institution. .AU and .AI commands can be repeated, if desired, for multiple authors from different institutions.

.AB [no]

Begins the abstract. When printed, this is preceded by a centered heading of the word ABSTRACT unless suppressed by use of the argument no. The abstract is filled, hyphenated and adjusted on a line length 5/6 the normal text line length.

.AE

Ends the abstract.

Note: in order for cover sheet/title page material to be handled properly, it must be followed by a beginning or initializing macro such as one of the paragraph or section heading commands before the regular text begins. If .RP is used, all of the title/author/abstract material is put on the cover sheet and all except the abstract is repeated at the top of page one. Otherwise, all of the material is placed on page one prior to the beginning of regular text.

Dates

.ND [date]

When used without an argument, this macro suppresses printing of the date on the document. (By default, if .ND is omitted, -ms causes nroff to print the current date at the bottom center of every page, and on the cover sheet in .RP format; with troff, the date is printed only on the cover sheet.) If a date is given as an argument to this macro, it appears on the cover sheet in .RP format but nowhere else.

.DA [date]

Without an argument, .DA causes the current date to be printed at the bottom of every page of output in troff, as well as on the cover sheet. (This is the default condition in nroff.) With a date as an argument, the command causes the specified date (rather than the current date) to be printed at the bottom of every page, and on the cover sheet, for both nroff and troff. The current date is always available in the \*(DY string register.

Note: when typing the date as an argument to either of these macros, you can include spaces without having to enclose the whole thing in double-quote marks as you ordinarily would in an argument to a command.

Tables of Contents

.XS [page] [indentation]

Begin a table of contents entry, to be saved and printed when .PX or .TC is called. The current page number will appear after a line of dots, unless a different page number is specified. If the word no is given instead of a page, the line of dots and page number will be suppressed. The entry will be left-justified unless an indentation is specified; this indentation will remain in effect until another indentation level is specified.

.XA [page] [indentation]

Append a table of contents entry to the sequence of entries currently being saved. Same arguments as for the .XS macro.

.XE

End a table of contents entry, or a sequence of entries begun with a single .XS and having an arbitrary number of .XA macros.

.PX [no]

Print the table of contents collected so far, preceded by a centered title saying Table of Contents. The argument no will suppress the title.

.TC [no]

Same as .PX except that it should be used at the end of a file when the table of contents has been automatically collected. The .TC macro causes a page break and sets the page number back to "i" (Roman numeral one).

Multi-column Formats

.2C

Switches to two-column format. Column widths are 7/15 of the current value of the LL number register; gutter width is 1/15 LL.

.1C

Switches to single-column format (the default format). A switch from two or more columns to single-column causes a page break before output is resumed.

.MC [column-width]

Switches to multi-column format. The number of columns is computed automatically: it will be the largest number of the specified width that can fit within the regular line length (the value of register LL). The column-width argument must be numeric (it may be an integer or contain a decimal fraction), and is understood to be a number of ens unless a different unit is indicated. If no column-width is specified, .MC means the same as .2C. Any change in the number of columns, except from one to a larger number, causes a page break first.

Keeps

.KS

Begins a standard keep. Text on following input lines will be kept together on one page if possible. If not enough space remains on the current page, a new page is begun at this point.

.KF

Begins a floating keep. If not enough space remains on the current page for the keep, the current page will be completed with the input text that follows the end of the keep; the kept material then begins the next page.

.KE

Marks the end of either standard or floating keep.

Note: In formats of two or more columns, the effect is to try to keep the material together in one column; if there isn't room in the current column, the material starts in the next.

Displays

.DS [format] [indentation]

Begins a display, i.e., unfilled text. Set off by vertical space above and below by the value of register DD (1v in nroff, 0.5v in troff). A format indicator may be given as an argument. The possible format indicators are:

L

left-adjusted

I

indented 0.5i (troff) or 8n (nroff)

C

each line is centered individually

B

left-adjusted lines are centered as a group

.DS with no format indicator means the same as .DS I. Either of these forms may also take a numeric argument representing a non-standard indentation in ens. Any of the displays described above automatically invokes a keep.

.LD

Left-adjusted display without invoking keep.

.ID [indentation]

Indented display without keep. Default indentation is the same as for .DS I. Other indentation may be specified as an argument.

.CD

Lines individually centered, without keep.

.BD

Left adjusted and then centered, without keep.

.DE

Marks the end of any type of display.

Page Headers and Footers

.P1

Print page header on the first page. Must be used before beginning of text.

.EH 'left'center'right'

Specifies a header to be printed on even-numbered pages.

.OH 'left'center'right'

Specifies a header to be printed on odd-numbered pages.

.EF 'left'center'right'

Specifies a footer to be printed on even-numbered pages.

.OF 'left'center'right'

Specifies a footer to be printed on odd-numbered pages.

Note: the three strings specified between the four apostrophes will be left justified, centered, and right justified, respectively. Another character besides the apostrophe may be used as the string delimiter, as long as it does not occur in any of the three strings. No more than nine words are allowed. When used without arguments, .EH, .OH, .EF, and .OF cancel their respective headers or footers.

Thesis Mode

.TM

Formats using the style preferred for UC Berkeley theses. It doublespaces, prints the page number in the right header, even on page one, and suppresses the date. Additionally, defines the .CT macro for chapter titles.

.CT

Only defined when .TM has been called. It begins a new page, moves the page number from the right header to the center footer, and centers and emboldens the lines following the request, until the next paragraph macro.

Tables and Equations

.TS [H]

Signals the beginning of material to be preprocessed by tbl. When used with -ms, it also has the effect of supplying half of a vertical space separation between the table and any preceding text. When used with the argument "H", table data up to the command .TH is understood as a running head for the table and recurs on following pages of a multi-page table. (This effect is obtainable only when -ms is used.)

.TH

Signals the end of the running table heading.

.TE

Signals the end of material to be preprocessed by tbl, and, with -ms, supplies half of a vertical space at the end of the table.

.EQ [format] [number]

Marks the beginning of material to be preprocessed by eqn or neqn. When used with -ms, generates vertical separation before the equation is output and, by default, centers the equation in the output line. Placement of the equation can be controlled by use of a format indicator as an argument: use .EQ L for left-adjusted, .EQ I for indented, and .EQ C for centered. An equation number, whatever you choose, may also be given as an argument to .EQ. If both arguments are used, the format indicator should be placed first. Equation numbers ordinarily appear on the right; they can be made to appear on the left by setting number register EP to one.

.EN

Signals the end of material to be preprocessed by eqn or neqn.