MANDOC(1) | General Commands Manual | MANDOC(1) |
mandoc
— format
and display UNIX manuals
mandoc |
[-acfhkl ] [-I
os =name]
[-K encoding]
[-m format]
[-O option]
[-T output]
[-W level]
[file ...] |
The mandoc
utility formats
UNIX manual pages for display.
By default, mandoc
reads
mdoc(7) or
man(7) text from stdin, implying
-m
andoc
, and produces
-T
locale
output.
The options are as follows:
-a
-c
is not specified, use more(1)
to paginate the output, just like
man(1) would.-c
-a
.-f
-k
and
-l
options.-I
os
=name-h
-c
.-K
encodingus-ascii
,
iso-8859-1
, and utf-8
. If
not specified, autodetection uses the first match:
utf-8
utf-8
iso-8859-1
-k
-f
and
-l
options.-l
-a
. Also reverts any earlier
-f
and -k
options.-m
format-m
andoc
.-O
option-T
output-T
locale
.-W
levelwarning
,
error
, or unsupp
;
all
is an alias for
warning
. 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
will halt
with the first failed parse.In -f
and -k
mode,
mandoc
also supports the options
-CMmOSsw
described in the
apropos(1) manual.
The mandoc
utility accepts
mdoc(7) and
man(7) input with
-m
doc
and
-m
an
, respectively. The
mdoc(7) format is
strongly
recommended; man(7) should only
be used for legacy manuals.
A third option,
-m
andoc
, 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
-m
andoc
, each has its
file-type determined this way. If multiple files are specified and
-m
doc
or
-m
an
is specified, then this
format is used exclusively.
The mandoc
utility accepts the following
-T
arguments, which correspond to output modes:
-T
ascii
-T
html
-T
lint
-W
warning
.-T
locale
-T
man
-T
pdf
-T
ps
-T
tree
-T
utf8
-T
xhtml
-T
html
.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.
Output width is limited to 78 visible columns unless literal input lines exceed this limit.
The following -O
arguments are
accepted:
indent
=indentwidth
=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 example.style.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:
fragment
style
argument will be ignored. This
is useful when embedding manual content within existing documents.includes
=fmtman
=fmtstyle
=style.cssLocale-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.
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 a UTF-8 locale. See Locale
Output for details and options.
The mandoc
utility exits with one of the
following values, controlled by the message level
associated with the -W
option:
-W
warning
was
specified.-W
error
or -W
warning
was
specified.-W
unsupp
,
-W
error
or
-W
warning
was
specified.mandoc
to exit at once, possibly in the middle of
parsing or formatting a file.Note that selecting -T
lint
output mode implies -W
warning
.
To page manuals to the terminal:
$ mandoc -W all,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 -T html -O style=style.css
mdoc.7 > mdoc.7.html
To 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.ps
Convert 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.man
Messages displayed by mandoc
follow this
format:
mandoc
:
file:line:column:
level: message:
macro argsLine 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. 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:
unsupp
mandoc
to process the file may be preferable.error
mandoc
or GNU troff is used. In many cases, the
output of mandoc
and GNU troff is identical, but
in some, mandoc
is more resilient than GNU troff
with respect to malformed input.
Non-existent or unreadable input files are also reported on
the error
level. In that case, the parser cannot
even be started and no output is produced from those input files.
warning
mandoc
.Messages of the 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.
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.Dt
or TH
macro lacks the mandatory section argument.Dt
line is invalid,
but still used.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 Os
macro
occurs after some non-prologue macro, but still takes effect.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.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.Nd
child macro.Nd
child
macro, but other content follows it.Nm
and Nd
.Nd
macro lacks the required argument.
The title line of the manual will end after the dash.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 SS
Bl
list contains a
trailing paragraph macro. The paragraph macro is moved after the end of
the list.Ns
macro. 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.Vt
macro supports plain text arguments
only. Formatting may be ugly and semantic searching for the affected
content might not work.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.el
clause.Bd
, Bk
,
Bl
, D1
,
Dl
, 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.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.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.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.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.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.mandoc
utility treats the line as a
comment line even without the backslash, but leaving out the backslash
might not be portable.\*
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.so
file inclusion.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.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.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.Bl
macro fails to specify the list
type.Nm
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
-D
OSNAME="\"
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.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
,
PD
, RS
,
UR
, ft
, or
sp
with more than one argumentAn
with another argument after -split
or
-nosplit
RE
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.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 was written by
Kristaps Dzonsons
<kristaps@bsd.lv> and
is maintained by Ingo Schwarze
<schwarze@openbsd.org>.
In -T
html
, 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 -O
style
=really/long/link.
April 3, 2015 | OpenBSD-5.8 |