-.\" $Id: mandoc.1,v 1.178 2017/03/08 19:40:59 schwarze Exp $
+.\" $Id: mandoc.1,v 1.199 2017/06/13 15:06:56 schwarze Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2012, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
-.Dd $Mdocdate: March 8 2017 $
+.Dd $Mdocdate: June 13 2017 $
.Dt MANDOC 1
.Os
.Sh NAME
.Nm mandoc
-.Nd format and display UNIX manuals
+.Nd format manual pages
.Sh SYNOPSIS
.Nm mandoc
-.Op Fl acfhkl
+.Op Fl ac
.Op Fl I Cm os Ns = Ns Ar name
.Op Fl K Ar encoding
-.Op Fl m Ns Ar format
-.Op Fl O Ar option
+.Op Fl mdoc | man
+.Op Fl O Ar options
.Op Fl T Ar output
.Op Fl W Ar level
.Op Ar
.Xr mdoc 7
or
.Xr man 7
-text from stdin, implying
-.Fl m Ns Cm andoc ,
-and produces
+text from stdin and produces
.Fl T Cm locale
output.
.Pp
This is the default.
It can be specified to override
.Fl a .
-.It Fl f
-A synonym for
-.Xr whatis 1 .
-This overrides any earlier
-.Fl k
-and
-.Fl l
-options.
-.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 mdoc 7
-.Sq \&Os
+.Ic \&Os
and for the
.Xr man 7
-.Sq \&TH
+.Ic \&TH
macro.
+This can also be used to perform style checks according to the
+conventions of one operating system while running on a different
+operating system; see
+.Sx Style messages
+for details.
.It Fl K Ar encoding
Specify the input encoding.
The supported
Otherwise, input is interpreted as
.Cm iso-8859-1 .
.El
-.It Fl k
-A synonym for
-.Xr apropos 1 .
-This overrides any earlier
-.Fl f
-and
-.Fl l
-options.
-.It Fl l
-A synonym for
-.Fl a .
-Also reverts any earlier
-.Fl f
-and
-.Fl k
-options.
-.It Fl m Ns Ar format
-Input format.
-See
-.Sx Input Formats
-for available formats.
-Defaults to
-.Fl m Ns Cm andoc .
-.It Fl O Ar option
+.It Fl mdoc | man
+With
+.Fl mdoc ,
+all input files are interpreted as
+.Xr mdoc 7 .
+With
+.Fl man ,
+all input files are interpreted as
+.Xr man 7 .
+By default, the input language is automatically detected for each file:
+if the the first macro is
+.Ic \&Dd
+or
+.Ic \&Dt ,
+the
+.Xr mdoc 7
+parser is used; otherwise, the
+.Xr man 7
+parser is used.
+With other arguments,
+.Fl m
+is silently ignored.
+.It Fl O Ar options
Comma-separated output options.
.It Fl T Ar output
Output format.
The
.Ar level
can be
+.Cm style ,
.Cm warning ,
.Cm error ,
or
.Cm unsupp ;
.Cm all
is an alias for
-.Cm warning .
+.Cm style .
By default,
.Nm
is silent.
will halt with the first failed parse.
.El
.Pp
+The options
+.Fl fhklw
+are also supported and are documented in man(1).
In
.Fl f
and
mode,
.Nm
also supports the options
-.Fl CMmOSsw
+.Fl CMmOSs
described in the
.Xr apropos 1
manual.
-.Ss Input Formats
-The
-.Nm
-utility accepts
-.Xr mdoc 7
-and
-.Xr man 7
-input with
-.Fl m Ns Cm doc
-and
-.Fl m Ns Cm an ,
-respectively.
-The
-.Xr mdoc 7
-format is
-.Em strongly
-recommended;
-.Xr man 7
-should only be used for legacy manuals.
-.Pp
-A third option,
-.Fl m Ns Cm andoc ,
-which is also the default, determines encoding on-the-fly: if the first
-non-comment macro is
-.Sq \&Dd
-or
-.Sq \&Dt ,
-the
-.Xr mdoc 7
-parser is used; otherwise, the
-.Xr man 7
-parser is used.
-.Pp
-If multiple
-files are specified with
-.Fl m Ns Cm andoc ,
-each has its file-type determined this way.
-If multiple files are
-specified and
-.Fl m Ns Cm doc
-or
-.Fl m Ns Cm an
-is specified, then this format is used exclusively.
+The options
+.Fl fkl
+are mutually exclusive and override each other.
.Ss Output Formats
The
.Nm
.It Fl T Cm lint
Parse only: produce no output.
Implies
-.Fl W Cm warning .
+.Fl W Cm style .
.It Fl T Cm locale
Encode output using the current locale.
This is the default.
Encode output in the UTF\-8 multi-byte format.
See
.Sx UTF\-8 Output .
-.It Fl T Cm xhtml
-This is a synonym for
-.Fl T Cm html .
.El
.Pp
If multiple input files are specified, these will be processed by the
for example overfull lines or ugly line breaks.
.It Cm width Ns = Ns Ar width
The output width is set to
-.Ar width ,
-which will normalise to \(>=58.
+.Ar width .
.El
.Ss HTML Output
Output produced by
for example,
.Ar ../src/%I.html ,
is used as a template for linked header files (usually via the
-.Sq \&In
+.Ic \&In
macro).
Instances of
.Sq \&%I
for example,
.Ar ../html%S/%N.%S.html ,
is used as a template for linked manuals (usually via the
-.Sq \&Xr
+.Ic \&Xr
macro).
Instances of
.Sq \&%N
.Xr man 7 ,
the input is copied to the output, expanding any
.Xr roff 7
-.Sq so
+.Ic so
requests.
The parser is also run, and as usual, the
.Fl W
.It Ev MANPAGER
Any non-empty value of the environment variable
.Ev MANPAGER
-will be used instead of the standard pagination program,
-.Xr more 1 .
+is used instead of the standard pagination program,
+.Xr more 1 ;
+see
+.Xr man 1
+for details.
+Only used if
+.Fl a
+or
+.Fl l
+is specified.
.It Ev PAGER
Specifies the pagination program to use when
.Ev MANPAGER
If neither PAGER nor MANPAGER is defined,
.Xr more 1
.Fl s
-will be used.
+is used.
+Only used if
+.Fl a
+or
+.Fl l
+is specified.
.El
.Sh EXIT STATUS
The
.Pp
.Bl -tag -width Ds -compact
.It 0
-No warnings or errors occurred, or those that did were ignored because
-they were lower than the requested
+No style suggestions, warnings or errors occurred, or those that
+did were ignored because they were lower than the requested
.Ar level .
+.It 1
+At least one style suggestion occurred, but no warning or error, and
+.Fl W Cm style
+was specified.
.It 2
At least one warning occurred, but no error, and
.Fl W Cm warning
+or
+.Fl W Cm style
was specified.
.It 3
At least one parsing error occurred,
but no unsupported feature was encountered, and
.Fl W Cm error
-or
-.Fl W Cm warning
-was specified.
+or a lower
+.Ar level
+was requested.
.It 4
At least one unsupported feature was encountered, and
-.Fl W Cm unsupp ,
-.Fl W Cm error
-or
-.Fl W Cm warning
-was specified.
+.Fl W Cm unsupp
+or a lower
+.Ar level
+was requested.
.It 5
Invalid command line arguments were specified.
No input files have been read.
Note that selecting
.Fl T Cm lint
output mode implies
-.Fl W Cm warning .
+.Fl W Cm style .
.Sh EXAMPLES
To page manuals to the terminal:
.Pp
-.Dl $ mandoc \-W all,stop mandoc.1 2\*(Gt&1 | less
-.Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
+.Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8
.Pp
To produce HTML manuals with
.Pa mandoc.css
Documents causing warnings may render poorly when using other
formatting tools instead of
.Nm .
+.It Cm style
+An input file uses dubious or discouraged style.
+This is not a complaint about the syntax, and probably neither
+formatting nor portability are in danger.
+While great care is taken to avoid false positives on the higher
+message levels, the
+.Cm style
+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
+.Cm style
+suggestion really justifies a change to the input file.
.El
.Pp
Messages of the
+.Cm style ,
.Cm warning ,
.Cm error ,
and
option or
.Fl T Cm lint
output mode.
+.Ss Style messages
+As indicated below, some style checks are only performed if a
+specific operating system name occurs in the arguments of the
+.Ic \&Os
+macro, of the
+.Fl Ios
+command line option, or, if neither are present, in the return value
+of the
+.Xr uname 3
+function.
+.Bl -ohang
+.It Sy "useless macro"
+.Pq mdoc
+A
+.Ic \&Bt ,
+.Ic \&Tn ,
+or
+.Ic \&Ud
+macro was found.
+Simply delete it: it serves no useful purpose.
+.It Sy "consider using OS macro"
+.Pq mdoc
+A string was found in plain text or in a
+.Ic \&Bx
+macro that could be represented using
+.Ic \&Ox ,
+.Ic \&Nx ,
+.Ic \&Fx ,
+or
+.Ic \&Dx .
+.It Sy "errnos out of order"
+.Pq mdoc, Nx
+The
+.Ic \&Er
+items in a
+.Ic \&Bl
+list are not in alphabetical order.
+.It Sy "duplicate errno"
+.Pq mdoc, Nx
+A
+.Ic \&Bl
+list contains two consecutive
+.Ic \&It
+entries describing the same
+.Ic \&Er
+number.
+.It Sy "description line ends with a full stop"
+.Pq mdoc
+Do not use punctuation at the end of an
+.Ic \&Nd
+block.
+.It Sy "no blank before trailing delimiter"
+.Pq mdoc
+The last argument of a macro that supports trailing delimiter
+arguments is longer than one byte and ends with a trailing delimiter.
+Consider inserting a blank such that the delimiter becomes a separate
+argument, thus moving it out of the scope of the macro.
+.It Sy "function name without markup"
+.Pq mdoc
+A word followed by an empty pair of parentheses occurs on a text line.
+Consider using an
+.Ic \&Fn
+or
+.Ic \&Xr
+macro.
+.El
.Ss Warnings related to the document prologue
.Bl -ohang
.It Sy "missing manual title, using UNTITLED"
.Ic \&Bl
.Fl offset
or
-.Fl width.
+.Fl width .
.It Sy "missing display type, using -ragged"
.Pq mdoc
The
.Ic \&Fn
macro contains an opening or closing parenthesis; that's probably wrong,
parentheses are added automatically.
+.It Sy "unknown library name"
+.Pq mdoc, not on Ox
+An
+.Ic \&Lb
+macro has an unknown name argument and will be rendered as
+.Qq library Dq Ar name .
.It Sy "invalid content in Rs block"
.Pq mdoc
An
A
.Ic \&Bl
macro fails to specify the list type.
+.It Sy "argument is not numeric, using 1"
+.Pq roff
+The argument of a
+.Ic \&ce
+request is not a number.
.It Sy "missing manual name, using \(dq\(dq"
.Pq mdoc
The first call to
git.ckatri.com / mandoc.git / blobdiff