man(5) File Formats Manual man(5)
NAME
man - 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.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
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 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
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 mea-
sure 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 nonbreaking, 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 margin. 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 increment 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 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 macro.
Set the interparagraph distance to
pd vertical spaces. If pd is omitted, set the interparagraph 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 section.
Set text in italic.
(There is no (roman) macro, but you can use one of the combinations 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), (con-
stant-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 con-
version 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 references.)
emphasis is a word or phrase that you want to emphasize, such as Use emphasis sparingly. It is displayed in italics. (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 status of a command, usually as defined in a RETURN VALUE or EXIT STATUS sec-
tion. It is generally used for number expressions, such as and but not for word descriptions, such as "nonzero". It is dis-
played in constant-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 references are defined:
Registered Trademark symbol:
displayed as in and using the inline macro in
Change to default type size.
This is executed as a inline macro.
Trademark indicator, TM, displayed as a superscript if possible.
Numbers
The following number references 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 characters in 6.5 inches in Also see the Options subsection. is expressed in basic units
Current interparagraph distance.
Set by is expressed in vertical line spaces
Measure
and 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 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
----------------------------------------------------
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
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.
Used for all literals that are typed exactly as shown when used
as keyboard commands or command-line options, in programs, etc.
Page Footers
The strings used in the page footer are initialized by the macro. defaults to a nonprinting (null) string. defaults to the date the man-
page is formatted, as in In HP manpages, is set to the company name, "Hewlett-Packard Company"; 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. is printed
on the left, is printed on the right, and the page number is printed in the center. These strings can be defined anywhere after the macro
call, provided 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 preprocessor (see tbl(1)) can be used to insert tables in manpages. The macros allow you to use the standard macros: and They do not
support the macro extensions, and (see mm(5)).
In general, avoid using the macros within a table, particularly the font macros, which can produce peculiar and unpredictable results. Use
the intrinsic macros instead. For example, to specify bold type, use the in-line macro or, more generally, To insert horizontal 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 specifica-
tions. Otherwise, indentation will be erratic.
WARNINGS
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 database, as described below.
The macro package used to print the HP-UX Reference increases the interword spaces (to eliminate ambiguity) in the 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
o The names predefined by the processor.
o The macro
o The number register
o Macro, string, and number names in the forms and where x stands for some alphanumeric character,
o Macro, string, and number names in the form XY, where X and Y are capital letters.
Fonts
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 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 corresponding font 3 specification 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 Database
The NAME section of each manpage is processed by (see catman(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]... - explanatory-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 specified here to accommodate manpages with additional macro requirements.
File of strings from manpage NAME sections,
created by and used by the and options.
SEE ALSO
col(1), man(1), neqn(1), nroff(1), tbl(1), catman(1M), mm(5).
man(5)