Split the -Werror message level into -Werror (broken manual, probably

using mandoc is better than using groff) and -Wunsupp (manual using
unsupported low-level roff(7) feature, probably using groff is better
than using mandoc).  Once this feature is complete, it is intended
to help porting, making the decision whether to USE_GROFF easier.

As a first step, distinguish four classes of roff(7) requests:
1. Supported (currently 24 requests)
2. Currently ignored because unimportant (120)  ->  no message
3. Ignored for good because insecure (14)  ->  -Werror
4. Currently unsupported (68)  ->  these trigger the new -Wunsupp messages

1 files changed, 62 insertions, 24 deletions

diff --git a/mandoc.1 b/mandoc.1
index 0489f0a3..817ef569 100644
--- a/mandoc.1
+++ b/mandoc.1
@@ -1,4 +1,4 @@
-.\"	$Id: mandoc.1,v 1.132 2015/01/15 04:26:40 schwarze Exp $
+.\"	$Id: mandoc.1,v 1.133 2015/01/20 21:16:51 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2012, 2014, 2015 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: January 15 2015 $
+.Dd $Mdocdate: January 20 2015 $
 .Dt MANDOC 1
 .Os
 .Sh NAME
@@ -159,9 +159,10 @@ to be reported on the standard error output and to affect the exit status.
 The
 .Ar level
 can be
-.Cm warning
+.Cm warning ,
+.Cm error ,
 or
-.Cm error ;
+.Cm unsupp ;
 .Cm all
 is an alias for
 .Cm warning .
@@ -532,7 +533,15 @@ At least one warning occurred, but no error, and
 .Fl W Ns Cm warning
 was specified.
 .It 3
-At least one parsing error occurred, and
+At least one parsing error occurred,
+but no unsupported feature was encountered, and
+.Fl W Ns Cm error
+or
+.Fl W Ns Cm warning
+was specified.
+.It 4
+At least on unsupported feature was encountered, and
+.Fl W Ns Cm unsupp ,
 .Fl W Ns Cm error
 or
 .Fl W Ns Cm warning
@@ -601,16 +610,28 @@ fields.
 .Pp
 Message levels have the following meanings:
 .Bl -tag -width "warning"
-.It Cm error
-An input file contains syntax that cannot be safely interpreted,
-either because it is invalid or because
+.It Cm unsupp
+An input file uses unsupported low-level
+.Xr roff 7
+features.
+The output may be incomplete and/or misformatted,
+so using GNU troff instead of
 .Nm
-does not implement it yet.
+to process the file may be preferable.
+.It Cm error
+An input file contains invalid syntax that cannot be safely interpreted.
 By discarding part of the input or inserting missing tokens,
 the parser is able to continue, and the error does not prevent
 generation of formatted output, but typically, preparing that
 output involves information loss, broken document structure
-or unintended formatting.
+or unintended formatting, no matter whether
+.Nm
+or GNU troff is used.
+In many cases, the output of
+.Nm
+and GNU troff is identical, but in some,
+.Nm
+is more resilient than GNU troff with respect to malformed input.
 .Pp
 Non-existent or unreadable input files are also reported on the
 .Cm error
@@ -627,9 +648,10 @@ formatting tools instead of
 .El
 .Pp
 Messages of the
-.Cm warning
+.Cm warning ,
+.Cm error ,
 and
-.Cm error
+.Cm unsupp
 levels except those about non-existent or unreadable input files
 are hidden unless their level, or a lower level, is requested using a
 .Fl W
@@ -1260,26 +1282,14 @@ keeps the code more readable.
 .El
 .Ss "Errors related to tables"
 .Bl -inset -compact
-.It "bad table syntax"
-.It "bad table option"
-.It "bad table layout"
 .It "no table layout cells specified"
 .It "no table data cells specified"
 .It "ignore data in cell"
 .It "data block still open"
 .It "ignoring extra data cells"
-.It "ignoring macro in table"
 .El
 .Ss "Errors related to roff, mdoc, and man code"
 .Bl -ohang
-.It Sy "input too large"
-.Pq mdoc , man
-Currently,
-.Nm
-cannot handle input files larger than its arbitrary size limit
-of 2^31 bytes (2 Gigabytes).
-Since useful manuals are always small, this is not a problem in practice.
-Parsing is aborted as soon as the condition is detected.
 .It Sy "input stack limit exceeded, infinite loop?"
 .Pq roff
 Explicit recursion limits are implemented for the following features,
@@ -1318,6 +1328,11 @@ or
 macro.
 It may be mistyped or unsupported.
 The request or macro is discarded including its arguments.
+.It Sy "skipping insecure request"
+.Pq roff
+An input file attempted to run a shell command
+or to read or write an external file.
+Such attempts are denied for security reasons.
 .It Sy "skipping item outside list"
 .Pq mdoc , eqn
 An
@@ -1530,6 +1545,29 @@ macro is invoked with more than one argument, or a request of the
 family is invoked with more than two arguments.
 The excess arguments are ignored.
 .El
+.Ss Unsupported features
+.Bl -ohang
+.It Sy "input too large"
+.Pq mdoc , man
+Currently,
+.Nm
+cannot handle input files larger than its arbitrary size limit
+of 2^31 bytes (2 Gigabytes).
+Since useful manuals are always small, this is not a problem in practice.
+Parsing is aborted as soon as the condition is detected.
+.It Sy "unsupported roff request"
+.Pq roff
+An input file contains a
+.Xr roff 7
+request supported by GNU troff or Heirloom troff but not by
+.Nm ,
+and it is likely that this will cause information loss
+or considerable misformatting.
+.It Sy "bad table syntax"
+.It Sy "bad table option"
+.It Sy "bad table layout"
+.It Sy "ignoring macro in table"
+.El
 .Sh COMPATIBILITY
 This section summarises
 .Nm