-.\" $Id: mandoc.1,v 1.141 2015/01/29 00:33:57 schwarze Exp $
+.\" $Id: mandoc.1,v 1.168 2017/01/08 00:11:23 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
-.\" Copyright (c) 2012, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2012, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: January 29 2015 $
+.Dd $Mdocdate: January 8 2017 $
.Dt MANDOC 1
.Os
.Sh NAME
.Nd format and display UNIX manuals
.Sh SYNOPSIS
.Nm mandoc
-.Op Fl acfhklV
-.Sm off
-.Op Fl I Cm os Li = Ar name
-.Sm on
-.Op Fl K Ns Ar encoding
+.Op Fl acfhkl
+.Op Fl I Cm os Ns = Ns Ar name
+.Op Fl K Ar encoding
.Op Fl m Ns Ar format
-.Op Fl O Ns Ar option
-.Op Fl T Ns Ar output
-.Op Fl W Ns Ar level
+.Op Fl O Ar option
+.Op Fl T Ar output
+.Op Fl W Ar level
.Op Ar
.Sh DESCRIPTION
The
text from stdin, implying
.Fl m Ns Cm andoc ,
and produces
-.Fl T Ns Cm locale
+.Fl T Cm locale
output.
.Pp
The options are as follows:
and
.Fl l
options.
-.Sm off
-.It Fl I Cm os Li = Ar name
-.Sm on
+.It Fl h
+Display only the SYNOPSIS lines.
+Implies
+.Fl c .
+.It Fl I Cm os Ns = Ns Ar name
Override the default operating system
.Ar name
for the
.Xr man 7
.Sq \&TH
macro.
-.It Fl h
-Display only the SYNOPSIS lines.
-Implies
-.Fl c .
-.It Fl K Ns Ar encoding
+.It Fl K Ar encoding
Specify the input encoding.
The supported
.Ar encoding
for available formats.
Defaults to
.Fl m Ns Cm andoc .
-.It Fl O Ns Ar option
+.It Fl O Ar option
Comma-separated output options.
-.It Fl T Ns Ar output
+.It Fl T Ar output
Output format.
See
.Sx Output Formats
for available formats.
Defaults to
-.Fl T Ns Cm locale .
-.It Fl V
-Print version and exit.
-.It Fl W Ns Ar level
+.Fl T Cm locale .
+.It Fl W Ar level
Specify the minimum message
.Ar level
to be reported on the standard error output and to affect the exit status.
for details.
.Pp
The special option
-.Fl W Ns Cm stop
+.Fl W Cm stop
tells
.Nm
to exit after parsing a file that causes warnings or errors of at least
and
.Cm stop
are requested, they can be joined with a comma, for example
-.Fl W Ns Cm error , Ns Cm stop .
+.Fl W Cm error , Ns Cm stop .
.It Ar file
Read input from zero or more files.
If unspecified, reads from stdin.
utility accepts the following
.Fl T
arguments, which correspond to output modes:
-.Bl -tag -width "-Tlocale"
-.It Fl T Ns Cm ascii
+.Bl -tag -width "-T locale"
+.It Fl T Cm ascii
Produce 7-bit ASCII output.
See
.Sx ASCII Output .
-.It Fl T Ns Cm html
+.It Fl T Cm html
Produce HTML5, CSS1, and MathML output.
See
.Sx HTML Output .
-.It Fl T Ns Cm lint
+.It Fl T Cm lint
Parse only: produce no output.
Implies
-.Fl W Ns Cm warning .
-.It Fl T Ns Cm locale
+.Fl W Cm warning .
+.It Fl T Cm locale
Encode output using the current locale.
This is the default.
See
.Sx Locale Output .
-.It Fl T Ns Cm man
+.It Fl T Cm man
Produce
.Xr man 7
format output.
See
.Sx Man Output .
-.It Fl T Ns Cm pdf
+.It Fl T Cm pdf
Produce PDF output.
See
.Sx PDF Output .
-.It Fl T Ns Cm ps
+.It Fl T Cm ps
Produce PostScript output.
See
.Sx PostScript Output .
-.It Fl T Ns Cm tree
+.It Fl T Cm tree
Produce an indented parse tree.
-.It Fl T Ns Cm utf8
+See
+.Sx Syntax tree output .
+.It Fl T Cm utf8
Encode output in the UTF\-8 multi-byte format.
See
.Sx UTF\-8 Output .
-.It Fl T Ns Cm xhtml
+.It Fl T Cm xhtml
This is a synonym for
-.Fl T Ns Cm html .
+.Fl T Cm html .
.El
.Pp
If multiple input files are specified, these will be processed by the
corresponding filter in-order.
.Ss ASCII Output
Output produced by
-.Fl T Ns Cm ascii
+.Fl T Cm ascii
is rendered in standard 7-bit ASCII documented in
.Xr ascii 7 .
.Pp
.El
.Ss HTML Output
Output produced by
-.Fl T Ns Cm html
+.Fl T Cm html
conforms to HTML5 using optional self-closing tags.
Default styles use only CSS1.
Equations rendered from
blocks use MathML.
.Pp
The
-.Pa example.style.css
+.Pa mandoc.css
file documents style-sheet classes available for customising output.
If a style-sheet is not specified with
-.Fl O Ns Ar style ,
-.Fl T Ns Cm html
+.Fl O Cm style ,
+.Fl T Cm html
defaults to simple output (via an embedded style-sheet)
readable in any graphical or text-based web
browser.
.El
.Ss Locale Output
Locale-depending output encoding is triggered with
-.Fl T Ns Cm locale .
+.Fl T Cm locale .
This is the default.
.Pp
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
-.Fl T Ns Cm ascii .
+.Fl T Cm ascii .
See
.Sx ASCII Output
for font style specification and available command-line arguments.
are displayed before copying the input to the output.
.Ss PDF Output
PDF-1.1 output may be generated by
-.Fl T Ns Cm pdf .
+.Fl T Cm pdf .
See
.Sx PostScript Output
for
PostScript
.Qq Adobe-3.0
Level-2 pages may be generated by
-.Fl T Ns Cm ps .
+.Fl T Cm 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.
.El
.Ss UTF\-8 Output
Use
-.Fl T Ns Cm utf8
+.Fl T Cm utf8
to force a UTF\-8 locale.
See
.Sx Locale Output
for details and options.
+.Ss Syntax tree output
+Use
+.Fl T Cm 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.
+Each output line shows one syntax tree node.
+Child nodes are indented with respect to their parent node.
+The columns are:
+.Pp
+.Bl -enum -compact
+.It
+For macro nodes, the macro name; for text and
+.Xr tbl 7
+nodes, the content.
+There is a special format for
+.Xr eqn 7
+nodes.
+.It
+Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
+.It
+Flags:
+.Bl -dash -compact
+.It
+An opening parenthesis if the node is an opening delimiter.
+.It
+An asterisk if the node starts a new input line.
+.It
+The input line number (starting at one).
+.It
+A colon.
+.It
+The input column number (starting at one).
+.It
+A closing parenthesis if the node is a closing delimiter.
+.It
+A full stop if the node ends a sentence.
+.El
+.El
.Sh ENVIRONMENT
.Bl -tag -width MANPAGER
.It Ev MANPAGER
.Ev MANPAGER
is not defined.
If neither PAGER nor MANPAGER is defined,
-.Pa /usr/bin/more Fl s
+.Xr more 1
+.Fl s
will be used.
.El
.Sh EXIT STATUS
.Ar level .
.It 2
At least one warning occurred, but no error, and
-.Fl W Ns Cm warning
+.Fl W Cm warning
was specified.
.It 3
At least one parsing error occurred,
but no unsupported feature was encountered, and
-.Fl W Ns Cm error
+.Fl W Cm error
or
-.Fl W Ns Cm warning
+.Fl W Cm warning
was specified.
.It 4
At least one unsupported feature was encountered, and
-.Fl W Ns Cm unsupp ,
-.Fl W Ns Cm error
+.Fl W Cm unsupp ,
+.Fl W Cm error
or
-.Fl W Ns Cm warning
+.Fl W Cm warning
was specified.
.It 5
Invalid command line arguments were specified.
.El
.Pp
Note that selecting
-.Fl T Ns Cm lint
+.Fl T Cm lint
output mode implies
-.Fl W Ns Cm warning .
+.Fl W Cm warning .
.Sh EXAMPLES
To page manuals to the terminal:
.Pp
-.Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less
+.Dl $ mandoc \-W all,stop mandoc.1 2\*(Gt&1 | less
.Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
.Pp
To produce HTML manuals with
-.Ar style.css
+.Pa mandoc.css
as the style-sheet:
.Pp
-.Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
+.Dl $ mandoc \-T html -O style=mandoc.css mdoc.7 \*(Gt mdoc.7.html
.Pp
To check over a large set of manuals:
.Pp
-.Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]`
+.Dl $ mandoc \-T lint \(gafind /usr/src -name \e*\e.[1-9]\(ga
.Pp
To produce a series of PostScript manuals for A4 paper:
.Pp
-.Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
+.Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 \*(Gt manuals.ps
.Pp
Convert a modern
.Xr mdoc 7
.Xr mdoc 7
parser:
.Pp
-.Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man
+.Dl $ mandoc \-T man foo.mdoc \*(Gt foo.man
.Sh DIAGNOSTICS
Messages displayed by
.Nm
are hidden unless their level, or a lower level, is requested using a
.Fl W
option or
-.Fl T Ns Cm lint
+.Fl T Cm lint
output mode.
.Ss Warnings related to the document prologue
.Bl -ohang
.Pq mdoc
The
.Ic \&Dt
-macro can only occur before the first non-prologue macro
-because traditional formatters write the page header
-before parsing the document body.
+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
.Nm ,
traditional semantics is preserved.
.Xr makewhatis 8
and
.Xr apropos 1 .
-.It Sy "bad NAME section contents"
+.It Sy "NAME section without Nm before Nd"
.Pq mdoc
-The last node in the NAME section is not an
+The NAME section does not contain any
+.Ic \&Nm
+child macro before the first
.Ic \&Nd
-macro, or any preceding macro is not
-.Ic \&Nm ,
-or the NAME section is completely empty.
-This may confuse
-.Xr makewhatis 8
+macro.
+.It Sy "NAME section without description"
+.Pq mdoc
+The NAME section lacks the mandatory
+.Ic \&Nd
+child macro.
+.It Sy "description not at the end of NAME"
+.Pq mdoc
+The NAME section does contain an
+.Ic \&Nd
+child macro, but other content follows it.
+.It Sy "bad NAME section content"
+.Pq mdoc
+The NAME section contains plain text or macros other than
+.Ic \&Nm
and
-.Xr apropos 1 .
+.Ic \&Nd .
+.It Sy "missing comma before name"
+.Pq mdoc
+The NAME section contains an
+.Ic \&Nm
+macro that is neither the first one nor preceded by a comma.
+.It Sy "missing description line, using \(dq\(dq"
+.Pq mdoc
+The
+.Ic \&Nd
+macro lacks the required argument.
+The title line of the manual will end after the dash.
.It Sy "sections out of conventional order"
.Pq mdoc
A standard section occurs after another section it usually precedes.
macro with a lower section number follows one with a higher number,
or two
.Ic \&Xr
-macros refering to the same section are out of alphabetical order.
+macros referring to the same section are out of alphabetical order.
.It Sy "unusual Xr punctuation"
.Pq mdoc
In the SEE ALSO section, punctuation between two
.Pq mdoc
The name of a macro that is not callable appears on a macro line.
It is printed verbatim.
-If the intention is to call it, move it to its own line;
+If the intention is to call it, move it to its own input line;
otherwise, escape it by prepending
.Sq \e& .
.It Sy "skipping paragraph macro"
.Ic \&It
macro.
The offending children are moved before the beginning of the list.
-.It Sy ".Vt block has child macro"
-.Pq mdoc
-The
-.Ic \&Vt
-macro supports plain text arguments only.
-Formatting may be ugly and semantic searching
-for the affected content might not work.
.It Sy "fill mode already enabled, skipping"
.Pq man
A
.It Sy "skipping empty macro"
.Pq mdoc
The indicated macro has no arguments and hence no effect.
+.It Sy "empty block"
+.Pq mdoc , man
+A
+.Ic \&Bd ,
+.Ic \&Bk ,
+.Ic \&Bl ,
+.Ic \&D1 ,
+.Ic \&Dl ,
+.Ic \&RS ,
+or
+.Ic \&UR
+block contains nothing in its body and will produce no output.
.It Sy "empty argument, using 0n"
.Pq mdoc
The required width is missing after
.Fl offset
or
.Fl width.
-.It Sy "argument count wrong"
-.Pq mdoc , man
-The indicated macro has too few or too many arguments.
-The syntax tree will contain the wrong number of arguments as given.
-Formatting behaviour depends on the specific macro in question.
-Note that the same message may also occur as an ERROR, see below.
.It Sy "missing display type, using -ragged"
.Pq mdoc
The
macro is called without an argument before
.Ic \&Nm
has first been called with an argument.
+.It Sy "missing function name, using \(dq\(dq"
+.Pq mdoc
+The
+.Ic \&Fo
+macro is called without an argument.
+No function name is printed.
.It Sy "empty head in list item"
.Pq mdoc
In a
.Ic \&It
block is empty.
An empty list item is shown.
-.It Sy "missing font type"
+.It Sy "missing font type, using \efR"
.Pq mdoc
A
.Ic \&Bf
macro has no argument.
-It switches to the default font,
-.Cm \efR .
-.It Sy "unknown font type"
+It switches to the default font.
+.It Sy "unknown font type, using \efR"
.Pq mdoc
The
.Ic \&Bf
argument is invalid.
-The default font
-.Cm \efR
-is used instead.
+The default font is used instead.
.It Sy "nothing follows prefix"
.Pq mdoc
A
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.
+.It Sy "empty reference block"
+.Pq mdoc
+An
+.Ic \&Rs
+macro is immediately followed by an
+.Ic \&Re
+macro on the next input line.
+Such an empty block does not produce any output.
+.It Sy "missing section argument"
+.Pq mdoc
+An
+.Ic \&Xr
+macro lacks its second, section number argument.
+The first argument, i.e. the name, is printed, but without subsequent
+parentheses.
.It Sy "missing -std argument, adding it"
.Pq mdoc
An
utility assumes
.Fl std
even when it is not specified, but other implementations may not.
+.It Sy "missing option string, using \(dq\(dq"
+.Pq man
+The
+.Ic \&OP
+macro is invoked without any argument.
+An empty pair of square brackets is shown.
+.It Sy "missing resource identifier, using \(dq\(dq"
+.Pq man
+The
+.Ic \&UR
+macro is invoked without any argument.
+An empty pair of angle brackets is shown.
.It Sy "missing eqn box, using \(dq\(dq"
.Pq eqn
A diacritic mark or a binary operator is found,
.Fl width
argument.
That has no effect.
+.It Sy "wrong number of cells"
+In a line of a
+.Ic \&Bl Fl column
+list, the number of tabs or
+.Ic \&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.
.It Sy "unknown AT&T UNIX version"
.Pq mdoc
An
layout modifier has an unknown
.Ar font
argument.
+.It Sy "odd number of characters in request"
+.Pq roff
+A
+.Ic \&tr
+request contains an odd number of characters.
+The last character is mapped to the blank character.
.El
.Ss "Warnings related to plain text"
.Bl -ohang
A block that doesn't support bad nesting
ends before all of its children are properly closed.
The open child nodes are closed implicitly.
-.It Sy "scope open on exit"
+.It Sy "appending missing end of block"
.Pq mdoc , man , eqn , tbl , roff
At the end of the document, an explicit
.Xr mdoc 7
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.
-.It Sy "argument count wrong"
-.Pq mdoc , man , roff
-The indicated request or macro has too few or too many arguments.
-The syntax tree will contain the wrong number of arguments as given.
-Formatting behaviour depends on the specific request or macro in question.
-Note that the same message may also occur as a WARNING, see above.
.It Sy "NOT IMPLEMENTED: Bd -file"
.Pq mdoc
For security reasons, the
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.
+.It Sy "skipping display without arguments"
+.Pq mdoc
+A
+.Ic \&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.
.It Sy "missing list type, using -item"
.Pq mdoc
A
.It Sy "missing manual name, using \(dq\(dq"
.Pq mdoc
The first call to
-.Ic \&Nm
-lacks the required argument.
+.Ic \&Nm ,
+or any call in the NAME section, lacks the required argument.
.It Sy "uname(3) system call failed, using UNKNOWN"
.Pq mdoc
The
.Ic \&Ef ,
.Ic \&Ek ,
.Ic \&El ,
+.Ic \&Lp ,
+.Ic \&Pp ,
.Ic \&Re ,
+.Ic \&Rs ,
or
.Ic \&Ud
macro, an
.Ic \&EN
macro, or a
.Xr roff 7
+.Ic \&br ,
+.Ic \&fi ,
+or
+.Ic \&nf
+request or
.Sq \&..
block closing request is invoked with at least one argument.
All arguments are ignored.
.It Sy "skipping excess arguments"
.Pq mdoc , man , roff
-The
-.Ic \&Bf
-macro is invoked with more than one argument, the
+A macro or request is invoked with too many arguments:
+.Bl -dash -offset 2n -width 2n -compact
+.It
+.Ic \&Fo ,
+.Ic \&PD ,
+.Ic \&RS ,
+.Ic \&UR ,
+.Ic \&ft ,
+or
+.Ic \&sp
+with more than one argument
+.It
+.Ic \&An
+with another argument after
+.Fl split
+or
+.Fl nosplit
+.It
.Ic \&RE
-macro is invoked with more than one argument
-or with a non-integer argument, or a request of the
+with more than one argument or with a non-integer argument
+.It
+.Ic \&OP
+or a request of the
.Ic \&de
-family is invoked with more than two arguments.
+family with more than two arguments
+.It
+.Ic \&Dt
+with more than three arguments
+.It
+.Ic \&TH
+with more than five arguments
+.It
+.Ic \&Bd ,
+.Ic \&Bk ,
+or
+.Ic \&Bl
+with invalid arguments
+.El
The excess arguments are ignored.
.El
.Ss Unsupported features
.Xr roff 7 ,
.Xr tbl 7
.Sh AUTHORS
+.An -nosplit
The
.Nm
utility was written by
.An Ingo Schwarze Aq Mt schwarze@openbsd.org .
.Sh BUGS
In
-.Fl T Ns Cm html ,
+.Fl T Cm html ,
the maximum size of an element attribute is determined by
.Dv BUFSIZ ,
which is usually 1024 bytes.
Be aware of this when setting long link
formats such as
-.Fl O Ns Cm style Ns = Ns Ar really/long/link .
+.Fl O Cm style Ns = Ns Ar really/long/link .
git.ckatri.com / mandoc.git / blobdiff