Print this page
9718 update mandoc to 1.14.4

Split Close
Expand all
Collapse all
          --- old/usr/src/man/man1/mandoc.1.man.txt
          +++ new/usr/src/man/man1/mandoc.1.man.txt
   1    1  MANDOC(1)                        User Commands                       MANDOC(1)
   2    2  
   3    3  NAME
   4    4       mandoc - format manual pages
   5    5  
   6    6  SYNOPSIS
   7    7       mandoc [-ac] [-I os=name] [-K encoding] [-mdoc | -man] [-O options]
   8    8              [-T output] [-W level] [file ...]
   9    9  
  10   10  DESCRIPTION
  11      -     The mandoc utility formats UNIX manual pages for display.
       11 +     The mandoc utility formats manual pages for display.
  12   12  
  13   13       By default, mandoc reads mdoc(5) or man(5) text from stdin and produces
  14   14       -T locale output.
  15   15  
  16   16       The options are as follows:
  17   17  
  18   18       -a      If the standard output is a terminal device and -c is not
  19   19               specified, use more(1) to paginate the output, just like man(1)
  20   20               would.
  21   21  
↓ open down ↓ 23 lines elided ↑ open up ↑
  45   45  
  46   46               3.   If the first non-ASCII byte in the file introduces a valid
  47   47                    UTF-8 sequence, input is interpreted as utf-8.
  48   48  
  49   49               4.   Otherwise, input is interpreted as iso-8859-1.
  50   50  
  51   51       -mdoc | -man
  52   52               With -mdoc, all input files are interpreted as mdoc(5).  With
  53   53               -man, all input files are interpreted as man(5).  By default, the
  54   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.
       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   58  
  59   59       -O options
  60      -             Comma-separated output options.
       60 +             Comma-separated output options.  See the descriptions of the
       61 +             individual output formats for supported options.
  61   62  
  62   63       -T output
  63      -             Output format.  See Output Formats for available formats.
  64      -             Defaults to -T locale.
       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.
  65   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 +
  66   72       -W level
  67   73               Specify the minimum message level to be reported on the standard
  68   74               error output and to affect the exit status.  The level can be
  69   75               base, style, warning, error, or unsupp.  The base level
  70   76               automatically derives the operating system from the contents of
  71   77               the Os macro, from the -Ios command line option, or from the
  72   78               uname(2) return value.  The levels openbsd and netbsd are
  73   79               variants of base that bypass autodetection and request validation
  74   80               of base system conventions for a particular operating system.
  75   81               The level all is an alias for base.  By default, mandoc is
  76   82               silent.  See EXIT STATUS and DIAGNOSTICS for details.
  77   83  
  78   84               The special option -W stop tells mandoc to exit after parsing a
  79   85               file that causes warnings or errors of at least the requested
  80   86               level.  No formatted output will be produced from that file.  If
  81   87               both a level and stop are requested, they can be joined with a
  82   88               comma, for example -W error,stop.
  83   89  
  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.
       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.
  87   93  
  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   94     ASCII Output
 120      -     Output produced by -T ascii is rendered in standard 7-bit ASCII
 121      -     documented in ascii(5).
       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.
 122   98  
 123   99       Font styles are applied by using back-spaced encoding such that an
 124  100       underlined character `c' is rendered as `_\[bs]c', where `\[bs]' is the
 125  101       back-space character number 8.  Emboldened characters are rendered as
 126  102       `c\[bs]c'.
 127  103  
 128  104       The special characters documented in mandoc_char(5) are rendered best-
 129  105       effort in an ASCII equivalent.
 130  106  
 131      -     Output width is limited to 78 visible columns unless literal input lines
 132      -     exceed this limit.
 133      -
 134  107       The following -O arguments are accepted:
 135  108  
 136  109       indent=indent
 137  110               The left margin for normal text is set to indent blank characters
 138  111               instead of the default of five for mdoc(5) and seven for man(5).
 139  112               Increasing this is not recommended; it may result in degraded
 140      -             formatting, for example overfull lines or ugly line breaks.
      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.
 141  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 +
 142  123       width=width
 143      -             The output width is set to 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.
 144  129  
 145  130     HTML Output
 146  131       Output produced by -T html conforms to HTML5 using optional self-closing
 147  132       tags.  Default styles use only CSS1.  Equations rendered from eqn(5)
 148  133       blocks use MathML.
 149  134  
 150  135       The mandoc.css file documents style-sheet classes available for
 151  136       customising output.  If a style-sheet is not specified with -O style, -T
 152  137       html defaults to simple output (via an embedded style-sheet) readable in
 153  138       any graphical or text-based web browser.
 154  139  
 155      -     Special characters are rendered in decimal-encoded UTF-8.
      140 +     Non-ASCII characters are rendered as hexadecimal Unicode character
      141 +     references.
 156  142  
 157  143       The following -O arguments are accepted:
 158  144  
 159  145       fragment
 160  146               Omit the <!DOCTYPE> declaration and the <html>, <head>, and
 161  147               <body> elements and only emit the subtree below the <body>
 162  148               element.  The style argument will be ignored.  This is useful
 163  149               when embedding manual content within existing documents.
 164  150  
 165  151       includes=fmt
↓ open down ↓ 7 lines elided ↑ open up ↑
 173  159               template for linked manuals (usually via the Xr macro).
 174  160               Instances of `%N' and `%S' are replaced with the linked manual's
 175  161               name and section, respectively.  If no section is included,
 176  162               section 1 is assumed.  The default is not to present a hyperlink.
 177  163  
 178  164       style=style.css
 179  165               The file style.css is used for an external style-sheet.  This
 180  166               must be a valid absolute or relative URI.
 181  167  
 182  168     Locale Output
 183      -     Locale-depending output encoding is triggered with -T locale.  This is
 184      -     the default.
      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.
 185  175  
 186  176     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.
      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.
 189  180  
 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.
      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.
 195  185  
 196  186     Markdown Output
 197      -     Translate mdoc(5) input to the markdown format conforming to John
 198      -     Gruber's 2004 specification:
      187 +     Use -T markdown to translate mdoc(5) input to the markdown format
      188 +     conforming to John Gruber's 2004 specification:
 199  189       http://daringfireball.net/projects/markdown/syntax.text. The output also
 200  190       almost conforms to the CommonMark: http://commonmark.org/ specification.
 201  191  
 202  192       The character set used for the markdown output is ASCII.  Non-ASCII
 203  193       characters are encoded as HTML entities.  Since that is not possible in
 204  194       literal font contexts, because these are rendered as code spans and code
 205  195       blocks in the markdown output, non-ASCII characters are transliterated to
 206  196       ASCII approximations in these contexts.
 207  197  
 208  198       Markdown is a very weak markup language, so all semantic markup is lost,
↓ open down ↓ 18 lines elided ↑ open up ↑
 227  217  
 228  218       The following -O arguments are accepted:
 229  219  
 230  220       paper=name
 231  221               The paper size name may be one of a3, a4, a5, legal, or letter.
 232  222               You may also manually specify dimensions as NNxNN, width by
 233  223               height in millimetres.  If an unknown value is encountered,
 234  224               letter is used.
 235  225  
 236  226     UTF-8 Output
 237      -     Use -T utf8 to force a UTF-8 locale.  See Locale Output for details and
 238      -     options.
      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.
 239  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 +
 240  235     Syntax tree output
 241  236       Use -T tree to show a human readable representation of the syntax tree.
 242  237       It is useful for debugging the source code of manual pages.  The exact
 243  238       format is subject to change, so don't write parsers for it.
 244  239  
 245  240       The first paragraph shows meta data found in the mdoc(5) prologue, on the
 246  241       man(5) TH line, or the fallbacks used.
 247  242  
 248  243       In the tree dump, each output line shows one syntax tree node.  Child
 249  244       nodes are indented with respect to their parent node.  The columns are:
↓ open down ↓ 15 lines elided ↑ open up ↑
 265  260            -   NOPRT if the node is not supposed to generate output for any
 266  261                output format.
 267  262  
 268  263       The following -O argument is accepted:
 269  264  
 270  265       noval   Skip validation and show the unvalidated syntax tree.  This can
 271  266               help to find out whether a given behaviour is caused by the
 272  267               parser or by the validator.  Meta data is not available in this
 273  268               case.
 274  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 +
 275  276  EXIT STATUS
 276  277       The mandoc utility exits with one of the following values, controlled by
 277  278       the message level associated with the -W option:
 278  279  
 279  280       0       No base system convention violations, style suggestions,
 280  281               warnings, or errors occurred, or those that did were ignored
 281  282               because they were lower than the requested level.
 282  283       1       At least one base system convention violation or style suggestion
 283  284               occurred, but no warning or error, and -W base or -W style was
 284  285               specified.
↓ open down ↓ 64 lines elided ↑ open up ↑
 349  350  
 350  351       style    An input file uses dubious or discouraged style.  This is not a
 351  352                complaint about the syntax, and probably neither formatting nor
 352  353                portability are in danger.  While great care is taken to avoid
 353  354                false positives on the higher message levels, the style level
 354  355                tries to reduce the probability that issues go unnoticed, so it
 355  356                may occasionally issue bogus suggestions.  Please use your good
 356  357                judgement to decide whether any particular style suggestion
 357  358                really justifies a change to the input file.
 358  359  
 359      -     base     A convertion used in the base system of a specific operating
      360 +     base     A convention used in the base system of a specific operating
 360  361                system is not adhered to.  These are not markup mistakes, and
 361  362                neither the quality of formatting nor portability are in danger.
 362  363                Messages of the base level are printed with the more intuitive
 363  364                style level tag.
 364  365  
 365  366       Messages of the base, style, warning, error, and unsupp levels except
 366  367       those about non-existent or unreadable input files are hidden unless
 367  368       their level, or a lower level, is requested using a -W option or -T lint
 368  369       output mode.
 369  370  
↓ open down ↓ 30 lines elided ↑ open up ↑
 400  401       (mdoc) An Xr macro references a manual page that is not found in the base
 401  402       system.  The path to look for base system manuals is configurable at
 402  403       compile time and defaults to /usr/share/man: /usr/X11R6/man.
 403  404  
 404  405     Style suggestions
 405  406       legacy man(7) date format
 406  407       (mdoc) The Dd macro uses the legacy man(5) date format "yyyy-dd-mm".
 407  408       Consider using the conventional mdoc(5) date format "Month dd, yyyy"
 408  409       instead.
 409  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 +
 410  416       lower case character in document title
 411  417       (mdoc, man) The title is still used as given in the Dt or TH macro.
 412  418  
 413  419       duplicate RCS id
 414  420       A single manual page contains two copies of the RCS identifier for the
 415  421       same operating system.  Consider deleting the later instance and moving
 416  422       the first one up to the top of the page.
 417  423  
 418      -     typo in section name
      424 +     possible typo in section name
 419  425       (mdoc) Fuzzy string matching revealed that the argument of an Sh macro is
 420  426       similar, but not identical to a standard section name.
 421  427  
 422  428       unterminated quoted argument
 423  429       (roff) Macro arguments can be enclosed in double quote characters such
 424  430       that space characters and macro names contained in the quoted argument
 425  431       need not be escaped.  The closing quote of the last argument of a macro
 426  432       can be omitted.  However, omitting it is not recommended because it makes
 427  433       the code harder to read.
 428  434  
↓ open down ↓ 24 lines elided ↑ open up ↑
 453  459       argument, thus moving it out of the scope of the macro.
 454  460  
 455  461       fill mode already enabled, skipping
 456  462       (man) A fi request occurs even though the document is still in fill mode,
 457  463       or already switched back to fill mode.  It has no effect.
 458  464  
 459  465       fill mode already disabled, skipping
 460  466       (man) An nf request occurs even though the document already switched to
 461  467       no-fill mode and did not switch back to fill mode yet.  It has no effect.
 462  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 +
 463  474       function name without markup
 464  475       (mdoc) A word followed by an empty pair of parentheses occurs on a text
 465  476       line.  Consider using an Fn or Xr macro.
 466  477  
 467  478       whitespace at end of input line
 468  479       (mdoc, man, roff) Whitespace at the end of input lines is almost never
 469  480       semantically significant -- but in the odd case where it might be, it is
 470  481       extremely confusing when reviewing and maintaining documents.
 471  482  
 472  483       bad comment style
↓ open down ↓ 621 lines elided ↑ open up ↑
1094 1105       eqn(5), man(5), mandoc_char(5), mandoc_roff(5), mdoc(5), tbl(5)
1095 1106  
1096 1107  HISTORY
1097 1108       The mandoc utility first appeared in OpenBSD 4.8.  The option -I appeared
1098 1109       in OpenBSD 5.2, and -aCcfhKklMSsw in OpenBSD 5.7.
1099 1110  
1100 1111  AUTHORS
1101 1112       The mandoc utility was written by Kristaps Dzonsons <kristaps@bsd.lv> and
1102 1113       is maintained by Ingo Schwarze <schwarze@openbsd.org>.
1103 1114  
1104      -illumos                          July 20, 2017                         illumos
     1115 +illumos                          July 28, 2018                         illumos
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX