Provided by: mandoc_1.14.3-3_amd64 bug

NAME

       man - legacy formatting language for manual pages

DESCRIPTION

       Traditionally, the man language has been used to write UNIX manuals for the man(1)
       utility.  It supports limited control of presentational details like fonts, indentation
       and spacing.  This reference document describes the structure of manual pages and the
       syntax and usage of the man language.

       Do not use man to write your manuals: It lacks support for semantic markup.  Use the
       mdoc(7) language, instead.

       In a man document, lines beginning with the control character ‘.’  are called macro lines.
       The first word is the macro name.  It usually consists of two capital letters.  For a list
       of available macros, see MACRO OVERVIEW.  The words following the macro name are arguments
       to the macro.

       Lines not beginning with the control character are called text lines.  They provide free-
       form text to be printed; the formatting of the text depends on the respective processing
       context:

             .SH Macro lines change control state.
             Text lines are interpreted within the current state.

       Many aspects of the basic syntax of the man language are based on the roff(7) language;
       see the LANGUAGE SYNTAX and MACRO SYNTAX sections in the roff(7) manual for details, in
       particular regarding comments, escape sequences, whitespace, and quoting.

MANUAL STRUCTURE

       Each man document must contain the TH macro describing the document's section and title.
       It may occur anywhere in the document, although conventionally it appears as the first
       macro.

       Beyond TH, at least one macro or text line must appear in the document.

       The following is a well-formed skeleton man file for a utility "progname":

             .TH PROGNAME 1 2009-10-10
             .SH NAME
             \fBprogname\fR \(en one line about what it does
             .\" .SH LIBRARY
             .\" For sections 2, 3, and 9 only.
             .\" Not used in OpenBSD.
             .SH SYNOPSIS
             \fBprogname\fR [\fB\-options\fR] \fIfile ...\fR
             .SH DESCRIPTION
             The \fBfoo\fR utility processes files ...
             .\" .Sh CONTEXT
             .\" For section 9 functions only.
             .\" .SH IMPLEMENTATION NOTES
             .\" Not used in OpenBSD.
             .\" .SH RETURN VALUES
             .\" For sections 2, 3, and 9 function return values only.
             .\" .SH ENVIRONMENT
             .\" For sections 1, 6, 7, and 8 only.
             .\" .SH FILES
             .\" .SH EXIT STATUS
             .\" For sections 1, 6, and 8 only.
             .\" .SH EXAMPLES
             .\" .SH DIAGNOSTICS
             .\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
             .\" .SH ERRORS
             .\" For sections 2, 3, 4, and 9 errno settings only.
             .\" .SH SEE ALSO
             .\" .BR foobar ( 1 )
             .\" .SH STANDARDS
             .\" .SH HISTORY
             .\" .SH AUTHORS
             .\" .SH CAVEATS
             .\" .SH BUGS
             .\" .SH SECURITY CONSIDERATIONS
             .\" Not used in OpenBSD.

       The sections in a man document are conventionally ordered as they appear above.  Sections
       should be composed as follows:

             NAME
             The name(s) and a short description of the documented material.  The syntax for this
             is generally as follows:

                   \fBname\fR \(en description

             LIBRARY
             The name of the library containing the documented material, which is assumed to be a
             function in a section 2 or 3 manual.  For functions in the C library, this may be as
             follows:

                   Standard C Library (libc, -lc)

             SYNOPSIS
             Documents the utility invocation syntax, function call syntax, or device
             configuration.

             For the first, utilities (sections 1, 6, and 8), this is generally structured as
             follows:

                   \fBname\fR [-\fBab\fR] [-\fBc\fR\fIarg\fR] \fBpath\fR...

             For the second, function calls (sections 2, 3, 9):

                   .B char *name(char *\fIarg\fR);

             And for the third, configurations (section 4):

                   .B name* at cardbus? function
             ?

             Manuals not in these sections generally don't need a SYNOPSIS.

             DESCRIPTION
             This expands upon the brief, one-line description in NAME.  It usually contains a
             break-down of the options (if documenting a command).

             CONTEXT
             This section lists the contexts in which functions can be called in section 9.  The
             contexts are autoconf, process, or interrupt.

             IMPLEMENTATION NOTES
             Implementation-specific notes should be kept here.  This is useful when implementing
             standard functions that may have side effects or notable algorithmic implications.

             RETURN VALUES
             This section documents the return values of functions in sections 2, 3, and 9.

             ENVIRONMENT
             Documents any usages of environment variables, e.g., environ(7).

             FILES
             Documents files used.  It's helpful to document both the file name and a short
             description of how the file is used (created, modified, etc.).

             EXIT STATUS
             This section documents the command exit status for section 1, 6, and 8 utilities.
             Historically, this information was described in DIAGNOSTICS, a practise that is now
             discouraged.

             EXAMPLES
             Example usages.  This often contains snippets of well-formed, well-tested
             invocations.  Make sure that examples work properly!

             DIAGNOSTICS
             Documents error conditions.  In section 4 and 9 manuals, these are usually messages
             printed by the kernel to the console and to the kernel log.  In section 1, 6, 7, and
             8, these are usually messages printed by userland programs to the standard error
             output.

             Historically, this section was used in place of EXIT STATUS for manuals in sections
             1, 6, and 8; however, this practise is discouraged.

             ERRORS
             Documents errno(2) settings in sections 2, 3, 4, and 9.

             SEE ALSO
             References other manuals with related topics.  This section should exist for most
             manuals.

                   .BR bar ( 1 ),

             Cross-references should conventionally be ordered first by section, then
             alphabetically.

             STANDARDS
             References any standards implemented or used, such as

                   IEEE Std 1003.2 (\(lqPOSIX.2\(rq)

             If not adhering to any standards, the HISTORY section should be used.

             HISTORY
             A brief history of the subject, including where support first appeared.

             AUTHORS
             Credits to the person or persons who wrote the code and/or documentation.  Authors
             should generally be noted by both name and email address.

             CAVEATS
             Common misuses and misunderstandings should be explained in this section.

             BUGS
             Known bugs, limitations, and work-arounds should be described in this section.

             SECURITY CONSIDERATIONS
             Documents any security precautions that operators should consider.

MACRO OVERVIEW

       This overview is sorted such that macros of similar purpose are listed together, to help
       find the best macro for any given purpose.  Deprecated macros are not included in the
       overview, but can be found in the alphabetical reference below.

   Page header and footer meta-data
              TH   set the title: title section date [source [volume]]

              AT   display AT&T UNIX version in the page footer (<= 1 argument)

              UC   display BSD version in the page footer (<= 1 argument)

   Sections and paragraphs
              SH          section header (one line)

              SS          subsection header (one line)

              PP, LP, P   start an undecorated paragraph (no arguments)

              RS, RE      reset the left margin: [width]

              IP          indented paragraph: [head [width]]

              TP          tagged paragraph: [width]

              HP          hanged paragraph: [width]

              PD          set vertical paragraph distance: [height]

              fi, nf      fill mode and no-fill mode (no arguments)

              in          additional indent: [width]

   Physical markup
              B    boldface font

              I    italic font

              R    roman (default) font

              SB   small boldface font

              SM   small roman font

              BI   alternate between boldface and italic fonts

              BR   alternate between boldface and roman fonts

              IB   alternate between italic and boldface fonts

              IR   alternate between italic and roman fonts

              RB   alternate between roman and boldface fonts

              RI   alternate between roman and italic fonts

MACRO REFERENCE

       This section is a canonical reference to all macros, arranged alphabetically.  For the
       scoping of individual macros, see MACRO SYNTAX.

   AT
       Sets the volume for the footer for compatibility with man pages from AT&T UNIX releases.
       The optional arguments specify which release it is from.

   B
       Text is rendered in bold face.

       See also I and R.

   BI
       Text is rendered alternately in bold face and italic.  Thus, ‘.BI this word and that’
       causes ‘this’ and ‘and’ to render in bold face, while ‘word’ and ‘that’ render in italics.
       Whitespace between arguments is omitted in output.

       Examples:

             .BI bold italic bold italic

       The output of this example will be emboldened bold and italicised italic, with spaces
       stripped between arguments.

       See also IB, BR, RB, RI, and IR.

   BR
       Text is rendered alternately in bold face and roman (the default font).  Whitespace
       between arguments is omitted in output.

       See BI for an equivalent example.

       See also BI, IB, RB, RI, and IR.

   DT
       Restore the default tabulator positions.  They are at intervals of 0.5 inches.  This has
       no effect unless the tabulator positions were changed with the roff(7) ta request.

   EE
       This is a non-standard GNU extension, included only for compatibility.  In mandoc(1), it
       does the same as fi.

   EX
       This is a non-standard GNU extension, included only for compatibility.  In mandoc(1), it
       does the same as nf.

   HP
       Begin a paragraph whose initial output line is left-justified, but subsequent output lines
       are indented, with the following syntax:

             [width]

       The width argument is a roff(7) scaling width.  If specified, it's saved for later
       paragraph left-margins; if unspecified, the saved or default width is used.

       See also IP, LP, P, PP, and TP.

   I
       Text is rendered in italics.

       See also B and R.

   IB
       Text is rendered alternately in italics and bold face.  Whitespace between arguments is
       omitted in output.

       See BI for an equivalent example.

       See also BI, BR, RB, RI, and IR.

   IP
       Begin an indented paragraph with the following syntax:

             [head [width]]

       The width argument is a roff(7) scaling width defining the left margin.  It's saved for
       later paragraph left-margins; if unspecified, the saved or default width is used.

       The head argument is used as a leading term, flushed to the left margin.  This is useful
       for bulleted paragraphs and so on.

       See also HP, LP, P, PP, and TP.

   IR
       Text is rendered alternately in italics and roman (the default font).  Whitespace between
       arguments is omitted in output.

       See BI for an equivalent example.

       See also BI, IB, BR, RB, and RI.

   LP
       Begin an undecorated paragraph.  The scope of a paragraph is closed by a subsequent
       paragraph, sub-section, section, or end of file.  The saved paragraph left-margin width is
       reset to the default.

       See also HP, IP, P, PP, and TP.

   ME
       End a mailto block.  This is a non-standard GNU extension, included only for
       compatibility.  See MT.

   MT
       Begin a mailto block.  This is a non-standard GNU extension, included only for
       compatibility.  It has the following syntax:

             link description to be shown
             ⟨⟩

   OP
       Optional command-line argument.  This is a non-standard GNU extension, included only for
       compatibility.  It has the following syntax:

             key [value]

       The key is usually a command-line flag and value its argument.

   P
       Synonym for LP.

       See also HP, IP, LP, PP, and TP.

   PD
       Specify the vertical space to be inserted before each new paragraph.
       The syntax is as follows:

             [height]

       The height argument is a roff(7) scaling width.  It defaults to 1v.  If the unit is
       omitted, v is assumed.

       This macro affects the spacing before any subsequent instances of HP, IP, LP, P, PP, SH,
       SS, and TP.

   PP
       Synonym for LP.

       See also HP, IP, LP, P, and TP.

   R
       Text is rendered in roman (the default font).

       See also I and B.

   RB
       Text is rendered alternately in roman (the default font) and bold face.  Whitespace
       between arguments is omitted in output.

       See BI for an equivalent example.

       See also BI, IB, BR, RI, and IR.

   RE
       Explicitly close out the scope of a prior RS.  The default left margin is restored to the
       state before that RS invocation.

       The syntax is as follows:

             [level]

       Without an argument, the most recent RS block is closed out.  If level is 1, all open RS
       blocks are closed out.  Otherwise, level − 1 nested RS blocks remain open.

   RI
       Text is rendered alternately in roman (the default font) and italics.  Whitespace between
       arguments is omitted in output.

       See BI for an equivalent example.

       See also BI, IB, BR, RB, and IR.

   RS
       Temporarily reset the default left margin.  This has the following syntax:

             [width]

       The width argument is a roff(7) scaling width.  If not specified, the saved or default
       width is used.

       See also RE.

   SB
       Text is rendered in small size (one point smaller than the default font) bold face.

   SH
       Begin a section.  The scope of a section is only closed by another section or the end of
       file.  The paragraph left-margin width is reset to the default.

   SM
       Text is rendered in small size (one point smaller than the default font).

   SS
       Begin a sub-section.  The scope of a sub-section is closed by a subsequent sub-section,
       section, or end of file.  The paragraph left-margin width is reset to the default.

   TH
       Sets the title of the manual page for use in the page header and footer with the following
       syntax:

             title section date [source [volume]]

       Conventionally, the document title is given in all caps.  The recommended date format is
       YYYY-MM-DD as specified in the ISO-8601 standard; if the argument does not conform, it is
       printed verbatim.  If the date is empty or not specified, the current date is used.  The
       optional source string specifies the organisation providing the utility.  When
       unspecified, mandoc(1) uses its -Ios argument.  The volume string replaces the default
       rendered volume, which is dictated by the manual section.

       Examples:

             .TH CVS 5 1992-02-12 GNU

   TP
       Begin a paragraph where the head, if exceeding the indentation width, is followed by a
       newline; if not, the body follows on the same line after a buffer to the indentation
       width.  Subsequent output lines are indented.  The syntax is as follows:

             [width]

       The width argument is a roff(7) scaling width.  If specified, it's saved for later
       paragraph left-margins; if unspecified, the saved or default width is used.

       See also HP, IP, LP, P, and PP.

   UC
       Sets the volume for the footer for compatibility with man pages from BSD releases.  The
       optional first argument specifies which release it is from.

   UE
       End a uniform resource identifier block.  This is a non-standard GNU extension, included
       only for compatibility.  See UE.

   UR
       Begin a uniform resource identifier block.  This is a non-standard GNU extension, included
       only for compatibility.  It has the following syntax:

             link description to be shown
             ⟨⟩

   fi
       End literal mode begun by nf.

   in
       Indent relative to the current indentation:

       If width is signed, the new offset is relative.  Otherwise, it is absolute.  This value is
       reset upon the next paragraph, section, or sub-section.

   nf
       Begin literal mode: all subsequent free-form lines have their end of line boundaries
       preserved.  May be ended by fi.  Literal mode is implicitly ended by SH or SS.

MACRO SYNTAX

       The man macros are classified by scope: line scope or block scope.  Line macros are only
       scoped to the current line (and, in some situations, the subsequent line).  Block macros
       are scoped to the current line and subsequent lines until closed by another block macro.

   Line Macros
       Line macros are generally scoped to the current line, with the body consisting of zero or
       more arguments.  If a macro is scoped to the next line and the line arguments are empty,
       the next line, which must be text, is used instead.  Thus:

             .I
             foo

       is equivalent to ‘.I foo’.  If next-line macros are invoked consecutively, only the last
       is used.  If a next-line macro is followed by a non-next-line macro, an error is raised.

       The syntax is as follows:

             .YO [body...]
             [body...]

                          Macro   Arguments   Scope       Notes

                          AT      <=1         current

                          B       n           next-line

                          BI      n           current

                          BR      n           current

                          DT      0           current

                          EE      0           current     compat

                          EX      0           current     compat

                          I       n           next-line

                          IB      n           current

                          IR      n           current

                          OP      0, 1        current     compat

                          PD      1           current

                          R       n           next-line

                          RB      n           current

                          RI      n           current

                          SB      n           next-line

                          SM      n           next-line

                          TH      >1, <6      current

                          UC      <=1         current

                          fi      0           current     compat

                          in      1           current     compat

                          nf      0           current     compat

       Macros marked as "compat" are included for compatibility with the significant corpus of
       existing manuals that mix dialects of roff.  These macros should not be used for portable
       man manuals.

   Block Macros
       Block macros comprise a head and body.  As with in-line macros, the head is scoped to the
       current line and, in one circumstance, the next line (the next-line stipulations as in
       Line Macros apply here as well).

       The syntax is as follows:

             .YO [head...]
             [head...]
             [body...]

       The closure of body scope may be to the section, where a macro is closed by SH; sub-
       section, closed by a section or SS; part, closed by a section, sub-section, or RE; or
       paragraph, closed by a section, sub-section, part, HP, IP, LP, P, PP, or TP.  No closure
       refers to an explicit block closing macro.

       As a rule, block macros may not be nested; thus, calling a block macro while another block
       macro scope is open, and the open scope is not implicitly closed, is syntactically
       incorrect.

                          Macro   Arguments   Head Scope   Body Scope    Notes

                          HP      <2          current      paragraph

                          IP      <3          current      paragraph

                          LP      0           current      paragraph

                          P       0           current      paragraph

                          PP      0           current      paragraph

                          RE      0           current      none          compat

                          RS      1           current      part          compat

                          SH      >0          next-line    section

                          SS      >0          next-line    sub-section

                          TP      n           next-line    paragraph

                          UE      0           current      none          compat

                          UR      1           current      part          compat

       Macros marked "compat" are as mentioned in Line Macros.

       If a block macro is next-line scoped, it may only be followed by in-line macros for
       decorating text.

   Font handling
       In man documents, both Physical markup macros and roff(7) ‘\f’ font escape sequences can
       be used to choose fonts.  In text lines, the effect of manual font selection by escape
       sequences only lasts until the next macro invocation; in macro lines, it only lasts until
       the end of the macro scope.  Note that macros like BR open and close a font scope for each
       argument.

SEE ALSO

       man(1), mandoc(1), eqn(7), mandoc_char(7), mdoc(7), roff(7), tbl(7)

HISTORY

       The man language first appeared as a macro package for the roff typesetting system in
       Version 7 AT&T UNIX.  It was later rewritten by James Clark as a macro package for groff.
       Eric S. Raymond wrote the extended man macros for groff in 2007.  The stand-alone
       implementation that is part of the mandoc(1) utility written by Kristaps Dzonsons appeared
       in OpenBSD 4.6.

AUTHORS

       This man reference was written by Kristaps Dzonsons <kristaps@bsd.lv>.

CAVEATS

       Do not use this language.  Use mdoc(7), instead.