 |
» |
|
|
|
NAMEman — macros for formatting manpages SYNOPSISman file
... nroff -man
[option]...
[file]... DESCRIPTIONThe
man
macros are used by the
man
and
nroff
commands (see
man(1)
and
nroff(1))
—
and are usable by
troff
(see third-party documentation)
—
to format the on-line versions of manpages
found in
HP-UX Reference
and other related reference manuals.
The
man
command calls
nroff. man and nroff DefaultsThe default page size is 85 characters by 66 lines (8.5Ч11 inches),
with a 75-character by 60-line text area.
Hyphenation is turned off
and paragraphs are left-adjusted, ragged-right. troff DefaultsThe default page size is 8.5Ч11 inches with a 6.5Ч10-inch text area.
The type size is 10 points
and the vertical line spacing is 12 points.
Hyphenation is turned on
and paragraphs are justified left and right. Other DefaultsType font and size are reset to default values
before each paragraph and after processing
font- and size-setting macros
such as
.I,
.RB,
and
.SM.
Tab stops are neither used nor set by any macro
except
.DT
and
.TH.
The
.TH
macro invokes
.DT
(see below). OptionsThe following options can be specified for
nroff
or
troff.
They are not permitted for the
man
command.
- -rs1
Reduce the dimensions for
troff
to a page size of 6Ч9 inches with a 4.75Ч8.375-inch text area,
the type size to 9 points,
and the vertical line spacing to 10 points.
This option is ignored by
nroff. - -rV2
Set certain parameters to values appropriate for certain Versatec printers:
line length to 82 characters (ens);
page length to 84 lines;
underlining inhibited.
Do not confuse this option with the
-Tvp
option of the
man
command, which is available on some operating systems,
but not on HP-UX.
Summary of Macros, Strings, and NumbersThe defined
man
macros, strings, and numbers
are summarized here and described in detail
in the following subsections.
- .B
Set
text
in bold. - .BC
Set
words
alternately in bold and constant-width. - .BI
Set
words
alternately in bold and italics. - .BR
Set
words
alternately in bold and roman. - .C
Set
text
in constant-width. - .CB
Set
words
alternately in constant-width and bold. - .CD
Identify command name. - .CI
Set
words
alternately in constant-width and italics. - .CR
Set
words
alternately in constant-width and roman. - .CT
Identify citation title. - .DT
Restore default tab settings. - .EM
Identify emphasis. - .ER
Identify error name. - .EV
Identify environment variable name. - .GT
Identify glossary term. - .HP
Begin paragraph with hanging indent. - .I
Set
text
in italics. - .IB
Set
words
alternately in italics and bold. - .IC
Set
words
alternately in italics and constant-width. - .IP
Begin indented paragraph with optional tag. - .IR
Set
words
alternately in italics and roman. - .KC
Identify keycap. - .P
Begin normal paragraph. - .PD
Set interparagraph spacing. - .PM
Use Bell System proprietary subfooters. - .PP
Begin normal paragraph. - .RB
Set
words
alternately in roman and bold. - .RC
Set
words
alternately in roman and constant-width. - .RE
End relative margin indent. - .RI
Set
words
alternately in roman and italics. - .RS
Start relative margin indent. - .RV
Identify return value. - .S3
Insert third level header. - .SC
Identify system constant name. - .SH
Insert section header. - .SM
Print
text
one point smaller. - .SS
Insert subsection header. - .TH
Start new manpage and define page headers and footers. - .TP
Begin tagged paragraph. - \*R
Registered trademark. - \*S
Change to default type size. - \*(Tm
Trademark. - \n(IN
Left text margin; default margin indent and paragraph indent. - \n(LL
Line length, including
\n(IN. - \n(PD
Interparagraph distance.
Macro ParametersAll macro parameters are positional and can be omitted,
starting from the right.
Each parameter is a
word,
as described below.
- mi
Margin increment.
This is the amount by which the left text margin will be increased.
If it is omitted, it defaults to
\n(IN
basic units
(u).
The default measure for
mi
is ens
(n).
The left text margin's base value is
\n(IN. - in
Paragraph indent.
This is the amount by which indented lines of a paragraph will be indented.
If it is omitted, it defaults to the value
that was established by the most recent paragraph macro:
explicitly or default by
.HP,
.IP,
or
.TP;
implicitly by
.P,
.PP,
.RE,
or
.RS.
The default measure for
in
is ens
(n). - text
Consists of zero to six
words.
If
text
is empty,
the special treatment is applied to
the next line containing text to be printed.
For example,
.I
can be used to italicize a whole line, or
.SM
followed by
.B
to make small bold text. - word
A string of characters separated by spaces (not tabs).
Use quotation marks
("
[word]"
)
to include spaces in a
word
("
string string
"
)
or to specify a null
word
(""
).
(The nonbreaking, nonpaddable space
(\ )
is not a separating space.)
Header Macros- .TH t1 s2 c3 n4 a5
Set the title and entry heading.
t1,
s2,
c3,
n4,
and
a5
are
words.
- t1
Entry title. - s2
Section number.
t1
is combined with
s2
in parentheses to form
the top left- and righthand corners of the page heading. - c3
Extra commentary, such as "Optional Software Required".
It is placed at the center of the bottom line
in the two- or three-line page heading space. - n4
Other notations, such as "Series 300/400 Only".
It is centered between the title and section on the first page heading line. - a5
Support for alternate naming,
such as a FORTRAN routine name corresponding
to a C function name specified in
t1.
The resulting output is in the form: - .SH text
Place section head
text,
such as
SYNOPSIS,
here.
Section headings start at the left margin.
Since they are normally all uppercase,
they are printed a point-size smaller in
troff. - .SS text
Place subsection head
text,
such as
Options,
here.
Subsection headings start between the left margin
and the normal text indent. - .S3 text
Place third-level head
text,
such as subhead,
here.
Third-level headings start at the normal text indent.
Paragraph Macros- .P
- .PP
Begin a block paragraph.
Reset
in
to
\n(IN,
"cancelling" any value set by previous
.HP,
.IP,
and
.TP
macros. - .HP in
Begin a paragraph with hanging indent.
The text begins at the current margin.
The second and following output lines are indented. - .TP in
Begin an indented paragraph with hanging tag.
The next input line that contains text to be printed is taken as the tag.
The tag begins at the current margin.
If the tag fits in the indent,
the paragraph text begins at the indent position on the same line.
If the tag does not fit in the indent,
the paragraph text begins at the indent position on the next line. - .IP t in
Same as
.TP in
with tag
t.
Often used to get an indented paragraph without a tag. - .RS mi
Increase the current left margin by
mi.
If
mi
is omitted, it defaults to the current value of
in.
Set the paragraph indent,
in,
for the new margin level to
\n(IN.
You can specify up to nine
.RS
increment levels.
Margin increments can be backed out with the
.RE
macro and are reset to the base margin by the
.TH,
.SH,
.SS,
and
.S3
header macros. - .RE k
Return to the
kth
left margin setting (initially,
k=1;
k=0
is equivalent to
k=1).
If
k
is omitted, return to the previous margin value.
The paragraph indent,
in,
is restored to the value it had prior to the corresponding
.RS
macro. - .PD pd
Set the interparagraph distance to
pd
vertical spaces.
If
pd
is omitted,
set the interparagraph distance to the default value:
1 line in
nroff.
0.4 line in
troff.
The measure for
pd
is vertical line spaces
(v).
Font Macros- .B text
Set
text
in bold. - .C text
Set
text
in constant-width font.
See the WARNINGS section. - .I text
Set
text
in italic.
(There is no
.R
(roman) macro,
but you can use one of the
.XY
combinations if need be.)
- .XY a b
Concatenate
a
in font
X
with
b
in font
Y
and alternate these two fonts for up to six
words.
The font letters
X
and
Y
can be
B
(bold),
C
(constant-width),
I
(italic), and
R
(roman), in the following combinations:
.CB .IB .RB
.BC .IC .RC
.BI .CI .RI
.BR .CR .IR For more about constant-width font, see the WARNINGS section. - .SM text
Make
text
one point smaller than the default point size.
This has no effect in
nroff.
Special MacrosThese macros identify common text elements in manpages.
They aid in providing consistent font usage in the HP style
and in improving conversion to other formatting systems. The first parameter is set in an appropriate font or format.
The second parameter,
punctuation,
is set in roman font and is provided for concatenated punctuation.
The two parameters are concatenated as with the font macros.
- .CD commandname punctuation
commandname
is a command name, usually defined in a section 1 or 1M manpage,
such as
man.
It is displayed in constant-width font. - .CT citationtitle punctuation
citationtitle
is the name of a document, such as
HP-UX Reference.
It is displayed in italics.
(Use the standard
.IR
macro for manpage references.) - .EM emphasis punctuation
emphasis
is a word or phrase that you want to emphasize, such as
Do not.
Use emphasis sparingly.
It is displayed in italics.
(Use the standard
.I
macro for variable names.) - .ER errorname punctuation
errorname
is an error name that corresponds to a value assigned to
errno
by a function and described in the ERRORS section of a manpage.
It is displayed in roman, enclosed in square brackets.
For example,
.ER EIO .
is displayed as
EIO. - .EV environvarname punctuation
environvarname
is the name of an environmental variable,
such as
PATH.
It is displayed in constant-width font. - .GT glossterm punctuation
glossterm
is a glossary term, or a term that you are defining for later use
in the manpage, such as
path name.
It is displayed in bold. - .KC keycap punctuation
keycap
is the name of a keyboard key, such as
Tab.
It is displayed in bold. - .RV returnvalue punctuation
returnvalue
is a numerical return value of a function or exit status of a command,
usually as defined in a RETURN VALUE or EXIT STATUS section.
It is generally used for number expressions, such as
0,
>3,
and
<>0,
but not for word descriptions, such as "nonzero".
It is displayed in constant-width font. - .SC systemconstant punctuation
systemconstant
is an operating system constant name, such as
PATH_MAX.
It is displayed in constant-width font.
See
getconf(1).
Other Macros- .DT
Restore default tab settings:
every 5 ens in
nroff;
every 3.6 ems in
troff. - .PM sf
Produce Bell System proprietary subfooters.
- sf
produces - P
PRIVATE - N
NOTICE - BP
BELL LABORATORIES PROPRIETARY - BR
BELL LABORATORIES RESTRICTED
StringsThe following string references are defined:
- \*R
Registered Trademark symbol:
displayed as
(Reg.)
in
nroff,
and using the
\(rg
inline macro in
troff. - \*S
Change to default type size.
This is executed as a
\s
inline macro. - \*(Tm
Trademark indicator, TM, displayed as a superscript if possible.
NumbersThe following number references are defined:
- \n(IN
Left text margin indent relative to section heads
and default value for
mi
and
in:
5 ens in
nroff;
3.6 ems in
troff.
IN
is expressed in basic units
(u). - \n(LL
Line length including
\n(IN:
75 characters in
nroff;
6.5 inches in
troff.
Also see the Options subsection.
LL
is expressed in basic units
(u). - \n(PD
Current interparagraph distance.
Set by
.PD.
PD
is expressed in vertical line spaces
(v).
Measurenroff
and
troff
use a number of scale indicators
to qualify horizontal and vertical measurements.
Many macro parameters have default units of measure.
Because all assignments to numeric variables are converted to basic units
(u),
it is important to take care in assigning and referencing values.
- C
Character width of output device. - D
Dots per inch (dpi) of output device. - S
Current type size in points. - V
Current vertical line spacing in basic units.
Font ConventionsEntries in the
HP-UX Reference
use the following font conventions:
- roman
Regular typeface. - italic
Used for variables and other words that represent an argument
that may take on a user-defined or variable value.
Also used for
emphasis. - boldface
Used primarily in headings and occasionally for terms when first
introduced or when being defined. - constant-width
Used for all literals that are typed exactly as shown when used
as keyboard commands or command-line options, in programs, etc.
Page FootersThe strings used in the page footer are initialized by the
.TH
macro.
)H
defaults to a nonprinting (null) string.
]W
defaults to the date the manpage is formatted, as in
Formatted: July 5, 1995.
In HP manpages,
)H
is set to the company name, "Hewlett-Packard Company";
]W
is set to release information, as in "HP-UX Release 10.10: November 1995". This arrangement enables users and third-party software suppliers
to directly control the contents of the left- and right-hand fields
of the footer line for use in displaying company name,
release version, etc., as desired when creating their own manual entries.
)H
is printed on the left,
]W
is printed on the right,
and the page number is printed in the center.
These strings can be defined anywhere after the
.TH
macro call, provided they appear before the end of the first page.
For example, the following source file segment:
.TH man 5
.ds )H XYZ Company
.ds ]W Release 2.3: May 1996 produces a footer with text in the form:
TablesThe
tbl
preprocessor (see
tbl(1))
can be used to insert tables in manpages.
The
man
macros allow you to use the standard
tbl
macros:
.TS,
.T&,
and
.TE.
They do not support the
mm
macro extensions,
.TS H
and
.TH
(see
mm(5)). In general, avoid using the
man
macros within a table,
particularly the font macros,
which can produce peculiar and unpredictable results.
Use the
nroff/troff
intrinsic macros instead.
For example, to specify bold type, use the in-line macro
\fB,
or, more generally,
\f3.
To insert horizontal blank lines, you can use the
.PP
or
.IP
macro, depending on which one preceded the table,
but you must then avoid using the
center
and
expand
table format specifications.
Otherwise, indentation will be erratic. WARNINGSHP no longer uses the NAME section to prepare
the Table of Contents and Index for the printed manual.
Instead, that information is coded as comments
at the end of each manpage source file
where it can be accessed by various tools and programs as desired.
The NAME section is still used for the
whatis
database, as described below. The macro package used to print the
HP-UX Reference
increases the interword spaces (to eliminate ambiguity) in the
SYNOPSIS
section of each entry. In addition to the macros, strings, and number registers mentioned above,
a number of internal macros, strings, and number registers are defined.
These include
The names predefined by the
nroff/troff
processor. Macro, string, and number names in the forms
)x,
]x,
and
}x,
where
x
stands for some alphanumeric character, Macro, string, and number names in the form
XY,
where
X
and
Y
are capital letters.
Fontsnroff
uses only three fonts: roman, italic, and bold,
designated as font positions 1, 2, and 3, respectively.
The constant-width font macros in the macro package
(.C,
.RC,
.IC,
.BC,
.CR,
.CI,
.CB)
simulate a constant-width font with the bold font,
since all
nroff
output is constant width or typewriter format. To use a true constant-width font with
troff,
change the corresponding font 3 specification
in each constant-width font macro to font 4
and mount a constant-width font in position 4 using a
troff
.fp
request, as in:
The whatis DatabaseThe NAME section of each manpage is processed by
catman
(see
catman(1M))
to create an entry in the
whatis
database, which is used by the
-f
and
-k
options of the
man
command.
catman
processes the lines of the NAME section into a single line in the format:
name[, name]... - explanatory-text
Hyphens
(typed as
-
or
\-),
en-dashes
(\(mi),
and em-dashes
(\(em)
are treated equivalently.
The last space-hyphen-space in the line becomes the dividing point
between names and explanatory text. FILES- /usr/share/lib/macros/an
The
man
macros. - /usr/share/lib/tmac/tmac.an
Called by
man.
Sources
(.so)
the macros in
/usr/share/lib/macros/an.
Other macro files can be specified here
to accommodate manpages with additional macro requirements. - /usr/share/lib/whatis
File of strings from manpage NAME sections,
created by
catman,
and used by the
man
-k
and
-f
options.
|
Printable version
