[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 Commands Reference, Volume 5

troff Command

Purpose

Formats text for printing on typesetting devices.

Syntax

troff -a ] [ -i ] [ -q ] [ -z ] [ -F Directory ] [ -n Number ] [ -o List ] [ -r ANumber ] [ -s Number ] [ -T Name ] [ -mm | -me | -mptx | -ms | -man | -mv ] [ -M Media ] [ File ... | ]

Description

The troff command reads one or more files and formats the text for printing on a phototypesetter or comparable device. A postprocessor is then required to post process the output of the troff command to the target device. See the accompanying example.

If no file is specified or the - (minus) flag is not the last parameter, standard input is read by default.

For the 3812, 3816, and Hewlett-Packard LaserJet Series II printer, the default fonts are the native fonts for the printer. Additional fonts also are available for these printers, which may be loaded through the use of the troff .fp directive. These fonts are stored on the host in the directory /usr/lib/font/devPrinter/bitmaps, and downloaded to the printer as necessary.

Typefaces

Three different typefaces are provided in four styles. The following chart shows the relationship between typeface, style, and the name that the troff command uses to access the font.

Note: The fonts in this set are based on the Computer Modern letter forms developed by Donald E Knuth. (Refer to Knuth, Donald: Computer Modern Typefaces. Addison-Wesley, 1986.)

Typeface      Regular     Italic       Bold        Italic
Roman         cr          cR           Cr          CR
Sans Serif    cs          cS           Cs          CS
Typewriter    ct          cT           Ct          CT
troff special sp

These fonts are all provided in the standard 15 troff sizes: 6, 7, 8, 9, 10, 11, 12, 14, 16, 28, 20, 22, 24, 28, and 36 points.

For example, .fp 1 Cr loads the Roman bold font into position 1.

Note: The .tl request cannot be used before the first break-producing request in the input to the troff command.

Flags

-a Sends a printable ASCII approximation of the results to standard output.
-FDirectory Accesses font information from the Directory/devName directory instead of the default /usr/lib/font/devName directory (where Name is specified by the -T flag).
-i Reads standard input after there are no more files.
-M Media Specifies a paper size in order to determine the amount of imageable area on the paper. Valid values for the Media variable are:
A4 Specifies a paper size of 8.3 X 11.7 inches (210 X 297 mm).
A5 Specifies a paper size of 5.83 X 8.27 inches (148 X 210 mm).
B5 Specifies a paper size of 6.9 X 9.8 inches (176 X 250 mm).
EXEC Specifies a paper size of 7.25 X 10.5 inches (184.2 X 266.7 mm).
LEGAL Specifies a paper size of 8.5 X 14 inches (215.9 X 355.6 mm).
LETTER Specifies a paper size of 8.5 X 11 inches (215.9 X 279.4 mm). This is the default value.

Note: The Media variable is not case-sensitive.

-nNumber Numbers the first printed page with the value specified by the Number variable.
-oList Prints only pages specified by the List variable, which consists of a comma-separated list of page numbers and ranges:
  • A range of Start-Stop means print pages Start through Stop. For example: 9-15 prints pages 9 through 15.
  • An initial -Stop means print from the beginning to page Stop.
  • A final Start- means print from pageStart to the end.
  • A combination of page numbers and ranges prints the specified pages. For example: -3,6-8,10,12- prints from the beginning through page 3, pages 6 through 8, page 10, and page 12 to the end.

    Note: When this flag is used in a pipeline (for example, with one or more of the pic, eqn, or tbl commands), you may receive a broken pipe message if the last page in the document is not specified in the List variable. This broken pipe message is not an indication of any problem and can be ignored.

-q Calls the simultaneous input and output mode of the .rd request.
-rANumber Sets the register specified by the A variable to the specified number. The A variable value must have a one-character ASCII name.
-sNumber Generates output to make the typesetter stop every specified number of pages.
-TName Prepares the output for the specified printing device. Phototypesetters or comparable printing devices use the following Name variables for AIX international extended characters. The default is ibm3816.

Note: You get a message that reads bad point sizeif your device does not support the point size that you specified. The troff command uses the closest valid point size to continue formatting.

canonls Canon Lasershot LBP-B406S/D/E,A404/E,A304E.
ibm3812 3812 Pageprinter II.
ibm3816 3816 Pageprinter.
hplj Hewlett-Packard LaserJet II.
ibm5585H-T 5585-H01 Traditional Chinese Language support.
ibm5587G 5587-G01, 5584-H02, 5585-H01, 5587-H01, and 5589-H01 Kanji Printer multibyte language support.
psc PostScript printer.
X100 AIXwindows display.

Note: You also can set the TYPESETTER environment variable to one of the preceding values instead of using the -TName flag of the troff command.

-man Selects the man macro processing package.
-me Selects the me macro processing package.
-mm Selects the mm macro processing package.
-mptx Selects the mptx macro processing package.
-ms Selects the ms macro processing package.
-mv Selects the mv macro processing package.

Note: See Macro Packages for Formatting Tools for more inforamtion on the macros.

-z Prints only messages generated by .tm (workstation message) requests.
- Forces input to be read from standard input.

Environment Variables

TYPESETTER Contains information about a particular printing device.

Examples

The following is an example of the troff command:

troff -Tibm3812 File | ibm3812 | qprt

Macro Packages for Formatting Tools

The following macro packages are part of the Formatting Tools in the Text Formatting System and are described in more detail on the next pages:

man Enables you to create your own manual pages from online manual pages.
me Provides macros for formatting papers.
mm Formats documents with nroff and troff formatters.
mptx Formats a permuted index.
ms Provides a formatting facility for various styles of articles, theses, and books.
mv Typesets English-language view graphs and slides by using the troffcommand.

man Macro Package for the nroff and troff Commands

The man macro package is provided to enable users to create their own manual pages from online manual pages that have been processed with either the nroff command or troff command. The man macro package is used with either the nroff command or the troff command.

Note: The man macro package cannot be used to process the InfoExplorer information bases into manual pages.

Special macros, strings, and number registers exist, internal to the man macro package, in addition to the following lists of format macros, strings, and registers. Except for the names predefined by the troff command and the d, m, and y number registers, all such internal names are of the form SymbolAlpha, where Symbol is one of ), ], or }, and Alphais any alphanumeric character.

The man macro package uses only the Roman font. If the input text of an entry contains requests for other fonts (for example, the .I format macro, .RB request, or \fI request) the corresponding fonts must be mounted.

Format Macros

The following macros are used to alter the characteristics of manual pages that are formatted using the manmacro package.

Type font and size are reset to default values before each paragraph and after processing font- and size-setting macros (for example, the .I format macro, .SM format macro, and .B format macro).

Tab stops are neither used nor set by any of the format macros except the .DT format macro and the .TH format macro.

.B [Text] Makes text bold.

The Text variable represent up to six words; use " " (double quotation marks) to include character spaces in a word. If the variable is empty, this treatment is applied to the next input text line that contains text to be printed. For example, use the .I format macro to italicize an entire line, or use the .SM and .B format macros to produce an entire line of small-bold text. By default, hyphenation is turned off for the nroff command, but remains on for the troff command.

.DT Restores default tab settings every 5 ens for the nroff command and every 7.2 ens for the troff command.
.HP [Indent] Begins a paragraph with a hanging indent as specified by the Indentvariable.

If the Indent variable is omitted, the previous Indent value is used. This value is set to its default (5 ens for the nroff command and 7.2 ens for the troff command) by the .TH format macro, .P format macro, and .RS format macro, and restored by the .RE format macro. The default unit for Indent is ens.

.I [Text] Makes text italic.

The Text variable represent up to six words; use " " (double quotation marks) to include character spaces in a word. If the variable is empty, this treatment is applied to the next input text line that contains text to be printed. For example, use the .I format macro to italicize an entire line, or use the .SM and .B format macros to produce an entire line of small-bold text. By default, hyphenation is turned off for the nroff command, but remains on for the troff command.

.IP [Tag] [Indent] Same as the .TP Indent macro with the Tag variable; if the value of the Tag variable is NULL, begin indented paragraph. This macro is often used to get an indented paragraph without a tag.

If the Indent variable is omitted, the previous Indent value is used. This value is set to its default (5 ens for the nroff command and 7.2 ens for the troff command) by the .TH format macro, .P format macro, and .RS format macro, and restored by the .RE format macro. The default unit for Indent is ens.

.P Begins paragraph with normal font, point size, and indent. The .PP macro is a synonym for the mm macro package .P macro.
.PD [Number] Sets inter-paragraph distance the number of vertical spaces specified by the Number parameter. The default Number variable value is 0.4v for the troff command and 1v for the nroff command.
.PM [Indicator] Sets proprietary marking as follows:
Indicator Marking
P PRIVATE
N NOTICE
No Indicator specified Turns off proprietary marking.

.RE [Number] Ends relative indent (.RS) at indent level position specified by the Number variable. If the Number variable value is omitted, return to the most recent lower indent level.
.RI Character1Character2... Concatenates the Roman Character1 with the italic Character2; alternate these two fonts up to six sets of Character1Character2. Similar macros alternate between any two of Roman, italic, and bold: the .IR, .RB, .BR, .IB, and .BI macros.
.RS [Indent] Increases relative indent (initially zero). Indent all output an extra number of units from the left margin as specified by the Indent variable.

If the Indent variable is omitted, the previous Indent value is used. This value is set to its default (5 ens for the nroff command and 7.2 ens for the troff command) by the .TH format macro, .P format macro, and .RS format macro, and restored by the .RE format macro. The default unit for Indent is ens.

.SH [Text] Places subhead text.

The Text variable represent up to six words; use " " (double quotation marks) to include character spaces in a word. If the variable is empty, this treatment is applied to the next input text line that contains text to be printed. For example, use the .I format macro to italicize an entire line, or use the .SM and .B format macros to produce an entire line of small-bold text. By default, hyphenation is turned off for the nroff command, but remains on for the troff command.

.SM [Text] Makes text one point smaller than default point size.

The Text variable represent up to six words; use " " (double quotation marks) to include character spaces in a word. If the variable is empty, this treatment is applied to the next input text line that contains text to be printed. For example, use the .I format macro to italicize an entire line, or use the .SM and .B format macros to produce an entire line of small-bold text. By default, hyphenation is turned off for the nroff command, but remains on for the troff command.

.SS [Text] Places sub-subhead text.

The Text variable represent up to six words; use " " (double quotation marks) to include character spaces in a word. If the variable is empty, this treatment is applied to the next input text line that contains text to be printed. For example, use the .I format macro to italicize an entire line, or use the .SM and .B format macros to produce an entire line of small-bold text. By default, hyphenation is turned off for the nroff command, but remains on for the troff command.

.TH [Title][Section][Commentary][Name]
                          Sets the title and entry heading. This macro calls the .DT format macro.
Variable Marking
Title Title
Section Section number
Commentary Extra commentary
Name New manual name.

Note: If the .TH format macro values contain character spaces that are not enclosed in " " (double quotation marks), irregular dots are displayed on the output.

.TP [Indent] Begins indented paragraph with hanging tag. The next input line that contains text is the tag. If the tag does not fit, it is printed on a separate line.

If the Indent variable is omitted, the previous Indent value is used. This value is set to its default (5 ens for the nroff command and 7.2 ens for the troff command) by the .TH format macro, .P format macro, and .RS format macro, and restored by the .RE format macro. The default unit for Indent is ens.

Strings

\*R Adds trademark, (Reg.) for the nroff command and the registered trademark symbol for the troff command.
\*S Changes to default type size.
\*(Tm Adds trademark indicator.

Registers

IN Indent left margin relative to subheads. The default is 7.2 ens for the troff command and 5 ens for the nroff command.
LL Line length including the value specified by the IN register.
PD Current inter-paragraph distance.

Flags

-rs1 Reduces default page size of 8.5 inches by 11 inches with a 6.5-inch by 10-inch text area to a 6-inch by 9-inch page size with a 4.75-inch by 8.375-inch text area. This flag also reduces the default type size from 10-point to 9-point and the vertical line spacing from 12-point to 10-point.

Examples

  1. To process the file your.book and pipe the formatted output to the local line printer, qprt, enter:
    nroff -Tlp -man your.book | qprt -dp 
  2. To process the files my.book and dept.book, which contain tables, and pipe the formatted output to the local line printer, qprt, enter:
    tbl my.book dept.book | nroff -Tlp -man | col -Tlp | qprt -dp

    Note: Before the output is sent to qprt, it is first filtered through the col command to process reverse linefeeds used by the tbl command.

  3. To process the file group, which contains pictures, graphs, and tables, and prepare the formatted output for processing on the IBM 3816 printer, enter:
    grap group | pic | tbl | troff -Tibm3816 -man \
      | ibm3816 | qprt -dp

Notes:

  1. If manual pages created with the man macro package are intended for an online facility, components requiring the troff command, such as the grap or pic command, should be avoided.
  2. The grap command precedes the piccommand since it is a preprocessor to the pic command; the reverse does not format correctly.
  3. The col command is not required as a filter to the tbl command; typeset documents do not require reverse linefeeds.

me Macro Package for the nroff and troff Commands

The me package of the nroff and troff command macro definitions provides a formatting facility for technical papers in various formats. The col command may be required to postprocess nroff output in certain cases.

The macro requests are defined in the following section, in me Requests. Many nroff/troff requests can have unpredictable results in conjunction with this package. However, the following requests can be used after the first .pp request:

.bp Begins new page.
.br Breaks output line here.
.ce [Number]
                          Centers next specified number of lines. Default is 1 (one).
.ls [Number]
                          Sets line spacing. Text is single-spaced if Number is set to 1 (one); double-spaced if the value is set to 2.
.na Leaves right margin unjustified.
.sp [Number]
                          Inserts the specified number of spacing lines.
.sz [+]Number
                          Adds the specified number to point size.
.ul [Number]
                          Underlines next specified number of lines. Default is 1 (one).

Output of the eqn, neqn, refer, and tbl commands preprocessors for equations and tables can be used as input.

me Requests

The following list contains all macros, strings, and number registers available in the me macros. Selected troff commands, registers, and functions are included.

\(space) Defines unpaddable space (troff command built-in function).
\" Comments to end of line (troff command built-in function).
\*# Indicates optional delayed text tag string.
\$Number Interpolates the value specified by the Number variable (troff command built-in function).
\n($0 Defines section depth (number register).
.$0 Started after section title printed (user-definable macro).
\n($1 Defines first section number (number register).
.$1 Started before printing depth 1 (one) section (user-definable macro).
\n($2 Defines second section number (number register).
.$2 Started before printing depth 2 section (user-definable macro).
\n($3 Defines third section number (number register).
.$3 Started before printing depth 3 section (user-definable macro).
\n($4 Defines fourth section number (number register).
.$4 Started before printing depth 4 section (user-definable macro).
\n($5 Defines fifth section number (number register).
.$5 Started before printing depth 5 section (user-definable macro).
\n($6 Defines sixth section number (number register).
.$6 Started before printing depth 6 section (user-definable macro).
.$C Called at beginning of chapter (user-definable macro).
.$H Indicates text header (user-definable macro).
\n($R Defines relative vertical spacing in displays (number register defined by default; changing is not recommended).
\n($c Defines current column header (number register).
.$c Prints chapter title (macro defined by default; changing is not recommended).
\n($d Indicates delayed text number (number register).
\n($f Indicates footnote number (number register).
.$f Prints footer (macro defined by default; changing is not recommended).
.$h Prints header (macro defined by default; changing is not recommended).
\n($i Defines paragraph base indent (number register).
\n($l Defines column width (number register).
\n($m Indicates number of columns in effect (number register).
\*($n Indicates section name (string).
\n($p Defines numbered paragraph number (number register).
.$p Prints section heading (macro defined by default; changing is not recommended).
\n($r Defines relative vertical spacing in text (number register defined by default; changing is not recommended).
\n($s Defines column indent (number register).
.$s Separates footnoter from text (macro defined by default; changing is not recommended).
\n% Defines current page number (number register defined by default; changing is not recommended).
\& Indicates zero-width character; useful for hiding controls (troff command built-in function).
\(XX Interpolates special character specified by the XX variable (troff command built-in function).
.(b Begins block (macro).
.(c Begins centered block (macro).
.(d Begins delayed text (macro).
.(f Begins footnote (macro).
.(l Begins list (macro).
.(q Begins quote (macro).
.(xIndex Begins indexed item in the specified index (macro).
.(z Begins floating keep (macro).
.)b Ends block (macro).
.)c Ends centered block (macro).
.)d Ends delayed text (macro).
.)f Ends footnote (macro).
.)l Ends list (macro).
.)q Ends quote (macro).
.)x Ends index entry (macro).
.)z Ends floating keep (macro).
\*String Interpolates the value specified by the String variable (troff command built-in function).
\*String1String2 Interpolates the value specified by the String1String2 variable (troff command built-in function).
\** Indicates optional footnote tag string.
.++mH Macro to define paper section. The value specified by the m variable defines the part of the paper. The m variable can have the following values:
C Defines chapter.
A Defines appendix.
P Defines preliminary information, such as abstract and table of contents.
B Defines bibliography.
RC Defines chapters to be renumbered from page 1 (one) of each chapter.
RA Defines appendix to be renumbered from page 1 (one).

The H parameter defines the new header. If there are any spaces in it, the entire header must be quoted. If you want the header to have the chapter number in it, use the string \\\n(ch. For example, to number appendixes A.1, A.2, ..., type: .++ RA '''\\\n(ch.%'. Each section (such as chapters and appendixes) should be preceded by the .+c request.

.+cTitle Begins chapter (or appendix, for instance, as set by the .++macro). The value specified by the Title variable is the chapter title (macro).
\*, Indicates cedilla (string).
\- Indicates minus sign (troff command built-in function).
\*- Indicates 3/4 em dash (string).
\0 Defines unpaddable digit-width space (troff command built-in function).
.1c Reverts to single-column output (macro).
.2c Begins two-column output (macro).
\*: Indicates umlaut (string).
\*< Begins subscript (string).
\*> Ends subscript (string).
.EN Ends equation. Space after equation produced by the eqn command or neqn command (macro).
.EQXY Begins equation; breaks out and adds space. The value specified by the Y variable is the equation number. The optional X variable value may be any of the following:
I Indents equation (default).
L Left-adjusts equation.
C Centers equation (macro).

\L'Distance' Indicates vertical line-drawing function for the specified distance (troff command built-in function).
.PE Ends pic picture (macro).
.PF Ends pic picture with flyback (macro).
.PS Starts pic picture (macro).
.TE Ends table (macro).
.TH Ends header of table (macro).
.TS X Begins table. If the value of the X variable is H, the table has a repeated heading (macro).
\*[ Begins superscript (string).
\n(.$ Defines number of options to macro (number register defined by default; changing is not recommended).
\n(.i Indicates current indent (number register defined by default; changing is not recommended).
\n(.l Indicates current line length (number register defined by default; changing is not recommended).
\n(.s Indicates current point size (number register defined by default; changing is not recommended).
\*(4 Indicates acute accent (string).
\*(` Indicates grave accent (string).
\(4 Indicates acute accent (troff command built-in function).
\(` Indicates grave accent (troff command built-in function).
\*] Ends superscript (string).
\^ Indicates 1/12 em narrow space (troff command built-in function).
\*^ Indicates caret (string).
.acAuthorNumber Sets up for ACM-style output. The Author variable specifies the author name or names. The Number variable specifies the total number of pages. Must be used before the first initialization (macro).
.ad Sets text adjustment (macro).
.af Assigns format to register (macro).
.am Appends to macro (macro).
.ar Sets page numbers in Arabic (macro).
.as Appends to string (macro).
.b X Prints in boldface the value specified by the X variable. If the X variable is omitted, boldface text follows (macro).
.ba +Number Augments the base indent by the specified Number value. Sets the indent on regular text such as paragraphs (macro).
.bc Begins new column (macro).
.bi X Prints in bold italic the value specified by the X parameter, in no-fill mode only. If the X parameter is not used, bold italic text follows (macro).
\n(bi Displays block indent (number register).
.bl Requests blank lines, even at top of page (macro).
\n(bm Sets bottom title margin (number register).
.bp Begins page (macro).
.br Sets break; starts new line (macro).
\n(bs Displays block pre- or post-spacing (number register).
\n(bt Blocks keep threshold (number register).
.bu Begins bulleted paragraph (macro).
.bx X Prints in no-fill mode only the value specified by the X variable in box (macro).
\c Continues input (troff command built-in function).
.ce Centers lines (macro).
\n(ch Defines current chapter number (number register).
.de Defines macro (macro).
\n(df Displays font (number register).
.ds Defines string (macro).
\n(dw Defines current day of week (number register).
\*(dw Defines current day of week (string).
\n(dy Defines current day of month (number register).
\e Indicates printable version of \ (backslash) (troff command built-in function).
.ef'X'Y'Z'
                          Sets even-page footer to the values specified by the XYZ variables (macro).
.eh'X'Y'Z'
                          Sets even-page header to the values specified by the XYZ variables (macro).
.el Specifies the else part of an if/else conditional (macro).
.ep Ends page (macro).
\n(es Indicates equation pre- or post-space (number register).
\fFont Sets inline font change to the specified Font variable value (troff command built-in function).
\f(Fontf Sets inline font change to the specified Fontf variable value (troff command built-in function).
.fc Sets field characters (macro).
\n(ff Sets footnote font (number register).
.fi Fills output lines (macro).
\n(fi Indicates footnote indent, first line only (number register).
\n(fm Sets footer margin (number register).
.fo 'X'Y'Z'
                          Sets footer to the values specified by the XYZ variables (macro).
\n(fp Sets footnote point size (number register).
\n(fs Sets footnote pre-space (number register).
\n(fu Sets footnote indent from right margin (number register).
\h'Distance' Sets local horizontal motion for the specified distance (troff command built-in function).
.hc Sets hyphenation character (macro).
.he 'X'Y'Z'
                          Sets header to the values specified by the XYZ variables (macro).
.hl Draws horizontal line (macro).
\n(hm Sets header margin (number register).
.hx Suppresses headers and footers on next page (macro).
.hy Sets hyphenation mode (macro).
.i X Italicizes the value specified by the X variable. If the Xvariable is omitted, italic text follows (macro).
.ie Specifies the else part of an if/else conditional (macro).
.if Designates a conditional (macro).
\n(ii Sets indented paragraph indent (number register).
.in Indents (transient); use the .ba macro if pervasive (macro).
.ip X Y Starts indented paragraph, with hanging tag specified by the X variable. Indentation is the en value specified by the Y variable. Default is 5 (macro).
.ix Indents, no break (macro).
\l'Distance' Starts horizontal line-drawing function for the specified distance (troff command built-in function).
.lc Sets leader repetition character (macro).
.lh Interpolates local letterhead (macro).
.ll Sets line length (macro).
.lo Reads in a file of local macros of the form .*x. Must be used before initialization (macro).
.lp Begins left-justified paragraph (macro).
\*(lq Designates left quotation marks (string).
.ls Sets multi-line spacing (macro).
.m1 Sets space from top of page to header (macro).
.m2 Sets space from header to text (macro).
.m3 Sets space from text to footer (macro).
.m4 Sets space from footer to bottom of page (macro).
.mc Inserts margin character (macro).
.mk Marks vertical position (macro).
\n(mo Defines month of year (number register).
\*(mo Defines current month (string).
\nX Interpolates number register specified by the X variable value (number register).
\n(XX Interpolates number register specified by the XX variable (number register).
.n1 Sets number lines in margin (macro).
.n2 Sets number lines in margin (macro).
.na Turns off text adjustment (macro).
.neNumber Sets the specified number of lines of vertical space (macro).
.nf Leaves output lines unfilled (macro).
.nh Turns off hyphenation (macro).
.np Begins numbered paragraph (macro).
.nr Sets number register (macro).
.ns Indicates no-space mode (macro).
\*o Indicates superscript circle (such as for Norse A; string).
.of'X'Y'Z'
                          Sets odd footer to the values specified by the XYZ variables (macro).
.oh'X'Y'Z'
                          Sets odd header to the values specified by the XYZ variables (macro).
.pa Begins page (macro).
.pd Prints delayed text (macro).
\n(pf Indicates paragraph font (number register).
\n(pi Indicates paragraph indent (number register).
.pl Sets page length (macro).
.pn Sets next page number (macro).
.po Sets page offset (macro).
\n(po Simulates page offset (number register).
.pp Begins paragraph, first line indented (macro).
\n(pp Sets paragraph point size (number register).
\n(ps Sets paragraph pre-space (number register).
.q Indicates quoted (macro).
\*(qa For all (string).
\*qe There exists (string).
\n(qi Sets quotation indent; also shortens line (number register).
\n(qp Sets quotation point size (number register).
\n(qs Sets quotation pre- or post-space (number register).
.r Sets Roman text to follow (macro).
.rb Sets real bold font (macro).
.re Resets tabs to default values (macro).
.rm Removes macro or string (macro).
.rn Renames macro or string (macro).
.ro Sets page numbers in Roman (macro).
\*(rq Indicates right quotation marks (string).
.rr Removes register (macro).
.rs Restores register (macro).
.rt Returns to vertical position (macro).
\sSize Changes inline size to specified size (troff command built-in function).
.sc Reads in a file of special characters and diacritical marks. Must be used before initialization (macro).
\n(sf Sets section title font (number register).
.shLevelTitle Indicates section head to follow; font automatically bold. The Level variable specifies the level of section. The Title variable specifies the title of section (macro).
\n(si Sets relative base indent-per-section depth (number register).
.sk Leaves the next page blank. Only one page is remembered ahead (macro).
.smX Sets, in a smaller point size, the value specified by the X variable (macro).
.so Indicates source input file (macro).
\n(so Sets additional section title offset (number register).
.sp Indicates vertical space (macro).
\n(sp Indicates section title point size (number register).
\n(ss Indicates section prespace (number register).
.sx Changes section depth (macro).
.sz +Number Augments point size by the specified number of points (macro).
.ta Sets tab stops (macro).
.tc Sets tab repetition character (macro).
\*(td Sets today's date (string).
n(tf Indicates title font (number register).
.th Produces paper in thesis format. Must be used before initialization (macro).
.ti Indicates temporary indent, next line only (macro).
.tl Indicates 3-part title (macro).
\n(tm Sets top title margin (number register).
.tp Begins title page (macro).
\n(tp Sets title point size (number register).
.tr Translates (macro).
.u X Underlines the value specified by the X variable, even in the troff command. No-fill mode only (macro).
.uh Sets section head to follow; font automatically bold. Similar to the .sh macro, but unnumbered (macro).
.ul Underlines next line (macro).
\v'Distance' Local vertical motion for the specified distance (troff command built-in function).
\*v Inverts v for Czech e (string).
\w'String' Returns width of the specified string (troff command built-in function).
.xl Sets local line length (macro).
.xpIndex Prints the specified index (macro).
\n(xs Sets index entry prespace (number register).
\n(xu Sets index indent, from right margin (number register).
\n(yr Indicates year, last two digits only (number register).
\n(zs Sets floating keep pre- or post-space (number register).
\{ Begins conditional group (troff command built-in function).
\| 1/6 em, narrow space (troff command built-in function).
\} Ends conditional group (troff command built-in function).
\*~ Indicates tilde (string).

For further information, see the -ME Reference Manual by E. P. Allman.

mm Macro Package for the mm, mmt, nroff, and troff Commands

The mm macro package provides macros to format text in a wide variety of document forms, such as memos, letters, and reports. The manner in which you type and edit a document is essentially independent of whether the document is later formatted at a terminal or phototypeset.

The col command may be required to postprocess nroff output. See the colcommand for specific requirements.

The mm macros and additional information are summarized under the following headings:

Beginning Macros for Formal Memoranda

.ND Date Sets new date.
.TL [ChgNumber] [FileNumber] Sets title information. Text on the following line is used as the title of the document.
.AF [CompanyName] Specifies author's company name.
.AU Name [Initials] [Loc] [Dept] [Ext] [Room] [Option...]
                          Sets author information.
.AT AuthorTitle [...] Specifies title to follow signer's name (up to nine options).
.TM [Number] Sets technical memorandum number.
.AS [ 0 | 1 | 2 ] [Indent] Starts abstract, for technical memorandum and released paper only:
0 Abstract on cover sheet and first page
1 Abstract only on cover sheet
2 Abstract only on memorandum for file cover sheet.

.AE Ends abstract.
.NS Starts notation, allowed on memorandum for file cover sheets following an .AS 2/.AE macro pair (see "Ending Macros").
.NE Ends notation, allowed on memorandum for file cover sheets following an .AS 2/.AE macro pair (see "Ending Macros").
.OK [Keyword ...] Specifies other keywords (up to nine options).
.MT [type] [title] Sets document type:
"" No type.
0 No type (internal letter).
1 Memorandum for file.
2 Programmer's notes.
3 Engineer's notes.
4 Released paper.
5 External letter.
"String" The specified string is printed.

Title User-supplied text prefixed to page number

Business Letter Macros

.WA Starts writer's address.
.WE Ends writer's address.
.LO CN [Notation] Specifies confidential notation.
.LO RN [Notation] Specifies reference notation.
.IA Starts inside (recipient's) address.
.IE Ends inside (recipient's) address.
.LO AT [Notation] Specifies attention line.
.LO SA [Notation] Specifies salutation.
.LO SJ [Notation] Specifies subject line.
.LT [ { none BL SB FB SP} ] Specifies business letter type:
none Blocked
BL Blocked
SB Semiblocked
FB Full-Blocked
SP Simplified.

Ending Macros (Trailing Information)

.FC [Closing] Prints formal closing.
.SG [Initials] [1] Prints signature line.
.NS [{" "0 1 2 3 4 5 6 7 8 9 10 11 12 13 String}]
                          Starts notation:
" "
                          Copy to
0 Copy to
1 Copy (with attachment) to
2 Copy (without attachment) to
3 Attachment
4 Attachments
5 Enclosure
6 Enclosures
7 Under Separate Cover
8 Letter to
9 Memorandum to
10 Copy (with attachments) to
11 Copy (without attachments) to
12 Abstract Only to
13 Complete Memorandum to
String Copy (String) to.

.NE Ends notation.
.AV Name [1] Prints approval signature.
.CS [Pgs] [Other] [Tot] [Figs] [Tbls] [Ref]
                          Prints cover sheet.
.TX Calls user exit for table-of-contents titles.
.TY Calls user exit for table-of-contents header.
.TC [Slev] [Spacing] [Tlev] [Tab] [H1] [H2] [H3] [H4] [H5]
                          Prints table of contents.

Paragraphs

.P [ {0 1 2} ] Starts paragraph:
0 Left-justified (default)
1 Indented
2 Indented except after .H, .LE, .DE.

Section Headings

.H {1 2 3 4 5 6 7} [HeadingText] [FootnoteMark]
                          Specifies numbered headings.
.HU HeadingText Specifies unnumbered headings.
.HM {1 0001 A a I i}... Specifies heading mark style:
1 Arabic
0001 Arabic with leading 0s (zeros)
A Uppercase alphabetic
a Lowercase alphabetic
I Uppercase Roman
i Lowercase Roman.

.HX [Dlev] [Rlev] [HeadingText]
                          Calls user-defined exit macro before headings.
.HY [Dlev] [Rlev] [HeadingText]
                          Calls user-defined exit macro in the middle of headings.
.HZ [Dlev] [Rlev] [HeadingText]
                          Calls user-defined exit macro after headings.

Lists

If the last option [1] is present in the list-start macros, there is no space between items.

.AL [ {1 A a I i} ] [TextIndent] [1]
                          Starts automatically incremented list (1).
.BL [TextIndent] [1] Starts a bullet list.
.DL [TextIndent] [1] Starts a dash list.
.ML Mark [TextIndent] [1]
                          Starts a list in which each list item is tagged with a specified mark. If the value of the TextIndent is NULL or omitted, it is set to [Mark - width + 1]. If the 3rd argument is specified, no blank lines separate items in the list.
.RL [TextIndent] [1] Starts a reference list.
.VL TextIndent [MarkIndent] [1]
                          Starts a variable tag list.
.LI [Mark] [1] Starts list item; 1 means that the Mark variable value is to be prefixed to the current mark.
.LE [1] Ends list item; 1 means to output a blank line after list. The default is no blank line.
.LB TextIndent MarkIndent Pad Type [Mark] [{0 1}] [{0 1}]
                          Begins list:
The value of the Type variable is:
                          1=. 2=) 3=() 4=[] 5=<> 6={}.

Sixth option:

0 No blank line before each list item.

Seventh option:

0 No blank line before list.
.LC [Level] Clears list status up to the Level variable value.

Displays, Tables, Equations, and Footnotes

.DS [{0 1 2 3 }] [{0 1}] [Number]

.DS [{L I C CB}] [{N F}] [Number]
                          Starts static display:
0 or L
                          No indent
1 or I Indent from left
2 or C Center each line
3 or CB
                          Center as a block
0 or N No-fill
1 or F Fill.
Number Indent from right the number of spaces specified by the Number parameter.

.DF [{0 1 2 3 }] [{0 1}] [Number]

.DF [{L I C CB}] [{N F}] [Number]
                          Starts floating display:
0 or L
                          No indent
1 or I Indent from left
2 or C Center each line
3 or CB
                          Center as a block
0 or N No-fill
1 or F Fill.
Number Indent from right the number of spaces specified by the Number parameter.

.DE Ends display.
.FG [Title] [Override] [0 1 2]
                          The value of the Override variable replaces or enhances the default numbering. Specifies figure caption:
0
                          Override value is used as a prefix.
1 Override value becomes a suffix.
2 Replace Override value becomes a replacement.

.TS [H] Starts table:
H Multipage table.

.TH [N] Must be used when specifying option H to .TS:
N Suppresses table headers unless on top of new page.

.TE Ends table.
.TB [Title] [Override] [0 1 2]
                          The value of the Override variable replaces or enhances the default numbering. Specifies table caption:
0
                          Override value is used as a prefix.
1 Override value becomes a suffix.
2 Replace Override value becomes a replacement.

.EX [Title] [Override] [0 1 2]
                          The value of the Override variable replaces or enhances the default numbering. Specifies exhibit caption:
0
                          Override value is used as a prefix.
1 Override value becomes a suffix.
2 Replace Override value becomes a replacement.

.EQ [Label] Starts equation display using the specified label.
.EN Ends equation display.
.EC [Title] [Override] [0 1 2]
                          The value of the Override variable replaces or enhances the default numbering. Specifies equation caption:
0
                          Override value is used as a prefix.
1 Override value becomes a suffix.
2 Replace Override value becomes a replacement.

.FS [Label] Starts footnote using the specified label as an indicator. Default is numbered footnote.
.FE Ends footnote.
.FD [{0 1 2 3 4 ... 11}] [1] Sets footnote format:

First option:

Set up formatting style for footnote text. Default is 0 for mmt command. Default is 10 for mm command. See the following table for the value.

Second option:

Reset footnote counter on first-level heading.

.FD Arg. Hyphens Adjusted Text Indented Label Justified
0 .nh .ad Yes Left
1 .hy .ad Yes Left
2 .nh .na Yes Left
3 .hy .na Yes Left
4 .nh .ad No Left
5 .hy .ad No Left
6 .nh .na No Left
7 .hy .na No Left
8 .nh .ad Yes Right
9 .hy .ad Yes Right
10 .nh .na Yes Right
11 .hy .na Yes Right

Page Headers and Footers

.PH "'Left'Center'Right'"
                          Specifies page header.
.OH "'Left'Center'Right'"
                          Specifies odd-page header.
.EH "'Left'Center'Right'"
                          Specifies even-page header.
.PF "'Left'Center'Right'"
                          Specifies page footer.
.OF "'Left'Center'Right'"
                          Specifies odd-page footer.
.EF "'Left'Center'Right'"
                          Specifies even-page footer.
.BS Starts bottom-block.
.BE Ends bottom-block.
.PX Calls user exit for page-header.
.TP Calls top of page macro.

Miscellaneous Macros

.B [Option] [Prev-Font-option]
                          Prints in bold (up to six options).
.I [Option] [Prev-Font-option]
                          Prints in italics (up to six options); underlines with the nroff command.
.R Returns to Roman font.
.PM [Option] Sets proprietary marking. If you do not give the .PM macro an option, you turn off proprietary markings. The /usr/lib/macros/string.mm file contains some proprietary markings. This file should be edited to meet the user's needs.
.RD [Prompt] [Diversion] [String]
                          Stops code macro. The Prompt variable should be a user-defined string without spaces. The Diversion variable allows the typed-in text to be saved. The String variable contains the first line typed following the prompt.
.RP [{0 1 }] [{0 1 2 3}]
                          Produces reference page:

First option:

0
                          Resets reference counter (default).
1 Does not reset reference counter.

Second option:

0 Causes an .SK macro after (default).
1 Does not cause an .SK macro after.
2 Does not cause an .SK macro before.
3 Does not cause an .SK macro before or after.
.RS/.RF Numbers references automatically.
.WC [{N WF -WF FF -FF WD -WD FB -FB}]
                          Controls width for footnotes and displays when using two columns:
N
                          Normal mode ( -WF, -FF, -WD).
WF Footnotes always wide.
-WF Footnotes follow page style.
FF First footnote determines width of remaining footnotes on that page.
-FF Footnotes follow setting of WF or -WF option.
WD Always wide displays.
-WD Displays follow page style.
FB Floating display causes page break (default).
-FB Floating display does not cause page break.

.SP [Lines] Skips lines down.
.SK [Number] Skips the specified number of pages. (The default is 1.)
.OP Breaks to an odd page.
.2C Prints output in two columns.
.1C Prints output in one column (normal line width restored).
.SA [Option] Sets right-margin justification

Options:

0 Sets default to off (default for the nroff command).
1 Sets default to on (default for the troff command).

If no option is specified, macro reverts to current default.

.SM String1 [String2] [String3]
                          Reduces size of the String1 variable value by 1 point if the String3 variable value is omitted; otherwise, reduces size of the String2 variable value by one point.
.HC Character Sets hyphenation character to the Character variable value.
.S [PointSize] [VerticalSpacing]
                          Sets point size and vertical spacing (the troff command only).

Defaults:

Point size = 10p

Vertical spacing = 12p

Options 1 and 2:

Number
                          New value.
+/-Number Increment to current value.
D Default.
C Current value.
P Previous value.
.VM [Top] [Bottom] Sets variable vertical margins.
.nP Starts double-line indent on paragraph.

The following macros are for alternating fonts and all take one to six options:

.IB Alternates italics (underlines for nroff) and bold.
.BI Alternates bold and italics.
.RI Alternates Roman and italics.
.IR Alternates italics (underlines for nroff) and Roman.
.RB Alternates Roman and bold.
.BR Alternates bold and Roman.

mm Registers

If an * (asterisk) follows a register name, that register can be set one of two ways: from the command line (see the example in the mm command) or before the formatter reads mm macro definitions. In the following list, the number shown in parentheses is the default value.

A * Handle preprinted forms.
Au Inhibit author information on first page (1).
C * Copy type (such as Original and Draft) (0).
Cl Contents level (2).
Cp Placement of figures, tables, equations, and exhibits (1).
D * Debug flag (0). If set to 1, the mm command continues even if it encounters a normally fatal error.
De Eject page after floating displays (0).
Df If set to 1, format register for floating displays (5).
Ds Static display pre- and post-space (1).
E * Control font of the Subject/Date/From fields (0): 0 = bold; 1 = Roman.
0 Bold (0)
1 Roman.

Ec Equation counter.
Ej Page-ejection flag for headings (0).
Eq Equation label placement (0).
Ex Exhibit counter.
Fg Figure counter.
Fs Vertical footnote separation (1).
H1...H7 Heading counters.
Hb Heading break level (after .H and .HU) (2).
Hc Heading centering level for .H and .HU (0).
Hi Heading temporary indent (after .H and .HU) (1).
Hs Heading space level (after .H and .HU) (2).
Ht Heading type:
0 Concatenated numbers (0)
1 Single numbers (0).

Hu Heading level for unnumbered heading (2).
Hy Hyphenation control:
0 No hyphenation (0)
1 Enable hyphenation.

L * Length of page (66v).
Le List of equations following table of contents (0):
0 Do not print
1 Print.

Lf List of figures following table of contents (0):
0 Do not print
1 Print.

Li List indent (5, troff command); (6, nroff command).
Ls List level down to which there is spacing between items (6).
Lt List of tables following table of contents (0):
0 Do not print
1 Print

Lx List of exhibits following table of contents (1):
0 Do not print
1 Print.

N * Numbering style (0).
Np Numbered paragraphs:
0 Unnumbered
1 Numbered (0).

O * Offset of page.
Oc Page numbering style for table of contents:
0 Lowercase Roman
1 Arabic (0).

Of Figure caption style (0).
P Page number; managed by the mm command (0). The register accepts a value of 0, or positive integers.
Pi Paragraph indent (5).
Ps Paragraph spacing (1).
Pt Paragraph type (0).
Pv PRIVATE header:
0 Do not print PRIVATE
1 On first page only

2 On all pages (0).
Rf Reference counter; used by .RS macro.
S * The troff command's default point size (10).
Si Display indent (5).
T * Type of the nroff command output device (0).
Tb Table counter.
U * Underlining style (the nroff command) for .H and .HU (0).
W * Width of page (line and title length).

mm Strings

Print special strings by using the following escape sequences:

\*x For strings with single-character names (x)
\*(xx For strings with two-character names (xx).

String Names

BU Bullet.
Ci Indent of heading levels in the table of contents.
DT Current date. The locale-specific date format specified by the locale setting for the LC_TIME category is used as the default setting. This corresponds to the %x format specifier of the strftime subroutine. Use the .ND macro to change the current date.
EM Em dash.
F Footnote numbering.
HF Heading level font string:
1 Roman
2 italics
3 Bold (2 2 2 2 2 2 2).

HP Point sizes of the various heading levels.
Le Title of the list of equations.
Lf Title of the list of figures.
Lt Title of the list of tables.
Lx Title of the list of exhibits.
RE SCCS SID of mm macros.
Rf Reference numberer.
Rp Title of the reference page.
Tm Trademark.
` Grave accent.
' Acute accent.
^ Circumflex.
~ Tilde.
: Lowercase umlaut.
; Uppercase umlaut.
, Cedilla.

Reserved Names

If you define your own strings, macros, and registers, use only names that consist of either a single lowercase letter, or a lowercase letter followed by any character other than a lowercase letter. The names c2 and nP are exceptions to this; they are reserved.

mptx Macro Package for the nroff and troff Commands

The mptx macro package provides a definition for the .xx macro that is used for formatting a permuted index produced by the ptx command. The mptx macro package does not provide any other formatting capabilities, such as headers and footers. Use the mptx macro package in conjunction with the mm macro package if such capabilities are required. In this case, call the -mptx option after the -mm call, as follows:

nroff -mm -mptx File... | Printer

ms Macro Package for the nroff and troff Commands

The ms macro package of nroff and troff command macro definitions provides a formatting facility for various styles of articles, theses, and books. In certain cases, the col command may be required to postprocess output.

The macro requests are defined in the ms Requests section. Many nroff and troff command requests can have unpredictable results in conjunction with this package. However, the first 4 requests in the following list can be used after initialization, and the last 2 requests can be used before initialization.

.bp Begins new page.
.br Breaks output line.
.ce [Number]
                          Centers the next specified number of lines.
.ls [Number]
                          Sets line spacing. Set the value of the Number variable to 1 (one) to single-space text; and to 2 to double-space text.
.na Turns off alignment of right margin.
.sp [Number]
                          Inserts the specified number of spacing lines.

Font and point-size changes with the\f and \s macros are also allowed. For example, \fIword\fR italicizes word. Output of the tbl, eqn, and refer command preprocessors for equations, tables, and references is acceptable as input.

Formatting distances can be controlled in ms macros by means of built-in number registers. For example, the following number register sets the line length to 6.5 inches:

.nr LL 6.5i

For more information on ms macro registers, see ms Registers.

ms Requests

Following are external ms macro requests:

.AB [X] Begins abstract. If X is no, do not label abstract.

Initial Value: -

Break: yes

.AE Ends abstract.

Break: yesInitial Value: -

Break: yes

.AIName Author's institution.

Initial Value: -

Break: yes

.AM Sets accent mark definitions.

Initial Value: -

Break: no

.AUName Sets author's name.

Initial Value: -

Break: yes

.B [X] Puts X in boldface. If no X, switches to boldface.

Initial Value: -

Break: no

.B1 Begins text to be enclosed in a box.

Initial Value: -

Break: yes

.B2 Ends boxed text and prints it.

Initial Value: -

Break: yes

.BT Prints bottom title at foot of page.

Initial Value: date

Break: no

.BX X Prints word X in a box.

Initial Value: -

Break: no

.CM Cuts mark between pages.

Initial Value: if t

Break: no

.CT Indicates chapter title; page number moved to CF (TM).
Initial Value: -

Break: yes

Reset: yes

.DA [X] Forces date X at bottom of page. If no X, date is today.

Initial Value: if n

Break: no

.DE Ends display (unfilled text) of any kind.

Initial Value: -

Break: yes

.DS X Y Begins display with keep. X=I, L, C, B; Y=indent.

Initial Value: I

Break: yes

.ID Y Indents display with no keep; Y=indent.

Initial Value: 8n, .5i

Break: yes

.LD Sets left display with no keep.

Initial Value: -

Break: yes

.CD Centers display with no keep.

Initial Value: -

Break: yes

.BD Block display; centers entire block.

Initial Value: -

Break: yes

.EF X Sets even page footer X (3 part as for troff command, .tl request).

Initial Value: -

Break: no

.EH X Sets even page header X (3 part as for troff command, .tl request).

Initial Value: -

Break: no

.EN Ends displayed equation produced by eqn command.

Initial Value: -

Break: yes

.EQ [X] [Y] Breaks out equation. X=L, I, C; Y is equation number.

Initial Value: -

Break: yes

.FE Ends footnote to be placed at bottom of page.

Initial Value: -

Break: no

.FP Numbers footnote paragraph; can be redefined.

Initial Value: -

Break: no

FS [X] Starts footnote; X is optional footnote label.

Initial Value: -

Break: no

.HD Sets optional page header below header margin.

Initial Value: undef

Break: no

.I [X] Italicizes X. If no X, equivalent to italics font .ft 2.

Initial Value: -

Break: no

.IP X Y Indents paragraph, with hanging tag X. Y specifies spaces to indent.

Initial Value: -

Break: yes

Reset: yes

.IX X Y Indexes words such as X and Y, up to five levels.

Initial Value: -

Break: yes

.KE Ends keep of any kind.

Initial Value: -

Break: no

.KF Begins floating keep; text fills remainder.

Initial Value: -

Break: no

.KS Begins keep; keeps unit together on a single page.

Initial Value: -

Break: yes

.LG Sets larger type size; increases point size by 2. Valid only for the troff command.

Initial Value: -

Break: no

.LP Begins left block paragraph.

Initial Value: -

Break: yes

Reset: yes

.MC X Sets multiple columns. X is column width.

Initial Value: -

Break: yes

Reset: yes

.ND [X] Indicates no date in page footer; X is date on cover.

Initial Value: if t

Break: no

.NH X Y Sets numbered header: X=level; X=0, resets; X=S, sets to Y.

Initial Value: -

Break: yes

Reset: yes

.NL Sets point size back to default. Valid for the troff command only.

Initial Value: 10p

Break: no

.OF X Sets odd page footer X (3 part as for me macro, .tlrequest).

Initial Value: -

Break: no

.OH X Sets odd page header X (3 part as for me macro, .tlrequest).

Initial Value: -

Break: no

.P1 Prints header on first page.

Initial Value: if TM

Break: no

.PP Indents first line of paragraph.

Initial Value: -

Break: yes

Reset: yes

.PT Prints page title at head of page.

Initial Value: %

Break: no

.PX X Prints index (table of contents); X=do not suppress title.

Initial Value: -

Break: yes

.QP Quotes paragraph (indented and shorter).

Initial Value: -

Break: yes

Reset: yes

.R [X] Returns to Roman font. Prints in Roman font. If X is missing, equivalent to font .ft1.

Initial Value: on

Break: no

.RE Retreats (end level of relative indentation). Used with the .RS request.

Initial Value: 5n

Break: yes

Reset: yes

.RP [X] Prints title page in released paper format; X=no, stops title on first page.

Initial Value: -

Break: no

.RS Right-shifts in one indentation level (start level of relative indentation). Used with the .IP request.

Initial Value: 5n

Break: yes

Reset: yes

.SG Sets signature line.
.SH Sets unnumbered section header (in boldface).

Initial Value: -

Break: yes

Reset: yes

.SM Sets smaller type size; decrease point size by 2. Valid for the troff command only.

Initial Value: -

Break: no

.TA Sets tabs to 8n, 16n, ... (nroff); 5n, 10n, ... (troff).

Initial Value: 8n, 5n

Break: no

.TC X Prints table of contents at end; X=do not suppress title.

Initial Value: -

Break: yes

.TE Ends table processed by tbl command.

Initial Value: -

Break: yes

.TH Ends multipage header of table. Must be used with the .TS H request.

Initial Value: -

Break: yes

.TL Sets title line (in boldface and 2 points larger).

Initial Value: -

Break: yes

.TM Sets UC Berkeley thesis mode.

Initial Value: off

Break: no

.TS X Begins table. If X is H, table prints header on all pages.

Initial Value: -

Break: yes

Reset: yes

.UL X Underlines X, even for the troff command.

Initial Value: -

Break: no

.UX X Sets UNIX; trademark message first time; X appended.

Initial Value: -

Break: no

.XA X Y Sets another index entry; X=page; X=no, for none.

Initial Value: -

Break: yes

.XE Ends index entry or series of .IX request entries.

Initial Value: -

Break: yes

.XP Exdents first line of paragraph; others indented.

Initial Value: -

Break: yes

Reset: yes

.XS X Y Begins index entry; X=page; X=no, for none; Y=indent.

Initial Value: -

Break: yes

.1C Begins one-column format, on a new page.

Initial Value: on

Break: yes

Reset: yes

.2C Begins two-column format.

Initial Value: -

Break: yes

Reset: yes

.]- Sets beginning of refer command reference.

Initial Value: -

Break: no

.[0 Sets end of unclassifiable type of reference.

Initial Value: -

Break: no

.[N For journal article, N=1 (one). For book, N=2. For book article, N=3.

Initial Value: -

Break: no

ms Registers

Following is a list of number registers and their default values:

PS Sets point size. Takes effect for paragraph. Default is 10.
VS Sets vertical spacing. Takes effect for paragraph. Default is 12.
LL Sets line length. Takes effect for paragraph. Default is 6i.
LT Sets title length. Takes effect on next page. Defaults to the LL register value.
FL Sets footnote length. Takes effect at next .FS request. Default is 5.5i.
PD Sets paragraph distance. Takes effect for paragraph. Default is 1v (in nroff), .3v (in troff).
DD Sets display distance. Takes effect for displays. Default is 1v (in nroff), .5v (in troff).
PI Sets paragraph indent. Takes effect for paragraph. Default is 5n.
QI Sets quotation indent. Takes effect at next .QP request. Default is 5n.
FI Sets footnote indent. Takes effect at next .FS request. Default is 2n.
PO Sets page offset. Takes effect on next page. Default is 0 (zero) (in nroff), 1i (in troff).
HM Sets header margin. Takes effect on next page. Default is 1i.
FM Sets footer margin. Takes effect on next page. Default is 1i.
FF Sets footnote format. Takes effect at next .FS request. Default is 0 (zero) (1, 2, 3 available).

When resetting number register values, make sure to specify the appropriate units. Set the line length to 7i instead of just 7, which would result in output with one character per line. Setting the FF register to 1 (one) suppresses footnote superscripting. Setting it to 2 also suppresses indentation of the first line. Setting the FF register to 3 produces a footnote paragraph like the .IP request.

Following is a list of string registers available in the ms macros. These string registers can be used anywhere in the text.

\*Q Open quotation marks (" in nroff; ` ` in troff)
\*U Close quotation marks (" in nroff; ' ' introff)
\*- Dash (-- in nroff; - in troff)
\*(MO Month of year
\*(DY Day (current date)
\** Automatically numbered footnote
\*' Acute accent (before letter)
\*` Grave accent (before letter)
\*^ Circumflex accent (before letter)
\*, Cedilla (before letter)
\*: Umlaut (before letter)
\*~ Tilde (before letter).

When using the extended accent mark definitions available with the .AM request, these strings should come after, rather than before, the letter to be accented.

Notes:

  1. It is important to note that floating keeps and regular keeps are diverted to the same space, so they cannot be mixed.
  2. The date format is restricted to U.S. English format.

mv Macro Package for the mvt and troff Commands

This package simplifies the typesetting of view graphs and projection slides in a variety of sizes. Although a few macros accomplish most of the formatting tasks needed in making transparencies, the entire facilities of the troff, tbl, pic, and grap commands are available for more difficult tasks.

The output can be previewed on most terminals, in particular the Tektronix 4014. For this device, specify the -rX1 flag (which is automatically specified by the mvt command when that command is called with the -D4014 flag). To preview output on other terminals, specify the -a flag.

The mv macros are summarized under the following headings:

Foil-Start Macros

For the following nine macros, the first character of the name (V or S) distinguishes between view graphs and slides, respectively, while the second character indicates whether the foil is square (S), small wide (w), small high (h), big wide (W), or big high (H). Slides are narrower than the corresponding view graphs. The ratio of the longer dimension to the shorter one is larger for slides than for view graphs. As a result, slide foils can be used for view graphs, but view graphs cannot be used for slide foils. On the other hand, view graphs can accommodate a bit more text.

.VS [FoilNumber] [FoilID] [Date]
                          Starts a square view graph. Foil size is to be 7 inches by 7 inches. The foil-start macro resets all variables (such as indent and point size) to initial default values, except for the values of the FoilID and Date variables inherited from a previous foil-start macro. The .VSmacro also calls the .A macro.
.Vw, .Vh,.VW, .VH, .Sw, .Sh, .SW, .SH
                          Same as the .VS macro, except that these macros start view graphs (V) or slides (S) that are small wide (w), small high (h), large wide (W), or large high (H).

The following macros are recommended:

  • .VS for square view graphs and slides
  • .Sw (and, if necessary, .Sh) for 35mm slides.
.Vw [FoilNumber] [FoilID] [Date]
                          Same as the .VS macro, except that foil size is 7 inches wide by 5 inches high.
.Vh [FoilNumber] [FoilID] [Date]
                          Same as the .VS macro, except that foil size is 5 inches wide by 7 inches high.
.VW [FoilNumber] [FoilID] [Date]
                          Same as the .VS macro, except that foil size is 7 inches wide by 5.4 inches high.
.VH [FoilNumber] [FoilID] [Date]
                          Same as the .VS macro, except that foil size is 7 inches wide by 9 inches high.
.Sw [FoilNumber] [FoilID] [Date]
                          Same as the .VS macro, except that foil size is 7 inches wide by 5 inches high.
.Sh [FoilNumber] [FoilID] [Date]
                          Same as the .VS macro, except that foil size is 5 inches wide by 7 inches high.
.SW [FoilNumber] [FoilID] [Date]
                          Same as the .VS macro, except that foil size is 7 inches wide by 5.4 inches high.
.SH [FoilNumber] [FoilID] [Date]
                          Same as the .VS macro, except that foil size is 7 inches wide by 9 inches high.

Note: The .VW and .SW foils are meant to be 9 inches wide by 7 inches high. However, because the typesetter paper is generally only 8 inches wide, .VW and .SW foils are printed 7 inches wide by 5.4 inches high and have to be enlarged by a factor of 9/7 before use as view graphs.

Level Macros

.A [X] Places text that follows at the first indentation level (left margin). The presence of the X variable suppresses the half-line spacing from the preceding text.
.B [Mark [Size]] Places text that follows at the second indentation level. Text is preceded by a specified mark (default is a large bullet). The Size variable is the increment or decrement to the point size of the mark with respect to the prevailing point size (default is 0). A value of 100 for the Size variable makes the point size of the mark equal to the default value of the Mark variable.
.C [Mark [Size]] Same as the .B macro, but for the third indentation level. The default value of the Mark variable is an em dash.
.D [Mark [Size]] Same as the .B macro, but for the fourth indentation level. The default value of the Mark variable is a small bullet.

Text-Control Macros

.I [+/-] [Indentation] [A[X]] Changes the current text indent (does not affect titles). The specified indentation is in inches unless dimensioned. The default is 0. If the Indentation variable is signed, it is an increment or decrement. The presence of the A variable calls the .A macro and passes the X variable (if any) to it.
.S [Size] [Length] Sets the point size and the line length. The value specified in the Size variable is the point size (default is previous). If the Size variable value is 100, the point size reverts to the initial default for the current foil-start macro. If the Size variable is signed, it is an increment or decrement (default is 18 for the .VS, .VH, and .SH macros, and 14 for the other foil-start macros). The Lengthvariable specifies the line length (in inches unless dimensioned; the default is 4.2 inches for the .Vh macro, 3.8 inches for the .Sh macro, 5 inches for the .SH macro, and 6 inches for the other foil-start macros).
.T String Prints the String variable value as a centered, enlarged title.
.U String1[String2] Underlines the String1 variable value and concatenates the String2 variable value (if any) to it. Using this operation is not recommended.

Default-Setting Macros

.DF [Number Name]... Sets font positions. It cannot be displayed within foil input text; that is, it must follow the input text for a foil, but it must precede the next foil-start macro. The specified number is the position of the font specified by the Name variable. The .DF macro takes up to four pairs of Number Name variables, such as 1 H. The first Name variable specifies the prevailing font. For example: .DF 1 H 2 I 3 B 4 S.
.DV [A] [B] [C] [D]
                          Alters the vertical spacing between indentation levels. The value specified by the A, B, C, or D variable is the spacing for the .A, .B, .C, or .D macro, respectively. All non-null parameters must be dimensioned. Null parameters leave the corresponding spacing unaffected. The default setting is: .DV .5v .5v .5v 0v.

The .S, .DF, .DV, and .U macros do not cause a break. The .I macro causes a break only if it is called with more than one variable. All the other macros cause a break.

The mv macro package also recognizes the following uppercase synonyms for the following corresponding lowercase troff command requests:

The Tm string produces the trademark symbol.

Environment Variable

LANG Determines the locale's equivalent of y for yes or no queries. The allowed affirmative responses are defined in the locale variable YESSTR. If LANG is not set, or if it is set to an empty string, the YESSTR from the default C locale is used.

nroff and troff Requests for the nroff and troff Commands

The following nroff and troffrequests are included in a specified working file or in standard input. The nroff and troff requests control the characteristics of the formatted output when the file or standard input is processed with the nroff or troff commands. The nroff and troffrequests are grouped by function, in the following sections:

For number variables written as +Number, the variable can be expressed as follows:

The notes at the end of this article are referenced in the specific requests where applicable.

Numerical Parameter Input

Both nroff and troff requests accept numerical input with the appended scale indicators shown in the following table, where S is the current type size in points, V is the current vertical line spacing in basic units, and C is a nominal character width in basic units.

Scale
Number of Basic Units
Indicator Meaning troff nroff
i Inch machine- 240
c Centimeter dependent 240x50/127
P Pica = 1/6 inch
240/6
m Em = S points
C
n En = Em/2
C (same as Em)
p Point = 1/72 inch
240/72
u Basic unit
1
v Vertical line space
V
*k Width single-width kana
C
**K Width double-width kanji
Two Cs
none Default

* If a non-kanji output device is selected, an en-width is used instead.

** If a non-kanji output device is selected, an em-width is used instead.

In the nroff request, both the em and the en are taken to be equal to the C, which is output-device dependent; frequent values are 1/10 and 1/12 inch. Actual character widths in the nroff request need not be all the same, and characters constructed with predefined strings such as - > are often extra wide.

Japanese Language Support: In the output from the nroff command, all double-width Japanese characters such as all kanji and some katakana characters have a fixed width equal to two Cs. All single-width Japanese characters such as some katakana characters have a fixed width equal to C.

The scaling for horizontally-oriented control characters, vertically oriented control characters, and the requests .nr, .if, and .ie are as follows:

Orientation Default Measure Request or Function
Horizontal Em (m) .ll, .in, .ta, .lt, .po, .mc,\h, \l
Vertical Vertical line space (v) .pl, .wh, .ch, .dt, .sp, .sv, .ne, .rt, \v, \x, \L
Register-oriented or Conditional Basic unit (u) .nr, .if, .ie
Miscellaneous Point (p) .ps, .vs, \H, \s

All other requests ignore scale indicators. When a number register containing an already appropriately scaled number is interpreted to provide numerical input, the unit scale indicator u may need to be appended to prevent an additional inappropriate default scaling. The Number may be specified in decimal-fraction form, but the parameter that is finally stored is rounded to an integer number of basic units.

Font and Character Size Control

.bd Font Number Makes the characters in the specified font artificially bold by overstriking them the specified number of times when using nroff, or by printing each character twice separated by Number -1 basic units when using troff. If the Number variable is not specified, the bold mode is turned off. The Font value must be an ASCII font name or font position. For the nroff command, the default setting of the .bd request is 3 3, specifying that characters on the font mounted at position 3 (normally bold) are to be overstruck 3 times (that is, printed in place a total of 4 times).

The font name itself can be substituted for the font position; for example, .bd I 3. The Number variable is functionally identical to the -u flag of the nroff command. (The bold mode must be in effect when the characters are physically printed.) This request can affect the contents of the .b general-number register.

The bold mode still must be in effect, or restarted at the time of physical output. You cannot turn off the bold mode in the nroff command if it is being controlled locally by the printing device as with, for example, a DASI 300.

Initial Value: Off

If No Value Specified: -

.bd S Font Number Makes the characters in the special font bold whenever the specified font is the current font. The mode must be in effect when the characters are physically printed. The Font value must be an ASCII font name or font position. The mode still must be in effect, or again so, at the time of physical output.

Initial Value: Off

If No Value Specified: -

.cs Font Number M Sets constant character space (width) mode to the Font variable value (if mounted). The width of every character is taken to be the value specified in the Number variable divided by 36 ems. If the M variable is not specified, the em width is that of the character's point size; if the M variable is given, the width is the value specified by the M variable minus points. All affected characters are centered in this space, including those with an actual width larger than this space. Special font characters occurring while the specified font is the current font are also so treated. The Font value must be an ASCII font name or font position. If the Number variable is absent, the mode is turned off. The mode must be in effect when the characters are physically printed. This request is ignored by the nroff command. Relevant values are part of the current environment. The mode still must be in effect, or again so, at the time of physical output.

Initial Value: Off

If No Value Specified: -

.fp Font NumberFile ]
                          Specifies the font position. This is a statement that the specified font is mounted on the position specified by the Number variable. The Font variable must be a one- or two-character ASCII font name.

Attention: It is an irrecoverable error if the Font variable is not specified.

The .fp request accepts a third optional variable, the File variable, which is the actual path name of the file containing the specified font. The File variable value can be any legal file name and can contain extended characters.

Japanese Language Support: The Filevalue can be any legal file name. Values are typesetter- or printer-dependent.

Initial Value: -

If No Value Specified: Ignored

.ft Font Changes the font style to the specified font, or if Font value is numeric, to the font mounted on that position. Alternatively, embed \fFont command. The font name P is reserved to mean the previous font. The Font variable value must be an ASCII font name or font position.

If using a font name consisting of two characters, use the alternative form of .ft, \f. Relevant values are part of the current environment. Values are typesetter or printer-dependent.

Initial Value: Roman

If No Value Specified: Previous

.ps [+/-][Number] Sets the point size to that specified by the +/-Number variable. Although any positive size value can be requested, an invalid size results in the nearest valid size being used. Size 0 refers to the previous size. Alternatively, \sNumber or \s+/-Number; if the Number value is two digits, use \s(Number or \s+/-(Number. For compatibility with older versions of the troff command, the form is valid for two-digit values of 10, 11, 12, 14, 16, 18, 20, 22, 24, 28, and 36.

This request is ignored by the nroff command. Relevant values are part of the current environment.

Initial Value: 10 point

If No Value Specified: Previous

.ss Number Sets space-character size to the specified number divided by 36 ems. This size is the minimum word spacing in adjusted text. This request is ignored by the nroff command. Relevant values are part of the current environment.

Initial Value: 12/36 em

If No Value Specified: Ignored

Page Control

.bp [+/-][Number] Specifies a break page. The current page is ejected and a new page is begun. If the +/-Number variable is specified, its value becomes the new page number. Also refer to the .ns request.

This request normally causes a line break similar to the .br request. Calling this request with the control character " ' " (instead of ".") suppresses that break function.

Initial Value: Number=1

If No Value Specified: -

.mk Register Marks the current vertical place (or a place in the current diversion) in an internal register (associated with the current diversion level) or in the specified register, if given. The Register variable is the ASCII name of a number register. Mode or relevant values are associated with the current diversion level. For more information, refer to the .rt request.

Initial Value: None

If No Value Specified: Internal

.ne Number D Indicates a need for the specified vertical space. If the page space needed (Number) is greater than the distance to the next trap (D), a forward vertical space of size D occurs, which springs the trap. If there are no remaining traps on the page, the size specified by the D variable is the distance to the bottom of the page. If the distance to the next trap (D) is less than one vertical line space (v), another line could still be output before the trap is sprung. In a diversion, the size specified by D is the distance to the diversion trap, if any, or is very large.

The value of D is also normally contained in the .t Number register. Mode or relevant values are associated with the current diversion level.

Initial Value: Number=1V

If No Value Specified: -

.pl [+/-][Number] Sets page length to the +/-Number variable value. The internal limitation is approximately 136 inches in the nroff command, but varies with the device type in the troff command. A good working maximum for the troff command is 75 inches. The current page length is available in the .p register.

Initial Value: 11 inches

If No Value Specified: 11 inches

.pn [+/-][Number] Specifies that the next page (when it occurs) has the page number specified by the +/-Number variable. A .pn request must occur either before text is initially printed or before a break occurs to affect the page number of the first page. The current page number is in the % register.

Initial Value: Number=1

If No Value Specified: Ignored

.po [+/-][Number] Specifies a page offset. The current left margin is set to the +/-Numbervariable value. The initial troff command value provides 1 inch of left margin. For more information, refer to "Line Length and Indenting". The current page offset is available in the .o register.

Initial Value: 0 for the nroff command; 1 for the troff command.

If No Value Specified: Previous

.rt [+/-][Number] Returns upward only to a marked vertical place in the current diversion. If the +/-Number variable value (relative to the current place) is given, the place is the value specified by the +/-Number variable from the top of the page or diversion. If the Number variable is not specified, the place is marked by a previous .mk request. Mode or relevant values are associated with the current diversion level.

The .sp request can be used in all cases, instead of the .rt request, by spacing to the absolute place stored in an explicit register as, for example, when using the sequence .mk Register . . . .sp|\nRu.

Initial Value: None

If No Value Specified: Internal

Text Filling, Adjusting, and Centering

.ad Indicator Begins line adjustment. If the fill mode is not on, adjustment is deferred until the fill mode is back on. If the Indicator variable is present, the adjustment type is changed as shown in the following list:
Indicator Adjustment Type
l Adjust left margin only.
r Adjust right margin only.
c Center.
b or n Adjust both margins.
blank Unchanged.

The adjustment indicator can also be a number obtained from the .j register.

Japanese Language Support:

Indicator Adjustment Type
k Turn on kinsoku shori processing (turned off with .ad n, .ad b, or .ad l).

Normally, lines of Japanese text are filled to the margins without regard for the characters beginning or ending lines. When kinsoku shori processing is enabled, lines are prevented from ending with an open bracket character or from beginning with a close bracket or punctuation character. If a line ends with an open bracket, the line is left short and the bracket begins the next line. If a line begins with a close bracket or punctuation character, the preceding line is extended and the character ends the preceding line. Requesting Japanese kinsoku shori processing on an output device that does not support kanji characters has no effect.

Relevant values are part of the current environment.

Initial Value: Adjust, both

If No Value Specified: Adjust

.br Specifies a break. The filling of the line currently being collected is stopped and the line is output without adjustment. Text lines beginning with space characters and empty text lines (blank lines) also cause a break.

Initial Value: -

If No Value Specified: -

.ce [Number] Centers the next specified number of input text lines within the current line length, minus indent. If the Number variable equals 0, any residual count is cleared. A break occurs after each of the Number variable input lines. If the input line is too long, it is left adjusted. Relevant values are part of the current environment. This request normally causes a line break similar to the .br request. Calling this request with the control character " " (instead of ".") suppresses that break function.

Initial Value: Off

If No Value Specified: Number=1

.fi Fills subsequent output lines. The .u register has a value of 1 (one) in fill mode and a value of 0 (zero) in no-fill mode. Relevant values are part of the current environment. This request normally causes a line break similar to the .br request. Calling this request with the control character " " (instead of ".") suppresses that break function.

Initial Value: Fill

If No Value Specified: -

.na Specifies no-adjust mode. Adjustment is turned off; the right margin is ragged. The adjustment type for the .ad request is not changed. Output-line filling still occurs if the fill mode is on. Relevant values are part of the current environment.

Initial Value: None

If No Value Specified: -

.nf Specifies no-fill mode. Subsequent output lines are neither filled nor adjusted. Input-text lines are copied directly to output lines without regard for the current line length. Relevant values are part of the current environment. This request normally causes a line break similar to the .br request. Calling this request with the control character " ' " (instead of ".") suppresses that break function.

Initial Value: Fill

If No Value Specified: -

Vertical Spacing

Blank text line Causes a break and outputs a blank line exactly like an .sp 1 request.
.ls Number Sets line spacing to the value specified by the +/-Number variable. The Number-1 Vs (blank lines) variable values are appended to each output-text line. Appended blank lines are omitted if the text or previous appended blank line reached a trap position. Relevant values are part of the current environment.

Initial Value: 1

If No Value Specified: Previous

.ns Turns on no-space mode. When on, the no-space mode inhibits .sp and .bp requests without a next page number. The no-space mode is turned off when a line of output occurs or with the .rs request. This request normally causes a break.

Initial Value: Space

If No Value Specified: -

.os Outputs saved vertical space. The no-space mode has no effect. Used to output a block of vertical space requested by the previous .sv request.

Initial Value: -

If No Value Specified: -

.rs Restores spacing. The no-space mode is turned off. This request normally causes a break.

Initial Value: None

If No Value Specified: -

.sp Number Spaces vertically in either direction. If the Number variable value is negative, the motion is backward (upward) and is limited to the distance to the top of the page. Forward (downward) motion is truncated to the distance to the nearest trap. If the no-space mode is on, no spacing occurs. Refer to the .ns and .rs requests. This request normally causes a line break similar to the .br request. Calling this request with the control character "'" (instead of ".") suppresses that break function.

Initial Value: -

If No Value Specified: 1V

.sv Number Saves a contiguous vertical block of the specified size. If the distance to the next trap is greater than the Number variable value, the specified vertical space is output. The no-space mode has no effect. If this distance is less than the specified vertical space, no vertical space is immediately output, but is remembered for later output (refer to the .os request). Subsequent .sv requests overwrite any still-remembered Number variable value.

Initial Value: -

If No Value Specified: Number=1V

.vs Number Sets vertical base-line spacing size V to the Number variable. Transient extra vertical space can be specified by \x N. Relevant values are part of the current environment.

Initial Value: The Number variable equals 1/16 inch for the nroff command and 12 points for the troff command.

If No Value Specified: Previous

Line Length and Indenting

.in [+/-]Number Sets indent to the +/-Number variable value. The indent is prepended to each output line. Relevant values are part of the current environment. This request normally causes a line break similar to the .br request. Calling this request with the control character " ' " (instead of ".") suppresses that break function.

Initial Value: Number=0

If No Value Specified: Previous

.ll [+/-]Number Sets line length to the +/-Number variable value. In the troff command, the maximum line length plus page offset is device-dependent. Relevant values are part of the current environment.

Initial Value: 6.5 inches

If No Value Specified: Previous

.ti [+/-]Number Specifies a temporary indent. The next output text line is indented a distance of the value specified by the +/-Number variable with respect to the current indent. A negative value for the Number variable can result in spacing backward over the current indent, so that the resulting total indent can be a value of 0 (zero) (equal to current page offset), but cannot be less than the current page offset. The temporary indent applies only for the one output line following the request; the value of the current indent, which is stored in the .i register, is not changed.

Relevant values are part of the current environment. This request normally causes a line break similar to the .br request. Calling this request with the control character " ' " (instead of ".") suppresses that break function.

Initial Value: -

If No Value Specified: Ignored

Macros, Strings, Diversions, and Position Traps

.am Macro1 [Macro2] Appends to Macro 1; appends version of the .de request. Both the Macro1 and Macro2 variables must be either one or two ASCII characters. Macro2 is a termination sequence to end the diversion.

Initial Value: -

If No Value Specified: .Macro2=..

.as StringName String Appends the specified string to the value specified by the StringName variable; appended version of the .ds request. The StringName variable value must be one or two ASCII characters.

Initial Value: -

If No Value Specified: Ignored

.ch Macro [Number] Changes the trap position for the specified macro to the value specified by the Number variable. In the absence of the Number variable, the trap, if any, is removed. The Macro variable value must be one or two ASCII characters.

Initial Value: -

If No Value Specified: -

.da [Macro] Diverts, appending to the specified macro and appends version of the .di request. The Macro variable must be one or two ASCII characters. Mode or relevant values are associated with the current diversion level.

Initial Value: -

If No Value Specified: End current diversion

.de Macro1 [Macro2] Defines or redefines the value specified by the Macro1 variable. The contents of the macro begins on the next input line. Input lines are copied in copy mode until the definition is stopped by a line beginning with .Macro2. In the absence of the Macro2 variable, the definition is stopped by a line beginning with "..". A macro can contain .de requests, provided the stopping macros differ or the contained definition terminator is concealed. The ".." can be concealed as "\\ .", which copies as "\..." and is reread as "..". The Macro1 and Macro2variables must each be one or two ASCII characters.

Initial Value: -

If No Value Specified: .Macro2=..

.di [Macro] Diverts output to the specified macro. Normal text processing occurs during diversion except that page offsetting is not performed. The diversion ends when the .di or .da request is encountered without a variable. Extraneous requests of this type should not be displayed when nested diversions are being used. The Macro variable must be one or two ASCII characters. Mode or relevant values are associated with the current diversion level.

Initial Value: -

If No Value Specified: End

.ds StringName String Defines a string specified by the StringName variable to contain the value specified by the String variable. Any initial double-quote in String is stripped off to permit initial blanks. The StringName variable must be one or two ASCII characters.
.ds StringName ^A<SetNumber>  <MessageNumber> [^A"<DefaultMessage>"] [^A<Argument>^B<Argument>^B<Argument>...]
                          Provides an alternate .ds syntax that allows the use of a message catalog for language-independent string definitions.

Based on the message SetNumber and the MessageNumber within the locale-specific catalog, the message catalog is read in copy mode and the corresponding message is placed into the StringName variable. The initial sequence specifying the message set and message number can be omitted for backward compatibility. The ASCII code Control-A (^A) delimits message identification, default message and optional argument list. The ASCII code Control-B (^B) delimits an individual optional argument list.

In the following example,

.ds {c ^A2 41^A"ERROR: (%1$s) input line \
%2$s" ^A\n(.F^B\n(.c

2 is the message set number.

41 is the message number.

text within quotes (". . .") is the default message.

\n(.F is the name of the current input file.

\n(.c is the number of lines read from the input file.

If you assume the troff command runs with these conditions:

  • The message at set 2 and number 41 matches the default message
  • The current input file is paper.doc
  • The .ds directive is on line 124 in the input file.

then the string {c would be defined as:

ERROR: (paper.doc)input line 123

Other examples are:

.ds {c ^A2 41 
/* Without optional default message */
 
.ds {c ^A2 41^A"ERROR: (%1$s) input file \
%2$s" /* Without optional arguments */

If both the set number and the message number are set to zero, then the current date is returned in the current local's format. A user defined date format string can be defined in the default message field. The user defined format string must conform to the conversion specifications outlined by the strftime function in Technical Reference: Base Operating System and Extensions.

In the following examples:

.ds DT^A0 0

If the current date were July 10, 1991, in an English U.S. locale, DT would be defined as 7/10/91.

.ds DT^A0 0^A"Today is %B %d, %Y"

If the current date were July 10, 1991, in an English U.S. locale, DT would be defined as Today is July 10, 1991.

The second syntax method is not intended for general use. It is used in the nroff and troff macro files supplied with the system to facilitate internationalization of internally generated messages.

Initial Value: -

If No Value Specified: Ignored

.dt Number Macro Installs a diversion trap at the position specified by the Number variable in the current diversion to start the specified macro. Another .dt request redefines the diversion trap. If no variables are given, the diversion trap is removed. The Macro variable must be one or two ASCII characters. Mode or relevant values are associated with the current diversion level.

Initial Value: -

If No Value Specified: Off

.em Macro Calls the specified macro when all input has ended. The effect is the same as if the contents of the specified macro had been at the end of the last file processed. The specified macro must be one or two ASCII characters.

Initial Value: None

If No Value Specified: None

.it Number Macro Sets an input-line-count trap to call the specified macro after the number of lines of text input specified by the Number variable have been read (control or request lines are not counted). The text can be inline text or text provided by macros called explicitly (through inline calls) or implicitly (through traps). The Macro variable must be one or two ASCII characters. Relevant values are part of the current environment.

Initial Value: -

If No Value Specified: Off

.rm Name Removes the specified request, macro, or string. The Name variable value is removed from the name list and any related storage space is freed. Subsequent references have no effect. The Name variable must be one or two ASCII characters.

Initial Value: -

If No Value Specified: Ignored

.rn Name1 Name2 Renames the request, macro, or string value specified by the Name1variable to the value specified by the Name2 variable. The Name1and Name2 variable values must each be one or two ASCII characters.

Initial Value: Ignored

If No Value Specified: -

.wh Number Macro Installs a trap to call the specified macro at the page position specified by the Number variable. A negative Number variable value is interpreted with respect to the page bottom. Any macro previously planted at the page position specified by the Number variable is replaced by the Macro variable value. A Number variable value of 0 refers to the top of a page. In the absence of the Macro variable, the first trap found at the page position specified by the Number variable, if any, is removed. The Macro variable must be one or two ASCII characters.

Initial Value: -

If No Value Specified: -

Number Registers

.af Register Indicator Assigns the format as specified by the Indicator variable to the specified register. The Register variable must be one or two ASCII characters. The available format Indicator variable values are as follows:
Indicator Numbering Sequence
1 0,1,2,3,4,5, . . .
001 000,001,002,003,004,005, . . .
i 0,i,ii,iii,iv,v, . . .
I 0,I,II,III,IV,V, . . .
a 0,a,b,c, . . . ,z,aa,ab, . . . ,zz,aaa, . . .
A 0,A,B,C, . . . ,Z,AA,AB, . . . ,ZZ,AAA, . . .

An Arabic format indicator having N digits (for example, 000000001) indicates a field width of N digits. The read-only registers and the width function are always Arabic.

Japanese Language Support: The following value specifies the character width for formatting Japanese numeric output in kanji:

k The number is formatted as a kanji string. If this is requested when a non-kanji codeset is specified, a warning message is printed and the 1 format is used.

Initial Value: Arabic

If No Value Specified: -

.nr Register +/-Number1 Number2
                          Assigns the specified register the value specified by the +/-Number variable with respect to the previous value, if any. The increment for auto-incrementing is set to the Number2 variable value. The Register variable must be one or two ASCII characters.

Initial Value: -

If No Value Specified: -

.rr Register Removes the specified register. If many registers are being created dynamically, it can become necessary to remove registers that are not needed to recapture internal storage space for new registers. The Register variable must be one or two ASCII characters.

Initial Value: -

If No Value Specified: -

Tabs, Leaders, and Fields

.fc Delimiter Indicator Sets the field delimiter to the specified delimiter; the padding indicator is set to the space character or to the specified indicator. In the absence of variables, the field mechanism is turned off. The Delimiter variable value and the Indicator variable value must be ASCII characters.

Initial Value: Off

If No Value Specified: Off

.lc Character Sets the leader repetition character to the specified character, or removes specifying motion. The Character variable value must be an ASCII character. Relevant values are part of the current environment.

Initial Value: .

If No Value Specified: None

.ta Stop [Type]... Sets tab stops. Default tab stops are set at every eight characters for the nroff command and every half inch for the troff command. Multiple StopType pairs can be specified by separating them with spaces; a value preceded by + (plus sign) is treated as an increment to the previous stop value.

The specified type determines how the text is adjusted at the tab stops. The Type variable values are as follows:

Type Adjustment
R Right-adjusting
C Centering
blank Left-adjusting

Relevant values are part of the current environment.

Initial Value: 8 ens for the nroff command and 0.5 inch for the troff command

If No Value Specified: None

.tc Character Sets the tab repetition character to the specified character, or removes specifying motion. The Character variable value must be an ASCII character. Relevant values are part of the current environment.

Initial Value: None

If No Value Specified: None

Input/Output Conventions and Character Translations

.cc Character Sets the basic control character to the specified character, or resets to ".". The Character variable value must be an ASCII character. Relevant values are part of the current environment.

Initial Value: .

If No Value Specified: .

.cu [Number] A variant of the .ul request that causes every character to be underlined and causes no line breaks to occur in the affected input lines. That is, each output space following a .cu request is similar to an unpaddable space. The .cu request is identical to the .ulrequest in the troff command. Relevant values are part of the current environment.

Initial Value: Off

If No Value Specified: Number=1

.c2 Character Sets the no-break control character to the specified character or resets to " ". The Character variable value must be an ASCII character. Relevant values are part of the current environment.

Initial Value: '

If No Value Specified: '

.ec Character Sets the escape character to \ (backslash) or to the value specified by the Character variable, if given. The Character variable value must be an ASCII character.

Initial Value: \

If No Value Specified: \

.eo Turns off the escape mechanism.

Initial Value: On

If No Value Specified: -

.lg [Number] Turns on the ligature mode if the Number variable value is absent or nonzero; turns off ligature mode if the Number variable value is 0. If the Number variable value is 2, only the two-character ligatures are automatically called. The ligature mode is inhibited for request, macro, string, register, or file names, and in the copy mode. This request has no effect in the nroff command.

Initial Value: On, for the troff command

If No Value Specified: On

.tr Character1Character2Character3Character4
                          Translates, among other things, the character value specified by the Character1 variable into the Character2 variable value, the character value specified by the Character3 variable into the Character4variable value. If an odd number of characters is given, the last one is mapped into the space character. To be consistent, a particular translation must stay in effect from input to output time. All specified characters must be ASCII characters. To reset the .tr request, follow the request with previous variables given in duplicate.

For example, the following .tr request:

.tr aAbBc<C,> 

can be reset by entering:

.tr aabbcc

It must stay in effect until logical output.

Initial Value: None

If No Value Specified: -

.ul [Number] Underlines in the nroff command (or italicizes in the troffcommand) the number of input-text lines specified by the Numbervariable. Actually switches to underline font, saving the current font for later restoration. Other font changes within the span of a .ul request take effect, but the restoration undoes the last change. Output generated by the .tl request is affected by the font change, but does not decrement the Number variable value. For more information, refer to the section "Three-Part Titles". If the specified number is greater than 1, there is the risk that a trap-called macro can provide text lines within the span; environment switching can prevent this.

Relevant values are part of the current environment.

Initial Value: Off

If No Value Specified: Number=1

.uf Font Underlines the font set to the value specified by the Font variable. In the nroff command, the Font variable cannot be on position 1 (initially Times Roman). The Font variable value must be an ASCII font name.

Initial Value: Italic

If No Value Specified: Italic

Hyphenation

.hc Character Sets the hyphenation indicator character to the value specified by the Character variable or to the default. The indicator is not displayed in the output. The Character variable value must be an ASCII character. Relevant values are part of the current environment.

Initial Value: \%

If No Value Specified: \%

.hw Word1... Specifies hyphenation points in words with embedded minus signs. Versions of a word with a terminal s are implied; that is, dig-it implies dig-its. This list is examined initially and after each suffix stripping. The space available is 1024 characters, or about 50 to 100 words.

Initial Value:

If No Value Specified: Ignored

.hy Number Turns on automatic hyphenation if the specified number is equal to or greater than 1; turns it off if the specified number is equal to 0 (equal to the .nh request). If the specified number is 2, the last lines (ones that cause a trap) are not hyphenated. If the specified number is 4 or 8, the last or first two characters, respectively, of a word are not split off. These values are additive; for example, a value of 14 calls all three restrictions (number equal to 2, number equal to 4, and number equal to 8).

Relevant values are part of the current environment.

Initial Value: No hyphenation

If No Value Specified: Hyphenate

.nh Turns off automatic hyphenation. Relevant values are part of the current environment.

Initial Value: No hyphenation

If No Value Specified: -

Three-Part Titles

.lt [+/-][Number] Sets the length of title value specified by the +/-Number variable. The line length and the title length are independent. Indents do not apply to titles, although page offsets do. Relevant values are part of the current environment.

Initial Value: 6.5 inches

If No Value Specified: Previous

.pc Character Sets the page number character to the specified character or removes it. The page-number register remains %. The Character variable value must be an ASCII character.

Initial Value: %

If No Value Specified: Off

.tl 'Left'Center'Right' The strings represented by the Left, Center, and Rightvariables, respectively, are left-adjusted, centered, and right-adjusted in the current title length. Any of the strings can be empty, and overlapping is permitted. If the page-number character (initially %) is found within any of the fields, it is replaced by the current page number having the format assigned to the % register. Any ASCII character that is not displayed in the strings can be used as the string delimiter.

Initial Value: -

If No Value Specified: -

Output-Line Numbering

.nm [+/-][Number] [M] [S] [I]
                          Turns on line-number mode. If the M variable is specified, only those line numbers that are multiples of the M variable value are to be printed. Every line number is printed if the M variable is absent (default is M=1). When line-number mode is in effect, a three-digit Arabic number plus a digit space are prepended to output text lines. The text lines are thus offset by four digit spaces, but otherwise retain their line length. If the S variable is given, it specifies the number of digit spaces to be displayed between the line number and the text (default is S=1). If the I variable is given, it specifies the number of digit spaces to indent before the line number (default is I=0).

Relevant values are part of the current environment.

Initial Value: -

If No Value Specified: Off

.nn Number Suspends line numbering. The specified number of lines are not numbered. Relevant values are part of the current environment.

Initial Value: -

If No Value Specified: Number=1

Conditional Acceptance of Input

The Condition variable specifies one of the following one-character names:

o If the current page number is odd.
e If the current page number is even.
t If the formatter is the troff command.
n If the formatter is the nroff command.
.if Condition Anything If the value specified by the Condition variable is true, accepts the value specified by the Anything variable as input; in multiline case, uses \{Anything\}.
.if !Condition Anything If the value specified by the Condition variable is false, accepts the value specified by the Anything variable as input.
.if Number Anything If the expression states that the Number variable value is greater than 0, accept the value specified by the Anything variable as input.
.if !Number Anything If the expression states that the Number variable value is less than or equal to 0, accepts the value specified by the Anything variable as input.
.if 'String1'String2' Anything If the String1 variable value is identical to the String2 variable value, accepts the value specified by the Anything variable as input. Any nonblank ASCII character not in the String1 and String2 variables can be used as the delimiter.
.if !'String1'String2' Anything If the String1 variable value is not identical to the String2variable value, accepts the value specified by the Anything variable as input. Any nonblank ASCII character not in the String1 and String2 variables can be used as the delimiter.
.el Anything Specifies the else portion of an if/else conditional.
.ie Condition Anything Specifies the if portion of an if/else conditional dependent on the value of the Condition variable. Can be used with any of the preceding forms of the .if request.

Environment Switching

.ev Environment Switches to the specified environment. The value specified by the Environmentvariable must be 0, 1, or 2. Switching is done in push-down fashion so that restoring a previous environment must be performed with the .evrequest rather than with a specific reference.

Initial Value: Environment=0

If No Value Specified: Previous

Insertions from Standard Input

.ex Exits from the nroff command or troff command. Text processing is stopped exactly as if all input had ended.

Initial Value: -

If No Value Specified: -

.rd Prompt Reads insertion from standard input until two newline characters in a row are found. If the standard input is the user's keyboard, the specified prompt (or the ASCII BEL character) is written onto the user's terminal. The .rd request behaves like a macro, and additional variables can be placed after the Prompt variable.

Initial Value: -

If No Value Specified: Prompt=the ASCII BEL character

Input and Output File Switching

.cf File Copies the contents of the specified file, uninterrupted, into the troff command output file at this point. Problems occur unless the motions in the file restore the current horizontal and vertical position.

Initial Value: -

If No Value Specified: -

.lf Number File Corrects the troff command interpretation of the current line number (as specified by the Number variable) and the current file (as specified by the File variable) for use in error messages.

Initial Value: -

If No Value Specified: -

.nx File Uses the specified file as the input file. The current file is considered ended and the input is immediately switched to the specified file.

Initial Value: -

If No Value Specified: End of file

.pi Program Pipes output to the specified program. This request must occur before any printing occurs. No variables are transmitted to the specified program.

Initial Value: -

If No Value Specified: -

.so File Switches the source file. The top input (file-reading) level is switched to the specified file. When this file ends, input is again taken from the original file. The .so request can be nested.

Once a .so request is encountered, the processing of the specified file is immediate. Processing of the original file (for example, a macro that is still active) is suspended.

A file should be preprocessed, if necessary, before being called by the .so request. The eqn, tbl, pic, and grap commands do not reach through a .so request to process an object file.

Initial Value: -

If No Value Specified: -

Miscellaneous

.ab Text Prints the value specified by the Text variable to the diagnostic output (normally the terminal) and ends without further processing. If text is missing, the message User Abort is printed and the output buffer is flushed. This request is used in interactive debugging to force output.
.ab ^A<SetNumber> <MessageNumber> [^A"<Default>"] [^A<Argument>^B<Argument> ^B<Argument>...]
                          Provides alternate syntax to allow use of a message catalog for language-independent abort messages. Prints the appropriate message specified by the parameter on the diagnostic output (normally the terminal) and ends without further processing. If there are no parameters, the message catalog equivalent to the following:
troff: User Abort, line no. file filename

is output. The output buffer is flushed. This request is used in interactive debugging to force output.

Based on the message SetNumber and the MessageNumber variables within the locale-specific catalog, the message catalog is read in copy mode and the corresponding message is written to the user's terminal. The initial sequence specifying the message set and message number can be omitted for backward compatibility. The ASCII code Control-A (^A) delimits message identification, default message, and optional argument list. The ASCII code Control-B (^B) delimits individual optional argument list.

In the following example:

.ab ^A2 42^A"Processing has been terminated \
 at line %1$s."^A\n(c.

2 is the message set number.

42 is the message number.

Text within quotes "..." is the default message.

\n(c. is the number of lines read from the input file.

If you assume the troff command runs with the following conditions:

  • The message at set 2 and number 42matches the default message.
  • The .ab directive is on line 124in the input file.

then the following would be displayed on the user's terminal:

Processing has been terminated at line 123.

Initial Value: -

If No Value Specified: User cancel

.Dt Parameter Defines the format for returning the date within the nroff or troff request. By default, without the optional Parameter, the locale-specific date format specified by the current locale setting for the LC_TIME category is used. This corresponds to the "%x" format specifier of strftime. Parameter is a format string identical to the format string used with the strftime function in Technical Reference: Base Operating System and Extensions. Reference this function for a complete list of the format specifiers.

For example,

.Dt "%A, %B %d, %Y (%T)"

provides the following output for an English-speaking locale:

Thursday, January 31, 1991 (10:40:00)

The %A format is replaced by the locale-specific weekday name. The %B format is replaced by the locale-specific month name. The %d format is replaced by the day of the month in a two-digit format. The %Y format is replaced by the year with the century as a decimal number. The %T format is replaced by the time in hours (24-hour clock), minutes, and seconds in decimal numbers. This format provides for leap seconds and double leap seconds.

.fl Flushes output buffer. This request normally causes a line break similar to the .br request. Calling this request with the control character " ' " (instead of ".") suppresses that break function.

Initial Value: -

If No Value Specified: -

.ig Macro Ignores input lines. The .ig request works exactly like the .de request, except that the input is discarded. For more information, refer to "Macros, Strings, Diversions, and Position Traps". The input is read in copy mode, and any auto-incremented registers are affected. The Macro variable must be one or two ASCII characters.

Initial Value: -

If No Value Specified: .Macro=..

.mc [Character] [N] Uses the specified character as the margin character to display the specified distance (N) to the right of the margin after each non-empty text line (except those produced by the .tl request). If the output line is too long (as can happen in no-fill mode), the character is appended to the line. If the N variable is not given, the previous N variable is used. The first N variable is 0.2 inches in the nroff command and 1 em in the troff command.

Relevant values are part of the current environment.

Initial Value: .2 inches in nroff; 1 em in troff

If No Value Specified: Off

.pm [Character] Prints macros. The names and sizes of all of the defined macros and strings are printed on the user's terminal. If any ASCII alphanumeric character is given as a variable, only the total of the sizes is printed. The size is given in blocks of 128 characters.

Initial Value: -

If No Value Specified: All

.sy Command [Flags] The specified command is run but its output is not captured at this point. The standard input for the specified command is closed. Output must be explicitly saved in an output file for later processing. Often the .sy directive is followed by a subsequent .so directive to include the results of the previous command.

For example:

.sy date > /tmp/today
Today is
.so /tmp/today

Initial Value: -

If No Value Specified: -

.tm String The specified string is written to the user's terminal.
.tm ^A<SetNumber> <MessageNumber> [^A"<DefaultMessage>"] [^A<Argument> ^B <Argument>^B<Argument>...]
                          Based on the message set number and the message number within the locale-specific catalog, the message catalog is read in copy mode and the corresponding message is written to the user's terminal. The initial sequence specifying the message set and message number can be omitted for backward compatibility. The ASCII code Control-A ^A delimits message identification, default message, and optional argument list. The ASCII code Control-B ^B delimits individual optional argument list.

In the following example:

.tm ^A2 23^A"The typesetter is %1$s.On line 
%2$s."^A\*(.T^B\n(c.

2 is the message set number.

23 is the message number.

Text within quotes "..." is the default message.

\*(.T is the first argument in troff for value of -T.

\n(c. is the number of lines read from the input file.

If you assume the troff command runs with the following conditions:

  • The message at set 2 and number 23 matches the default message.
  • The command line has troff using the -T option with device PSC.
  • The .tm directive is on line 539 in the input file.

Then the following would be displayed on the user's terminal:

The typesetter is psc. On line 538.

The locale-specific message catalog is found in /usr/lib/nls/msg/$LANG/macros.cat.

Initial Value: -

If No Value Specified: Newline

Notes

The following notes apply to the nroff and troff requests. They are referenced by number in the requests where they apply.

  1. The .L string register contains the current program locale value of all the categories.
  2. The .m string register contains the locale value of the LC_MESSAGES category.
  3. The .t string register contains the locale value for the LC_TIME category.
  4. While the .L, .t, and .mstring registers provide access to some environment values, a more general technique can be used to access any other environment variable. For example, if the TED environment variable is exported, the following troff commands:
    .sy echo .ds z $TED >x
    .so x
    .sy rm x

set the z string register to contain the value of $TED.

Environment Variables

LC_ALL
                          Specifies the locale to be used for all the locale categories. It overrides any setting of the other locale environment variables.
LC_MESSAGES
                          Specifies the locale value for the LC_MESSAGES category. This is used if the LC_ALL environment variable is not set.
LC_TIME
                          Specifies the locale value for the LC_TIME category. This is used if the LC_ALL environment variable is not set.
LANG Specifies the locale value to be used for all the locale categories. This is used if none of the above environment variables are set. This is the most often used environment variable to specify the locale.

Files

/usr/share/lib/tmac/tmac.*
                          Contains the pointers to standard macro files.
/usr/share/lib/macros/*
                          Denotes standard macro files.
/usr/share/lib/tmac/tmac.an
                          Contains the pointer to the man macro package.
/usr/share/lib/macros/an
                          Contains the man macro package.
/usr/share/lib/tmac/tmac.e file
                          Contains the me macro definition file.
/usr/share/lib/me directory
                          Contains the macro definition files.
/usr/share/lib/tmac/tmac.m
                          Contains the pointer to the mm macro package.
/usr/share/lib/macros/mmn
                          Contains the mm macro package.
/usr/share/lib/macros/mmt
                          Contains the mm macro package.
/usr/share/lib/tmac/tmac.ptx
                          Points to the macro package.
/usr/share/lib/macros/ptx
                          Contains the macro package.
/usr/share/lib/tmac/tmac.x
                          Contains the macro definition files.
/usr/share/lib/ms Contains the ms macro definitions.
/usr/share/lib/tmac/tmac.v
                          Contains macro definitions.
/usr/share/lib/macros/vmca
                          Contains macro definitions.
/usr/lib/nls/msg/$LANG/macros.cat
                          Contains locale-specific message catalog for the mm, me, ms, and mv macro packages.
/usr/lib/font/dev*/*
                          Contains the font width tables.
/var/tmp/trtmp* Denotes a temporary file.

Related Information

The col command, eqn command, grap command, hplj command, ibm3812 command, ibm3816 command, mm command, mmt command, mvt command, neqn command, nroff command, pic command, ptx command, refer command, tbl command, tc command, xpreview command.

The nroff and troff Input file format, troff file format, troff font file format.

The setlocale function, strftime function.

Message Facility Overview for Programming in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.

National Language Support Overview for Programming in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.


[ Previous | Next | Contents | Glossary | Home | Search ]