General Commands Manual
The last two lines above are fictional additions to mandoc's usual synopsis, included to demonstrate handling of more complex synopsis content.
The mandoc utility formats UNIX 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:
If the standard output is a terminal device and -c is not specified, use more(1) to paginate the output, just like man(1) would.
Copy the formatted manual pages to the standard output without using more(1) to paginate them. This is the default. It can be specified to override -a.
Override the default operating system name for the mdoc(7) Os
and for the man(7) TH
macro.
Specify the input encoding. The supported encoding arguments are us-ascii
, iso-8859-1
, and utf-8
. If not specified, autodetection uses the first match in the following list:
utf-8
..\" -*- […;] coding: encoding; -*-
then input is interpreted according to encoding.utf-8
.iso-8859-1
.With -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.
Comma-separated output options.
Output format. See Output Formats for available formats. Defaults to -T locale
.
Specify the minimum message level to be reported on the standard error output and to affect the exit status.
The level can be base
, 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.
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.
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.
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.
The mandoc utility accepts the following -T arguments, which correspond to output modes:
Produce 7-bit ASCII output. See ASCII Output.
Produce HTML5, CSS1, and MathML output. See HTML Output.
Parse only: produce no output. Implies -W all and redirects parser messages, which usually appear on standard error output, to standard output.
Encode output using the current locale. This is the default. See Locale Output.
Produce man(7) format output. See Man Output.
Produce output in markdown format. See Markdown Output.
Produce PDF output. See PDF Output.
Produce PostScript output. See PostScript Output.
Produce an indented parse tree. See Syntax tree output.
Encode output in the UTF-8 multi-byte format. See UTF-8 Output.
If multiple input files are specified, these will be processed by the corresponding filter in-order.
Output produced by -T ascii 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.
The following -O arguments are accepted:
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. When output is to a pager on a terminal that is less than 66 columns wide, the default is reduced to three columns.
Format man(7) input files in mdoc(7) output style. Specifically, this suppresses the two additional blank lines near the top and the bottom of each page, and it implies -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.
The output width is set to width instead of the default of 78. When output is to a pager on a terminal that is less than 79 columns wide, the default is reduced to one less than the terminal width. In any case, lines that are output in literal mode are never wrapped and may exceed the output width.
Output produced by -T html conforms to HTML5 using optional self-closing tags. Default styles use only CSS1. Equations rendered from eqn(7) blocks use MathML.
The mandoc.css file 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.
Special characters are rendered in decimal-encoded UTF-8.
The following -O arguments are accepted:
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.
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.
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.
The file style.css is used for an external style-sheet. This must be a valid absolute or relative URI.
Locale-depending output encoding is triggered with -T locale. This is the default.
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 -T ascii. See ASCII Output for font style specification and available command-line arguments.
Translate input format into man(7) output format. This is useful for distributing manual sources to legacy 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.
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.
PDF-1.1 output may be generated by -T pdf. See PostScript output for -O arguments and defaults.
PostScript “Adobe-3.0” Level-2 pages may be generated by -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:
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.
Use -T utf8 to force a UTF-8 locale. See Locale output for details and options.
Use -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:
text
, elem
, block
, head
, body
, body-end
, tail
, tbl
, eqn
).The following -O argument is accepted:
The mandoc utility exits with one of the following values, controlled by the message level associated with the -W option:
Note that selecting -T lint output mode implies -W all.
Messages displayed by mandoc follow this format:
mandoc: file:line:column: level: message: macro args (os)
Line and column numbers start at 1. Both are omitted for messages referring to an input file as a whole. Macro names and 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:
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.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.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.m
modifier. The modifier is discarded.apropos(1), man(1), eqn(7), man(7), mandoc_char(7), mdoc(7), roff(7), tbl(7)
The mandoc utility first appeared in OpenBSD 4.8. The option -I appeared in OpenBSD 5.2, and -aCcfhKklMSsw in OpenBSD 5.7.