| MDOC(7) | Miscellaneous Information Manual | MDOC(7) | 
mdoc —
mdoc language supports authoring of manual pages for
  the man(1) utility by allowing
  semantic annotations of words, phrases, page sections and complete manual
  pages. Such annotations are used by formatting tools to achieve a uniform
  presentation across all manuals written in mdoc, and
  to support hyperlinking if supported by the output medium.
This reference document describes the structure of manual pages
    and the syntax and usage of the mdoc language. The
    reference implementation of a parsing and formatting tool is
    mandoc(1); the
    COMPATIBILITY section describes
    compatibility with other implementations.
In an mdoc document, lines beginning with
    the control character ‘.’ are called “macro
    lines”. The first word is the macro name. It consists of two or three
    letters. Most macro names begin with a capital letter. For a list of
    available macros, see MACRO
    OVERVIEW. The words following the macro name are arguments to the macro,
    optionally including the names of other, callable macros; see
    MACRO SYNTAX for details.
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
    mdoc 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. However, using
    roff(7) requests in
    mdoc documents is discouraged;
    mandoc(1) supports some of
    them merely for backward compatibility.
mdoc document consists of a document
  prologue followed by one or more sections.
The prologue, which consists of the Dd,
    Dt, and Os macros in that
    order, is required for every document.
The first section (sections are denoted by
    Sh) must be the NAME section, consisting of at least
    one Nm followed by Nd.
Following that, convention dictates specifying at least the SYNOPSIS and DESCRIPTION sections, although this varies between manual sections.
The following is a well-formed skeleton
    mdoc file for a utility
  “progname”:
.Dd $Mdocdate$ .Dt PROGNAME section .Os .Sh NAME .Nm progname .Nd one line about what it does .\" .Sh LIBRARY .\" For sections 2, 3, and 9 only. .\" Not used in OpenBSD. .Sh SYNOPSIS .Nm progname .Op Fl options .Ar .Sh DESCRIPTION The .Nm 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 .\" .Xr foobar 1 .\" .Sh STANDARDS .\" .Sh HISTORY .\" .Sh AUTHORS .\" .Sh CAVEATS .\" .Sh BUGS .\" .Sh SECURITY CONSIDERATIONS .\" Not used in OpenBSD.
The sections in an mdoc document are
    conventionally ordered as they appear above. Sections should be composed as
    follows:
.Nm name0 ,
.Nm name1 ,
.Nm name2
.Nd a one line description
    
    Multiple ‘Nm’ names should be separated by commas.
The Nm macro(s) must precede the
        Nd macro.
See Nm and
      Nd.
.Lb libarm
    
    See Lb.
For the first, utilities (sections 1, 6, and 8), this is generally structured as follows:
.Nm bar
.Op Fl v
.Op Fl o Ar file
.Op Ar
.Nm foo
.Op Fl v
.Op Fl o Ar file
.Op Ar
    
    Commands should be ordered alphabetically.
For the second, function calls (sections 2, 3, 9):
.In header.h
.Vt extern const char *global;
.Ft "char *"
.Fn foo "const char *src"
.Ft "char *"
.Fn bar "const char *src"
    
    Ordering of In,
        Vt, Fn, and
        Fo macros should follow C header-file
        conventions.
And for the third, configurations (section 4):
.Cd "it* at isa? port 0x2e"
.Cd "it* at isa? port 0x4e"
    
    Manuals not in these sections generally don't need a SYNOPSIS.
Some macros are displayed differently in the
        SYNOPSIS section, particularly
        Nm, Cd,
        Fd, Fn,
        Fo, In,
        Vt, and Ft. All of these
        macros are output on their own line. If two such dissimilar macros are
        pairwise invoked (except for Ft before
        Fo or Fn), they are
        separated by a vertical space, unless in the case of
        Fo, Fn, and
        Ft, which are always separated by vertical
        space.
When text and macros following an Nm
        macro starting an input line span multiple output lines, all output
        lines but the first will be indented to align with the text immediately
        following the Nm macro, up to the next
        Nm, Sh, or
        Ss macro or the end of an enclosing block,
        whichever comes first.
The
.Nm
utility does this, that, and the other.
    
    It usually follows with a breakdown of the options (if documenting a command), such as:
The arguments are as follows:
.Bl -tag -width Ds
.It Fl v
Print verbose information.
.El
    
    List the options in alphabetical order, uppercase before lowercase for each letter and with no regard to whether an option takes an argument. Put digits in ascending order before all letter options.
Manuals not documenting a command won't include the above fragment.
Since the DESCRIPTION section usually
        contains most of the text of a manual, longer manuals often use the
        Ss macro to form subsections. In very long
        manuals, the DESCRIPTION may be split into multiple
        sections, each started by an Sh macro followed
        by a non-standard section name, and each having several subsections,
        like in the present mdoc manual.
See Rv.
See Ev.
See Pa.
See Ex.
Historically, this section was used in place of EXIT STATUS for manuals in sections 1, 6, and 8; however, this practise is discouraged.
See Bl
      -diag.
See Er.
References to other documentation concerning the topic of the manual page, for example authoritative books or journal articles, may also be provided in this section.
See Rs and
      Xr.
See St.
See An.
| Dd | document date: $Mdocdate$|
      month day, year | 
| Dt | document title: TITLE section [arch] | 
| Os | operating system version: [system [version]] | 
| Nm | document name (one argument) | 
| Nd | document description (one line) | 
| Sh | section header (one line) | 
| Ss | subsection header (one line) | 
| Sx | internal cross reference to a section or subsection | 
| Xr | cross reference to another manual page: name section | 
| Pp | start a text paragraph (no arguments) | 
| Bd,Ed | display block: -type
      [-offsetwidth]
      [-compact] | 
| D1 | indented display (one line) | 
| Dl | indented literal display (one line) | 
| Ql | in-line literal display:
      ‘ text’ | 
| Bl,El | list block: -type
      [-widthval]
      [-offsetval]
      [-compact] | 
| It | list item (syntax depends on -type) | 
| Ta | table cell separator in Bl-columnlists | 
| Rs,%*,Re | bibliographic block (references) | 
| Pf | prefix, no following horizontal space (one argument) | 
| Ns | roman font, no preceding horizontal space (no arguments) | 
| Ap | apostrophe without surrounding whitespace (no arguments) | 
| Sm | switch horizontal spacing mode: [ on|off] | 
| Bk,Ek | keep block: -words | 
| Nm | start a SYNOPSIS block with the name of a utility | 
| Fl | command line options (flags) (>=0 arguments) | 
| Cm | command modifier (>0 arguments) | 
| Ar | command arguments (>=0 arguments) | 
| Op,Oo,Oc | optional syntax elements (enclosure) | 
| Ic | internal or interactive command (>0 arguments) | 
| Ev | environmental variable (>0 arguments) | 
| Pa | file system path (>=0 arguments) | 
| Lb | function library (one argument) | 
| In | include file (one argument) | 
| Fd | other preprocessor directive (>0 arguments) | 
| Ft | function type (>0 arguments) | 
| Fo,Fc | function block: funcname | 
| Fn | function name: funcname [argument ...] | 
| Fa | function argument (>0 arguments) | 
| Vt | variable type (>0 arguments) | 
| Va | variable name (>0 arguments) | 
| Dv | defined variable or preprocessor constant (>0 arguments) | 
| Er | error constant (>0 arguments) | 
| Ev | environmental variable (>0 arguments) | 
| An | author name (>0 arguments) | 
| Lk | hyperlink: uri [display_name] | 
| Mt | “mailto” hyperlink: localpart@domain | 
| Cd | kernel configuration declaration (>0 arguments) | 
| Ad | memory address (>0 arguments) | 
| Ms | mathematical symbol (>0 arguments) | 
| Em | italic font or underline (emphasis) (>0 arguments) | 
| Sy | boldface font (symbolic) (>0 arguments) | 
| No | return to roman font (normal) (>0 arguments) | 
| Bf,Ef | font block: -type |Em|Li|Sy | 
| Dq,Do,Dc | enclose in typographic double quotes: “text” | 
| Qq,Qo,Qc | enclose in typewriter double quotes: “text” | 
| Sq,So,Sc | enclose in single quotes: ‘text’ | 
| Pq,Po,Pc | enclose in parentheses: (text) | 
| Bq,Bo,Bc | enclose in square brackets: [text] | 
| Brq,Bro,Brc | enclose in curly braces: {text} | 
| Aq,Ao,Ac | enclose in angle brackets: ⟨text⟩ | 
| Eo,Ec | generic enclosure | 
| Ex-std | standard command exit values: [utility ...] | 
| Rv-std | standard function return values: [function ...] | 
| St | reference to a standards document (one argument) | 
| At | AT&T UNIX | 
| Bx | BSD | 
| Bsx | BSD/OS | 
| Nx | NetBSD | 
| Fx | FreeBSD | 
| Ox | OpenBSD | 
| Dx | DragonFly | 
%A
    first_name ... last_nameRs block. Multiple authors
      should each be accorded their own %A line. Author
      names should be ordered with full or abbreviated forename(s) first, then
      full surname.%B
    titleRs block. This macro may also be
      used in a non-bibliographic context when referring to book titles.%C
    locationRs block.%D
    [month day,] yearRs block. Provide the full
      English name of the month and all four digits of the
      year.%I
    nameRs block.%J
    nameRs block.%N
    numberRs
      block.%O
    lineRs block.%P
    numberRs block.%Q
    nameRs block. Multiple institutional authors should
      each be accorded their own %Q line.%R
    nameRs block.%T
    titleRs block. This macro may also
      be used in a non-bibliographical context when referring to article
    titles.%U
    protocol://path%V
    numberRs block.AcAo block. Does not have any tail
      arguments.Ad
    addressExamples:
.Ad [0,$].Ad 0x00000000An
    -split |
    -nosplit
    | first_name ... last_nameThe default is -nosplit. The effect of
        selecting either of the -split modes ends at the
        beginning of the AUTHORS section. In the
        AUTHORS section, the default is
        -nosplit for the first author listing and
        -split for all other author listings.
Examples:
.An -nosplit.An Kristaps Dzonsons Aq Mt
      kristaps@bsd.lvAo
    blockAq for more details.ApExamples:
.Fn execve Ap dAq
    lineMt for an
      example.
    Occasionally, it is used for names of characters and keys, for example:
Press the
.Aq escape
key to ...
    
    For URIs, use Lk instead, and
        In for “#include” directives.
        Never wrap Ar in Aq.
Since Aq usually renders with
        non-ASCII characters in non-ASCII output modes, do not use it where the
        ASCII characters ‘<’ and ‘>’ are
        required as syntax elements. Instead, use these characters directly in
        such cases, combining them with the macros Pf,
        Ns, or Eo as needed.
See also Ao.
Ar
    [placeholder ...]Examples:
.Fl o Ar file.Ar.Ar arg1 , arg2 .The arguments to the Ar macro are
        names and placeholders for command arguments; for fixed strings to be
        passed verbatim as arguments, use Fl or
        Cm.
At
    [version]Note that these arguments do not begin with a hyphen.
Examples:
.At.At III.At V.1See also Bsx,
        Bx, Dx,
        Fx, Nx, and
        Ox.
BcBo block. Does not have any tail
      arguments.Bd
    -type
    [-offset width]
    [-compact]The type must be one of the following:
-centeredmdoc implementations render it poorly.-filled-literal-ragged-unfilled-literal, but using the same font
          as for normal text, which is a variable width font if supported by the
          output device.The type must be provided first. Additional arguments may follow:
-offset
        widthindent, the
              width of a standard indentation (six constant width characters);
              indent-two, twice
              indent; left,
              which has no effect; right, which
              justifies to the right margin; or center,
              which aligns around an imagined center axis.When the argument is missing,
            -offset is ignored.
-compactExamples:
.Bd -literal -offset indent -compact
   Hello       world.
.Ed
    
    See also D1 and
        Dl.
Bf
    -emphasis |
    -literal
    |
    -symbolic
    | Em
    | Li
    |
    Sy-emphasis and Em argument
      are equivalent, as are -symbolic and
      Sy, and -literal and
      Li. Without an argument, this macro does nothing.
      The font mode continues until broken by a new font mode in a nested scope
      or Ef is encountered.
    See also Li,
        Ef, Em, and
        Sy.
Bk
    -wordsThe -words argument is required;
        additional arguments are ignored.
The following example will not break within each
        Op macro line:
.Bk -words
.Op Fl f Ar flags
.Op Fl o Ar output
.Ek
    
    Be careful in using over-long lines within a keep block! Doing so will clobber the right margin.
Bl
    -type
    [-width val]
    [-offset val]
    [-compact] [col ...]It macro, containing a head or a body or both.
    The list type is mandatory and must be
        specified first. The -width and
        -offset arguments accept macro names as
        described for Bd
        -offset, scaling widths as described in
        roff(7), or use the length
        of the given string. The -offset is a global
        indentation for the whole list, affecting both item heads and bodies.
        For those list types supporting it, the -width
        argument requests an additional indentation of item bodies, to be added
        to the -offset. Unless the
        -compact argument is specified, list entries are
        separated by vertical space.
A list must specify one of the following list types:
-bullet-width argument.-column-width argument has no
          effect; instead, the string length of each argument specifies the
          width of one column. If the first line of the body of a
          -column list is not an
          It macro line, It
          contexts spanning one input line each are implied until an
          It macro line is encountered, at which point
          items start being interpreted as described in the
          It documentation.-dash-bullet, except that dashes are used in
          place of bullets.-diag-inset, except that item heads are not
          parsed for macro invocations. Most often used in the
          DIAGNOSTICS section with error constants in the item
          heads.-enum-bullet, except that cardinal numbers are used
          in place of bullets, starting at 1.-hang-tag, except that the first lines of item
          bodies are not indented, but follow the item heads like in
          -inset lists.-hyphen-dash.-inset-width argument is ignored.-item-width argument is
        ignored.-ohang-width argument is ignored.-tag-width argument. When an item head fits inside
          the indentation, the item body follows this head on the same output
          line. Otherwise, the body starts on the output line following the
          head.Lists may be nested within lists and displays. Nesting of
        -column and -enum lists
        may not be portable.
See also El and
        It.
Bo
    blockExamples:
.Bo 1 ,
.Dv BUFSIZ Bc
    
    See also Bq.
Bq
    lineExamples:
.Bq 1, Dv BUFSIZRemarks: this macro is sometimes abused to
        emulate optional arguments for commands; the correct macros to use for
        this purpose are Op, Oo,
        and Oc.
See also Bo.
BrcBro block. Does not have any tail
      arguments.Bro
    blockExamples:
.Bro 1 , ... ,
.Va n Brc
    
    See also Brq.
Brq
    lineExamples:
.Brq 1, ..., Va nSee also Bro.
Bsx
    [version]Examples:
.Bsx 1.0.BsxSee also At,
        Bx, Dx,
        Fx, Nx, and
        Ox.
BtBx
    [version [variant]]Examples:
.Bx 4.3 Tahoe.Bx 4.4.BxSee also At,
        Bsx, Dx,
        Fx, Nx, and
        Ox.
Cd
    lineExamples:
.Cd device le0 at
      scode?Remarks: this macro is commonly abused by
        using quoted literals to retain whitespace and align consecutive
        Cd declarations. This practise is
      discouraged.
Cm
    keyword ...Fl is more appropriate. Also useful when
      specifying configuration options or keys.
    Examples:
.Nm mt Fl f Ar device Cm
      rewind.Nm ps Fl o Cm pid , Ns Cm
      command.Nm dd Cm if= Ns Ar file1 Cm of=
      Ns Ar file2.Cm IdentityFile Pa
      ~/.ssh/id_rsa.Cm LogLevel Dv
      DEBUGD1
    lineExamples:
.D1 Fl abcdefghSee also Bd and
        Dl.
DbDcDo block. Does not have any tail
      arguments.Dd
    $Mdocdate$ | month day,
    yearmdoc manual.
    The month is the full English month name, the day is an integer number, and the year is the full four-digit year.
Other arguments are not portable; the mandoc(1) utility handles them as follows:
Examples:
.Dd $Mdocdate$.Dd $Mdocdate: July 2
      2018$.Dd July 2, 2018See also Dt and
        Os.
Dl
    lineExamples:
.Dl % mandoc mdoc.7 \(ba
      lessSee also Ql,
        Bd -literal, and
        D1.
Do
    blockExamples:
.Do
April is the cruellest month
.Dc
\(em T.S. Eliot
    
    See also Dq.
Dq
    lineExamples:
.Dq April is the cruellest month
\(em T.S. Eliot
    
    See also Qq,
        Sq, and Do.
Dt
    TITLE section [arch]mdoc file.
    Its arguments are as follows:
1
          (General Commands), 2 (System Calls),
          3 (Library Functions),
          3p (Perl Library), 4
          (Device Drivers), 5 (File Formats),
          6 (Games), 7
          (Miscellaneous Information), 8 (System
          Manager's Manual), or 9 (Kernel Developer's
          Manual). It should correspond to the manual's filename suffix and
          defaults to the empty string if unspecified.alpha,
          amd64, i386, or
          sparc64. The list of valid architectures
          varies by operating system.Examples:
.Dt FOO 1.Dt FOO 9 i386See also Dd and
        Os.
Dv
    identifier ...Examples:
.Dv NULL.Dv BUFSIZ.Dv STDOUT_FILENOSee also Er and
        Ev for special-purpose constants,
        Va for variable symbols, and
        Fd for listing preprocessor variable definitions
        in the SYNOPSIS.
Dx
    [version]Examples:
.Dx 2.4.1.DxSee also At,
        Bsx, Bx,
        Fx, Nx, and
        Ox.
Ec
    [closing_delimiter]Eo.
    The closing_delimiter argument is used
        as the enclosure tail, for example, specifying \(rq will emulate
        Dc.
EdBd.EfBf.EkBk.ElBl. See also
      It.Em
    word ...This is most often used for stress emphasis (not to be
        confused with importance, see Sy). In the rare
        cases where none of the semantic markup macros fit, it can also be used
        for technical terms and placeholders, except that for syntax elements,
        Sy and Ar are preferred,
        respectively.
Examples:
Selected lines are those
.Em not
matching any of the specified patterns.
Some of the functions use a
.Em hold space
to save the pattern space for subsequent retrieval.
    
    See also No,
        Ql, and Sy.
En
    word ...Eo or any of the other
      enclosure macros.
    It encloses its argument in the delimiters specified by the
        last Es macro.
Eo
    [opening_delimiter]Do.Er
    identifier ...Examples:
.Er EPERM.Er ENOENTSee also Dv for general constants.
Es
    opening_delimiter closing_delimiterEo or any of the other
      enclosure macros.
    It takes two arguments, defining the delimiters to be used by
        subsequent En macros.
Ev
    identifier ...Examples:
.Ev DISPLAY.Ev PATHSee also Dv for general constants.
Ex
    -std [utility ...]If utility is not specified, the
        document's name set by Nm is used. Multiple
        utility arguments are treated as separate
        utilities.
See also Rv.
Fa
    argument ...Fa macro.
    This macro is also used to specify the field name of a structure.
Most often, the Fa macro is used in
        the SYNOPSIS within Fo blocks
        when documenting multi-line function prototypes. If invoked with
        multiple arguments, the arguments are separated by a comma. Furthermore,
        if the following macro is another Fa, the last
        argument will also have a trailing comma.
Examples:
.Fa "const char
      *p".Fa "int a" "int
      b" "int c".Fa "char *"
      size_tSee also Fo.
FcFo.Fd
    #directive [argument ...]In.
    Examples:
.Fd #define sa_handler
      __sigaction_u.__sa_handler.Fd #define
      SIO_MAXNFDS.Fd #ifdef FS_DEBUG.Ft void.Fn dbg_open "const char
      *".Fd #endifSee also MANUAL
        STRUCTURE, In, and
        Dv.
Fl
    [word ...]Examples:
.Fl R Op Fl H | L |
      P.Op Fl
      1AaCcdFfgHhikLlmnopqRrSsTtux.Fl type Cm d Fl name Pa
      CVS.Fl Ar signal_number.Fl o FlSee also Cm.
Fn
    funcname [argument ...]Function arguments are surrounded in parenthesis and are delimited by commas. If no arguments are specified, blank parenthesis are output. In the SYNOPSIS section, this macro starts a new output line, and a blank line is automatically inserted between function definitions.
Examples:
.Fn "int funcname"
      "int arg0" "int arg1".Fn funcname "int
      arg0".Fn funcname arg0
.Ft functype
.Fn funcname
    
    When referring to a function documented in another manual
        page, use Xr instead. See also
        MANUAL STRUCTURE,
        Fo, and Ft.
Fo
    funcnameFn.
    Invocations usually occur in the following context:
Ft
      functype
    Fo funcname
    Fa “argtype
      argname”
    FcA Fo scope is closed by
        Fc.
See also MANUAL
        STRUCTURE, Fa, Fc,
        and Ft.
Fr
    numberIt was used to show numerical function return values in an italic font.
Ft
    functypeIn the SYNOPSIS section, a new output line is started after this macro.
Examples:
.Ft int
.Ft functype
.Fn funcname
    
    See also MANUAL
        STRUCTURE, Fn, and
        Fo.
Fx
    [version]Examples:
.Fx 7.1.FxSee also At,
        Bsx, Bx,
        Dx, Nx, and
        Ox.
Hf
    filenameIc
    keyword ...Cm but used for instructions rather than values.
    Examples:
.Ic :wq.Ic hash.Ic aliasNote that using Ql,
        Dl, or Bd
        -literal is preferred for displaying code
        samples; the Ic macro is used when referring to
        an individual command name.
In
    filenameWhen invoked as the first macro on an input line in the SYNOPSIS section, the argument is displayed in angle brackets and preceded by “#include”, and a blank line is inserted in front if there is a preceding function declaration. In other sections, it only encloses its argument in angle brackets and causes no line break.
Examples:
.In sys/types.hSee also MANUAL STRUCTURE.
It
    [head]Lists of type -hang,
        -ohang, -inset, and
        -diag have the following syntax:
It
      argsLists of type -bullet,
        -dash, -enum,
        -hyphen and -item have
        the following syntax:
Itwith subsequent lines interpreted within the scope of the
        It until either a closing
        El or another It.
The -tag list has the following
        syntax:
It
      [args]Subsequent lines are interpreted as with
        -bullet and family. The line arguments
        correspond to the list's left-hand side; body arguments correspond to
        the list's contents.
The -column list is the most
        complicated. Its syntax is as follows:
It
      cell [Ta
      cell ...]It
      cell [<TAB> cell
      ...]The arguments consist of one or more lines of text and macros
        representing a complete table line. Cells within the line are delimited
        by the special Ta block macro or by literal tab
        characters.
Using literal tabs is strongly discouraged because they are
        very hard to use correctly and mdoc code using
        them is very hard to read. In particular, a blank character is
        syntactically significant before and after the literal tab character. If
        a word precedes or follows the tab without an intervening blank, that
        word is never interpreted as a macro call, but always output
      literally.
The tab cell delimiter may only be used within the
        It line itself; on following lines, only the
        Ta macro can be used to delimit cells, and
        portability requires that Ta is called by other
        macros: some parsers do not recognize it when it appears as the first
        macro on a line.
Note that quoted strings may span tab-delimited cells on an
        It line. For example,
.It "col1 , <TAB> col2
      ," ;will preserve the whitespace before both commas, but not the whitespace before the semicolon.
See also Bl.
Lb
    libnameThe name parameter may be a system
        library, such as z or
        pam, in which case a small library description
        is printed next to the linker invocation; or a custom library, in which
        case the library name is printed in quotes. This is most commonly used
        in the SYNOPSIS section as described in
        MANUAL STRUCTURE.
Examples:
.Lb libz.Lb libmandocLi
    word ...Ql (in-line),
      Dl (single line), or Bd
      -literal (multi-line) instead.Lk
    uri [display_name]Examples:
.Lk http://bsd.lv "The
      BSD.lv Project".Lk http://bsd.lvSee also Mt.
LpPp.Ms
    nameExamples:
.Ms sigma.Ms alephMt
    localpart@domainExamples:
.Mt
      discuss@manpages.bsd.lv.An Kristaps Dzonsons Aq Mt
      kristaps@bsd.lvNd
    lineExamples:
.Nd mdoc
      language reference.Nd format and
      display UNIX manualsThe Nd macro technically accepts child
        macros and terminates with a subsequent Sh
        invocation. Do not assume this behaviour: some
        whatis(1) database
        generators are not smart enough to parse more than the line arguments
        and will display macros verbatim.
See also Nm.
Nm
    [name]Nm macro
      expects a single argument, the name of the manual page. Usually, the first
      invocation happens in the NAME section of the page. The
      specified name will be remembered and used whenever the macro is called
      again without arguments later in the page. The Nm
      macro uses Block
      full-implicit semantics when invoked as the first macro on an input
      line in the SYNOPSIS section; otherwise, it uses
      ordinary In-line semantics.
    Examples:
.Sh SYNOPSIS
.Nm cat
.Op Fl benstuv
.Op Ar
    
    In the SYNOPSIS of section 2, 3 and 9 manual
        pages, use the Fn macro rather than
        Nm to mark up the name of the manual page.
No
    word ...Em or
      Sy, switches back to the standard font face and
      weight. Can also be used to embed plain text strings in macro lines using
      semantic annotation macros.
    Examples:
.Em italic , Sy bold , No and
      roman
.Sm off
.Cm :C No / Ar pattern No / Ar replacement No /
.Sm on
    
    See also Em,
        Ql, and Sy.
NsNo macro.
    This has no effect when invoked at the start of a macro line.
Examples:
.Ar name Ns = Ns Ar
      value.Cm :M Ns Ar pattern.Fl o Ns Ar outputSee also No and
        Sm.
Nx
    [version]Examples:
.Nx 5.01.NxSee also At,
        Bsx, Bx,
        Dx, Fx, and
        Ox.
OcOo context.Oo
    blockOp.
    Examples:
.Oo
.Op Fl flag Ns Ar value
.Oc
    
    Op
    lineExamples:
.Op Fl a Ar b.Op Ar a | bSee also Oo.
Os
    [system [version]]mdoc file.
    The optional system parameter specifies
        the relevant operating system or environment. It is suggested to leave
        it unspecified, in which case
        mandoc(1) uses its
        -Ios argument or, if that isn't specified
        either, sysname and release
        as returned by
      uname(3).
Examples:
.Os.Os KTH/CSC/TCS.Os BSD 4.3See also Dd and
        Dt.
Ot
    functypeFt instead; with
      mandoc(1), both have the
      same effect.
    Historical mdoc packages described it
        as “old function type (FORTRAN)”.
Ox
    [version]Examples:
.Ox 4.5.OxSee also At,
        Bsx, Bx,
        Dx, Fx, and
        Nx.
Pa
    name ...Examples:
.Pa /usr/bin/mandoc.Pa
      /usr/share/man/man7/mdoc.7See also Lk.
PcPo.Pf
    prefix macro [argument ...]No
      \&prefix Ns
      macro [argument ...]The prefix argument is not parsed for macro names or delimiters, but used verbatim as if it were escaped.
Examples:
.Pf $ Ar
      variable_name.Pf . Ar macro_name.Pf 0x Ar hex_digitsSee also Ns and
        Sm.
Po
    blockPq.PpParagraph breaks are not needed before or after
        Sh or Ss macros or
        before displays (Bd line)
        or lists (Bl) unless the
        -compact flag is given.
Pq
    lineSee also Po.
QcQo.Ql
    lineSee also Dl and
        Bd -literal.
Qo
    blockQq.Qq
    lineDq.
    See also Dq,
        Sq, and Qo.
ReRs block. Does not have any tail
      arguments.Rs%A, %B,
      %C, %D,
      %I, %J,
      %N, %O,
      %P, %Q,
      %R, %T,
      %U, and %V child macros
      (at least one must be specified).
    Examples:
.Rs
.%A J. E. Hopcroft
.%A J. D. Ullman
.%B Introduction to Automata Theory, Languages, and Computation
.%I Addison-Wesley
.%C Reading, Massachusetts
.%D 1979
.Re
    
    If an Rs block is used within a SEE
        ALSO section, a vertical space is asserted before the rendered output,
        else the block continues on the current line.
Rv
    -std [function ...]If function is not specified, the
        document's name set by Nm is used. Multiple
        function arguments are treated as separate
        functions.
See also Ex.
ScSo.Sh
    TITLE LINESection names should be unique so that they may be keyed by
        Sx. Although this macro is parsed, it should not
        consist of child node or it may not be linked with
        Sx.
See also Pp,
        Ss, and Sx.
Sm
    [on | off]By default, spacing is on. When
        switched off, no white space is inserted between
        macro arguments and between the output generated from adjacent macros,
        but text lines still get normal spacing between words and sentences.
When called without an argument, the
        Sm macro toggles the spacing mode. Using this is
        not recommended because it makes the code harder to read.
So
    blockSq.Sq
    lineSee also Dq,
        Qq, and So.
Ss
    Title lineSh, there is
      no convention for the naming of subsections. Except
      DESCRIPTION, the conventional sections described in
      MANUAL STRUCTURE rarely have
      subsections.
    Sub-section names should be unique so that they may be keyed
        by Sx. Although this macro is parsed, it should
        not consist of child node or it may not be linked with
        Sx.
See also Pp,
        Sh, and Sx.
St
    -abbreviationSx
    Title lineExamples:
.Sx MANUAL STRUCTURESee also Sh and
        Ss.
Sy
    word ...This is most often used to indicate importance or seriousness
        (not to be confused with stress emphasis, see
        Em). When none of the semantic macros fit, it is
        also adequate for syntax elements that have to be given or that appear
        verbatim.
Examples:
.Sy Warning :
If
.Sy s
appears in the owner permissions, set-user-ID mode is set.
This utility replaces the former
.Sy dumpdir
program.
    
    See also Em,
        No, and Ql.
TaBl
      -column lists; can only be used below
      It.Tn
    word ...UdUxVa
    [type] identifier ...Examples:
.Va foo.Va const char *bar;For function arguments and parameters, use
        Fa instead. For declarations of global variables
        in the SYNOPSIS section, use
        Vt.
Vt
    type [identifier]This is also used for indicating global variables in the SYNOPSIS section, in which case a variable name is also specified. Note that it accepts Block partial-implicit syntax when invoked as the first macro on an input line in the SYNOPSIS section, else it accepts ordinary In-line syntax. In the former case, this macro starts a new output line, and a blank line is inserted in front if there is a preceding function definition or include directive.
Examples:
.Vt unsigned char.Vt extern const char * const
      sys_signame[] ;For parameters in function prototypes, use
        Fa instead, for function return types
        Ft, and for variable names outside the
        SYNOPSIS section Va, even when
        including a type with the name. See also
        MANUAL STRUCTURE.
XcXo.Xo
    blockIt macro or the body of a
      partial-implicit block macro beyond the end of the input line. This macro
      originally existed to work around the 9-argument limit of historic
      roff(7).Xr
    name sectionCross reference the name and section number of another man page.
Examples:
.Xr mandoc 1.Xr mandoc 1 ;.Xr mandoc 1 Ns s
      behaviourThe Callable column indicates that the macro may
    also be called by passing its name as an argument to another macro. For
    example, ‘.Op Fl O Ar file’ produces
    ‘[-O file]’. To
    prevent a macro call and render the macro name literally, escape it by
    prepending a zero-width space, ‘\&’. For example,
    ‘Op \&Fl O’ produces ‘[Fl O]’. If a macro is
    not callable but its name appears as an argument to another macro, it is
    interpreted as opaque text. For example, ‘.Fl Sh’ produces
    ‘-Sh’.
The Parsed column indicates whether the macro may call other macros by receiving their names as arguments. If a macro is not parsed but the name of another macro appears as an argument, it is interpreted as opaque text.
The Scope column, if applicable, describes closure rules.
Bf and (optionally)
  Bl contain a head.
.Yo [-arg [parm...]] [head...] [body...] .Yc
| Macro | Callable | Parsed | Scope | 
| Bd | No | No | closed by Ed | 
| Bf | No | No | closed by Ef | 
| Bk | No | No | closed by Ek | 
| Bl | No | No | closed by El | 
| Ed | No | No | opened by Bd | 
| Ef | No | No | opened by Bf | 
| Ek | No | No | opened by Bk | 
| El | No | No | opened by Bl | 
It
  -bullet, -hyphen,
  -dash, -enum,
  -item) don't have heads; only one
  (It in Bl
  -column) has multiple heads.
.Yo [-arg [parm...]] [head... [Ta head...]] [body...]
| Macro | Callable | Parsed | Scope | 
| It | No | Yes | closed by It,El | 
| Nd | No | No | closed by Sh | 
| Nm | No | Yes | closed by Nm,Sh,Ss | 
| Sh | No | Yes | closed by Sh | 
| Ss | No | Yes | closed by Sh,Ss | 
Note that the Nm macro is a
    Block full-implicit macro only
    when invoked as the first macro in a SYNOPSIS section
    line, else it is In-line.
Fo,
  Eo) and/or tail (Ec).
.Yo [-arg [parm...]] [head...] [body...] .Yc [tail...] .Yo [-arg [parm...]] [head...] [body...] Yc [tail...]
| Macro | Callable | Parsed | Scope | 
| Ac | Yes | Yes | opened by Ao | 
| Ao | Yes | Yes | closed by Ac | 
| Bc | Yes | Yes | closed by Bo | 
| Bo | Yes | Yes | opened by Bc | 
| Brc | Yes | Yes | opened by Bro | 
| Bro | Yes | Yes | closed by Brc | 
| Dc | Yes | Yes | opened by Do | 
| Do | Yes | Yes | closed by Dc | 
| Ec | Yes | Yes | opened by Eo | 
| Eo | Yes | Yes | closed by Ec | 
| Fc | Yes | Yes | opened by Fo | 
| Fo | No | No | closed by Fc | 
| Oc | Yes | Yes | closed by Oo | 
| Oo | Yes | Yes | opened by Oc | 
| Pc | Yes | Yes | closed by Po | 
| Po | Yes | Yes | opened by Pc | 
| Qc | Yes | Yes | opened by Oo | 
| Qo | Yes | Yes | closed by Oc | 
| Re | No | No | opened by Rs | 
| Rs | No | No | closed by Re | 
| Sc | Yes | Yes | opened by So | 
| So | Yes | Yes | closed by Sc | 
| Xc | Yes | Yes | opened by Xo | 
| Xo | Yes | Yes | closed by Xc | 
.Yo [-arg [val...]] [body...] [res...]
| Macro | Callable | Parsed | 
| Aq | Yes | Yes | 
| Bq | Yes | Yes | 
| Brq | Yes | Yes | 
| D1 | No | Yes | 
| Dl | No | Yes | 
| Dq | Yes | Yes | 
| En | Yes | Yes | 
| Op | Yes | Yes | 
| Pq | Yes | Yes | 
| Ql | Yes | Yes | 
| Qq | Yes | Yes | 
| Sq | Yes | Yes | 
| Vt | Yes | Yes | 
Note that the Vt macro is a
    Block partial-implicit only
    when invoked as the first macro in a SYNOPSIS section
    line, else it is In-line.
Ta macro can only be used below
  It in Bl
  -column lists. It delimits blocks representing table
  cells; these blocks have bodies, but no heads.
| Macro | Callable | Parsed | Scope | 
| Ta | Yes | Yes | closed by Ta,It | 
.Yo [-arg [val...]] [args...] [res...] .Yo [-arg [val...]] [args...] Yc... .Yo [-arg [val...]] arg0 arg1 argN
| Macro | Callable | Parsed | Arguments | 
| %A | No | No | >0 | 
| %B | No | No | >0 | 
| %C | No | No | >0 | 
| %D | No | No | >0 | 
| %I | No | No | >0 | 
| %J | No | No | >0 | 
| %N | No | No | >0 | 
| %O | No | No | >0 | 
| %P | No | No | >0 | 
| %Q | No | No | >0 | 
| %R | No | No | >0 | 
| %T | No | No | >0 | 
| %U | No | No | >0 | 
| %V | No | No | >0 | 
| Ad | Yes | Yes | >0 | 
| An | Yes | Yes | >0 | 
| Ap | Yes | Yes | 0 | 
| Ar | Yes | Yes | n | 
| At | Yes | Yes | 1 | 
| Bsx | Yes | Yes | n | 
| Bt | No | No | 0 | 
| Bx | Yes | Yes | n | 
| Cd | Yes | Yes | >0 | 
| Cm | Yes | Yes | >0 | 
| Db | No | No | 1 | 
| Dd | No | No | n | 
| Dt | No | No | n | 
| Dv | Yes | Yes | >0 | 
| Dx | Yes | Yes | n | 
| Em | Yes | Yes | >0 | 
| Er | Yes | Yes | >0 | 
| Es | Yes | Yes | 2 | 
| Ev | Yes | Yes | >0 | 
| Ex | No | No | n | 
| Fa | Yes | Yes | >0 | 
| Fd | No | No | >0 | 
| Fl | Yes | Yes | n | 
| Fn | Yes | Yes | >0 | 
| Fr | Yes | Yes | >0 | 
| Ft | Yes | Yes | >0 | 
| Fx | Yes | Yes | n | 
| Hf | No | No | n | 
| Ic | Yes | Yes | >0 | 
| In | No | No | 1 | 
| Lb | No | No | 1 | 
| Li | Yes | Yes | >0 | 
| Lk | Yes | Yes | >0 | 
| Lp | No | No | 0 | 
| Ms | Yes | Yes | >0 | 
| Mt | Yes | Yes | >0 | 
| Nm | Yes | Yes | n | 
| No | Yes | Yes | >0 | 
| Ns | Yes | Yes | 0 | 
| Nx | Yes | Yes | n | 
| Os | No | No | n | 
| Ot | Yes | Yes | >0 | 
| Ox | Yes | Yes | n | 
| Pa | Yes | Yes | n | 
| Pf | Yes | Yes | 1 | 
| Pp | No | No | 0 | 
| Rv | No | No | n | 
| Sm | No | No | <2 | 
| St | No | Yes | 1 | 
| Sx | Yes | Yes | >0 | 
| Sy | Yes | Yes | >0 | 
| Tn | Yes | Yes | >0 | 
| Ud | No | No | 0 | 
| Ux | Yes | Yes | n | 
| Va | Yes | Yes | n | 
| Vt | Yes | Yes | >0 | 
| Xr | Yes | Yes | 2 | 
For many macros, when the leading arguments are opening delimiters, these delimiters are put before the macro scope, and when the trailing arguments are closing delimiters, these delimiters are put after the macro scope. Spacing is suppressed after opening delimiters and before closing delimiters. For example,
renders as:
Opening delimiters are:
Closing delimiters are:
Note that even a period preceded by a backslash (‘\.’) gets this special handling; use ‘\&.’ to prevent that.
Many in-line macros interrupt their scope when they encounter delimiters, and resume their scope when more arguments follow that are not delimiters. For example,
renders as:
-a (-b
  | -c | -d)
  -eThis applies to both opening and closing delimiters, and also to the middle delimiter, which does not suppress spacing:
As a special case, the predefined string \*(Ba is handled and rendered in the same way as a plain ‘|’ character. Using this predefined string is not recommended in new manuals.
mdoc documents, usage of semantic markup is
  recommended in order to have proper fonts automatically selected; only when no
  fitting semantic markup is available, consider falling back to
  Physical markup macros. Whenever any
  mdoc macro switches the
  roff(7) font mode, it will
  automatically restore the previous font when exiting its scope. Manually
  switching the font using the
  roff(7)
  ‘\f’ font escape sequences is never
  required.
The following problematic behaviour is found in groff:
Dd
      with non-standard arguments behaves very strangely. When there are three
      arguments, they are printed verbatim. Any other number of arguments is
      replaced by the current date, but without any arguments the string
      “Epoch” is printed.Lk
      only accepts a single link-name argument; the remainder is
    misformatted.Pa
      does not format its arguments when used in the FILES section under certain
      list types.Ta
      can only be called by other macros, but not at the beginning of a
    line.%C
      is not implemented (up to and including groff-1.22.2).The following features are unimplemented in mandoc:
Bd
      -file file is unsupported
      for security reasons.Bd
      -filled does not adjust the right margin, but is
      an alias for Bd
    -ragged.Bd
      -literal does not use a literal font, but is an
      alias for Bd
    -unfilled.Bd
      -offset center and
      -offset right don't work.
      Groff does not implement centered and flush-right rendering either, but
      produces large indentations.The web page extended documentation for the mdoc language provides a few tutorial-style pages for beginners, an extensive style guide for advanced authors, and an alphabetic index helping to choose the best macros for various kinds of content.
mdoc language first appeared as a troff macro
  package in 4.4BSD. It was later significantly updated
  by Werner Lemberg and Ruslan Ermilov in groff-1.17. The standalone
  implementation that is part of the
  mandoc(1) utility written by
  Kristaps Dzonsons appeared in OpenBSD 4.6.
mdoc reference was written by
  Kristaps Dzonsons
  <kristaps@bsd.lv>.
| February 7, 2019 | NetBSD 10.0 |