version 1.123, 2014/11/25 20:18:15 |
version 1.136, 2015/01/26 00:57:22 |
|
|
.\" $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 |
|
|
text from stdin, implying |
text from stdin, implying |
.Fl m Ns Cm andoc , |
.Fl m Ns Cm andoc , |
and produces |
and produces |
.Fl T Ns Cm ascii |
.Fl T Ns Cm locale |
output. |
output. |
.Pp |
.Pp |
The options are as follows: |
The options are as follows: |
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. |
|
|
.Sx Output Formats |
.Sx Output Formats |
for available formats. |
for available formats. |
Defaults to |
Defaults to |
.Fl T Ns Cm ascii . |
.Fl T Ns Cm locale . |
.It Fl V |
.It Fl V |
Print version and exit. |
Print version and exit. |
.It Fl W Ns Ar level |
.It Fl W Ns Ar level |
|
|
.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 255 arguments, which correspond to output modes: |
|
Line 259 arguments, which correspond to output modes: |
|
.Bl -tag -width "-Tlocale" |
.Bl -tag -width "-Tlocale" |
.It Fl T Ns Cm ascii |
.It Fl T Ns Cm ascii |
Produce 7-bit ASCII output. |
Produce 7-bit ASCII output. |
This is the default. |
|
See |
See |
.Sx ASCII Output . |
.Sx ASCII Output . |
.It Fl T Ns Cm html |
.It Fl T Ns Cm html |
|
|
.Fl W Ns Cm warning . |
.Fl W Ns Cm warning . |
.It Fl T Ns Cm locale |
.It Fl T Ns Cm locale |
Encode output using the current locale. |
Encode output using the current locale. |
|
This is the default. |
See |
See |
.Sx Locale Output . |
.Sx Locale Output . |
.It Fl T Ns Cm man |
.It Fl T Ns Cm man |
Line 299 If multiple input files are specified, these will be p |
|
Line 303 If multiple input files are specified, these will be p |
|
corresponding filter in-order. |
corresponding filter in-order. |
.Ss ASCII Output |
.Ss ASCII Output |
Output produced by |
Output produced by |
.Fl T Ns Cm ascii , |
.Fl T Ns Cm ascii |
which is the default, is rendered in standard 7-bit ASCII documented in |
is rendered in standard 7-bit ASCII documented in |
.Xr ascii 7 . |
.Xr ascii 7 . |
.Pp |
.Pp |
Font styles are applied by using back-spaced encoding such that an |
Font styles are applied by using back-spaced encoding such that an |
|
|
.Ss Locale Output |
.Ss Locale Output |
Locale-depending output encoding is triggered with |
Locale-depending output encoding is triggered with |
.Fl T Ns Cm locale . |
.Fl T Ns Cm locale . |
|
This is the default. |
|
.Pp |
This option is not available on all systems: systems without locale |
This option is not available on all systems: systems without locale |
support, or those whose internal representation is not natively UCS-4, |
support, or those whose internal representation is not natively UCS-4, |
will fall back to |
will fall back to |
Line 527 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 one 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 624 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 665 macro lacks the mandatory section argument. |
|
Line 691 macro lacks the mandatory section argument. |
|
The section number in a |
The section number in a |
.Ic \&Dt |
.Ic \&Dt |
line is invalid, but still used. |
line is invalid, but still used. |
.It Sy "unknown manual volume or arch" |
|
.Pq mdoc |
|
The volume name in a |
|
.Ic \&Dt |
|
line is invalid, but still used. |
|
The manual is assumed to be architecture-independent. |
|
.It Sy "missing date, using today's date" |
.It Sy "missing date, using today's date" |
.Pq mdoc, man |
.Pq mdoc, man |
The document was parsed as |
The document was parsed as |
Line 809 Probably, there are author names lacking markup. |
|
Line 829 Probably, there are author names lacking markup. |
|
See the |
See the |
.Xr mdoc 7 |
.Xr mdoc 7 |
manual for replacements. |
manual for replacements. |
|
.It Sy "macro neither callable nor escaped" |
|
.Pq mdoc |
|
The name of a macro that is not callable appears on a macro line. |
|
It is printed verbatim. |
|
If the intention is to call it, move it to its own line; |
|
otherwise, escape it by prepending |
|
.Sq \e& . |
.It Sy "skipping paragraph macro" |
.It Sy "skipping paragraph macro" |
In |
In |
.Xr mdoc 7 |
.Xr mdoc 7 |
Line 1053 argument is invalid. |
|
Line 1080 argument is invalid. |
|
The default font |
The default font |
.Cm \efR |
.Cm \efR |
is used instead. |
is used instead. |
|
.It Sy "nothing follows prefix" |
|
.Pq mdoc |
|
A |
|
.Ic \&Pf |
|
macro has no argument, or only one argument and no macro follows |
|
on the same input line. |
|
This defeats its purpose; in particular, spacing is not suppressed |
|
before the text or macros following on the next input line. |
.It Sy "missing -std argument, adding it" |
.It Sy "missing -std argument, adding it" |
.Pq mdoc |
.Pq mdoc |
An |
An |
Line 1246 keeps the code more readable. |
|
Line 1281 keeps the code more readable. |
|
.It "unexpected end of equation" |
.It "unexpected end of equation" |
.El |
.El |
.Ss "Errors related to tables" |
.Ss "Errors related to tables" |
|
.Bl -ohang |
|
.It Sy "non-alphabetic character in tbl options" |
|
.Pq tbl |
|
The table options line contains a character other than a letter, |
|
blank, or comma where the beginning of an option name is expected. |
|
The character is ignored. |
|
.It Sy "skipping unknown tbl option" |
|
.Pq tbl |
|
The table options line contains a string of letters that does not |
|
match any known option name. |
|
The word is ignored. |
|
.It Sy "missing tbl option argument" |
|
.Pq tbl |
|
A table option that requires an argument is not followed by an |
|
opening parenthesis, or the opening parenthesis is immediately |
|
followed by a closing parenthesis. |
|
The option is ignored. |
|
.It Sy "wrong tbl option argument size" |
|
.Pq tbl |
|
A table option argument contains an invalid number of characters. |
|
Both the option and the argument are ignored. |
|
.El |
|
.Pp |
.Bl -inset -compact |
.Bl -inset -compact |
.It "bad table syntax" |
.It Sy "no table layout cells specified" |
.It "bad table option" |
.It Sy "no table data cells specified" |
.It "bad table layout" |
.It Sy "ignore data in cell" |
.It "no table layout cells specified" |
.It Sy "data block still open" |
.It "no table data cells specified" |
.It Sy "ignoring extra data cells" |
.It "ignore data in cell" |
|
.It "data block still open" |
|
.It "ignoring extra data cells" |
|
.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 |
Line 1332 right delimiter or closing brace, or the end of an equ |
|
Line 1392 right delimiter or closing brace, or the end of an equ |
|
.Xr roff 7 |
.Xr roff 7 |
conditional request is encountered but no matching block is open. |
conditional request is encountered but no matching block is open. |
The offending request or macro is discarded. |
The offending request or macro is discarded. |
|
.It Sy "fewer RS blocks open, skipping" |
|
.Pq man |
|
The |
|
.Ic \&RE |
|
macro is invoked with an argument, but less than the specified number of |
|
.Ic \&RS |
|
blocks is open. |
|
The |
|
.Ic \&RE |
|
macro is discarded. |
.It Sy "inserting missing end of block" |
.It Sy "inserting missing end of block" |
.Pq mdoc , tbl |
.Pq mdoc , tbl |
Various |
Various |
Line 1396 The indicated request or macro has too few or too many |
|
Line 1466 The indicated request or macro has too few or too many |
|
The syntax tree will contain the wrong number of arguments as given. |
The syntax tree will contain the wrong number of arguments as given. |
Formatting behaviour depends on the specific request or macro in question. |
Formatting behaviour depends on the specific request or macro in question. |
Note that the same message may also occur as a WARNING, see above. |
Note that the same message may also occur as a WARNING, see above. |
|
.It Sy "NOT IMPLEMENTED: Bd -file" |
|
.Pq mdoc |
|
For security reasons, the |
|
.Ic \&Bd |
|
macro does not support the |
|
.Fl file |
|
argument. |
|
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. |
|
The argument is ignored including the file name following it. |
.It Sy "missing list type, using -item" |
.It Sy "missing list type, using -item" |
.Pq mdoc |
.Pq mdoc |
A |
A |
|
|
.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 |
|
|
block closing request is invoked with at least one argument. |
block closing request is invoked with at least one argument. |
All arguments are ignored. |
All arguments are ignored. |
.It Sy "skipping excess arguments" |
.It Sy "skipping excess arguments" |
.Pq mdoc , roff |
.Pq mdoc , man , roff |
The |
The |
.Ic \&Bf |
.Ic \&Bf |
macro is invoked with more than one argument, or a request of the |
macro is invoked with more than one argument, the |
|
.Ic \&RE |
|
macro is invoked with more than one argument |
|
or with a non-integer argument, or a request of the |
.Ic \&de |
.Ic \&de |
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 1484 cannot handle input files larger than its arbitrary si |
|
Line 1591 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: Bd -file" |
.It Sy "unsupported control character" |
.Pq mdoc |
|
For security reasons, the |
|
.Ic \&Bd |
|
macro does not support the |
|
.Fl file |
|
argument. |
|
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. |
|
The parser exits immediately. |
|
.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" |
|
.Pq roff |
.Pq roff |
For security reasons, |
An ASCII control character supported by other |
|
.Xr roff 7 |
|
implementations but not by |
.Nm |
.Nm |
allows |
was found in an input file. |
.Ic \&so |
It is replaced by a question mark. |
file inclusion requests only with relative paths |
.It Sy "unsupported roff request" |
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. |
|
The parser exits immediately. |
|
.It Sy ".so request failed" |
|
.Pq roff |
.Pq roff |
Servicing a |
An input file contains a |
.Ic \&so |
.Xr roff 7 |
request requires reading an external file. |
request supported by GNU troff or Heirloom troff but not by |
While trying to do so, an |
.Nm , |
.Xr open 2 , |
and it is likely that this will cause information loss |
.Xr stat 2 , |
or considerable misformatting. |
or |
.It Sy "unsupported table layout" |
.Xr read 2 |
.It Sy "ignoring macro in table" |
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 |