man(7)man(7)Nameman - the man macro package for online reference pages
Syntax
tbl file... | nroff [ -nN ] [ -rl1 ] -man | col | ...
tbl file... | *troff [ -nN ] [ -rl1 ] -man | ...
Description
The macro package is used to format reference manual pages for online
viewing or printing. This reference page was formatted by the command
and the macros, or was formatted by the and the commands, using the
macro package.
The page size is 80 columns by 66 lines for output and is 8.5" x 11"
when formatted with text formatters. Page numbers appear at the bottom
of each output page with odd page numbers appearing on the right side
and even page numbers appearing on the left side.
The format of the ULTRIX online reference pages is determined by the
macro package. The macros are a compatible subset of the macros.
Macros
The following describes the macros in the macro package.
Any text argument can range from zero to six words. Quotation marks ("
") can be used to include blanks in words. If text is not specified,
special treatment is applied to the next input line that has text to be
printed. In this way, can be used to italicize a whole line or fol‐
lowed by to make small bold letters.
A prevailing indent distance is remembered between successive indented
paragraphs, and is reset to a default value upon reaching a nonindented
paragraph. Default units for indents i are ens (an en is 1 character
or 1/2 em space in current point size).
Typeface and size are reset to default values before each paragraph,
and after processing font and size setting macros.
.B [ text... ]
Sets text text in boldface. If no text is specified, the
next text line is set in boldface.
.BI word1 word2 [ words... ]
Sets word1 in boldface, word2 in an italic typeface, and
then alternates between these two fonts for the remaining
words, up to six words. Blanks between words are stripped
unless the string is enclosed in quotation marks (" ").
.BR word1 word2 [ words... ]
Sets word1 in boldface, word2 in a roman typeface, and then
alternates between these two fonts for the remaining words,
up to six words. Blanks between words are stripped unless
the string is enclosed in quotation marks (" ").
.CT character
Prints the keyboard control character indicator . For
example, prints as .
.CW Sets text in constant width font until another font change
is found.
.De Ends an unfilled display block (started by Also ends auto‐
matic centering, if it was in effect.
.Ds Starts an unfilled display block. Text between and is
printed in a roman typeface, with `no fill' mode (no wrap‐
ping and blank lines allowed) in effect. The display block
is set flush left.
.DT Restores default tabs. Default tabs are set to .5 inches,
starting with .5i, 1i, ... .
.EE Ends an example and restores basic text defaults and
indents.
.EX [ i ] Starts an example. Text between and is printed in a con‐
stant width font with `no fill' mode (no wrapping and blank
lines allowed) in effect. The example is set flush left
unless an indent i is specified. Units of i are ens.
.G [ text... ]
Sets text in a sans-serif typeface. If no text is speci‐
fied, the next text line is set in a sans-serif typeface.
.GL [ text... ]
Sets text in a sans-serif italic typeface. If no text is
specified, the next text line is set in a sans-serif italic
typeface.
.HB [ words... ]
Sets the text in underline mode or in a sans-serif bold
typeface, depending on the type of text formatter or If the
text formatter is of type the next 999 input lines are for‐
matted in underline mode italic mode), or all the lines up
to a font change are formatted in underline mode, depending
on which limit is encountered first. If the text formatter
is of type text is set in a sans-serif bold typeface until
a font change is encountered. Up to nine words can also be
specified as arguments.
.HP [i] Begins a paragraph with a hanging indent of i ens.
.I [ text... ]
Sets text in an italic typeface. If no text is specified,
the next text line is set in an italic typeface.
.I1 word Sets a temporary indent to the length of the specified
word.
.I2 word Reverses one line and then sets a temporary indent to the
length of the specified word.
.IB word1 word2 [ words... ]
Sets word1 in an italic typeface, word2 in boldface, and
then alternates between these two fonts for the remaining
words, up to six words. Blanks between words are stripped
unless the string is enclosed in quotation marks (" ").
.IP x [i] Sets the prevailing indent to i. Then begins the indented
paragraph with a hanging tag given by the next text line.
If the tag does not fit, the macro places the next text on
a separate line. Tag x appears in bold typeface.
.IR word1 word2 [ words... ]
Sets word1 in an italic typeface, word2 in a roman type‐
face, and then alternates between these two fonts for the
remaining words, up to six words. Blanks between words are
stripped unless the string is enclosed in quotation marks
(" ").
.LP Same as the macro. This macro is obsolete, but is provided
for backwards compatibility.
.MS reference_page section_subsection [ punctuation ]
Sets reference_page immediately followed by section_subsec‐
tion in parentheses followed by optional punctuation, using
fonts that distinguish this reference page reference from
ordinary text. For example,
.NE Ends a note. Also cancels automatic centering if it was in
effect.
.NT [ header1 ] [ C ]
.NT [ C ] [ header2 ]
Starts a note. If no arguments are specified, the default
header for the note is `Note'. If the first argument is
the letter `C', all text in the note is centered, for the
next 99 text lines or until the macro is called, whichever
comes first. If the first argument is not `C', it becomes
the header of the note, even if header2 is also specified.
The header2 argument becomes the header of the note if the
first argument is `C'.
.PD [ v ] Sets the interparagraph distance to v vertical spaces.
Resets the distance to the default value if v is omitted.
.PN x [ y ] Sets x in an italic or constant width typeface (depending
on the formatter type) and then reverts to the previous
typeface. The optional argument y is appended to x with no
space, but printed in the previous typeface. The x argu‐
ment is usually a path name; y is usually punctuation.
.Pn x y [ z ]
Sets x in the current typeface, sets y in an italic or con‐
stant width typeface (depending on the formatter type) and
appends it to x, and finally reverts to the previous type‐
face. The optional argument z is appended to y, but
printed in the previous typeface. Spaces are removed
between x, y, and z, unless quotation marks (" ") are used
to enclose strings with spaces. The x argument is usually
a fixed path name; y is usually a variable path name; and z
is usually punctuation.
.PP Starts a block paragraph. Sets the prevailing indent to
.5i for and four picas for text formatters.
.R Sets the text in a roman typeface until another font change
is encountered. Also ends underline mode if it was in
effect.
.RB word1 word2 [ words... ]
Sets word1 in a roman typeface, word2 in boldface, and then
alternates between these two fonts for the remaining words,
up to six words. Blanks between words are stripped unless
the string is enclosed in quotation marks (" ").
.RE [ k ] Returns to the kth relative right shift indent level.
(Restores the left margin to the position prior to the kth
call). Specifying k=0 is equivalent to specifying k=1. If
k is omitted, restores the left margin to the most recent
previous position. When k=1 or 0, the default indent
increment is restored.
.RI word1 word2 [ words... ]
Sets word1 in a roman typeface, word2 in an italic type‐
face, and then alternates between these two fonts for the
remaining words, up to six words. Blanks between words are
stripped unless the string is enclosed in quotation marks
(" ").
.RN Prints the return character indicator, .
.RS [ i ] Shifts the left margin to the right (relatively) the amount
of i ens. The macro calls can be nested up to nine levels.
If i is not specified for the first call, the relative
right shift increases .5 inch for and four picas for text
formatters. Nested calls increment the relative indent by
i ens, or by .2 inch for or by 2 picas for text formatters.
.SH text Creates a section header.
.SM [ text ]
Sets text to be two points smaller than the current point
size. If no text is specified, the next text line is set
in the smaller point size.
.SS text Creates a subsection header.
.TB [ words... ]
Same as the macro. This macro is obsolete, but is provided
for backwards compatibility.
.TH n c[s] [ a ] [ f ] [ x ]
Begins a new reference page and sets the page title. Also
sets up headers and footers for output pages, sets up all
defaults and traps, and calls the and macros. The title
appears as a header on all pages of the formatted reference
page. The n argument is the reference page name. The c
argument is the primary section number or letter. The s
argument is the subsection, if any. The a argument is for
an optional machine architecture specific label; for exam‐
ple ``VAX''. The f argument optionally alters a portion of
the page footer. The x argument is for optional extra com‐
mentary; for example ``Unsupported''.
Fields n, c, and s appear together at the top of each out‐
put page (see the top of this page for an example). These
fields alternate between the right top and left top of a
page header, corresponding to odd and even page numbers.
Field a appears opposing the page name in the header when
formatted with but appears as a bleed tab when formatted
with text formatters. The f argument appears in the page
footer on the inside edge of the page (left for odd page
numbers, right for even). The x argument appears under‐
neath the page name in the header.
The last three fields are optional. To skip a field, spec‐
ify a pair of quotation marks ("") in the field to be
skipped.
.TP [i] Sets the prevailing indent to i. Then begins the indented
paragraph with a hanging tag given by the next text line.
If the tag does not fit, the macro places the next text on
a separate line.
.VE End a vertical margin bar.
.VS [ 4 ] Starts a vertical margin bar, if `4' is specified; other‐
wise, the macro does nothing.
Macros That Cause Line Breaks
The following macros cause line breaks:
De Ds EE EX HP IP
LP PP RE SH SS TH
TP
Macros That Need Text Lines
The following macros affect the following line of text if they are
specified in the input without arguments:
B BI BR G GL I
IB IR RI RB SH SS
SM
Defaults
Automatic hyphenation is turned on. However, last lines (ones
that will cause a trap) are not hyphenated and the last and
first two characters of a word are not split off.
Characters printed from the Special Font are artificially bolded by
three units whenever the current font is `3'.
The default page size is 80 columns by 66 lines for output and 8.5" x
11" for output generated by text formatters. The text area is horizon‐
tally placed on the page so that the effective page margin is .3 inches
for and 7.5 picas for text formatters.
The macro sets up the following defaults:
· Text is set in ``noadjust'' mode; the right margin is ragged.
· The default interparagraph distance is 1v for and .5v for text for‐
matters.
· The basic text indent is .5 inches for and four picas for text for‐
matters, from the left margin.
· The maximum text line length is 7.4 inches for and 36 picas for
text formatters.
· Sets tab stops every .5 inches.
· The basic text point size is 11 points, with line spacing set to 12
points.
· The basic text font is ``R'' (a roman typeface).
· Reference page headers, section headers, and subsection headers are
set in a sans-serif bold typeface.
Options-nN Numbers the first generated page as N.
-rl1 Turns on line double-spacing mode.
Restrictions
Predefined Registers
The following registers are predefined by the macro package and should
not be changed:
PO Page offset and page margin
IN Left margin indent relative to the section headers
LL Line length including
PL Page length
The register `l' is predefined when you specify the option. Its default
value is 0. The command does not use this option.
Reserved Registers
The following registers are reserved for internal use by the and macro
packages:
A1 DX EX l p p#
PF
In addition, registers beginning with the characters `)', `]', and `}'
are also reserved for internal use.
Registers predefined by the commands, and the and text preprocessors
and formatters should not be redefined.
Predefined Strings
The following strings are predefined by the macro package and should
not be changed:
lq “ if `` if
rq ” if '' if
S Command string to change type size to 10 points.
Reserved Strings and Macros
The following string and macro names are reserved for internal use by
the and macro packages:
## A1 BD BK CD D
DE DS HH ID LD NO
NX P UF ya yn yl
ys
In addition, names beginning with the characters `)', `]', and `}' are
also reserved for internal use.
Names predefined by the commands, and the and text preprocessors and
formatters should not be redefined.
.TH Macro Restrictions
The section number should only be 1-8, `n', `l', `o', or `p'. Other
values might not be recognized by the or commands.
Sections 6, 7, `n', `l', `o', and `p' do not currently have subsec‐
tions, so subsections should not be specified.
The architecture field (a) should not exceed four characters. A value
longer than four characters might print outside the right page margin.
Reference pages containing commands should be preprocessed by an text
preprocessor before being installed on the system.
Reference pages containing commands must not be preprocessed before
being installed on the system.
The Name Section
The command assumes the Name section of a reference page has the fol‐
lowing format:
name[, name, name ...] \- explanatory text
There should be at least one space after any comma and only one space
following the ``backslash hyphen'' (\-). There should not be any com‐
mands in the explanatory text. The explanatory text should be brief.
The command combines information in the Name section with parameters of
the macro to create an entry in a database searched by the and com‐
mands.
Portability Considerations
The ULTRIX macro packages contain extensions and enhancements borrowed
from other macro packages. If you have a need to write portable refer‐
ence pages, you should not use the following macros:
CT CW De Ds EE EX
G GL HB I1 I2 LP
MS NE NT PN Pn R
RN TB UF
The and macros are obsolete.
The ULTRIX macro differs from other implementations of the macro. The
primary differences are in the placement of the page title, and third
and fifth fields in the output. The page title (the page name and sec‐
tion number) is commonly placed on both sides of the page header in
other implementations. The more common placement of the third field is
in the center of the page footer. The more common placement of the
fifth field is in the center of the page header.
The macro permits the use of the percent (%) character in any of its
fields. The presence of the percent character may cause problems for
other implementations of this macro.
Use of the and commands should be avoided, because the version of the
command in some other implementations might not preprocess reference
pages through the command. The commands also might not be installed.
Files
The macro package file
See Alsocol(1), man(1), nroff(1), tbl(1), man.nopage(7), man.repro(7), cat‐
man(8)man(7)
