man(5)man(5)NAMEman - macros for formatting manpages
SYNOPSIS
...
[option]... [file]...
DESCRIPTION
The macros are used by the and commands (see man(1) and nroff(1)) — and
are usable by (see third-party documentation) — to format the on-line
versions of manpages found in and other related reference manuals. The
command calls
man and nroff Defaults
The 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 Defaults
The 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 Defaults
Type font and size are reset to default values before each paragraph
and after processing font- and size-setting macros such as and Tab
stops are neither used nor set by any macro except and The macro
invokes (see below).
Options
The following options can be specified for or They are not permitted
for the command.
Reduce the dimensions for
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 spac‐
ing to 10 points. This option is ignored by
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
option of the command, which is available on some operating
systems, but not on HP-UX.
Summary of Macros, Strings, and Numbers
The defined macros, strings, and numbers are summarized here and
described in detail in the following subsections.
Set text in bold.
Set words alternately in bold and constant-width.
Set words alternately in bold and italics.
Set words alternately in bold and roman.
Set text in constant-width.
Set words alternately in constant-width and bold.
Identify command name.
Set words alternately in constant-width and italics.
Set words alternately in constant-width and roman.
Identify citation title.
Restore default tab settings.
Identify emphasis.
Identify error name.
Identify environment variable name.
Identify glossary term.
Begin paragraph with hanging indent.
Set text in italics.
Set words alternately in italics and bold.
Set words alternately in italics and constant-width.
Begin indented paragraph with optional tag.
Set words alternately in italics and roman.
Identify keycap.
Begin normal paragraph.
Set interparagraph spacing.
Use Bell System proprietary subfooters.
Begin normal paragraph.
Set words alternately in roman and bold.
Set words alternately in roman and constant-width.
End relative margin indent.
Set words alternately in roman and italics.
Start relative margin indent.
Identify return value.
Insert third level header.
Identify system constant name.
Insert section header.
Print text one point smaller.
Insert subsection header.
Start new manpage and define page headers and footers.
Begin tagged paragraph.
Registered trademark.
Change to default type size.
Trademark.
Left text margin; default margin indent and paragraph indent.
Line length, including
Interparagraph distance.
Macro Parameters
All 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
basic units The default measure for mi is ens The left text
margin's base value is
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 or implicitly by or
The default measure for in is ens
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, can be used to italicize a whole line,
or followed by 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 nonbreak‐
ing, nonpaddable space is not a separating space.)
Header Macros
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:
─────────────────────────────────────────────────────────────
t1(s2) n4 t1(s2)
a5 a5
c3
─────────────────────────────────────────────────────────────
Place section head
text, such as here. Section headings start at the left mar‐
gin. Since they are normally all uppercase, they are printed
a point-size smaller in
Place subsection head
text, such as here. Subsection headings start between the
left margin and the normal text indent.
Place third-level head
text, such as subhead, here. Third-level headings start at
the normal text indent.
Paragraph Macros
Begin a block paragraph.
Reset in to "cancelling" any value set by previous and
macros.
Begin a paragraph with hanging indent.
The text begins at the current margin. The second and
following output lines are indented.
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.
Same as with tag t. Often used to get an indented paragraph
without a tag.
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 You can specify up to nine incre‐
ment levels. Margin increments can be backed out with
the macro and are reset to the base margin by the and
header macros.
Return to the
kth left margin setting (initially, k=1; k=0 is equiv‐
alent to k=1). If k is omitted, return to the previ‐
ous margin value. The paragraph indent, in, is
restored to the value it had prior to the correspond‐
ing macro.
Set the interparagraph distance to
pd vertical spaces. If pd is omitted, set the inter‐
paragraph distance to the default value: 1 line in 0.4
line in The measure for pd is vertical line spaces
Font Macros
Set text in bold.
Set text in constant-width font. See the WARNINGS sec‐
tion.
Set text in italic.
(There is no (roman) macro, but you can use one of the combina‐
tions if need be.)
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 (bold), (constant-width), (italic), and
(roman), in the following combinations:
For more about constant-width font, see the WARNINGS
section.
Make text one point smaller than the default point size.
This has no effect in
Special Macros
These 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.
commandname
is a command name, usually defined in a section 1 or
1M manpage, such as It is displayed in constant-width
font.
citationtitle
is the name of a document, such as It is displayed in
italics. (Use the standard macro for manpage refer‐
ences.)
emphasis is a word or phrase that you want to emphasize, such
as Use emphasis sparingly. It is displayed in ital‐
ics. (Use the standard macro for variable names.)
errorname is an error name that corresponds to a value assigned
to by a function and described in the ERRORS section
of a manpage. It is displayed in roman, enclosed in
square brackets. For example, is displayed as
environvarname
is the name of an environmental variable, such as It
is displayed in constant-width font.
glossterm is a glossary term, or a term that you are defining
for later use in the manpage, such as It is displayed
in bold.
keycap is the name of a keyboard key, such as It is displayed
in bold.
returnvalue
is a numerical return value of a function or exit sta‐
tus of a command, usually as defined in a RETURN VALUE
or EXIT STATUS section. It is generally used for num‐
ber expressions, such as and but not for word descrip‐
tions, such as "nonzero". It is displayed in con‐
stant-width font.
systemconstant
is an operating system constant name, such as It is
displayed in constant-width font. See getconf(1).
Other Macros
Restore default tab settings:
every 5 ens in every 3.6 ems in
Produce Bell System proprietary subfooters.
sf produces
Strings
The following
string refer‐
ences are
defined:
Registered
Trademark
symbol:
dis‐
played
as
in
and
using
the
inline
macro
in
Change to
default type
size.
This
is
exe‐
cuted
as
a
inline
macro.
Trademark
indicator,
TM, displayed
as a super‐
script if
possible.
Numbers
The following
number refer‐
ences are
defined:
Left text
margin indent
relative to
section heads
and
default
value
for
mi
and
in:
5
ens
in
3.6
ems
in
is
expressed
in
basic
units
Line length
including
75
char‐
ac‐
ters
in
6.5
inches
in
Also
see
the
Options
sub‐
sec‐
tion.
is
expressed
in
basic
units
Current
interpara‐
graph dis‐
tance.
Set
by
is
expressed
in
ver‐
ti‐
cal
line
spa‐
ces
Measure
and use a
number of
scale indica‐
tors to qual‐
ify horizon‐
tal and ver‐
tical mea‐
surements.
Many macro
parameters
have default
units of mea‐
sure.
Because all
assignments
to numeric
variables are
converted to
basic units
it is impor‐
tant to take
care in
assigning and
referencing
values.
────────────────────────────────────────────────────
Scale Basic Units
Indicator Measure nroff troff
────────────────────────────────────────────────────
c centimeter 240/2.54 D/2.54
i inch 240 D
m em C p*S
n en = em/2 C p*S/2
p point = 1/72 inch 240/72 D/72
P pica = 1/6 inch 240/6 D/6
u basic unit 1 1
v vertical line space V V
────────────────────────────────────────────────────
C Char‐
ac‐
ter
width
of
out‐
put
device.
D Dots
per
inch
(dpi)
of
out‐
put
device.
S Cur‐
rent
type
size
in
points.
V Cur‐
rent
ver‐
ti‐
cal
line
spac‐
ing
in
basic
units.
Font Conventions
Entries in
the HP-UX
Reference use
the following
font conven‐
tions:
roman Reg‐
u‐
lar
type‐
face.
italic Used
for
vari‐
ables
and
other
words
that
rep‐
re‐
sent
an
argu‐
ment
that
may
take
on
a
user-
defined
or
vari‐
able
value.
Also
used
for
empha‐
sis.
bold‐
face Used
pri‐
mar‐
ily
in
head‐
ings
and
occa‐
sion‐
ally
for
terms
when
first
intro‐
duced
or
when
being
defined.
Used
for
all
liter‐
als
that
are
typed
exactly
as
shown
when
used as
key‐
board
com‐
mands
or
com‐
mand-
line
options,
in
pro‐
grams,
etc.
Page Footers
The strings
used in the
page footer
are initial‐
ized by the
macro.
defaults to a
nonprinting
(null)
string.
defaults to
the date the
manpage is
formatted, as
in In HP man‐
pages, is set
to the com‐
pany name,
"Hewlett-
Packard Com‐
pany"; is set
to release
information,
as in "HP-UX
Release
10.10: Novem‐
ber 1995".
This arrange‐
ment enables
users and
third-party
software sup‐
pliers to
directly con‐
trol the con‐
tents of the
left- and
right-hand
fields of the
footer line
for use in
displaying
company name,
release ver‐
sion, etc.,
as desired
when creating
their own
manual
entries. is
printed on
the left, is
printed on
the right,
and the page
number is
printed in
the center.
These strings
can be
defined any‐
where after
the macro
call, pro‐
vided they
appear before
the end of
the first
page. For
example, the
following
source file
segment:
produces a
footer with
text in the
form:
─────────────────────────────────────────────────────────────
XYZ Company − 1 − Release 2.3: May 1996
─────────────────────────────────────────────────────────────
Tables
The pre‐
processor
(see tbl(1))
can be used
to insert
tables in
manpages.
The macros
allow you to
use the stan‐
dard macros:
and They do
not support
the macro
extensions,
and (see
mm(5)).
In general,
avoid using
the macros
within a ta‐
ble, particu‐
larly the
font macros,
which can
produce pecu‐
liar and
unpredictable
results. Use
the intrinsic
macros
instead. For
example, to
specify bold
type, use the
in-line macro
or, more gen‐
erally, To
insert hori‐
zontal blank
lines, you
can use the
or macro,
depending on
which one
preceded the
table, but
you must then
avoid using
the and table
format speci‐
fications.
Otherwise,
indentation
will be
erratic.
WARNINGS
HP no longer
uses the NAME
section to
prepare the
Table of Con‐
tents and
Index for the
printed man‐
ual.
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 data‐
base, as
described
below.
The macro
package used
to print the
HP-UX Refer‐
ence
increases the
interword
spaces (to
eliminate
ambiguity) in
the section
of each
entry.
In addition
to the
macros,
strings, and
number regis‐
ters men‐
tioned above,
a number of
internal
macros,
strings, and
number regis‐
ters are
defined.
These include
· The
names
prede‐
fined by
the pro‐
cessor.
· The
macro
· The num‐
ber reg‐
ister
· Macro,
string,
and num‐
ber
names in
the
forms
and
where x
stands
for some
alphanu‐
meric
charac‐
ter,
· Macro,
string,
and num‐
ber
names in
the form
XY,
where X
and Y
are cap‐
ital
letters.
Fonts
uses only
three fonts:
roman,
italic, and
bold, desig‐
nated as font
positions 1,
2, and 3,
respectively.
The constant-
width font
macros in the
macro package
simulate a
constant-
width font
with the bold
font, since
all output is
constant
width or
typewriter
format.
To use a true
constant-
width font
with change
the corre‐
sponding font
3 specifica‐
tion in each
constant-
width font
macro to font
4 and mount a
constant-
width font in
position 4
using a
request, as
in:
The whatis Data‐
base
The NAME sec‐
tion of each
manpage is
processed by
(see cat‐
man(1M)) to
create an
entry in the
database,
which is used
by the and
options of
the command.
processes the
lines of the
NAME section
into a single
line in the
format:
name[, name]... - explana‐
tory-
text
Hyphens
(typed as or
en-dashes and
em-dashes are
treated
equivalently.
The last
space-hyphen-
space in the
line becomes
the dividing
point between
names and
explanatory
text.
FILES
The
macros.
Called
by
Sources
the
macros
in
Other
macro
files
can be
speci‐
fied
here
to
accom‐
modate
man‐
pages
with
addi‐
tional
macro
require‐
ments.
File
of
strings
from
man‐
page
NAME
sec‐
tions,
cre‐
ated
by and
used
by the
and
options.
SEE ALSOcol(1),
man(1),
neqn(1),
nroff(1),
tbl(1), cat‐
man(1M),
mm(5).
man(5)
