version 1.129, 2014/12/16 23:44:41 |
version 1.133, 2015/01/20 21:16:51 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2012, 2014 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2012, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
Line 85 Override the default operating system |
|
Line 85 Override the default operating system |
|
for the |
for the |
.Xr mdoc 7 |
.Xr mdoc 7 |
.Sq \&Os |
.Sq \&Os |
|
and for the |
|
.Xr man 7 |
|
.Sq \&TH |
macro. |
macro. |
.It Fl h |
.It Fl h |
Display only the SYNOPSIS lines. |
Display only the SYNOPSIS lines. |
|
|
.Cm warning , |
.Cm warning , |
.Cm error , |
.Cm error , |
or |
or |
.Cm fatal . |
.Cm unsupp ; |
The default is |
.Cm all |
.Fl W Ns Cm fatal ; |
|
.Fl W Ns Cm all |
|
is an alias for |
is an alias for |
.Fl W Ns Cm warning . |
.Cm warning . |
|
By default, |
|
.Nm |
|
is silent. |
See |
See |
.Sx EXIT STATUS |
.Sx EXIT STATUS |
and |
and |
Line 529 At least one warning occurred, but no error, and |
|
Line 533 At least one warning occurred, but no error, and |
|
.Fl W Ns Cm warning |
.Fl W Ns Cm warning |
was specified. |
was specified. |
.It 3 |
.It 3 |
At least one parsing error occurred, but no fatal error, and |
At least one parsing error occurred, |
|
but no unsupported feature was encountered, and |
.Fl W Ns Cm error |
.Fl W Ns Cm error |
or |
or |
.Fl W Ns Cm warning |
.Fl W Ns Cm warning |
was specified. |
was specified. |
.It 4 |
.It 4 |
A fatal parsing error occurred. |
At least on unsupported feature was encountered, and |
|
.Fl W Ns Cm unsupp , |
|
.Fl W Ns Cm error |
|
or |
|
.Fl W Ns Cm warning |
|
was specified. |
.It 5 |
.It 5 |
Invalid command line arguments were specified. |
Invalid command line arguments were specified. |
No input files have been read. |
No input files have been read. |
.It 6 |
.It 6 |
An operating system error occurred, for example memory exhaustion or an |
An operating system error occurred, for example exhaustion |
error accessing input files. |
of memory, file descriptors, or process table entries. |
Such errors cause |
Such errors cause |
.Nm |
.Nm |
to exit at once, possibly in the middle of parsing or formatting a file. |
to exit at once, possibly in the middle of parsing or formatting a file. |
|
|
.Pp |
.Pp |
Message levels have the following meanings: |
Message levels have the following meanings: |
.Bl -tag -width "warning" |
.Bl -tag -width "warning" |
.It Cm syserr |
.It Cm unsupp |
Opening or reading an input file failed, so the parser cannot |
An input file uses unsupported low-level |
even be started and no output is produced from that input file. |
.Xr roff 7 |
.It Cm fatal |
features. |
The parser is unable to parse a given input file at all. |
The output may be incomplete and/or misformatted, |
No formatted output is produced from that input file. |
so using GNU troff instead of |
.It Cm error |
|
An input file contains syntax that cannot be safely interpreted, |
|
either because it is invalid or because |
|
.Nm |
.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, |
By discarding part of the input or inserting missing tokens, |
the parser is able to continue, and the error does not prevent |
the parser is able to continue, and the error does not prevent |
generation of formatted output, but typically, preparing that |
generation of formatted output, but typically, preparing that |
output involves information loss, broken document structure |
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 |
|
level. |
|
In that case, the parser cannot even be started and no output |
|
is produced from those input files. |
.It Cm warning |
.It Cm warning |
An input file uses obsolete, discouraged or non-portable syntax. |
An input file uses obsolete, discouraged or non-portable syntax. |
All the same, the meaning of the input is unambiguous and a correct |
All the same, the meaning of the input is unambiguous and a correct |
Line 626 formatting tools instead of |
|
Line 648 formatting tools instead of |
|
.El |
.El |
.Pp |
.Pp |
Messages of the |
Messages of the |
.Cm warning |
.Cm warning , |
|
.Cm error , |
and |
and |
.Cm error |
.Cm unsupp |
levels are hidden unless their level, or a lower level, is requested using a |
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 |
.Fl W |
option or |
option or |
.Fl T Ns Cm lint |
.Fl T Ns Cm lint |
Line 1258 keeps the code more readable. |
|
Line 1282 keeps the code more readable. |
|
.El |
.El |
.Ss "Errors related to tables" |
.Ss "Errors related to tables" |
.Bl -inset -compact |
.Bl -inset -compact |
.It "bad table syntax" |
|
.It "bad table option" |
|
.It "bad table layout" |
|
.It "no table layout cells specified" |
.It "no table layout cells specified" |
.It "no table data cells specified" |
.It "no table data cells specified" |
.It "ignore data in cell" |
.It "ignore data in cell" |
.It "data block still open" |
.It "data block still open" |
.It "ignoring extra data cells" |
.It "ignoring extra data cells" |
.It "ignoring macro in table" |
|
.El |
.El |
.Ss "Errors related to roff, mdoc, and man code" |
.Ss "Errors related to roff, mdoc, and man code" |
.Bl -ohang |
.Bl -ohang |
|
|
macro. |
macro. |
It may be mistyped or unsupported. |
It may be mistyped or unsupported. |
The request or macro is discarded including its arguments. |
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" |
.It Sy "skipping item outside list" |
.Pq mdoc , eqn |
.Pq mdoc , eqn |
An |
An |
|
|
.Ic \&gsize |
.Ic \&gsize |
statement has a non-numeric or negative argument or no argument at all. |
statement has a non-numeric or negative argument or no argument at all. |
The invalid request or statement is ignored. |
The invalid request or statement is ignored. |
|
.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" |
|
.Pq roff |
|
For security reasons, |
|
.Nm |
|
allows |
|
.Ic \&so |
|
file inclusion requests only with relative paths |
|
and only without ascending to any parent directory. |
|
By requesting the inclusion of a sensitive file, a malicious document |
|
might otherwise trick a privileged user into inadvertently displaying |
|
the file on the screen, revealing the file content to bystanders. |
|
.Nm |
|
only shows the path as it appears behind |
|
.Ic \&so . |
|
.It Sy ".so request failed" |
|
.Pq roff |
|
Servicing a |
|
.Ic \&so |
|
request requires reading an external file, but the file could not be |
|
opened. |
|
.Nm |
|
only shows the path as it appears behind |
|
.Ic \&so . |
.It Sy "skipping all arguments" |
.It Sy "skipping all arguments" |
.Pq mdoc , man , eqn , roff |
.Pq mdoc , man , eqn , roff |
An |
An |
Line 1497 macro is invoked with more than one argument, or a req |
|
Line 1545 macro is invoked with more than one argument, or a req |
|
family is invoked with more than two arguments. |
family is invoked with more than two arguments. |
The excess arguments are ignored. |
The excess arguments are ignored. |
.El |
.El |
.Ss FATAL errors |
.Ss Unsupported features |
.Bl -ohang |
.Bl -ohang |
.It Sy "input too large" |
.It Sy "input too large" |
.Pq mdoc , man |
.Pq mdoc , man |
Line 1507 cannot handle input files larger than its arbitrary si |
|
Line 1555 cannot handle input files larger than its arbitrary si |
|
of 2^31 bytes (2 Gigabytes). |
of 2^31 bytes (2 Gigabytes). |
Since useful manuals are always small, this is not a problem in practice. |
Since useful manuals are always small, this is not a problem in practice. |
Parsing is aborted as soon as the condition is detected. |
Parsing is aborted as soon as the condition is detected. |
.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" |
.It Sy "unsupported roff request" |
.Pq roff |
.Pq roff |
For security reasons, |
An input file contains a |
.Nm |
.Xr roff 7 |
allows |
request supported by GNU troff or Heirloom troff but not by |
.Ic \&so |
.Nm , |
file inclusion requests only with relative paths |
and it is likely that this will cause information loss |
and only without ascending to any parent directory. |
or considerable misformatting. |
By requesting the inclusion of a sensitive file, a malicious document |
.It Sy "bad table syntax" |
might otherwise trick a privileged user into inadvertently displaying |
.It Sy "bad table option" |
the file on the screen, revealing the file content to bystanders. |
.It Sy "bad table layout" |
The parser exits immediately. |
.It Sy "ignoring macro in table" |
.It Sy ".so request failed" |
|
.Pq roff |
|
Servicing a |
|
.Ic \&so |
|
request requires reading an external file. |
|
While trying to do so, an |
|
.Xr open 2 , |
|
.Xr stat 2 , |
|
or |
|
.Xr read 2 |
|
system call failed. |
|
The parser exits immediately. |
|
Before showing this message, |
|
.Nm |
|
always shows another message explaining why the system call failed. |
|
.El |
.El |
.Sh COMPATIBILITY |
.Sh COMPATIBILITY |
This section summarises |
This section summarises |