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.

.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

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.