MAN(7)

NAME
man - quick reference guide for the -man macro package

SYNOPSIS
groff -man file ...

DESCRIPTION
The -man package is a set of macros used to format UNIX manual pages. On BSD systems, the use of man is deprecated and the more expressive mdoc package is recommended in its place.

USAGE

  Conventions
man macros are named using one or two upper case alphabetic characters. Following regular troff(1) convention, each macro request starts with a. as the first character of a line. Arguments to macro requests expecting printable text may consist of zero to six words. Some macros will process the next input line if no arguments are supplied. For example, a.I request on a line by itself will cause the next input line to be set in italics. Whitespace characters may be embedded in an argument by enclosing it in quotes. Type font and size are reset to their defaults before each paragraph and after processing font size and face changing macros.

  Indentation
The prevailing indent distance is remembered between successive indented paragraphs and is reset to the default on reaching a non-indented paragraph. Default units for indents are “ens”.

  Preprocessing
The man(1) program is conventionally used to format and display manual pages. If the first line of the manual page source starts with the literal string '\" then the remaining letters on the line indicate preprocessors that need to be run prior to formatting with troff(1). Supported preprocessing directives are:
Letter | Preprocessor
e | eqn(1)
g | grap(1)
p | pic(1)
r | refer(1)
t | tbl(1)
v | vgrind(1)

  Available Strings
The man package has the following predefined strings:
String | Description
\*R | registration symbol
\*S | change to default font size
\*(Tm | trademark symbol
\*(lq | left quote
\*(rq | right quote

  Available Macros
The available macros are presented in alphabetical order.

.B [words]
    typeset words using a bold face. Does not cause a line break. If no arguments are given the next text line is processed.

.BI [words]
    join words alternating bold and italic faces. Does not cause a line break. If no arguments are given the next text line is processed.

.BR [words]
    join words alternating bold and roman faces. Does not cause a line break. If no arguments are given the next text line is processed.

.DT restore the default tab spacing of 0.5 inches. Does not cause a line break.

.HP [indent]
    Begin a paragraph with a hanging indent and sets the prevailing indent to indent. This request forces a line break. If indent is not specified, the value of the prevailing indent is used.

.I [words]
    typeset words using an italic face. Does not cause a line break. If no arguments are given the next text line is processed.

.IB [words]
    join words alternating italic and bold faces. Does not cause a line break. If no arguments are given the next text line is processed.

.IP [tag [indent]]
    Begin an indented paragraph with tag tag and prevailing indent set to indent. If tag is not specified it is taken to be the null string "". If indent is not specified it is taken to be the prevailing indent.

.IR [words]
    join words alternating italic and roman faces. Does not cause a line break. If no arguments are given the next text line is processed.

.LP begin a left-aligned paragraph. The prevailing indent is set to the default. This request forces a line break.

.P  aliased to .LP.

.PD [distance]
    set the vertical distance between paragraphs to distance. If argument distance is not specified a value of 0.4v is used.

.PP aliased to .LP.

.RE end of a relative indent (see .RS below). This request forces a line break and restores the prevailing indent to its previous value.

.RB [words]
    join words alternating roman and bold faces. Does not cause a line break. If no arguments are given the next text line is processed.

.RI [words]
    join words alternating roman and italic faces. Does not cause a line break. If no arguments are given the next text line is processed.

.RS [indent]
    start a relative indent, increasing the indentation by indent. If argument indent is not specified, the value of the prevailing indent is used.

.SB [words]
    typeset words using a bold face after reducing the font size by 1 point. Does not cause a line break. If no arguments are given the next text line is processed.

.SH [words]
    specifies a section heading. This request forces a line break. It resets the prevailing indent and margins to their defaults.

.SM [words]
    typeset words after reducing the font size by 1 point. Does not cause a line break. If no arguments are given the next text line is processed.

.SS [words]
    specifies a section subheading. This request forces a line break. If no arguments are given the next text line is processed. It resets the prevailing indent and margins to their defaults.

.TH name section date
    [footer [center]] Begin reference page name belonging to section section. The third argument date, is the date of the most recent change. If present, footer specifies the left page footer text and center specifies the center header text. This request must the very first request in the manual page.

.TP [indent]
    begin an indented paragraph with the tag specified in the next text line. If argument indent is given, it specifies the new value of the prevailing indent. This request forces a line break.

PAGE STRUCTURE
Most manual pages follow the general structure outlined below:

.TH title [section-number]
    The very first macro request in a manual page has to be the .TH request which establishes the name and title of the manual page. The .TH request also establishes the number of the manual page section.

.SH NAME
    The name, or list of names, by which the command is called, followed by a dash and a one-line summary of the action performed. This section should not contain any troff commands or escapes, or any macro requests. This section is used to generate the database used by the whatis(1) command.

.SH SYNOPSIS
    A brief summary of the usage of the command or function being described.

    Commands
        The syntax of the command and its arguments as would be typed on the command line. Words that have to be typed exactly as printed are to be presented in bold face. Arguments are indicated by the use of an italic face. Arguments and command names so indicated should not be capitalized, even when starting a sentence.

        Syntactic symbols used should appear in roman face:

        []  square brackets are used to indicate optional arguments.

        |   vertical bars are used to indicate a one of many exclusive choice. Only one item from a list separated by vertical bars is to be selected.

        ... an ellipsis following an argument is used to indicate that the arguments can be repeated. When an ellipsis follows a bracketed set, the expression within the brackets can be repeated.

    Functions
        Required data declarations or #include directives are to be shown first, followed by the function declaration.

.SH DESCRIPTION
    An overview of the command or functions external behavior, including its interactions with files or data, how standard input, standard output and standard error are handled. Internals and implementation details are not normally specified. The question answered by this section is "what does it do?" or "what is it for?".

    Literal text, filenames and references to items that appear elsewhere in the reference manuals should be presented using a constant width face. Arguments should be presented using an italic face.

.SH OPTIONS
    The list of options together with a description of how each affects the commands operation.

.SH USAGE
    This section is optional and contains a detailed description of the subcommands and input grammar understood by the command.

.SH RETURN VALUES
    The list of return values a library routine could return to the caller, with the conditions that cause these values to be returned.

.SH EXIT STATUS
    The list of values returned as the exit status of the command, with the conditions that cause these values to be returned.

.SH FILES
    The 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 documentation.

.SH DIAGNOSTICS
    A list of diagnostic messages with corresponding explanations.

.SH BUGS
    Known defects and limitations, if any.

FILES

/usr/share/lib/tmac/tmac.an
    Initial file defining the man package.

/usr/share/lib/tmac/tmac.groff_an
    groff source for macro definitions.

/usr/share/lib/tmac/man.local
    local modifications to the man package.

SEE ALSO
apropos(1), groff(1), man(1), nroff(1), troff(1), whatis(1), mdoc(7), mdoc.samples(7)

HISTORY
This manual page was written by Joseph Koshy <jkoshy@freebsd.org>.