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

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

Environment Variables

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 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.

.RICharacter1Character2...

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

Registers

Flags

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:

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.

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
• Business Letter Macros
• Ending Macros (Trailing Information)
• Paragraphs
• Section Headings
• Lists
• Displays, Tables, Equations, and Footnotes
• Page Headers and Footers
• Miscellaneous Macros
• mm Registers
• mm Strings
• String Names
• Reserved Names.

Beginning Macros for Formal Memoranda

Business Letter Macros

Ending Macros (Trailing Information)

Paragraphs

Section Headings

Lists

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

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

Miscellaneous Macros

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

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.

mm Strings

Print special strings by using the following escape sequences:

String Names

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.

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:

ms Registers

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

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.

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
• Level Macros
• Text-Control Macros
• Default-Setting Macros.

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.

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

Text-Control Macros

Default-Setting Macros

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:

• .AD
• .BR
• .CE
• .FI
• .HY
• .NA
• .NF
• .NH
• .NX
• .SO
• .SP
• .TA
• .TI

The Tm string produces the trademark symbol.

Environment Variable

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:

• Numerical Parameter Input
• Font and Character Size Control
• Page Control
• Text Filling, Adjusting, and Centering
• Vertical Spacing
• Line Length and Indenting
• Macros, Strings, Diversions, and Position Traps
• Number Registers
• Tabs, Leaders, and Fields
• Input and Output Conventions and Character Translations
• Hyphenation
• Three-Part Titles
• Output Line Numbering
• Conditional Acceptance of Input
• Environment Switching
• Insertions from Standard Input
• Input and Output File Switching
• Miscellaneous

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

• The Number variable by itself is an absolute value.
• The +Number variable increases the currently set value.
• The -Number variable decreases the variable relative to its current value.

  Note: For all numeric parameters, numbers are expressed using ASCII Arabic numerals only.

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.

* 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             Request or Function
                    Measure
 
Horizontal          Em (m)              .ll, .in, .ta, .lt,
                                        .po, .mc, \h, \l
 
Vertical            Vertical line       .pl, .wh, .ch, .dt,
                    space (v)           .sp, .sv, .ne, .rt, \v
                                        \x, \L
 
Register-oriented   Basic unit (u)      .nr, .if. .ie
or Conditional
 
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

Page Control

Text Filling, Adjusting, and Centering

Japanese Language Support:

Vertical Spacing

Line Length and Indenting

Macros, Strings, Diversions, and Position Traps

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

ERROR: (paper.doc)input line 123

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

.ds DT^A0 0

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

Number Registers

Tabs, Leaders, and Fields

Input/Output Conventions and Character Translations

.tr aAbBc<C,> 

.tr aabbcc

Hyphenation

Three-Part Titles

Output-Line Numbering

Conditional Acceptance of Input

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

Environment Switching

Insertions from Standard Input

Input and Output File Switching

Miscellaneous

troff: User Abort, line no. file filename

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

Processing has been terminated at line 123.

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

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

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

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

The typesetter is psc. On line 538.

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

Files

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 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.

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