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