Print this page
9718 update mandoc to 1.14.4
   1 MANDOC(1)                        User Commands                       MANDOC(1)
   2 
   3 NAME
   4      mandoc - format manual pages
   5 
   6 SYNOPSIS
   7      mandoc [-ac] [-I os=name] [-K encoding] [-mdoc | -man] [-O options]
   8             [-T output] [-W level] [file ...]
   9 
  10 DESCRIPTION
  11      The mandoc utility formats UNIX manual pages for display.
  12 
  13      By default, mandoc reads mdoc(5) or man(5) text from stdin and produces
  14      -T locale output.
  15 
  16      The options are as follows:
  17 
  18      -a      If the standard output is a terminal device and -c is not
  19              specified, use more(1) to paginate the output, just like man(1)
  20              would.
  21 
  22      -c      Copy the formatted manual pages to the standard output without
  23              using more(1) to paginate them.  This is the default.  It can be
  24              specified to override -a.
  25 
  26      -I os=name
  27              Override the default operating system name for the mdoc(5) Os and
  28              for the man(5) TH macro.
  29 
  30      -K encoding
  31              Specify the input encoding.  The supported encoding arguments are


  35              1.   If the first three bytes of the input file are the UTF-8
  36                   byte order mark (BOM, 0xefbbbf), input is interpreted as
  37                   utf-8.
  38 
  39              2.   If the first or second line of the input file matches the
  40                   emacs mode line format
  41 
  42                         .\" -*- [...;] coding: encoding; -*-
  43 
  44                   then input is interpreted according to encoding.
  45 
  46              3.   If the first non-ASCII byte in the file introduces a valid
  47                   UTF-8 sequence, input is interpreted as utf-8.
  48 
  49              4.   Otherwise, input is interpreted as iso-8859-1.
  50 
  51      -mdoc | -man
  52              With -mdoc, all input files are interpreted as mdoc(5).  With
  53              -man, all input files are interpreted as man(5).  By default, the
  54              input language is automatically detected for each file: if the
  55              the first macro is Dd or Dt, the mdoc(5) parser is used;
  56              otherwise, the man(5) parser is used.  With other arguments, -m
  57              is silently ignored.
  58 
  59      -O options
  60              Comma-separated output options.

  61 
  62      -T output
  63              Output format.  See Output Formats for available formats.
  64              Defaults to -T locale.

  65 




  66      -W level
  67              Specify the minimum message level to be reported on the standard
  68              error output and to affect the exit status.  The level can be
  69              base, style, warning, error, or unsupp.  The base level
  70              automatically derives the operating system from the contents of
  71              the Os macro, from the -Ios command line option, or from the
  72              uname(2) return value.  The levels openbsd and netbsd are
  73              variants of base that bypass autodetection and request validation
  74              of base system conventions for a particular operating system.
  75              The level all is an alias for base.  By default, mandoc is
  76              silent.  See EXIT STATUS and DIAGNOSTICS for details.
  77 
  78              The special option -W stop tells mandoc to exit after parsing a
  79              file that causes warnings or errors of at least the requested
  80              level.  No formatted output will be produced from that file.  If
  81              both a level and stop are requested, they can be joined with a
  82              comma, for example -W error,stop.
  83 
  84      file    Read input from zero or more files.  If unspecified, reads from
  85              stdin.  If multiple files are specified, mandoc will halt with
  86              the first failed parse.
  87 
  88    Output Formats
  89      The mandoc utility accepts the following -T arguments, which correspond
  90      to output modes:
  91 
  92      -T ascii     Produce 7-bit ASCII output.  See ASCII Output.
  93 
  94      -T html      Produce HTML5, CSS1, and MathML output.  See HTML Output.
  95 
  96      -Tlint       Parse only: produce no output.  Implies -W all and redirects
  97                   parser messages, which usually appear on standard error
  98                   output, to standard output.
  99 
 100      -T locale    Encode output using the current locale.  This is the
 101                   default.  See Locale Output.
 102 
 103      -T man       Produce man(5) format output.  See Man Output.
 104 
 105      -T markdown  Produce output in markdown format.  See Markdown Output.
 106 
 107      -T pdf       Produce PDF output.  See PDF Output.
 108 
 109      -T ps        Produce PostScript output.  See PostScript Output.
 110 
 111      -T tree      Produce an indented parse tree.
 112 
 113      -T utf8      Encode output in the UTF-8 multi-byte format.  See UTF-8
 114                   Output.
 115 
 116      If multiple input files are specified, these will be processed by the
 117      corresponding filter in-order.
 118 
 119    ASCII Output
 120      Output produced by -T ascii is rendered in standard 7-bit ASCII
 121      documented in ascii(5).

 122 
 123      Font styles are applied by using back-spaced encoding such that an
 124      underlined character `c' is rendered as `_\[bs]c', where `\[bs]' is the
 125      back-space character number 8.  Emboldened characters are rendered as
 126      `c\[bs]c'.
 127 
 128      The special characters documented in mandoc_char(5) are rendered best-
 129      effort in an ASCII equivalent.
 130 
 131      Output width is limited to 78 visible columns unless literal input lines
 132      exceed this limit.
 133 
 134      The following -O arguments are accepted:
 135 
 136      indent=indent
 137              The left margin for normal text is set to indent blank characters
 138              instead of the default of five for mdoc(5) and seven for man(5).
 139              Increasing this is not recommended; it may result in degraded
 140              formatting, for example overfull lines or ugly line breaks.


 141 






 142      width=width
 143              The output width is set to width.




 144 
 145    HTML Output
 146      Output produced by -T html conforms to HTML5 using optional self-closing
 147      tags.  Default styles use only CSS1.  Equations rendered from eqn(5)
 148      blocks use MathML.
 149 
 150      The mandoc.css file documents style-sheet classes available for
 151      customising output.  If a style-sheet is not specified with -O style, -T
 152      html defaults to simple output (via an embedded style-sheet) readable in
 153      any graphical or text-based web browser.
 154 
 155      Special characters are rendered in decimal-encoded UTF-8.

 156 
 157      The following -O arguments are accepted:
 158 
 159      fragment
 160              Omit the <!DOCTYPE> declaration and the <html>, <head>, and
 161              <body> elements and only emit the subtree below the <body>
 162              element.  The style argument will be ignored.  This is useful
 163              when embedding manual content within existing documents.
 164 
 165      includes=fmt
 166              The string fmt, for example, ../src/%I.html, is used as a
 167              template for linked header files (usually via the In macro).
 168              Instances of `%I' are replaced with the include filename.  The
 169              default is not to present a hyperlink.
 170 
 171      man=fmt
 172              The string fmt, for example, ../html%S/%N.%S.html, is used as a
 173              template for linked manuals (usually via the Xr macro).
 174              Instances of `%N' and `%S' are replaced with the linked manual's
 175              name and section, respectively.  If no section is included,
 176              section 1 is assumed.  The default is not to present a hyperlink.
 177 
 178      style=style.css
 179              The file style.css is used for an external style-sheet.  This
 180              must be a valid absolute or relative URI.
 181 
 182    Locale Output
 183      Locale-depending output encoding is triggered with -T locale.  This is
 184      the default.




 185 
 186    Man Output
 187      Translate input format into man(5) output format.  This is useful for
 188      distributing manual sources to legacy systems lacking mdoc(5) formatters.

 189 
 190      If mdoc(5) is passed as input, it is translated into man(5).  If the
 191      input format is man(5), the input is copied to the output, expanding any
 192      mandoc_roff(5) so requests.  The parser is also run, and as usual, the -W
 193      level controls which DIAGNOSTICS are displayed before copying the input
 194      to the output.
 195 
 196    Markdown Output
 197      Translate mdoc(5) input to the markdown format conforming to John
 198      Gruber's 2004 specification:
 199      http://daringfireball.net/projects/markdown/syntax.text. The output also
 200      almost conforms to the CommonMark: http://commonmark.org/ specification.
 201 
 202      The character set used for the markdown output is ASCII.  Non-ASCII
 203      characters are encoded as HTML entities.  Since that is not possible in
 204      literal font contexts, because these are rendered as code spans and code
 205      blocks in the markdown output, non-ASCII characters are transliterated to
 206      ASCII approximations in these contexts.
 207 
 208      Markdown is a very weak markup language, so all semantic markup is lost,
 209      and even part of the presentational markup may be lost.  Do not use this
 210      as an intermediate step in converting to HTML; instead, use -T html
 211      directly.
 212 
 213      The man(5), tbl(5), and eqn(5) input languages are not supported by -T
 214      markdown output mode.
 215 
 216    PDF Output
 217      PDF-1.1 output may be generated by -T pdf.  See PostScript Output for -O
 218      arguments and defaults.
 219 
 220    PostScript Output
 221      PostScript "Adobe-3.0" Level-2 pages may be generated by -T ps.  Output
 222      pages default to letter sized and are rendered in the Times font family,
 223      11-point.  Margins are calculated as 1/9 the page length and width.
 224      Line-height is 1.4m.
 225 
 226      Special characters are rendered as in ASCII Output.
 227 
 228      The following -O arguments are accepted:
 229 
 230      paper=name
 231              The paper size name may be one of a3, a4, a5, legal, or letter.
 232              You may also manually specify dimensions as NNxNN, width by
 233              height in millimetres.  If an unknown value is encountered,
 234              letter is used.
 235 
 236    UTF-8 Output
 237      Use -T utf8 to force a UTF-8 locale.  See Locale Output for details and
 238      options.

 239 




 240    Syntax tree output
 241      Use -T tree to show a human readable representation of the syntax tree.
 242      It is useful for debugging the source code of manual pages.  The exact
 243      format is subject to change, so don't write parsers for it.
 244 
 245      The first paragraph shows meta data found in the mdoc(5) prologue, on the
 246      man(5) TH line, or the fallbacks used.
 247 
 248      In the tree dump, each output line shows one syntax tree node.  Child
 249      nodes are indented with respect to their parent node.  The columns are:
 250 
 251      1.   For macro nodes, the macro name; for text and tbl(5) nodes, the
 252           content.  There is a special format for eqn(5) nodes.
 253      2.   Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
 254      3.   Flags:
 255           -   An opening parenthesis if the node is an opening delimiter.
 256           -   An asterisk if the node starts a new input line.
 257           -   The input line number (starting at one).
 258           -   A colon.
 259           -   The input column number (starting at one).
 260           -   A closing parenthesis if the node is a closing delimiter.
 261           -   A full stop if the node ends a sentence.
 262           -   BROKEN if the node is a block broken by another block.
 263           -   NOSRC if the node is not in the input file, but automatically
 264               generated from macros.
 265           -   NOPRT if the node is not supposed to generate output for any
 266               output format.
 267 
 268      The following -O argument is accepted:
 269 
 270      noval   Skip validation and show the unvalidated syntax tree.  This can
 271              help to find out whether a given behaviour is caused by the
 272              parser or by the validator.  Meta data is not available in this
 273              case.
 274 






 275 EXIT STATUS
 276      The mandoc utility exits with one of the following values, controlled by
 277      the message level associated with the -W option:
 278 
 279      0       No base system convention violations, style suggestions,
 280              warnings, or errors occurred, or those that did were ignored
 281              because they were lower than the requested level.
 282      1       At least one base system convention violation or style suggestion
 283              occurred, but no warning or error, and -W base or -W style was
 284              specified.
 285      2       At least one warning occurred, but no error, and -W warning or a
 286              lower level was requested.
 287      3       At least one parsing error occurred, but no unsupported feature
 288              was encountered, and -W error or a lower level was requested.
 289      4       At least one unsupported feature was encountered, and -W unsupp
 290              or a lower level was requested.
 291      5       Invalid command line arguments were specified.  No input files
 292              have been read.
 293      6       An operating system error occurred, for example exhaustion of
 294              memory, file descriptors, or process table entries.  Such errors


 339               using GNU troff instead of mandoc to process the file may be
 340               preferable.
 341 
 342      error    Indicates a risk of information loss or severe misformatting, in
 343               most cases caused by serious syntax errors.
 344 
 345      warning  Indicates a risk that the information shown or its formatting
 346               may mismatch the author's intent in minor ways.  Additionally,
 347               syntax errors are classified at least as warnings, even if they
 348               do not usually cause misformatting.
 349 
 350      style    An input file uses dubious or discouraged style.  This is not a
 351               complaint about the syntax, and probably neither formatting nor
 352               portability are in danger.  While great care is taken to avoid
 353               false positives on the higher message levels, the style level
 354               tries to reduce the probability that issues go unnoticed, so it
 355               may occasionally issue bogus suggestions.  Please use your good
 356               judgement to decide whether any particular style suggestion
 357               really justifies a change to the input file.
 358 
 359      base     A convertion used in the base system of a specific operating
 360               system is not adhered to.  These are not markup mistakes, and
 361               neither the quality of formatting nor portability are in danger.
 362               Messages of the base level are printed with the more intuitive
 363               style level tag.
 364 
 365      Messages of the base, style, warning, error, and unsupp levels except
 366      those about non-existent or unreadable input files are hidden unless
 367      their level, or a lower level, is requested using a -W option or -T lint
 368      output mode.
 369 
 370      As indicated below, all base and some style checks are only performed if
 371      a specific operating system name occurs in the arguments of the -W
 372      command line option, of the Os macro, of the -Ios command line option,
 373      or, if neither are present, in the return value of the uname(3) function.
 374 
 375    Conventions for base system manuals
 376      Mdocdate found
 377      (mdoc, NetBSD) The Dd macro uses CVS Mdocdate keyword substitution, which
 378      is not supported by the NetBSD base system.  Consider using the
 379      conventional "Month dd, yyyy" format instead.


 390      operating system explicitly specified
 391      (mdoc, OpenBSD, NetBSD) The Os macro has an argument.  In the base
 392      system, it is conventionally left blank.
 393 
 394      RCS id missing
 395      (OpenBSD, NetBSD) The manual page lacks the comment line with the RCS
 396      identifier generated by CVS OpenBSD or NetBSD keyword substitution as
 397      conventionally used in these operating systems.
 398 
 399      referenced manual not found
 400      (mdoc) An Xr macro references a manual page that is not found in the base
 401      system.  The path to look for base system manuals is configurable at
 402      compile time and defaults to /usr/share/man: /usr/X11R6/man.
 403 
 404    Style suggestions
 405      legacy man(7) date format
 406      (mdoc) The Dd macro uses the legacy man(5) date format "yyyy-dd-mm".
 407      Consider using the conventional mdoc(5) date format "Month dd, yyyy"
 408      instead.
 409 





 410      lower case character in document title
 411      (mdoc, man) The title is still used as given in the Dt or TH macro.
 412 
 413      duplicate RCS id
 414      A single manual page contains two copies of the RCS identifier for the
 415      same operating system.  Consider deleting the later instance and moving
 416      the first one up to the top of the page.
 417 
 418      typo in section name
 419      (mdoc) Fuzzy string matching revealed that the argument of an Sh macro is
 420      similar, but not identical to a standard section name.
 421 
 422      unterminated quoted argument
 423      (roff) Macro arguments can be enclosed in double quote characters such
 424      that space characters and macro names contained in the quoted argument
 425      need not be escaped.  The closing quote of the last argument of a macro
 426      can be omitted.  However, omitting it is not recommended because it makes
 427      the code harder to read.
 428 
 429      useless macro
 430      (mdoc) A Bt, Tn, or Ud macro was found.  Simply delete it: it serves no
 431      useful purpose.
 432 
 433      consider using OS macro
 434      (mdoc) A string was found in plain text or in a Bx macro that could be
 435      represented using Ox, Nx, Fx, or Dx.
 436 
 437      errnos out of order
 438      (mdoc, NetBSD) The Er items in a Bl list are not in alphabetical order.


 443 
 444      trailing delimiter
 445      (mdoc) The last argument of an Ex, Fo, Nd, Nm, Os, Sh, Ss, St, or Sx
 446      macro ends with a trailing delimiter.  This is usually bad style and
 447      often indicates typos.  Most likely, the delimiter can be removed.
 448 
 449      no blank before trailing delimiter
 450      (mdoc) The last argument of a macro that supports trailing delimiter
 451      arguments is longer than one byte and ends with a trailing delimiter.
 452      Consider inserting a blank such that the delimiter becomes a separate
 453      argument, thus moving it out of the scope of the macro.
 454 
 455      fill mode already enabled, skipping
 456      (man) A fi request occurs even though the document is still in fill mode,
 457      or already switched back to fill mode.  It has no effect.
 458 
 459      fill mode already disabled, skipping
 460      (man) An nf request occurs even though the document already switched to
 461      no-fill mode and did not switch back to fill mode yet.  It has no effect.
 462 





 463      function name without markup
 464      (mdoc) A word followed by an empty pair of parentheses occurs on a text
 465      line.  Consider using an Fn or Xr macro.
 466 
 467      whitespace at end of input line
 468      (mdoc, man, roff) Whitespace at the end of input lines is almost never
 469      semantically significant -- but in the odd case where it might be, it is
 470      extremely confusing when reviewing and maintaining documents.
 471 
 472      bad comment style
 473      (roff) Comment lines start with a dot, a backslash, and a double-quote
 474      character.  The mandoc utility treats the line as a comment line even
 475      without the backslash, but leaving out the backslash might not be
 476      portable.
 477 
 478    Warnings related to the document prologue
 479      missing manual title, using UNTITLED
 480      (mdoc) A Dt macro has no arguments, or there is no Dt macro before the
 481      first non-prologue macro.
 482 


1084      unsupported table layout modifier
1085      (tbl) A table layout specification contains an `m' modifier.  The
1086      modifier is discarded.
1087 
1088      ignoring macro in table
1089      (tbl, mdoc, man) A table contains an invocation of an mdoc(5) or man(5)
1090      macro or of an undefined macro.  The macro is ignored, and its arguments
1091      are handled as if they were a text line.
1092 
1093 SEE ALSO
1094      eqn(5), man(5), mandoc_char(5), mandoc_roff(5), mdoc(5), tbl(5)
1095 
1096 HISTORY
1097      The mandoc utility first appeared in OpenBSD 4.8.  The option -I appeared
1098      in OpenBSD 5.2, and -aCcfhKklMSsw in OpenBSD 5.7.
1099 
1100 AUTHORS
1101      The mandoc utility was written by Kristaps Dzonsons <kristaps@bsd.lv> and
1102      is maintained by Ingo Schwarze <schwarze@openbsd.org>.
1103 
1104 illumos                          July 20, 2017                         illumos
   1 MANDOC(1)                        User Commands                       MANDOC(1)
   2 
   3 NAME
   4      mandoc - format manual pages
   5 
   6 SYNOPSIS
   7      mandoc [-ac] [-I os=name] [-K encoding] [-mdoc | -man] [-O options]
   8             [-T output] [-W level] [file ...]
   9 
  10 DESCRIPTION
  11      The mandoc utility formats manual pages for display.
  12 
  13      By default, mandoc reads mdoc(5) or man(5) text from stdin and produces
  14      -T locale output.
  15 
  16      The options are as follows:
  17 
  18      -a      If the standard output is a terminal device and -c is not
  19              specified, use more(1) to paginate the output, just like man(1)
  20              would.
  21 
  22      -c      Copy the formatted manual pages to the standard output without
  23              using more(1) to paginate them.  This is the default.  It can be
  24              specified to override -a.
  25 
  26      -I os=name
  27              Override the default operating system name for the mdoc(5) Os and
  28              for the man(5) TH macro.
  29 
  30      -K encoding
  31              Specify the input encoding.  The supported encoding arguments are


  35              1.   If the first three bytes of the input file are the UTF-8
  36                   byte order mark (BOM, 0xefbbbf), input is interpreted as
  37                   utf-8.
  38 
  39              2.   If the first or second line of the input file matches the
  40                   emacs mode line format
  41 
  42                         .\" -*- [...;] coding: encoding; -*-
  43 
  44                   then input is interpreted according to encoding.
  45 
  46              3.   If the first non-ASCII byte in the file introduces a valid
  47                   UTF-8 sequence, input is interpreted as utf-8.
  48 
  49              4.   Otherwise, input is interpreted as iso-8859-1.
  50 
  51      -mdoc | -man
  52              With -mdoc, all input files are interpreted as mdoc(5).  With
  53              -man, all input files are interpreted as man(5).  By default, the
  54              input language is automatically detected for each file: if the
  55              first macro is Dd or Dt, the mdoc(5) parser is used; otherwise,
  56              the man(5) parser is used.  With other arguments, -m is silently
  57              ignored.
  58 
  59      -O options
  60              Comma-separated output options.  See the descriptions of the
  61              individual output formats for supported options.
  62 
  63      -T output
  64              Select the output format.  Supported values for the output
  65              argument are ascii, html, the default of locale, man, markdown,
  66              pdf, ps, tree, and utf8.
  67 
  68              The special -T lint mode only parses the input and produces no
  69              output.  It implies -W all and redirects parser messages, which
  70              usually appear on standard error output, to standard output.
  71 
  72      -W level
  73              Specify the minimum message level to be reported on the standard
  74              error output and to affect the exit status.  The level can be
  75              base, style, warning, error, or unsupp.  The base level
  76              automatically derives the operating system from the contents of
  77              the Os macro, from the -Ios command line option, or from the
  78              uname(2) return value.  The levels openbsd and netbsd are
  79              variants of base that bypass autodetection and request validation
  80              of base system conventions for a particular operating system.
  81              The level all is an alias for base.  By default, mandoc is
  82              silent.  See EXIT STATUS and DIAGNOSTICS for details.
  83 
  84              The special option -W stop tells mandoc to exit after parsing a
  85              file that causes warnings or errors of at least the requested
  86              level.  No formatted output will be produced from that file.  If
  87              both a level and stop are requested, they can be joined with a
  88              comma, for example -W error,stop.
  89 
  90      file    Read from the given input file.  If multiple files are specified,
  91              they are processed in the given order.  If unspecified, mandoc
  92              reads from standard input.
  93 































  94    ASCII Output
  95      Use -T ascii to force text output in 7-bit ASCII character encoding
  96      documented in the ascii(5) manual page, ignoring the locale(1) set in the
  97      environment.
  98 
  99      Font styles are applied by using back-spaced encoding such that an
 100      underlined character `c' is rendered as `_\[bs]c', where `\[bs]' is the
 101      back-space character number 8.  Emboldened characters are rendered as
 102      `c\[bs]c'.
 103 
 104      The special characters documented in mandoc_char(5) are rendered best-
 105      effort in an ASCII equivalent.
 106 



 107      The following -O arguments are accepted:
 108 
 109      indent=indent
 110              The left margin for normal text is set to indent blank characters
 111              instead of the default of five for mdoc(5) and seven for man(5).
 112              Increasing this is not recommended; it may result in degraded
 113              formatting, for example overfull lines or ugly line breaks.  When
 114              output is to a pager on a terminal that is less than 66 columns
 115              wide, the default is reduced to three columns.
 116 
 117      mdoc    Format man(5) input files in mdoc(5) output style.  Specifically,
 118              this suppresses the two additional blank lines near the top and
 119              the bottom of each page, and it implies -O indent=5.  One useful
 120              application is for checking that -T man output formats in the
 121              same way as the mdoc(5) source it was generated from.
 122 
 123      width=width
 124              The output width is set to width instead of the default of 78.
 125              When output is to a pager on a terminal that is less than 79
 126              columns wide, the default is reduced to one less than the
 127              terminal width.  In any case, lines that are output in literal
 128              mode are never wrapped and may exceed the output width.
 129 
 130    HTML Output
 131      Output produced by -T html conforms to HTML5 using optional self-closing
 132      tags.  Default styles use only CSS1.  Equations rendered from eqn(5)
 133      blocks use MathML.
 134 
 135      The mandoc.css file documents style-sheet classes available for
 136      customising output.  If a style-sheet is not specified with -O style, -T
 137      html defaults to simple output (via an embedded style-sheet) readable in
 138      any graphical or text-based web browser.
 139 
 140      Non-ASCII characters are rendered as hexadecimal Unicode character
 141      references.
 142 
 143      The following -O arguments are accepted:
 144 
 145      fragment
 146              Omit the <!DOCTYPE> declaration and the <html>, <head>, and
 147              <body> elements and only emit the subtree below the <body>
 148              element.  The style argument will be ignored.  This is useful
 149              when embedding manual content within existing documents.
 150 
 151      includes=fmt
 152              The string fmt, for example, ../src/%I.html, is used as a
 153              template for linked header files (usually via the In macro).
 154              Instances of `%I' are replaced with the include filename.  The
 155              default is not to present a hyperlink.
 156 
 157      man=fmt
 158              The string fmt, for example, ../html%S/%N.%S.html, is used as a
 159              template for linked manuals (usually via the Xr macro).
 160              Instances of `%N' and `%S' are replaced with the linked manual's
 161              name and section, respectively.  If no section is included,
 162              section 1 is assumed.  The default is not to present a hyperlink.
 163 
 164      style=style.css
 165              The file style.css is used for an external style-sheet.  This
 166              must be a valid absolute or relative URI.
 167 
 168    Locale Output
 169      By default, mandoc automatically selects UTF-8 or ASCII output according
 170      to the current locale(1).  If any of the environment variables LC_ALL,
 171      LC_CTYPE, or LANG are set and the first one that is set selects the UTF-8
 172      character encoding, it produces UTF-8 Output; otherwise, it falls back to
 173      ASCII Output.  This output mode can also be selected explicitly with -T
 174      locale.
 175 
 176    Man Output
 177      Use -T man to translate mdoc(5) input into man(5) output format.  This is
 178      useful for distributing manual sources to legacy systems lacking mdoc(5)
 179      formatters.
 180 
 181      If the input format of a file is man(5), the input is copied to the
 182      output, expanding any mandoc_roff(5) so requests.  The parser is also
 183      run, and as usual, the -W level controls which DIAGNOSTICS are displayed
 184      before copying the input to the output.

 185 
 186    Markdown Output
 187      Use -T markdown to translate mdoc(5) input to the markdown format
 188      conforming to John Gruber's 2004 specification:
 189      http://daringfireball.net/projects/markdown/syntax.text. The output also
 190      almost conforms to the CommonMark: http://commonmark.org/ specification.
 191 
 192      The character set used for the markdown output is ASCII.  Non-ASCII
 193      characters are encoded as HTML entities.  Since that is not possible in
 194      literal font contexts, because these are rendered as code spans and code
 195      blocks in the markdown output, non-ASCII characters are transliterated to
 196      ASCII approximations in these contexts.
 197 
 198      Markdown is a very weak markup language, so all semantic markup is lost,
 199      and even part of the presentational markup may be lost.  Do not use this
 200      as an intermediate step in converting to HTML; instead, use -T html
 201      directly.
 202 
 203      The man(5), tbl(5), and eqn(5) input languages are not supported by -T
 204      markdown output mode.
 205 
 206    PDF Output
 207      PDF-1.1 output may be generated by -T pdf.  See PostScript Output for -O
 208      arguments and defaults.
 209 
 210    PostScript Output
 211      PostScript "Adobe-3.0" Level-2 pages may be generated by -T ps.  Output
 212      pages default to letter sized and are rendered in the Times font family,
 213      11-point.  Margins are calculated as 1/9 the page length and width.
 214      Line-height is 1.4m.
 215 
 216      Special characters are rendered as in ASCII Output.
 217 
 218      The following -O arguments are accepted:
 219 
 220      paper=name
 221              The paper size name may be one of a3, a4, a5, legal, or letter.
 222              You may also manually specify dimensions as NNxNN, width by
 223              height in millimetres.  If an unknown value is encountered,
 224              letter is used.
 225 
 226    UTF-8 Output
 227      Use -T utf8 to force text output in UTF-8 multi-byte character encoding,
 228      ignoring the locale(1) settings in the environment.  See ASCII Output
 229      regarding font styles and -O arguments.
 230 
 231      On operating systems lacking locale or wide character support, and on
 232      those where the internal character representation is not UCS-4, mandoc
 233      always falls back to ASCII Output.
 234 
 235    Syntax tree output
 236      Use -T tree to show a human readable representation of the syntax tree.
 237      It is useful for debugging the source code of manual pages.  The exact
 238      format is subject to change, so don't write parsers for it.
 239 
 240      The first paragraph shows meta data found in the mdoc(5) prologue, on the
 241      man(5) TH line, or the fallbacks used.
 242 
 243      In the tree dump, each output line shows one syntax tree node.  Child
 244      nodes are indented with respect to their parent node.  The columns are:
 245 
 246      1.   For macro nodes, the macro name; for text and tbl(5) nodes, the
 247           content.  There is a special format for eqn(5) nodes.
 248      2.   Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
 249      3.   Flags:
 250           -   An opening parenthesis if the node is an opening delimiter.
 251           -   An asterisk if the node starts a new input line.
 252           -   The input line number (starting at one).
 253           -   A colon.
 254           -   The input column number (starting at one).
 255           -   A closing parenthesis if the node is a closing delimiter.
 256           -   A full stop if the node ends a sentence.
 257           -   BROKEN if the node is a block broken by another block.
 258           -   NOSRC if the node is not in the input file, but automatically
 259               generated from macros.
 260           -   NOPRT if the node is not supposed to generate output for any
 261               output format.
 262 
 263      The following -O argument is accepted:
 264 
 265      noval   Skip validation and show the unvalidated syntax tree.  This can
 266              help to find out whether a given behaviour is caused by the
 267              parser or by the validator.  Meta data is not available in this
 268              case.
 269 
 270 ENVIRONMENT
 271      LC_CTYPE         The character encoding locale(1).  When Locale Output is
 272                       selected, it decides whether to use ASCII or UTF-8
 273                       output format.  It never affects the interpretation of
 274                       input files.
 275 
 276 EXIT STATUS
 277      The mandoc utility exits with one of the following values, controlled by
 278      the message level associated with the -W option:
 279 
 280      0       No base system convention violations, style suggestions,
 281              warnings, or errors occurred, or those that did were ignored
 282              because they were lower than the requested level.
 283      1       At least one base system convention violation or style suggestion
 284              occurred, but no warning or error, and -W base or -W style was
 285              specified.
 286      2       At least one warning occurred, but no error, and -W warning or a
 287              lower level was requested.
 288      3       At least one parsing error occurred, but no unsupported feature
 289              was encountered, and -W error or a lower level was requested.
 290      4       At least one unsupported feature was encountered, and -W unsupp
 291              or a lower level was requested.
 292      5       Invalid command line arguments were specified.  No input files
 293              have been read.
 294      6       An operating system error occurred, for example exhaustion of
 295              memory, file descriptors, or process table entries.  Such errors


 340               using GNU troff instead of mandoc to process the file may be
 341               preferable.
 342 
 343      error    Indicates a risk of information loss or severe misformatting, in
 344               most cases caused by serious syntax errors.
 345 
 346      warning  Indicates a risk that the information shown or its formatting
 347               may mismatch the author's intent in minor ways.  Additionally,
 348               syntax errors are classified at least as warnings, even if they
 349               do not usually cause misformatting.
 350 
 351      style    An input file uses dubious or discouraged style.  This is not a
 352               complaint about the syntax, and probably neither formatting nor
 353               portability are in danger.  While great care is taken to avoid
 354               false positives on the higher message levels, the style level
 355               tries to reduce the probability that issues go unnoticed, so it
 356               may occasionally issue bogus suggestions.  Please use your good
 357               judgement to decide whether any particular style suggestion
 358               really justifies a change to the input file.
 359 
 360      base     A convention used in the base system of a specific operating
 361               system is not adhered to.  These are not markup mistakes, and
 362               neither the quality of formatting nor portability are in danger.
 363               Messages of the base level are printed with the more intuitive
 364               style level tag.
 365 
 366      Messages of the base, style, warning, error, and unsupp levels except
 367      those about non-existent or unreadable input files are hidden unless
 368      their level, or a lower level, is requested using a -W option or -T lint
 369      output mode.
 370 
 371      As indicated below, all base and some style checks are only performed if
 372      a specific operating system name occurs in the arguments of the -W
 373      command line option, of the Os macro, of the -Ios command line option,
 374      or, if neither are present, in the return value of the uname(3) function.
 375 
 376    Conventions for base system manuals
 377      Mdocdate found
 378      (mdoc, NetBSD) The Dd macro uses CVS Mdocdate keyword substitution, which
 379      is not supported by the NetBSD base system.  Consider using the
 380      conventional "Month dd, yyyy" format instead.


 391      operating system explicitly specified
 392      (mdoc, OpenBSD, NetBSD) The Os macro has an argument.  In the base
 393      system, it is conventionally left blank.
 394 
 395      RCS id missing
 396      (OpenBSD, NetBSD) The manual page lacks the comment line with the RCS
 397      identifier generated by CVS OpenBSD or NetBSD keyword substitution as
 398      conventionally used in these operating systems.
 399 
 400      referenced manual not found
 401      (mdoc) An Xr macro references a manual page that is not found in the base
 402      system.  The path to look for base system manuals is configurable at
 403      compile time and defaults to /usr/share/man: /usr/X11R6/man.
 404 
 405    Style suggestions
 406      legacy man(7) date format
 407      (mdoc) The Dd macro uses the legacy man(5) date format "yyyy-dd-mm".
 408      Consider using the conventional mdoc(5) date format "Month dd, yyyy"
 409      instead.
 410 
 411      normalizing date format to: ...
 412      (mdoc, man) The Dd or TH macro provides an abbreviated month name or a
 413      day number with a leading zero.  In the formatted output, the month name
 414      is written out in full and the leading zero is omitted.
 415 
 416      lower case character in document title
 417      (mdoc, man) The title is still used as given in the Dt or TH macro.
 418 
 419      duplicate RCS id
 420      A single manual page contains two copies of the RCS identifier for the
 421      same operating system.  Consider deleting the later instance and moving
 422      the first one up to the top of the page.
 423 
 424      possible typo in section name
 425      (mdoc) Fuzzy string matching revealed that the argument of an Sh macro is
 426      similar, but not identical to a standard section name.
 427 
 428      unterminated quoted argument
 429      (roff) Macro arguments can be enclosed in double quote characters such
 430      that space characters and macro names contained in the quoted argument
 431      need not be escaped.  The closing quote of the last argument of a macro
 432      can be omitted.  However, omitting it is not recommended because it makes
 433      the code harder to read.
 434 
 435      useless macro
 436      (mdoc) A Bt, Tn, or Ud macro was found.  Simply delete it: it serves no
 437      useful purpose.
 438 
 439      consider using OS macro
 440      (mdoc) A string was found in plain text or in a Bx macro that could be
 441      represented using Ox, Nx, Fx, or Dx.
 442 
 443      errnos out of order
 444      (mdoc, NetBSD) The Er items in a Bl list are not in alphabetical order.


 449 
 450      trailing delimiter
 451      (mdoc) The last argument of an Ex, Fo, Nd, Nm, Os, Sh, Ss, St, or Sx
 452      macro ends with a trailing delimiter.  This is usually bad style and
 453      often indicates typos.  Most likely, the delimiter can be removed.
 454 
 455      no blank before trailing delimiter
 456      (mdoc) The last argument of a macro that supports trailing delimiter
 457      arguments is longer than one byte and ends with a trailing delimiter.
 458      Consider inserting a blank such that the delimiter becomes a separate
 459      argument, thus moving it out of the scope of the macro.
 460 
 461      fill mode already enabled, skipping
 462      (man) A fi request occurs even though the document is still in fill mode,
 463      or already switched back to fill mode.  It has no effect.
 464 
 465      fill mode already disabled, skipping
 466      (man) An nf request occurs even though the document already switched to
 467      no-fill mode and did not switch back to fill mode yet.  It has no effect.
 468 
 469      verbatim "--", maybe consider using \(em
 470      (mdoc) Even though the ASCII output device renders an em-dash as "--",
 471      that is not a good way to write it in an input file because it renders
 472      poorly on all other output devices.
 473 
 474      function name without markup
 475      (mdoc) A word followed by an empty pair of parentheses occurs on a text
 476      line.  Consider using an Fn or Xr macro.
 477 
 478      whitespace at end of input line
 479      (mdoc, man, roff) Whitespace at the end of input lines is almost never
 480      semantically significant -- but in the odd case where it might be, it is
 481      extremely confusing when reviewing and maintaining documents.
 482 
 483      bad comment style
 484      (roff) Comment lines start with a dot, a backslash, and a double-quote
 485      character.  The mandoc utility treats the line as a comment line even
 486      without the backslash, but leaving out the backslash might not be
 487      portable.
 488 
 489    Warnings related to the document prologue
 490      missing manual title, using UNTITLED
 491      (mdoc) A Dt macro has no arguments, or there is no Dt macro before the
 492      first non-prologue macro.
 493 


1095      unsupported table layout modifier
1096      (tbl) A table layout specification contains an `m' modifier.  The
1097      modifier is discarded.
1098 
1099      ignoring macro in table
1100      (tbl, mdoc, man) A table contains an invocation of an mdoc(5) or man(5)
1101      macro or of an undefined macro.  The macro is ignored, and its arguments
1102      are handled as if they were a text line.
1103 
1104 SEE ALSO
1105      eqn(5), man(5), mandoc_char(5), mandoc_roff(5), mdoc(5), tbl(5)
1106 
1107 HISTORY
1108      The mandoc utility first appeared in OpenBSD 4.8.  The option -I appeared
1109      in OpenBSD 5.2, and -aCcfhKklMSsw in OpenBSD 5.7.
1110 
1111 AUTHORS
1112      The mandoc utility was written by Kristaps Dzonsons <kristaps@bsd.lv> and
1113      is maintained by Ingo Schwarze <schwarze@openbsd.org>.
1114 
1115 illumos                          July 28, 2018                         illumos