===================================================================
RCS file: /cvs/mandoc/mandoc.1,v
retrieving revision 1.201
retrieving revision 1.202
diff -u -p -r1.201 -r1.202
--- mandoc/mandoc.1	2017/06/17 23:07:00	1.201
+++ mandoc/mandoc.1	2017/06/24 14:38:32	1.202
@@ -1,4 +1,4 @@
-.\"	$Id: mandoc.1,v 1.201 2017/06/17 23:07:00 schwarze Exp $
+.\"	$Id: mandoc.1,v 1.202 2017/06/24 14:38:32 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: June 17 2017 $
+.Dd $Mdocdate: June 24 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.
@@ -596,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
@@ -636,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
@@ -669,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
@@ -732,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 ,
@@ -746,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
@@ -756,6 +793,7 @@ 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
@@ -778,6 +816,17 @@ macro does not use CVS
 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
@@ -791,14 +840,6 @@ Consider using the conventional
 date format
 .Dq "Month dd, yyyy"
 instead.
-.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.
 .It Sy "duplicate RCS id"
 A single manual page contains two copies of the RCS identifier for
 the same operating system.