man(5) man(5)
NAME [Toc] [Back]
man - macros for formatting manpages
SYNOPSIS [Toc] [Back]
man file ...
nroff -man [option]... [file]...
DESCRIPTION [Toc] [Back]
The 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 Defaults
The default page size is 85 characters by 66 lines (8.5x11 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.5x11 inches with a 6.5x10-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 [Toc] [Back]
Type 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).
Options [Toc] [Back]
The 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 6x9 inches
with a 4.75x8.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 Numbers
The defined man macros, strings, and numbers are summarized here and
described in detail in the following subsections.
.B Set text in bold.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
man(5) man(5)
.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 Parameters [Toc] [Back]
All macro parameters are positional and can be omitted, starting from
the right. Each parameter is a word, as described below.
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
man(5) man(5)
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 [Toc] [Back]
.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.
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
man(5) man(5)
The resulting output is in the form:
____________________________________________________________
t1(s2) n4 t1(s2)
a5 a5
c3
____________________________________________________________
.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. Thirdlevel
headings start at the normal text indent.
Paragraph Macros [Toc] [Back]
.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
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
man(5) man(5)
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 [Toc] [Back]
.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 Macros [Toc] [Back]
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.
.CD commandname punctuation
commandname is a command name, usually defined in a section
1 or 1M manpage, such as man. It is displayed in constantwidth
font.
.CT citationtitle punctuation
citationtitle is the name of a document, such as HP-UX
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
man(5) man(5)
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 [Toc] [Back]
.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
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
man(5) man(5)
N NOTICE
BP BELL LABORATORIES PROPRIETARY
BR BELL LABORATORIES RESTRICTED
Strings [Toc] [Back]
The 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.
Numbers [Toc] [Back]
The 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).
Measure [Toc] [Back]
nroff 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.
___________________________________________________
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
___________________________________________________
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003
man(5) man(5)
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 Conventions [Toc] [Back]
Entries 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 commandline
options, in programs, etc.
Page Footers [Toc] [Back]
The 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
Hewlett-Packard Company - 8 - HP-UX 11i Version 2: August 2003
man(5) man(5)
produces a footer with text in the form:
____________________________________________________________
XYZ Company - 1 - Release 2.3: May 1996
____________________________________________________________
Tables [Toc] [Back]
The 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.
WARNINGS [Toc] [Back]
HP 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.
+ The macro th,
+ The number register :m,
+ 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.
Fonts [Toc] [Back]
nroff uses only three fonts: roman, italic, and bold, designated as
Hewlett-Packard Company - 9 - HP-UX 11i Version 2: August 2003
man(5) man(5)
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:
.fp 4 CW
The whatis Database [Toc] [Back]
The 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 [Toc] [Back]
/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.
SEE ALSO [Toc] [Back]
col(1), man(1), neqn(1), nroff(1), tbl(1), catman(1M), mm(5).
Hewlett-Packard Company - 10 - HP-UX 11i Version 2: August 2003 [ Back ] |
