===================================================================
RCS file: /cvs/mandoc/mandoc.1,v
retrieving revision 1.184
retrieving revision 1.206
diff -u -p -r1.184 -r1.206
--- mandoc/mandoc.1	2017/03/27 18:51:36	1.184
+++ mandoc/mandoc.1	2017/06/25 11:42:02	1.206
@@ -1,4 +1,4 @@
-.\"	$Id: mandoc.1,v 1.184 2017/03/27 18:51:36 schwarze Exp $
+.\"	$Id: mandoc.1,v 1.206 2017/06/25 11:42:02 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2012, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>
@@ -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: March 27 2017 $
+.Dd $Mdocdate: June 25 2017 $
 .Dt MANDOC 1
 .Os
 .Sh NAME
@@ -146,13 +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 warning .
+.Cm base .
 By default,
 .Nm
 is silent.
@@ -218,7 +238,7 @@ See
 .It Fl T Cm lint
 Parse only: produce no output.
 Implies
-.Fl W Cm warning .
+.Fl W Cm all .
 .It Fl T Cm locale
 Encode output using the current locale.
 This is the default.
@@ -252,9 +272,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
@@ -298,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
@@ -594,27 +610,36 @@ 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 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 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
-was specified.
+or a lower
+.Ar level
+was requested.
 .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.
@@ -629,12 +654,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 all .
 .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
@@ -663,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
@@ -714,9 +745,28 @@ 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.
+.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 ,
 and
@@ -727,6 +777,141 @@ are hidden unless their level, or a lower level, is re
 option or
 .Fl T Cm lint
 output mode.
+.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 "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
+.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.
+.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
 .It Sy "missing manual title, using UNTITLED"
@@ -1093,6 +1278,7 @@ A
 .Ic \&Bl ,
 .Ic \&D1 ,
 .Ic \&Dl ,
+.Ic \&MT ,
 .Ic \&RS ,
 or
 .Ic \&UR
@@ -1105,7 +1291,7 @@ or
 .Ic \&Bl
 .Fl offset
 or
-.Fl width.
+.Fl width .
 .It Sy "missing display type, using -ragged"
 .Pq mdoc
 The
@@ -1228,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.
@@ -1327,6 +1515,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
@@ -1574,7 +1768,7 @@ An
 .Xr mdoc 7
 block closing macro, a
 .Xr man 7
-.Ic \&RE
+.Ic \&ME , \&RE
 or
 .Ic \&UE
 macro, an
@@ -1608,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
@@ -1674,6 +1868,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
@@ -1775,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 ,