summaryrefslogtreecommitdiffstats
path: root/mandoc.1
diff options
context:
space:
mode:
authorIngo Schwarze <schwarze@openbsd.org>2015-01-20 21:16:51 +0000
committerIngo Schwarze <schwarze@openbsd.org>2015-01-20 21:16:51 +0000
commit222b2747ea0806609b71ff5fa9a4c6f21ddc3c46 (patch)
tree056a00f20a99a44fa9017101a00d94f962a4d8fd /mandoc.1
parent7b1d8d6cb19169cc19bdb9708793a3cbedf63b81 (diff)
downloadmandoc-222b2747ea0806609b71ff5fa9a4c6f21ddc3c46.tar.gz
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
Diffstat (limited to 'mandoc.1')
-rw-r--r--mandoc.182
1 files changed, 60 insertions, 22 deletions
diff --git a/mandoc.1 b/mandoc.1
index 064fb62c..7f885706 100644
--- a/mandoc.1
+++ b/mandoc.1
@@ -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