Tribblix: manual page: man.7

MAN(7) Standards, Environments, and Macros MAN(7)

NAME

man - macros to format Reference Manual pages

SYNOPSIS

mandoc -T man file ...
nroff -man file ...
troff -man file ...

DESCRIPTION

These macros are used to lay out the reference pages in this manual.
Note: if file contains format input for a preprocessor, the commands
shown above must be piped through the appropriate preprocessor. This
is handled automatically by the man(1) command. See the Conventions
section.

Any text argument t may be zero to six words. Quotes may be used to
include SPACE characters in a "word". If text is empty, the special
treatment is applied to the next input line with text to be printed.
In this way .I may be used to italicize a whole line, or .SB may be
used to make small bold letters.

A prevailing indent distance is remembered between successive indented
paragraphs, and is reset to default value upon reaching a non-indented
paragraph. Default units for indents i are ens.

Type font and size are reset to default values before each paragraph,
and after processing font and size setting macros.

These strings are predefined by -man:

\*R `(R)', `(Reg)' in nroff.

\*S Change to default type size.

Requests
* n.t.l. = next text line; p.i. = prevailing indent

Request Sy Cause Sy If No Sy Explanation
Sy Break Sy Argument
Nm .B t no Ar t=n.t.l.* Text is in bold font.
.BI t no Ar t=n.t.l. Join words, alternating
bold and italic.
.BR t no Ar t=n.t.l. Join words, alternating
bold and roman.
.DT no Li .5i 1i... Restore default tabs.
.HP i yes Ar i=p.i.* Begin paragraph with
hanging indent. Set
prevailing indent to Ar
i.
.I t no Ar t=n.t.l. Text is italic.
.IB t no Ar t=n.t.l. Join words, alternating
italic and bold.
.IP x i yes Ar x="" Same as .TP with tag x.
.IR t no Ar t=n.t.l. Join words, alternating
italic and roman.
.IX t no - Index macro, not used
(obsolete).
.LP yes - Begin left-aligned
paragraph. Set prevailing
indent to .5i.
.P yes - Same as .LP.
.PD d no Ar d=.4v Set vertical distance
between paragraphs.
.PP yes - Same as .LP.
.RE yes - End of relative indent.
Restores prevailing
indent.
.RB t no Ar t=n.t.l. Join words, alternating
roman and bold.
.RI t no Ar t=n.t.l. Join words, alternating
roman and italic.
.RS i yes Ar i=p.i. Start relative indent,
increase indent by i.
Sets prevailing indent to
.5i for nested indents.
.SB t no - Reduce size of text by 1
point, make text bold.
.SH t yes - Section Heading.
.SM t no Ar t=n.t.l. Reduce size of text by 1
point.
.SS t yes Ar t=n.t.l. Section Subheading.
.TH n s d f m yes - Begin reference page n,
of section s; d is the
date of the most recent
change. If present, f is
the left page footer; m
is the main page (center)
header. Sets prevailing
indent and tabs to .5i.
.TP i yes Ar i=p.i. Begin indented paragraph,
with the tag given on the
next text line. Set
prevailing indent to i.
.TX t p no - Resolve the title
abbreviation t; join to
punctuation mark (or
text) p.

Conventions

When formatting a manual page, man examines the first line to determine
whether it requires special processing. For example a first line
consisting of:

'\" t

indicates that the manual page must be run through the tbl(1)
preprocessor.

A typical manual page for a command or function is laid out as follows:

.TH title [1-9] The name of the command or function, which serves as
the title of the manual page. This is followed by
the number of the section in which it appears.

.SH NAME The name, or list of names, by which the command is
called, followed by a dash and then a one-line
summary of the action performed. All in roman font,
this section contains no troff(1) commands or
escapes, and no macro requests. It is used to
generate the database used by the whatis(1) command.

.SH SYNOPSIS

Commands: The syntax of the command and its
arguments, as typed on the command line.
When in boldface, a word must be typed
exactly as printed. When in italics, a
word can be replaced with an argument
that you supply. References to bold or
italicized items are not capitalized in
other sections, even when they begin a
sentence.

Syntactic symbols appear in roman face:

[ ] An argument, when surrounded by
brackets is optional.

| Arguments separated by a vertical
bar are exclusive. You can supply
only one item from such a list.

... Arguments followed by an ellipsis
can be repeated. When an ellipsis
follows a bracketed set, the
expression within the brackets can
be repeated.

Functions: If required, the data declaration, or
#include directive, is shown first,
followed by the function declaration.
Otherwise, the function declaration is
shown.

.SH DESCRIPTION A narrative overview of the command or function's
external behavior. This includes how it interacts
with files or data, and how it handles the standard
input, standard output and standard error.
Internals and implementation details are normally
omitted. This section attempts to provide a
succinct overview in answer to the question, "what
does it do?"

Literal text from the synopsis appears in constant
width, as do literal filenames and references to
items that appear elsewhere in the reference
manuals. Arguments are italicized.

If a command interprets either subcommands or an
input grammar, its command interface or input
grammar is normally described in a USAGE section,
which follows the OPTIONS section. The DESCRIPTION
section only describes the behavior of the command
itself, not that of subcommands.

.SH OPTIONS The list of options along with a description of how
each affects the command's operation.

.SH RETURN VALUES A list of the values the library routine will return
to the calling program and the conditions that
cause these values to be returned.

.SH EXIT STATUS A list of the values the utility will return to the
calling program or shell, and the conditions that
cause these values to be returned.

.SH FILES A list of files associated with the command or
function.

.SH SEE ALSO A comma-separated list of related manual pages,
followed by references to other published materials.

.SH DIAGNOSTICS A list of diagnostic messages and an explanation of
each.

.SH BUGS A description of limitations, known defects, and
possible problems associated with the command or
function.

FILES

/usr/share/man/whatis

NOTES

The man package should not be used for new documentation. The mdoc(7),
package is preferred, as it uses semantic markup rather than physical
markup.

CODE SET INDEPENDENCE

When processed with mandoc(1), this package is Code Set Independent.
However, when processed with legacy tools such as nroff(1) and
troff(1), the use of multi-byte characters may not be supported.

INTERFACE STABILITY

Obsolete Committed. The mdoc(7) package should be used instead.