man(5)
NAME
man − macros for formatting entries in this manual
DESCRIPTION
These macros are used by nroff (and are usable by troff) to determine the layout format of the on-line version of entries found in this and other related reference manuals. These macros are used by the man command (see man(1)).
The default page size is 8.5×11 inches, with a 6.5×10-inch text area. The −rs1 option (which is ignored by nroff) reduces these dimensions to 6×9 inches and 4.75×8.375 inches, respectively — and reduces the default type size from 10-point to 9-point; the vertical line spacing from 12 points to 10 points. The −rV2 option can be used to set certain parameters to values appropriate for certain Versatec printers: line length to 82 characters; page length to 84 lines; underlining inhibited. This option should not be confused with the −Tvp option of the man command, which is available on some UNIX operating systems.
Any text argument below can consist of one to six “words”. Double quotes ( can be used to include blanks in a “word”. 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.
By default, hyphenation is turned off for nroff, but remains on for troff. Paragraphs are left-justified, ragged-right for nroff, and adjusted both left and right for troff.
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. .TH invokes .DT (see below).
Default units for indents in are ens. When in is omitted, the previous indent is used. This remembered indent is set to its default value (7.2 ens in troff, 5 ens in nroff — corresponding to 0.5 inch in the default page size) by .TH, .P, .PP, and .RS, and restored by .RE.
.TH t s c n a Set the title and entry heading:
t Entry title.
s Section number. t is combined with s in parentheses to form the top left- and right-hand corners of the page heading.
c Extra commentary such as “Optional Software Required”; placed in parentheses at the center of the bottom line in the two- or three-line page heading space.
n (for “new manual name”) Used for other text such as "Series 300/400 Only"; centered between the title and section on the first page heading line.
a (for “alternate entry name”) Provided to support alternate naming such as a FORTRAN routine name corresponding to a C function name specified in t.
.SH text Place section head text, e.g., SYNOPSIS, here.
.SS text Place sub-section head text such as Options here.
.C text Set text in computer (monospaced) font. Handled the same as bold by nroff.
.B text Make text bold.
.I text Make text italic.
.SM text Make text 1 point smaller than default point size.
.RI a b Concatenate Roman a with italic b, and alternate these two fonts for up to six arguments. Similar macros alternate between any two of Roman, italic, and bold:
.IR .RB .BR .IB .BI
.CI a b Concatenate computer font a with italic b, and alternate these two fonts for up to six arguments. Similar macros alternate between any two of computer and Roman, italic, and bold:
.IC .CB .BC .CR .RC
Computer font printed the same as bold by nroff.
.P Begin a paragraph with normal font, point size, and indent. .PP is a synonym for .P.
.HP in Begin paragraph with hanging indent.
.TP in Begin indented paragraph with hanging tag. The next line that contains text to be printed is taken as the tag. If the tag does not fit, it is printed on a separate line.
.IP t in Same as .TP in with tag t; often used to get an indented paragraph without a tag.
.RS in Increase relative indent (initially zero). Indent all output an extra in units from the current left margin.
.RE k Return to the kth relative indent level (initially, k=1; k=0 is equivalent to k=1); if k is omitted, return to the most recent lower indent level.
.PM m Produces proprietary markings; where m may be P for PRIVATE, or N for NOTICE, BP for BELL LABORATORIES PROPRIETARY, or BR for BELL LABORATORIES RESTRICTED.
.DT Restore default tab settings (every 7.2 ens in troff, 5 ens in nroff).
.PD v Set the interparagraph distance to v vertical spaces. If v is omitted, set the interparagraph distance to the default value (0.4v in troff, 1v in nroff).
The following strings are defined:
\*R (Reg.) in nroff, Registered Trademark symbol in troff, if available.
\*S Change to default type size.
\*(Tm Trademark indicator.
The following number registers are given default values by .TH:
IN Left margin indent relative to section heads (default is 7.2 ens in troff, 5 ens in nroff).
LL Line length including IN.
PD Current interparagraph distance.
Font Conventions
Entries in the HP-UX Reference use the following font conventions:
Roman Normal typeface used for explanatory and other normal text.
computer Used for all literals which are typed exactly as shown when used as keyboard commands or command-line options, in programs, etc.
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 in regular text.
boldface Used primarily in headings and occasionally for terms when first introduced or when being defined.
Special Features
Strings used in the page footer macro are initialized by the .TH macro. One is defined as a non-printing (null) string to prevent the printing of "Hewlett-Packard Company" at the bottom of manual entries provided by other parties.
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. Footer string )H is printed on the left; string ]W is printed on the right, and the page number is printed in the center. Strings can be defined anywhere after the .TH macro call provided they appear before the end of the first page as in the following example source file segment:
.TH man 5
.ds )H XYZ Company
.ds ]W Release 2.3: July 1989
which produces a footer resembling:
XYZ Company- 1 -Release 2.3: July 1989
FILES
/usr/lib/macros/cmp.[nt].[dt].an
/usr/lib/tmac/tmac.an
/usr/lib/macros/ucmp.[nt].an
SEE ALSO
WARNINGS
In addition to the macros, strings, and number registers mentioned above, a number of internal macros, strings, and number registers are defined. Except for names predefined by nroff/troff and number registers d, m, and y, all such internal names are of the form XA, where X is one of ), ], and }, and A stands for any alphanumeric character.
The NAME section of each entry is assumed to consist of a single line of input that has the following format:
name[, name, name ...] \− explanatory text
The NAME section is no longer used to prepare the Table of Contents and Index for this manual. Instead, that information is coded as comments at the end of each manual entry source file where it can be accessed by various tools and programs as desired. However, catman(1M) and related programs still use the NAME line to create the mkwhatis database.
The macro package increases the inter-word spaces (to eliminate ambiguity) in the SYNOPSIS section of each entry.
The macro package itself uses only the Roman font (so that one can replace, for example, the bold font by the constant-width font if available). Of course, if the input text of an entry contains requests for other fonts (e.g., .I, .RB, \fI), the corresponding fonts must be mounted. The computer font macros use font position 3 (same as bold). To use a constant-width font, change the font 3 specification in each macro to font 4 and mount the constant-width font in position 4 using a troff .fp request.
Any argument to .TH containing blanks must be enclosed by double quotes ( to ensure correct interpretation for formatting.
Hewlett-Packard Company — HP-UX Release 9.0: August 1992