=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.180 retrieving revision 1.195 diff -u -p -r1.180 -r1.195 --- mandoc/mandoc.1 2017/03/20 14:32:24 1.180 +++ mandoc/mandoc.1 2017/06/07 23:29:48 1.195 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.1,v 1.180 2017/03/20 14:32:24 schwarze Exp $ +.\" $Id: mandoc.1,v 1.195 2017/06/07 23:29:48 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" Copyright (c) 2012, 2014-2017 Ingo Schwarze @@ -15,19 +15,19 @@ .\" 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 20 2017 $ +.Dd $Mdocdate: June 7 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 mdoc | man -.Op Fl O Ar option +.Op Fl O Ar options .Op Fl T Ar output .Op Fl W Ar level .Op Ar @@ -65,18 +65,6 @@ to paginate them. 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 @@ -87,6 +75,11 @@ and for the .Xr man 7 .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 @@ -120,22 +113,6 @@ sequence, input is interpreted as 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 mdoc | man With .Fl mdoc , @@ -158,7 +135,7 @@ parser is used. With other arguments, .Fl m is silently ignored. -.It Fl O Ar option +.It Fl O Ar options Comma-separated output options. .It Fl T Ar output Output format. @@ -174,13 +151,14 @@ to be reported on the standard error output and to aff 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. @@ -211,6 +189,9 @@ If multiple files are specified, 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 @@ -218,10 +199,13 @@ and mode, .Nm also supports the options -.Fl CMmOSsw +.Fl CMmOSs described in the .Xr apropos 1 manual. +The options +.Fl fkl +are mutually exclusive and override each other. .Ss Output Formats The .Nm @@ -240,7 +224,7 @@ See .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. @@ -274,9 +258,6 @@ See 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 @@ -616,27 +597,32 @@ option: .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. @@ -651,12 +637,11 @@ to exit at once, possibly in the middle of parsing or 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 @@ -736,9 +721,22 @@ rendering can be produced. 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 @@ -749,6 +747,58 @@ are hidden unless their level, or a lower level, is re 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. +.El .Ss Warnings related to the document prologue .Bl -ohang .It Sy "missing manual title, using UNTITLED" @@ -1127,7 +1177,7 @@ or .Ic \&Bl .Fl offset or -.Fl width. +.Fl width . .It Sy "missing display type, using -ragged" .Pq mdoc The @@ -1696,6 +1746,11 @@ whatever mode was active before the block. 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