-.\" $Id: mandoc.1,v 1.179 2017/03/18 19:51:19 schwarze Exp $
+.\" $Id: mandoc.1,v 1.188 2017/05/17 23:39:31 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 18 2017 $
+.Dd $Mdocdate: May 17 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.
.It Fl K Ar encoding
Specify the input encoding.
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
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,
.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
.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.
.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
.Ic \&Bl
.Fl offset
or
-.Fl width.
+.Fl width .
.It Sy "missing display type, using -ragged"
.Pq mdoc
The
git.ckatri.com / mandoc.git / blobdiff