Minix Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
MANDOC(1)                 BSD General Commands Manual                MANDOC(1)

NAME
     mandoc -- format and display UNIX manuals

SYNOPSIS
     mandoc [-V] [-mformat] [-Ooption] [-Toutput] [-Wlevel] [file ...]

DESCRIPTION
     The mandoc utility formats UNIX manual pages for display.

     By default, mandoc reads mdoc(7) or man(7) text from stdin, implying
     -mandoc, and produces -Tascii output.

     The arguments are as follows:

     -mformat
             Input format.  See Input Formats for available formats.  Defaults
             to -mandoc.

     -Ooption
             Comma-separated output options.

     -Toutput
             Output format.  See Output Formats for available formats.
             Defaults to -Tascii.

     -V      Print version and exit.

     -Wlevel
             Specify the minimum message level to be reported on the standard
             error output and to affect the exit status.  The level can be
             warning, error, or fatal.  The default is -Wfatal; -Wall is an
             alias for -Wwarning.  See EXIT STATUS and DIAGNOSTICS for
             details.

             The special option -Wstop 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 -Werror,stop.

     file    Read input from zero or more files.  If unspecified, reads from
             stdin.  If multiple files are specified, mandoc will halt with
             the first failed parse.

   Input Formats
     The mandoc utility accepts mdoc(7) and man(7) input with -mdoc and -man,
     respectively.  The mdoc(7) format is strongly recommended; man(7) should
     only be used for legacy manuals.

     A third option, -mandoc, which is also the default, determines encoding
     on-the-fly: if the first non-comment macro is 'Dd' or 'Dt', the mdoc(7)
     parser is used; otherwise, the man(7) parser is used.

     If multiple files are specified with -mandoc, each has its file-type
     determined this way.  If multiple files are specified and -mdoc or -man
     is specified, then this format is used exclusively.

   Output Formats
     The mandoc utility accepts the following -T arguments, which correspond
     to output modes:

     -Tascii   Produce 7-bit ASCII output.  This is the default.  See ASCII
               Output.

     -Thtml    Produce strict CSS1/HTML-4.01 output.  See HTML Output.

     -Tlint    Parse only: produce no output.  Implies -Wwarning.

     -Tlocale  Encode output using the current locale.  See Locale Output.

     -Tman     Produce man(7) format output.  See Man Output.

     -Tpdf     Produce PDF output.  See PDF Output.

     -Tps      Produce PostScript output.  See PostScript Output.

     -Ttree    Produce an indented parse tree.

     -Tutf8    Encode output in the UTF-8 multi-byte format.  See UTF-8
               Output.

     -Txhtml   Produce strict CSS1/XHTML-1.0 output.  See XHTML Output.

     If multiple input files are specified, these will be processed by the
     corresponding filter in-order.

   ASCII Output
     Output produced by -Tascii, which is the default, is rendered in standard
     7-bit ASCII documented in ascii(7).

     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'.

     The special characters documented in mandoc_char(7) are rendered best-
     effort in an ASCII equivalent.  If no equivalent is found, '?' is used
     instead.

     Output width is limited to 78 visible columns unless literal input lines
     exceed this limit.

     The following -O arguments are accepted:

     indent=indent
             The left margin for normal text is set to indent blank characters
             instead of the default of five for mdoc(7) and seven for man(7).
             Increasing this is not recommended; it may result in degraded
             formatting, for example overfull lines or ugly line breaks.

     width=width
             The output width is set to width, which will normalise to >=60.

   HTML Output
     Output produced by -Thtml conforms to HTML-4.01 strict.

     The example.style.css file documents style-sheet classes available for
     customising output.  If a style-sheet is not specified with -Ostyle,
     -Thtml defaults to simple output readable in any graphical or text-based
     web browser.

     Special characters are rendered in decimal-encoded UTF-8.

     The following -O arguments are accepted:

     fragment
             Omit the <!DOCTYPE> declaration and the <html>, <head>, and
             <body> elements and only emit the subtree below the <body>
             element.  The style argument will be ignored.  This is useful
             when embedding manual content within existing documents.

     includes=fmt
             The string fmt, for example, ../src/%I.html, is used as a
             template for linked header files (usually via the 'In' macro).
             Instances of '%I' are replaced with the include filename.  The
             default is not to present a hyperlink.

     man=fmt
             The string fmt, for example, ../html%S/%N.%S.html, is used as a
             template for linked manuals (usually via the '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.

     style=style.css
             The file style.css is used for an external style-sheet.  This
             must be a valid absolute or relative URI.

   Locale Output
     Locale-depending output encoding is triggered with -Tlocale.  This option
     is not available on all systems: systems without locale support, or those
     whose internal representation is not natively UCS-4, will fall back to
     -Tascii.  See ASCII Output for font style specification and available
     command-line arguments.

   Man Output
     Translate input format into man(7) output format.  This is useful for
     distributing manual sources to legancy systems lacking mdoc(7)
     formatters.

     If mdoc(7) is passed as input, it is translated into man(7).  If the
     input format 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.

   PDF Output
     PDF-1.1 output may be generated by -Tpdf.  See PostScript Output for -O
     arguments and defaults.

   PostScript Output
     PostScript "Adobe-3.0" Level-2 pages may be generated by -Tps.  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
             The paper size name may be one of a3, a4, a5, legal, or letter.
             You may also manually specify dimensions as NNxNN, width by
             height in millimetres.  If an unknown value is encountered,
             letter is used.

   UTF-8 Output
     Use -Tutf8 to force a UTF-8 locale.  See Locale Output for details and
     options.

   XHTML Output
     Output produced by -Txhtml conforms to XHTML-1.0 strict.

     See HTML Output for details; beyond generating XHTML tags instead of HTML
     tags, these output modes are identical.

EXIT STATUS
     The mandoc utility exits with one of the following values, controlled by
     the message level associated with the -W option:

     0       No warnings or errors occurred, or those that did were ignored
             because they were lower than the requested level.
     2       At least one warning occurred, but no error, and -Wwarning was
             specified.
     3       At least one parsing error occurred, but no fatal error, and
             -Werror or -Wwarning was specified.
     4       A fatal parsing error occurred.
     5       Invalid command line arguments were specified.  No input files
             have been read.
     6       An operating system error occurred, for example memory exhaustion
             or an error accessing input files.  Such errors cause mandoc to
             exit at once, possibly in the middle of parsing or formatting a
             file.

     Note that selecting -Tlint output mode implies -Wwarning.

EXAMPLES
     To page manuals to the terminal:

           $ mandoc -Wall,stop mandoc.1 2>&1 | less
           $ mandoc mandoc.1 mdoc.3 mdoc.7 | less

     To produce HTML manuals with style.css as the style-sheet:

           $ mandoc -Thtml -Ostyle=style.css mdoc.7 > mdoc.7.html

     To check over a large set of manuals:

           $ mandoc -Tlint `find /usr/src -name \*\.[1-9]`

     To produce a series of PostScript manuals for A4 paper:

           $ mandoc -Tps -Opaper=a4 mdoc.7 man.7 > manuals.ps

     Convert a modern mdoc(7) manual to the older man(7) format, for use on
     systems lacking an mdoc(7) parser:

           $ mandoc -Tman foo.mdoc > foo.man

DIAGNOSTICS
     Standard error messages reporting parsing errors are prefixed by

           file:line:column: level:

     where the fields have the following meanings:

     file    The name of the input file causing the message.

     line    The line number in that input file.  Line numbering starts at 1.

     column  The column number in that input file.  Column numbering starts at
             1.  If the issue is caused by a word, the column number usually
             points to the first character of the word.

     level   The message level, printed in capital letters.

     Message levels have the following meanings:

     fatal    The parser is unable to parse a given input file at all.  No
              formatted output is produced from that input file.

     error    An input file contains syntax that cannot be safely interpreted,
              either because it is invalid or because mandoc does not
              implement it yet.  By discarding part of the input or inserting
              missing tokens, the parser is able to continue, and the error
              does not prevent generation of formatted output, but typically,
              preparing that output involves information loss, broken document
              structure or unintended formatting.

     warning  An input file uses obsolete, discouraged or non-portable syntax.
              All the same, the meaning of the input is unambiguous and a
              correct rendering can be produced.  Documents causing warnings
              may render poorly when using other formatting tools instead of
              mandoc.

     Messages of the warning and error levels are hidden unless their level,
     or a lower level, is requested using a -W option or -Tlint output mode.

     The mandoc utility may also print messages related to invalid command
     line arguments or operating system errors, for example when memory is
     exhausted or input files cannot be read.  Such messages do not carry the
     prefix described above.

COMPATIBILITY
     This section summarises mandoc compatibility with GNU troff.  Each input
     and output format is separately noted.

   ASCII Compatibility
     +o   Unrenderable unicode codepoints specified with '\[uNNNN]' escapes are
         printed as '?' in mandoc.  In GNU troff, these raise an error.
     +o   The 'Bd -literal' and 'Bd -unfilled' macros of mdoc(7) in -Tascii are
         synonyms, as are -filled and -ragged.
     +o   In historic GNU troff, the 'Pa' mdoc(7) macro does not underline when
         scoped under an 'It' in the FILES section.  This behaves correctly in
         mandoc.
     +o   A list or display following the 'Ss' mdoc(7) macro in -Tascii does
         not assert a prior vertical break, just as it doesn't with 'Sh'.
     +o   The 'na' man(7) macro in -Tascii has no effect.
     +o   Words aren't hyphenated.

   HTML/XHTML Compatibility
     +o   The '\fP' escape will revert the font to the previous '\f' escape,
         not to the last rendered decoration, which is now dictated by CSS
         instead of hard-coded.  It also will not span past the current scope,
         for the same reason.  Note that in ASCII Output mode, this will work
         fine.
     +o   The mdoc(7) 'Bl -hang' and 'Bl -tag' list types render similarly (no
         break following overreached left-hand side) due to the expressive
         constraints of HTML.
     +o   The man(7) 'IP' and 'TP' lists render similarly.

SEE ALSO
     eqn(7), man(7), mandoc_char(7), mdoc(7), roff(7), tbl(7)

AUTHORS
     The mandoc utility was written by Kristaps Dzonsons, kristaps@bsd.lv.

CAVEATS
     In -Thtml and -Txhtml, the maximum size of an element attribute is
     determined by BUFSIZ, which is usually 1024 bytes.  Be aware of this when
     setting long link formats such as -Ostyle=really/long/link.

     Nesting elements within next-line element scopes of -man, such as 'br'
     within an empty 'B', will confuse -Thtml and -Txhtml and cause them to
     forget the formatting of the prior next-line scope.

     The ''' control character is an alias for the standard macro control
     character and does not emit a line-break as stipulated in GNU troff.

BSD                            December 25, 2011                           BSD

NAME | SYNOPSIS | DESCRIPTION | EXIT STATUS | EXAMPLES | DIAGNOSTICS | COMPATIBILITY | SEE ALSO | AUTHORS | CAVEATS