| MANDOC(1) | General Commands Manual | MANDOC(1) | 
mandoc —
| mandoc | [ -ac] [-Ios=name]
      [-Kencoding]
      [-mdoc|-man]
      [-Ooptions]
      [-Toutput]
      [-Wlevel]
      [file ...] | 
mandoc utility formats manual pages for display.
By default, mandoc reads
    mdoc(7) or
    man(7) text from stdin and
    produces -T locale
  output.
The options are as follows:
-a-c
      is not specified, use more(1)
      to paginate the output, just like
      man(1) would.-c-a.-I
    os=nameOs and for the
      man(7)
      TH macro.-K
    encodingus-ascii,
      iso-8859-1, and utf-8. If
      not specified, autodetection uses the first match in the following list:
    utf-8.then input is interpreted according to encoding.
utf-8.iso-8859-1.-mdoc
    |
    -man-mdoc, all input files are interpreted as
      mdoc(7). With
      -man, all input files are interpreted as
      man(7). By default, the input
      language is automatically detected for each file: if the first macro is
      Dd or Dt, the
      mdoc(7) parser is used;
      otherwise, the man(7) parser is
      used. With other arguments, -m is silently
      ignored.-O
    options-T
    outputascii,
      html, the default of
      locale, man,
      markdown, pdf,
      ps, tree, and
      utf8.
    The special -T
        lint mode only parses the input and produces no
        output. It implies -W
        all and redirects parser messages, which usually
        appear on standard error output, to standard output.
-W
    levelbase,
      style, warning,
      error, or unsupp. The
      base level automatically derives the operating
      system from the contents of the Os macro, from the
      -Ios command line option, or from the
      uname(3) return value. The
      levels openbsd and netbsd
      are variants of base that bypass autodetection and
      request validation of base system conventions for a particular operating
      system. The level all is an alias for
      base. By default, mandoc
      is silent. See EXIT STATUS and
      DIAGNOSTICS for details.
    The special option -W
        stop tells mandoc to
        exit after parsing a file that causes warnings or errors of at least the
        requested level. No formatted output will be produced from that file. If
        both a level and stop are
        requested, they can be joined with a comma, for example
        -W
        error,stop.
mandoc reads from standard input.The options -fhklw are also supported and
    are documented in man(1). In -f and
    -k mode, mandoc also
    supports the options -CMmOSs described in the
    apropos(1) manual. The
    options -fkl are mutually exclusive and override
    each other.
-T ascii to force text
  output in 7-bit ASCII character encoding documented in the
  ascii(7) manual page, ignoring
  the locale(1) set in the
  environment.
Font styles are applied by using back-spaced encoding such that an
    underlined character ‘c’ is rendered as
    ‘_\[bs]c’, where ‘\[bs]’ is the back-space
    character number 8. Emboldened characters are rendered as
    ‘c\[bs]c’. This markup is typically converted to appropriate
    terminal sequences by the pager or
    ul(1). To remove the markup, pipe
    the output to col(1)
    -b instead.
The special characters documented in mandoc_char(7) are rendered best-effort in an ASCII equivalent. In particular, opening and closing ‘single quotes’ are represented as characters number 0x60 and 0x27, respectively, which agrees with all ASCII standards from 1965 to the latest revision (2012) and which matches the traditional way in which roff(7) formatters represent single quotes in ASCII output. This correct ASCII rendering may look strange with modern Unicode-compatible fonts because contrary to ASCII, Unicode uses the code point U+0060 for the grave accent only, never for an opening quote.
The following -O arguments are
  accepted:
indent=indentmdoc-O
      indent=5. One useful application is for checking
      that -T man output formats
      in the same way as the mdoc(7)
      source it was generated from.tag[=term]man -akO tag
      Ic=ulimit’ to search for a keyword and jump right to its
      definition in the matching manual pages.width=width-T html
  conforms to HTML5 using optional self-closing tags. Default styles use only
  CSS1. Equations rendered from
  eqn(7) blocks use MathML.
The file /usr/share/misc/mandoc.css
    documents style-sheet classes available for customising output. If a
    style-sheet is not specified with -O
    style, -T
    html defaults to simple output (via an embedded
    style-sheet) readable in any graphical or text-based web browser.
Non-ASCII characters are rendered as hexadecimal Unicode character references.
The following -O arguments are
  accepted:
fragmentstyle argument will be ignored. This
      is useful when embedding manual content within existing documents.includes=fmtIn macro). Instances
      of ‘%I’ are replaced with the include filename. The default
      is not to present a hyperlink.man=fmt[;fmt]Xr macro).
      Instances of ‘%N’ and ‘%S’ are replaced with
      the linked manual's name and section, respectively. If no section is
      included, section 1 is assumed. The default is not to present a hyperlink.
      If two formats are given and a file %N.%S exists in
      the current directory, the first format is used; otherwise, the second
      format is used.style=style.csstocmandoc automatically selects UTF-8 or ASCII
  output according to the current
  locale(1). If any of the
  environment variables LC_ALL,
  LC_CTYPE, or LANG are set and
  the first one that is set selects the UTF-8 character encoding, it produces
  UTF-8 Output; otherwise, it falls back
  to ASCII Output. This output mode can
  also be selected explicitly with -T
  locale.
-T man to translate
  mdoc(7) input into
  man(7) output format. This is
  useful for distributing manual sources to legacy systems lacking
  mdoc(7) formatters.
If the input format of a file is
    man(7), the input is copied to
    the output, expanding any
    roff(7)
    so requests. The parser is also run, and as usual,
    the -W level controls which
    DIAGNOSTICS are displayed before
    copying the input to the output.
-T markdown to translate
  mdoc(7) input to the markdown
  format conforming to
  John
  Gruber's 2004 specification. The output also almost conforms to the
  CommonMark specification.
The character set used for the markdown output is ASCII. Non-ASCII characters are encoded as HTML entities. Since that is not possible in literal font contexts, because these are rendered as code spans and code blocks in the markdown output, non-ASCII characters are transliterated to ASCII approximations in these contexts.
Markdown is a very weak markup language, so all semantic markup is
    lost, and even part of the presentational markup may be lost. Do not use
    this as an intermediate step in converting to HTML; instead, use
    -T html directly.
The man(7),
    tbl(7), and
    eqn(7) input languages are not
    supported by -T markdown
    output mode.
-T
  pdf. See
  PostScript Output for
  -O arguments and defaults.
-T ps. Output pages default to
  letter sized and are rendered in the Times font family, 11-point. Margins are
  calculated as 1/9 the page length and width. Line-height is 1.4m.
Special characters are rendered as in ASCII Output.
The following -O arguments are
  accepted:
paper=name-T utf8 to force text output
  in UTF-8 multi-byte character encoding, ignoring the
  locale(1) settings in the
  environment. See ASCII Output regarding
  font styles and -O arguments.
On operating systems lacking locale or wide character support, and
    on those where the internal character representation is not UCS-4,
    mandoc always falls back to
    ASCII Output.
-T tree to show a human
  readable representation of the syntax tree. It is useful for debugging the
  source code of manual pages. The exact format is subject to change, so don't
  write parsers for it.
The first paragraph shows meta data found in the
    mdoc(7) prologue, on the
    man(7) TH
    line, or the fallbacks used.
In the tree dump, each output line shows one syntax tree node. Child nodes are indented with respect to their parent node. The columns are:
The following -O argument is accepted:
novalLC_CTYPEMANPAGERMANPAGER is used instead of the standard
      pagination program, more(1);
      see man(1) for details. Only
      used if -a or -l is
      specified.PAGERMANPAGER is not defined. If neither PAGER nor
      MANPAGER is defined, more(1)
      -s is used. Only used if
      -a or -l is
    specified.mandoc utility exits with one of the following
  values, controlled by the message level associated with
  the -W option:
-W
      base or -W
      style was specified.-W warning or a lower
      level was requested.-W error
      or a lower level was requested.-W unsupp or a lower
      level was requested.mandoc to exit at once, possibly in the middle of
      parsing or formatting a file.Note that selecting -T
    lint output mode implies -W
    all.
$ mandoc -l mandoc.1 man.1 apropos.1
  makewhatis.8To produce HTML manuals with /usr/share/misc/mandoc.css as the style-sheet:
$ mandoc -T html -O
  style=/usr/share/misc/mandoc.css mdoc.7 > mdoc.7.htmlTo check over a large set of manuals:
$ mandoc -T lint `find /usr/src -name
  \*\.[1-9]`To produce a series of PostScript manuals for A4 paper:
$ mandoc -T ps -O paper=a4 mdoc.7
  man.7 > manuals.psConvert a modern mdoc(7) manual to the older man(7) format, for use on systems lacking an mdoc(7) parser:
$ mandoc -T man foo.mdoc >
  foo.manmandoc follow this format:
mandoc:
  file:line:column:
  level: message:
  macro arguments (os)The first three fields identify the file name, line number, and column number of the input file where the message was triggered. The line and column numbers start at 1. Both are omitted for messages referring to an input file as a whole. All level and message strings are explained below. The name of the macro triggering the message and its arguments are omitted where meaningless. The os operating system specifier is omitted for messages that are relevant for all operating systems. Fatal messages about invalid command line arguments or operating system errors, for example when memory is exhausted, may also omit the file and level fields.
Message levels have the following meanings:
unsuppmandoc to process the file may be preferable.errorwarningstylestyle level tries to reduce
      the probability that issues go unnoticed, so it may occasionally issue
      bogus suggestions. Please use your good judgement to decide whether any
      particular style suggestion really justifies a
      change to the input file.basebase level are printed with the more intuitive
      style level tag.Messages of the base,
    style, warning,
    error, and unsupp levels
    except those about non-existent or unreadable input files are hidden unless
    their level, or a lower level, is requested using a
    -W option or -T
    lint output mode.
As indicated below, all base and some
    style checks are only performed if a specific
    operating system name occurs in the arguments of the
    -W command line option, of the
    Os macro, of the -Ios
    command line option, or, if neither are present, in the return value of the
    uname(3) function.
Dd
      macro uses CVS Mdocdate keyword substitution,
      which is not supported by the NetBSD base system.
      Consider using the conventional “Month dd, yyyy” format
      instead.Dd
      macro does not use CVS Mdocdate keyword
      substitution, but using it is conventionally expected in the
      OpenBSD base system.Dt macro does not match
      any of the architectures this operating system is running on.Os macro has an argument. In the base system,
      it is conventionally left blank.OpenBSD or NetBSD
      keyword substitution as conventionally used in these operating
    systems.Xr macro references a manual page that
      is not found in the base system. The path to look for base system manuals
      is configurable at compile time and defaults to
      /usr/share/man:
      /usr/X11R6/man.Dd macro uses the legacy
      man(7) date format
      “yyyy-dd-mm”. Consider using the conventional
      mdoc(7) date format
      “Month dd, yyyy” instead.Dd or TH
      macro provides an abbreviated month name or a day number with a leading
      zero. In the formatted output, the month name is written out in full and
      the leading zero is omitted.Dt or TH macro.Sh macro is similar, but not identical to a
      standard section name.Bt, Tn, or
      Ud macro was found. Simply delete it: it serves no
      useful purpose.Bx
      macro that could be represented using Ox,
      Nx, Fx, or
      Dx.Er
      items in a Bl list are not in alphabetical
    order.Bl list
      contains two consecutive It entries describing the
      same Er number.Ex,
      Fo, Nd,
      Nm, Os,
      Sh, Ss,
      St, or Sx macro ends with
      a trailing delimiter. This is usually bad style and often indicates typos.
      Most likely, the delimiter can be removed.fi request occurs even though the document
      is still in fill mode, or already switched back to fill mode. It has no
      effect.nf request occurs even though the
      document already switched to no-fill mode and did not switch back to fill
      mode yet. It has no effect.Fn or
      Xr macro.mandoc utility treats the line as a
      comment line even without the backslash, but leaving out the backslash
      might not be portable.Dt macro has no arguments, or there is no
      Dt macro before the first non-prologue macro.TH macro, or it has no
      arguments.Dt or TH
      macro lacks the mandatory section argument.Dt line is invalid,
      but still used.Dd macro, or the Dd macro
      has no arguments or only empty arguments; or the document was parsed as
      man(7) and it has no
      TH macro, or the TH macro
      has less than three arguments or its third argument is empty.Dd or
      TH macro does not follow the conventional
    format.Dd or
      TH macro is more than a day ahead of the current
      system time(3).Dd or Os macro
      occurs after some non-prologue macro, but still takes effect.Dd, Dt,
      Os. All three macros are used even when given in
      another order.Sh or SH section header.
      The offending macros and text are parsed and added to the top level of the
      syntax tree, outside any section block.Sh macro is not
      ‘NAME’. This may confuse
      makewhatis(8) and
      apropos(1).Nm
      child macro before the first Nd macro.Nd
      child macro.Nd child
      macro, but other content follows it.Nm and Nd.Nm macro that
      is neither the first one nor preceded by a comma.Nd macro lacks the required argument.
      The title line of the manual will end after the dash.Nd macro appears outside the NAME
      section. The arguments are printed anyway and the following text is used
      for apropos(1), but none of
      that behaviour is portable.Xr macro refers to a name and section
      matching the section of the present manual page and a name mentioned in an
      Nm macro in the NAME or SYNOPSIS section, or in an
      Fn or Fo macro in the
      SYNOPSIS. Consider using Nm or
      Fn instead of Xr.Xr macro with a
      lower section number follows one with a higher number, or two
      Xr macros referring to the same section are out of
      alphabetical order.Xr macros differs from a single comma, or there is
      trailing punctuation after the last Xr macro.An macros,
      or only empty ones. Probably, there are author names lacking markup.P, PP, and
          LP macrosIP macros having neither head nor body
          argumentsbr or sp right
          after SH or SSBl list contains a
      trailing paragraph macro. The paragraph macro is moved after the end of
      the list.Ns macro, or
      the next argument after an Ns macro is an isolated
      closing delimiter. The macro is ignored.Ao Bo Ac
      Bc” and “Ao Bq Ac”. In
      these examples, Ac breaks
      Bo and Bq,
    respectively.Bd, D1, or
      Dl display occurs nested inside another
      Bd display. This works with
      mandoc, but fails with most other
    implementations.Bl list block contains text or macros
      before the first It macro. The offending children
      are moved before the beginning of the list.Bl -column list,
      a Ta macro occurs as the first macro on a line,
      which is not portable.el clause.Bd, Bk,
      Bl, D1,
      Dl, MT,
      RS, or UR block contains
      nothing in its body and will produce no output.Bd or
      Bl -offset or
      -width.Bd macro is invoked without the
      required display type.Bl macro, at least one other argument
      precedes the type argument. The mandoc utility
      copes with any argument order, but some other
      mdoc(7) implementations do
      not.Bl macro having the
      -tag argument requires
      -width, too.Ex -std macro
      is called without an argument before Nm has first
      been called with an argument.Fo macro is called without an argument.
      No function name is printed.Bl -diag,
      -hang, -inset,
      -ohang, or -tag list, an
      It macro lacks the required argument. The item
      head is left empty.Bl -bullet,
      -dash, -enum, or
      -hyphen list, an It block
      is empty. An empty list item is shown.It macro in a Bd
      -column list has no arguments. While
      mandoc uses the text or macros of the following
      line, if any, for the cell, other formatters may misformat the list.Bf macro has no argument. It switches to
      the default font.Bf argument is invalid. The default
      font is used instead.Pf macro has no argument, or only one
      argument and no macro follows on the same input line. This defeats its
      purpose; in particular, spacing is not suppressed before the text or
      macros following on the next input line.Rs macro is immediately followed by an
      Re macro on the next input line. Such an empty
      block does not produce any output.Xr macro lacks its second, section
      number argument. The first argument, i.e. the name, is printed, but
      without subsequent parentheses.Ex or Rv macro
      lacks the required -std argument. The
      mandoc utility assumes
      -std even when it is not specified, but other
      implementations may not.OP macro is invoked without any
      argument. An empty pair of square brackets is shown.MT or UR macro
      is invoked without any argument. An empty pair of angle brackets is
    shown.Bd or Bl macro
      has more than one -compact, more than one
      -offset, or more than one
      -width argument. All but the last instances of
      these arguments are ignored.An macro has more than one
      -split or -nosplit
      argument. All but the first of these arguments are ignored.Bd macro has more than one type argument;
      the first one is used.Bl macro has more than one type argument;
      the first one is used.Bl -column,
      -diag, -ohang,
      -inset, or -item list has
      a -width argument. That has no effect.Bl -column
      list, the number of tabs or Ta macros is less than
      the number expected from the list header line or exceeds the expected
      number by more than one. Missing cells remain empty, and all cells
      exceeding the number of columns are joined into one single cell.At macro has an invalid argument. It is
      used verbatim, with “AT&T UNIX ” prefixed to it.Fa or
      Fn macro contains a comma; it should probably be
      split into two arguments.Fc or
      Fn macro contains an opening or closing
      parenthesis; that's probably wrong, parentheses are added
    automatically.Lb macro has an unknown name argument and will be
      rendered as “library
      “name””.Rs block contains plain text or non-%
      macros. The bogus content is left in the syntax tree. Formatting may be
      poor.Sm macro has an argument other than
      on or off. The invalid
      argument is moved out of the macro, which leaves the macro empty, causing
      it to toggle the spacing mode.char request
      contains more than one font escape sequence. A wrong font may remain
      active after using the character.ft request or a
      tbl(7)
      f layout modifier has an unknown
      font argument.tr request contains an odd number of
      characters. The last character is mapped to the blank character.sp requests.\* and \n
      expand to an empty string, \B to the digit
      ‘0’, and \w to the length of the
      incomplete argument. All other invalid escape sequences are ignored.s’). Data provided for this cell
      is ignored, and nothing is printed in the cell.^’). Data provided for this
      cell is ignored, and nothing is printed in the cell.s’) or vertical span
      (‘^’) in the table layout, but it
      contains data. The data is ignored.T{, but never
      closed with a matching T}. The remaining data
      lines of the table are all put into one cell, and any remaining cells stay
      empty.Dt macro appears after the first
      non-prologue macro. Traditional formatters cannot handle this because they
      write the page header before parsing the document body. Even though this
      technical restriction does not apply to mandoc,
      traditional semantics is preserved. The late macro is discarded including
      its arguments.so file inclusion.shift or return
      request occurs outside any macro definition and has no effect.It macro occurs outside any
      Bl list, or an
      eqn(7)
      above delimiter occurs outside any pile. It is
      discarded including its arguments.Ta macro occurs outside any
      Bl -column block. It is
      discarded including its arguments.ME, RE or
      UE macro, an
      eqn(7) right delimiter or
      closing brace, or the end of an equation, table, or
      roff(7) conditional request is
      encountered but no matching block is open. The offending request or macro
      is discarded.RE macro is invoked with an argument,
      but less than the specified number of RS blocks is
      open. The RE macro is discarded.MT, RS or
      UR block, an equation, table, or
      roff(7) conditional or ignore
      block is still open. The open block is closed implicitly.am, as,
      de, ds,
      nr, or rr request, or any
      argument of an rm request, or the name of a
      request or user defined macro being called, is terminated by an escape
      sequence. In the cases of as,
      ds, and nr, the request
      has no effect at all. In the cases of am,
      de, rr, and
      rm, what was parsed up to this point is used as
      the arguments to the request, and the rest of the input line is discarded
      including the escape sequence. When parsing for a request or a
      user-defined macro name to be called, only the escape sequence is
      discarded. The characters preceding it are used as the request or macro
      name, the characters following it are used as the arguments to the request
      or macro.Bd macro does not
      support the -file argument. By requesting the
      inclusion of a sensitive file, a malicious document might otherwise trick
      a privileged user into inadvertently displaying the file on the screen,
      revealing the file content to bystanders. The argument is ignored
      including the file name following it.Bd block macro does not have any
      arguments. The block is discarded, and the block content is displayed in
      whatever mode was active before the block.Bl macro fails to specify the list
    type.ce request is not a
      number.char request is
      neither a single ASCII character nor a single character escape sequence.
      The request is ignored including all its arguments.Nm, or any call in the
      NAME section, lacks the required argument.Os macro is called without arguments,
      and the uname(3) system call
      failed. As a workaround, mandoc can be compiled
      with
      -DOSNAME="\"
      string\"".St macro has an unknown argument and is
      discarded.it request or an
      eqn(7)
      size or gsize statement
      has a non-numeric or negative argument or no argument at all. The invalid
      request or statement is ignored.shift request is larger
      than the number of arguments of the macro that is currently being
      executed. All macro arguments are deleted and \n(.$ is set to zero.mandoc allows
      so file inclusion requests only with relative
      paths and only without ascending to any parent directory. By requesting
      the inclusion of a sensitive file, a malicious document might otherwise
      trick a privileged user into inadvertently displaying the file on the
      screen, revealing the file content to bystanders.
      mandoc only shows the path as it appears behind
      so.so request requires reading an
      external file, but the file could not be opened.
      mandoc only shows the path as it appears behind
      so.Bt, Ed,
      Ef, Ek,
      El, Lp,
      Pp, Re,
      Rs, or Ud macro, an
      It macro in a list that don't support item heads,
      a man(7)
      LP, P, or
      PP macro, an
      eqn(7)
      EQ or EN macro, or a
      roff(7)
      br, fi, or
      nf request or ‘..’ block closing
      request is invoked with at least one argument. All arguments are
    ignored.Fo,
          MT, PD,
          RS, UR,
          ft, or sp with more
          than one argumentAn
          with another argument after -split or
          -nosplitRE
          with more than one argument or with a non-integer argumentOP
          or a request of the de family with more than
          two argumentsDt
          with more than three argumentsTH
          with more than five argumentsBd,
          Bk, or Bl with invalid
          argumentsmandoc cannot handle input
      files larger than its arbitrary size limit of 2^31 bytes (2 Gigabytes).
      Since useful manuals are always small, this is not a problem in practice.
      Parsing is aborted as soon as the condition is detected.mandoc was found in an input file. It is
      replaced by a question mark.mandoc, and it is likely
      that this will cause information loss or considerable misformatting.mandoc, and
      it is likely that this will cause information loss or considerable
      misformatting.m’ modifier. The modifier is
      discarded.mandoc utility first appeared in
  OpenBSD 4.8. The option -I
  appeared in OpenBSD 5.2, and
  -aCcfhKklMSsw in OpenBSD 5.7.
mandoc utility was written by
  Kristaps Dzonsons
  <kristaps@bsd.lv> and is
  maintained by Ingo Schwarze
  <schwarze@openbsd.org>.
| February 23, 2019 | NetBSD 10.0 |