diff options
Diffstat (limited to 'mandoc.1')
| -rw-r--r-- | mandoc.1 | 82 |
1 files changed, 60 insertions, 22 deletions
@@ -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 |