===================================================================
RCS file: /cvs/mandoc/mandoc.1,v
retrieving revision 1.180
retrieving revision 1.188
diff -u -p -r1.180 -r1.188
--- mandoc/mandoc.1	2017/03/20 14:32:24	1.180
+++ mandoc/mandoc.1	2017/05/17 23:39:31	1.188
@@ -1,4 +1,4 @@
-.\"	$Id: mandoc.1,v 1.180 2017/03/20 14:32:24 schwarze Exp $
+.\"	$Id: mandoc.1,v 1.188 2017/05/17 23:39:31 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2012, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>
@@ -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: May 17 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
@@ -120,22 +108,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 +130,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 +146,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 +184,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 +194,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
@@ -274,9 +253,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 +592,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.
@@ -655,8 +636,7 @@ output mode implies
 .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 +716,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
@@ -1127,7 +1120,7 @@ or
 .Ic \&Bl
 .Fl offset
 or
-.Fl width.
+.Fl width .
 .It Sy "missing display type, using -ragged"
 .Pq mdoc
 The