version 1.182, 2017/03/27 14:40:39 |
version 1.195, 2017/06/07 23:29:48 |
|
|
.Nd format manual pages |
.Nd format manual pages |
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.Nm mandoc |
.Nm mandoc |
.Op Fl acfhkl |
.Op Fl ac |
.Op Fl I Cm os Ns = Ns Ar name |
.Op Fl I Cm os Ns = Ns Ar name |
.Op Fl K Ar encoding |
.Op Fl K Ar encoding |
.Op Fl mdoc | man |
.Op Fl mdoc | man |
.Op Fl O Ar option |
.Op Fl O Ar options |
.Op Fl T Ar output |
.Op Fl T Ar output |
.Op Fl W Ar level |
.Op Fl W Ar level |
.Op Ar |
.Op Ar |
Line 65 to paginate them. |
|
Line 65 to paginate them. |
|
This is the default. |
This is the default. |
It can be specified to override |
It can be specified to override |
.Fl a . |
.Fl a . |
.It Fl f |
|
A synonym for |
|
.Xr whatis 1 . |
|
.It Fl h |
|
Display only the SYNOPSIS lines. |
|
Implies |
|
.Fl c . |
|
.It Fl I Cm os Ns = Ns Ar name |
.It Fl I Cm os Ns = Ns Ar name |
Override the default operating system |
Override the default operating system |
.Ar name |
.Ar name |
|
|
.Xr man 7 |
.Xr man 7 |
.Ic \&TH |
.Ic \&TH |
macro. |
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 |
.It Fl K Ar encoding |
Specify the input encoding. |
Specify the input encoding. |
The supported |
The supported |
Line 115 sequence, input is interpreted as |
|
Line 113 sequence, input is interpreted as |
|
Otherwise, input is interpreted as |
Otherwise, input is interpreted as |
.Cm iso-8859-1 . |
.Cm iso-8859-1 . |
.El |
.El |
.It Fl k |
|
A synonym for |
|
.Xr apropos 1 . |
|
.It Fl l |
|
A synonym for |
|
.Fl a . |
|
.It Fl mdoc | man |
.It Fl mdoc | man |
With |
With |
.Fl mdoc , |
.Fl mdoc , |
|
|
With other arguments, |
With other arguments, |
.Fl m |
.Fl m |
is silently ignored. |
is silently ignored. |
.It Fl O Ar option |
.It Fl O Ar options |
Comma-separated output options. |
Comma-separated output options. |
.It Fl T Ar output |
.It Fl T Ar output |
Output format. |
Output format. |
Line 159 to be reported on the standard error output and to aff |
|
Line 151 to be reported on the standard error output and to aff |
|
The |
The |
.Ar level |
.Ar level |
can be |
can be |
|
.Cm style , |
.Cm warning , |
.Cm warning , |
.Cm error , |
.Cm error , |
or |
or |
.Cm unsupp ; |
.Cm unsupp ; |
.Cm all |
.Cm all |
is an alias for |
is an alias for |
.Cm warning . |
.Cm style . |
By default, |
By default, |
.Nm |
.Nm |
is silent. |
is silent. |
Line 196 If multiple files are specified, |
|
Line 189 If multiple files are specified, |
|
will halt with the first failed parse. |
will halt with the first failed parse. |
.El |
.El |
.Pp |
.Pp |
|
The options |
|
.Fl fhklw |
|
are also supported and are documented in man(1). |
In |
In |
.Fl f |
.Fl f |
and |
and |
|
|
mode, |
mode, |
.Nm |
.Nm |
also supports the options |
also supports the options |
.Fl CMmOSsw |
.Fl CMmOSs |
described in the |
described in the |
.Xr apropos 1 |
.Xr apropos 1 |
manual. |
manual. |
|
|
.It Fl T Cm lint |
.It Fl T Cm lint |
Parse only: produce no output. |
Parse only: produce no output. |
Implies |
Implies |
.Fl W Cm warning . |
.Fl W Cm style . |
.It Fl T Cm locale |
.It Fl T Cm locale |
Encode output using the current locale. |
Encode output using the current locale. |
This is the default. |
This is the default. |
|
|
Encode output in the UTF\-8 multi-byte format. |
Encode output in the UTF\-8 multi-byte format. |
See |
See |
.Sx UTF\-8 Output . |
.Sx UTF\-8 Output . |
.It Fl T Cm xhtml |
|
This is a synonym for |
|
.Fl T Cm html . |
|
.El |
.El |
.Pp |
.Pp |
If multiple input files are specified, these will be processed by the |
If multiple input files are specified, these will be processed by the |
|
|
.Pp |
.Pp |
.Bl -tag -width Ds -compact |
.Bl -tag -width Ds -compact |
.It 0 |
.It 0 |
No warnings or errors occurred, or those that did were ignored because |
No style suggestions, warnings or errors occurred, or those that |
they were lower than the requested |
did were ignored because they were lower than the requested |
.Ar level . |
.Ar level . |
|
.It 1 |
|
At least one style suggestion occurred, but no warning or error, and |
|
.Fl W Cm style |
|
was specified. |
.It 2 |
.It 2 |
At least one warning occurred, but no error, and |
At least one warning occurred, but no error, and |
.Fl W Cm warning |
.Fl W Cm warning |
|
or |
|
.Fl W Cm style |
was specified. |
was specified. |
.It 3 |
.It 3 |
At least one parsing error occurred, |
At least one parsing error occurred, |
but no unsupported feature was encountered, and |
but no unsupported feature was encountered, and |
.Fl W Cm error |
.Fl W Cm error |
or |
or a lower |
.Fl W Cm warning |
.Ar level |
was specified. |
was requested. |
.It 4 |
.It 4 |
At least one unsupported feature was encountered, and |
At least one unsupported feature was encountered, and |
.Fl W Cm unsupp , |
.Fl W Cm unsupp |
.Fl W Cm error |
or a lower |
or |
.Ar level |
.Fl W Cm warning |
was requested. |
was specified. |
|
.It 5 |
.It 5 |
Invalid command line arguments were specified. |
Invalid command line arguments were specified. |
No input files have been read. |
No input files have been read. |
Line 639 to exit at once, possibly in the middle of parsing or |
|
Line 637 to exit at once, possibly in the middle of parsing or |
|
Note that selecting |
Note that selecting |
.Fl T Cm lint |
.Fl T Cm lint |
output mode implies |
output mode implies |
.Fl W Cm warning . |
.Fl W Cm style . |
.Sh EXAMPLES |
.Sh EXAMPLES |
To page manuals to the terminal: |
To page manuals to the terminal: |
.Pp |
.Pp |
.Dl $ mandoc \-W all,stop mandoc.1 2\*(Gt&1 | less |
.Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8 |
.Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less |
|
.Pp |
.Pp |
To produce HTML manuals with |
To produce HTML manuals with |
.Pa mandoc.css |
.Pa mandoc.css |
Line 724 rendering can be produced. |
|
Line 721 rendering can be produced. |
|
Documents causing warnings may render poorly when using other |
Documents causing warnings may render poorly when using other |
formatting tools instead of |
formatting tools instead of |
.Nm . |
.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 |
.El |
.Pp |
.Pp |
Messages of the |
Messages of the |
|
.Cm style , |
.Cm warning , |
.Cm warning , |
.Cm error , |
.Cm error , |
and |
and |
Line 737 are hidden unless their level, or a lower level, is re |
|
Line 747 are hidden unless their level, or a lower level, is re |
|
option or |
option or |
.Fl T Cm lint |
.Fl T Cm lint |
output mode. |
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. |
|
.El |
.Ss Warnings related to the document prologue |
.Ss Warnings related to the document prologue |
.Bl -ohang |
.Bl -ohang |
.It Sy "missing manual title, using UNTITLED" |
.It Sy "missing manual title, using UNTITLED" |
|
|
.Ic \&Bl |
.Ic \&Bl |
.Fl offset |
.Fl offset |
or |
or |
.Fl width. |
.Fl width . |
.It Sy "missing display type, using -ragged" |
.It Sy "missing display type, using -ragged" |
.Pq mdoc |
.Pq mdoc |
The |
The |
Line 1684 whatever mode was active before the block. |
|
Line 1746 whatever mode was active before the block. |
|
A |
A |
.Ic \&Bl |
.Ic \&Bl |
macro fails to specify the list type. |
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" |
.It Sy "missing manual name, using \(dq\(dq" |
.Pq mdoc |
.Pq mdoc |
The first call to |
The first call to |