=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.193 retrieving revision 1.202 diff -u -p -r1.193 -r1.202 --- mandoc/mandoc.1 2017/06/03 12:17:25 1.193 +++ mandoc/mandoc.1 2017/06/24 14:38:32 1.202 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.1,v 1.193 2017/06/03 12:17:25 schwarze Exp $ +.\" $Id: mandoc.1,v 1.202 2017/06/24 14:38:32 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" Copyright (c) 2012, 2014-2017 Ingo Schwarze @@ -15,7 +15,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: June 3 2017 $ +.Dd $Mdocdate: June 24 2017 $ .Dt MANDOC 1 .Os .Sh NAME @@ -146,14 +146,33 @@ to be reported on the standard error output and to aff The .Ar level can be +.Cm base , .Cm style , .Cm warning , .Cm error , or -.Cm unsupp ; +.Cm unsupp . +The +.Cm base +level automatically derives the operating system from the contents of the +.Ic \&Os +macro, from the +.Fl Ios +command line option, or from the +.Xr uname 3 +return value. +The levels +.Cm openbsd +and +.Cm netbsd +are variants of +.Cm base +that bypass autodetection and request validation of base system +conventions for a particular operating system. +The level .Cm all is an alias for -.Cm style . +.Cm base . By default, .Nm is silent. @@ -219,7 +238,7 @@ See .It Fl T Cm lint Parse only: produce no output. Implies -.Fl W Cm style . +.Fl W Cm all . .It Fl T Cm locale Encode output using the current locale. This is the default. @@ -296,8 +315,7 @@ Increasing this is not recommended; it may result in d 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 @@ -592,19 +610,23 @@ option: .Pp .Bl -tag -width Ds -compact .It 0 -No style suggestions, warnings or errors occurred, or those that -did were ignored because they were lower than the requested +No base system convention violations, 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 +At least one base system convention violation or style suggestion +occurred, but no warning or error, and +.Fl W Cm base +or .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. +or a lower +.Ar level +was requested. .It 3 At least one parsing error occurred, but no unsupported feature was encountered, and @@ -632,7 +654,7 @@ to exit at once, possibly in the middle of parsing or Note that selecting .Fl T Cm lint output mode implies -.Fl W Cm style . +.Fl W Cm all . .Sh EXAMPLES To page manuals to the terminal: .Pp @@ -665,12 +687,19 @@ parser: Messages displayed by .Nm follow this format: +.Bd -ragged -offset indent +.Nm Ns : +.Ar file : Ns Ar line : Ns Ar column : level : message : macro args +.Pq Ar os +.Ed .Pp -.D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args -.Pp Line and column numbers start at 1. Both are omitted for messages referring to an input file as a whole. Macro names and arguments are omitted where meaningless. +The +.Ar os +operating system specifier is omitted for messages that are relevant +for all operating systems. Fatal messages about invalid command line arguments or operating system errors, for example when memory is exhausted, may also omit the @@ -728,9 +757,15 @@ 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. +.It Cm base +A convertion used in the base system of a specific operating system +is not adhered to. +These are not markup mistakes, and neither the quality of formatting +nor portability are in danger. .El .Pp Messages of the +.Cm base , .Cm style , .Cm warning , .Cm error , @@ -742,8 +777,74 @@ are hidden unless their level, or a lower level, is re option or .Fl T Cm lint output mode. -.Ss Style messages +.Pp +As indicated below, all +.Cm base +and some +.Cm style +checks are only performed if a specific operating system name occurs +in the arguments of the +.Fl W +command line option, 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. +.Ss Conventions for base system manuals .Bl -ohang +.It Sy "Mdocdate found" +.Pq mdoc , Nx +The +.Ic \&Dd +macro uses CVS +.Ic Mdocdate +keyword substitution, which is not supported by the +.Nx +base system. +Consider using the conventional +.Dq "Month dd, yyyy" +format instead. +.It Sy "Mdocdate missing" +.Pq mdoc , Ox +The +.Ic \&Dd +macro does not use CVS +.Ic Mdocdate +keyword substitution, but using it is conventionally expected in the +.Ox +base system. +.It Sy "RCS id missing" +.Pq Ox , Nx +The manual page lacks the comment line with the RCS identifier +generated by CVS +.Ic OpenBSD +or +.Ic NetBSD +keyword substitution as conventionally used in these operating systems. +.El +.Ss Style suggestions +.Bl -ohang +.It Sy "legacy man(7) date format" +.Pq mdoc +The +.Ic \&Dd +macro uses the legacy +.Xr man 7 +date format +.Dq yyyy-dd-mm . +Consider using the conventional +.Xr mdoc 7 +date format +.Dq "Month dd, yyyy" +instead. +.It Sy "duplicate RCS id" +A single manual page contains two copies of the RCS identifier for +the same operating system. +Consider deleting the later instance and moving the first one up +to the top of the page. .It Sy "useless macro" .Pq mdoc A @@ -763,11 +864,41 @@ macro that could be represented using .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 @@ -1369,6 +1500,12 @@ or .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 @@ -1716,6 +1853,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