=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.198 retrieving revision 1.206 diff -u -p -r1.198 -r1.206 --- mandoc/mandoc.1 2017/06/11 17:16:51 1.198 +++ mandoc/mandoc.1 2017/06/25 11:42:02 1.206 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.1,v 1.198 2017/06/11 17:16:51 schwarze Exp $ +.\" $Id: mandoc.1,v 1.206 2017/06/25 11:42:02 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 11 2017 $ +.Dd $Mdocdate: June 25 2017 $ .Dt MANDOC 1 .Os .Sh NAME @@ -75,11 +75,6 @@ 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 @@ -151,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. @@ -224,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. @@ -301,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 @@ -597,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 @@ -637,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 @@ -670,12 +687,19 @@ parser: Messages displayed by .Nm follow this format: +.Bd -ragged -offset indent +.Nm : +.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 @@ -733,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 , @@ -747,9 +777,15 @@ 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 +.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 @@ -757,7 +793,70 @@ command line option, or, if neither are present, in th 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 "unknown architecture" +.Pq mdoc , Ox , Nx +The third argument of the +.Ic \&Dt +macro does not match any of the architectures this operating system +is running on. +.It Sy "operating system explicitly specified" +.Pq mdoc , Ox , Nx +The +.Ic \&Os +macro has an argument. +In the base system, it is conventionally left blank. +.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 @@ -1179,6 +1278,7 @@ A .Ic \&Bl , .Ic \&D1 , .Ic \&Dl , +.Ic \&MT , .Ic \&RS , or .Ic \&UR @@ -1314,6 +1414,8 @@ An empty pair of square brackets is shown. .It Sy "missing resource identifier, using \(dq\(dq" .Pq man The +.Ic \&MT +or .Ic \&UR macro is invoked without any argument. An empty pair of angle brackets is shown. @@ -1666,7 +1768,7 @@ An .Xr mdoc 7 block closing macro, a .Xr man 7 -.Ic \&RE +.Ic \&ME , \&RE or .Ic \&UE macro, an @@ -1700,7 +1802,7 @@ At the end of the document, an explicit block, a .Xr man 7 next-line scope or -.Ic \&RS +.Ic \&MT , \&RS or .Ic \&UR block, an equation, table, or @@ -1872,6 +1974,7 @@ A macro or request is invoked with too many arguments: .Bl -dash -offset 2n -width 2n -compact .It .Ic \&Fo , +.Ic \&MT , .Ic \&PD , .Ic \&RS , .Ic \&UR ,