version 1.111, 2014/09/07 23:25:01 |
version 1.132, 2015/01/15 04:26:40 |
|
|
.\" $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 |
|
|
.Sm off |
.Sm off |
.Op Fl I Cm os Li = Ar name |
.Op Fl I Cm os Li = Ar name |
.Sm on |
.Sm on |
|
.Op Fl K Ns Ar encoding |
.Op Fl m Ns Ar format |
.Op Fl m Ns Ar format |
.Op Fl O Ns Ar option |
.Op Fl O Ns Ar option |
.Op Fl T Ns Ar output |
.Op Fl T Ns Ar output |
|
|
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 84 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. |
Implies |
Implies |
.Fl a . |
.Fl c . |
|
.It Fl K Ns Ar encoding |
|
Specify the input encoding. |
|
The supported |
|
.Ar encoding |
|
arguments are |
|
.Cm us-ascii , |
|
.Cm iso-8859-1 , |
|
and |
|
.Cm utf-8 . |
|
If not specified, autodetection uses the first match: |
|
.Bl -tag -width iso-8859-1 |
|
.It Cm utf-8 |
|
if the first three bytes of the input file |
|
are the UTF-8 byte order mark (BOM, 0xefbbbf) |
|
.It Ar encoding |
|
if the first or second line of the input file matches the |
|
.Sy emacs |
|
mode line format |
|
.Pp |
|
.D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*- |
|
.It Cm utf-8 |
|
if the first non-ASCII byte in the file introduces a valid UTF-8 sequence |
|
.It Cm iso-8859-1 |
|
otherwise |
|
.El |
.It Fl k |
.It Fl k |
A synonym for |
A synonym for |
.Xr apropos 1 . |
.Xr apropos 1 . |
|
|
.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 |
Line 130 to be reported on the standard error output and to aff |
|
Line 159 to be reported on the standard error output and to aff |
|
The |
The |
.Ar level |
.Ar level |
can be |
can be |
.Cm warning , |
.Cm warning |
.Cm error , |
|
or |
or |
.Cm fatal . |
.Cm error ; |
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 229 arguments, which correspond to output modes: |
|
Line 258 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 |
Produce strict CSS1/HTML-4.01 output. |
Produce HTML5, CSS1, and MathML output. |
See |
See |
.Sx HTML Output . |
.Sx HTML Output . |
.It Fl T Ns Cm lint |
.It Fl T Ns Cm lint |
|
|
.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 265 Encode output in the UTF\-8 multi-byte format. |
|
Line 294 Encode output in the UTF\-8 multi-byte format. |
|
See |
See |
.Sx UTF\-8 Output . |
.Sx UTF\-8 Output . |
.It Fl T Ns Cm xhtml |
.It Fl T Ns Cm xhtml |
Produce strict CSS1/XHTML-1.0 output. |
This is a synonym for |
See |
.Fl T Ns Cm html . |
.Sx XHTML Output . |
|
.El |
.El |
.Pp |
.Pp |
If multiple input files are specified, these will be processed by the |
If multiple input files are specified, these will be processed by the |
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 |
Line 320 which will normalise to \(>=60. |
|
Line 348 which will normalise to \(>=60. |
|
.Ss HTML Output |
.Ss HTML Output |
Output produced by |
Output produced by |
.Fl T Ns Cm html |
.Fl T Ns Cm html |
conforms to HTML-4.01 strict. |
conforms to HTML5 using optional self-closing tags. |
|
Default styles use only CSS1. |
|
Equations rendered from |
|
.Xr eqn 7 |
|
blocks use MathML. |
.Pp |
.Pp |
The |
The |
.Pa example.style.css |
.Pa example.style.css |
Line 328 file documents style-sheet classes available for custo |
|
Line 360 file documents style-sheet classes available for custo |
|
If a style-sheet is not specified with |
If a style-sheet is not specified with |
.Fl O Ns Ar style , |
.Fl O Ns Ar style , |
.Fl T Ns Cm html |
.Fl T Ns Cm html |
defaults to simple output readable in any graphical or text-based web |
defaults to simple output (via an embedded style-sheet) |
|
readable in any graphical or text-based web |
browser. |
browser. |
.Pp |
.Pp |
Special characters are rendered in decimal-encoded UTF\-8. |
Special characters are rendered in decimal-encoded UTF\-8. |
|
|
arguments are accepted: |
arguments are accepted: |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
.It Cm fragment |
.It Cm fragment |
Omit the |
Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body> |
.Aq !DOCTYPE |
elements and only emit the subtree below the <body> element. |
declaration and the |
|
.Aq html , |
|
.Aq head , |
|
and |
|
.Aq body |
|
elements and only emit the subtree below the |
|
.Aq body |
|
element. |
|
The |
The |
.Cm style |
.Cm style |
argument will be ignored. |
argument will be ignored. |
|
|
.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 471 to force a UTF\-8 locale. |
|
Line 498 to force a UTF\-8 locale. |
|
See |
See |
.Sx Locale Output |
.Sx Locale Output |
for details and options. |
for details and options. |
.Ss XHTML Output |
|
Output produced by |
|
.Fl T Ns Cm xhtml |
|
conforms to XHTML-1.0 strict. |
|
.Pp |
|
See |
|
.Sx HTML Output |
|
for details; beyond generating XHTML tags instead of HTML tags, these |
|
output modes are identical. |
|
.Sh ENVIRONMENT |
.Sh ENVIRONMENT |
.Bl -tag -width MANPAGER |
.Bl -tag -width MANPAGER |
.It Ev MANPAGER |
.It Ev MANPAGER |
Line 514 At least one warning occurred, but no error, and |
|
Line 532 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, 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 |
|
A fatal parsing error occurred. |
|
.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 |
|
Opening or reading an input file failed, so the parser cannot |
|
even be started and no output is produced from that input file. |
|
.It Cm fatal |
|
The parser is unable to parse a given input file at all. |
|
No formatted output is produced from that input file. |
|
.It Cm error |
.It Cm error |
An input file contains syntax that cannot be safely interpreted, |
An input file contains syntax that cannot be safely interpreted, |
either because it is invalid or because |
either because it is invalid or because |
Line 601 the parser is able to continue, and the error does not |
|
Line 611 the parser is able to continue, and the error does not |
|
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. |
|
.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 |
|
|
.Cm warning |
.Cm warning |
and |
and |
.Cm error |
.Cm error |
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 652 macro lacks the mandatory section argument. |
|
Line 669 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 766 The same standard section title occurs more than once. |
|
Line 777 The same standard section title occurs more than once. |
|
.Pq mdoc |
.Pq mdoc |
A standard section header occurs in a section of the manual |
A standard section header occurs in a section of the manual |
where it normally isn't useful. |
where it normally isn't useful. |
|
.It Sy "unusual Xr order" |
|
.Pq mdoc |
|
In the SEE ALSO section, an |
|
.Ic \&Xr |
|
macro with a lower section number follows one with a higher number, |
|
or two |
|
.Ic \&Xr |
|
macros refering to the same section are out of alphabetical order. |
|
.It Sy "unusual Xr punctuation" |
|
.Pq mdoc |
|
In the SEE ALSO section, punctuation between two |
|
.Ic \&Xr |
|
macros differs from a single comma, or there is trailing punctuation |
|
after the last |
|
.Ic \&Xr |
|
macro. |
.It Sy "AUTHORS section without An macro" |
.It Sy "AUTHORS section without An macro" |
.Pq mdoc |
.Pq mdoc |
An AUTHORS sections contains no |
An AUTHORS sections contains no |
Line 780 Probably, there are author names lacking markup. |
|
Line 807 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 900 The previous, interrupted macro is deleted from the pa |
|
Line 934 The previous, interrupted macro is deleted from the pa |
|
.Ss "Warnings related to missing arguments" |
.Ss "Warnings related to missing arguments" |
.Bl -ohang |
.Bl -ohang |
.It Sy "skipping empty request" |
.It Sy "skipping empty request" |
.Pq roff |
.Pq roff , eqn |
The macro name is missing from a macro definition request. |
The macro name is missing from a macro definition request, |
|
or an |
|
.Xr eqn 7 |
|
control statement or operation keyword lacks its required argument. |
.It Sy "conditional request controls empty scope" |
.It Sy "conditional request controls empty scope" |
.Pq roff |
.Pq roff |
A conditional request is only useful if any of the following |
A conditional request is only useful if any of the following |
Line 1021 argument is invalid. |
|
Line 1058 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 |
|
|
utility assumes |
utility assumes |
.Fl std |
.Fl std |
even when it is not specified, but other implementations may not. |
even when it is not specified, but other implementations may not. |
|
.It Sy "missing eqn box, using \(dq\(dq" |
|
.Pq eqn |
|
A diacritic mark or a binary operator is found, |
|
but there is nothing to the left of it. |
|
An empty box is inserted. |
.El |
.El |
.Ss "Warnings related to bad macro arguments" |
.Ss "Warnings related to bad macro arguments" |
.Bl -ohang |
.Bl -ohang |
Line 1102 macro has an invalid argument. |
|
Line 1152 macro has an invalid argument. |
|
It is used verbatim, with |
It is used verbatim, with |
.Qq "AT&T UNIX " |
.Qq "AT&T UNIX " |
prefixed to it. |
prefixed to it. |
|
.It Sy "comma in function argument" |
|
.Pq mdoc |
|
An argument of an |
|
.Ic \&Fa |
|
or |
|
.Ic \&Fn |
|
macro contains a comma; it should probably be split into two arguments. |
|
.It Sy "parenthesis in function name" |
|
.Pq mdoc |
|
The first argument of an |
|
.Ic \&Fc |
|
or |
|
.Ic \&Fn |
|
macro contains an opening or closing parenthesis; that's probably wrong, |
|
parentheses are added automatically. |
.It Sy "invalid content in Rs block" |
.It Sy "invalid content in Rs block" |
.Pq mdoc |
.Pq mdoc |
An |
An |
|
|
The invalid argument is moved out of the macro, which leaves the macro |
The invalid argument is moved out of the macro, which leaves the macro |
empty, causing it to toggle the spacing mode. |
empty, causing it to toggle the spacing mode. |
.It Sy "unknown font, skipping request" |
.It Sy "unknown font, skipping request" |
.Pq man |
.Pq man , tbl |
A |
A |
.Xr roff 7 |
.Xr roff 7 |
.Ic \&ft |
.Ic \&ft |
request has an invalid argument. |
request or a |
|
.Xr tbl 7 |
|
.Ic \&f |
|
layout modifier has an unknown |
|
.Ar font |
|
argument. |
.El |
.El |
.Ss "Warnings related to plain text" |
.Ss "Warnings related to plain text" |
.Bl -ohang |
.Bl -ohang |
Line 1187 keeps the code more readable. |
|
Line 1257 keeps the code more readable. |
|
.It "equation scope open on exit" |
.It "equation scope open on exit" |
.It "overlapping equation scopes" |
.It "overlapping equation scopes" |
.It "unexpected end of equation" |
.It "unexpected end of equation" |
.It "equation syntax error" |
|
.El |
.El |
.Ss "Errors related to tables" |
.Ss "Errors related to tables" |
.Bl -inset -compact |
.Bl -inset -compact |
Line 1199 keeps the code more readable. |
|
Line 1268 keeps the code more readable. |
|
.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 |
|
.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?" |
.It Sy "input stack limit exceeded, infinite loop?" |
.Pq roff |
.Pq roff |
Explicit recursion limits are implemented for the following features, |
Explicit recursion limits are implemented for the following features, |
|
|
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 item outside list" |
.It Sy "skipping item outside list" |
.Pq mdoc |
.Pq mdoc , eqn |
An |
An |
.Ic \&It |
.Ic \&It |
macro occurs outside any |
macro occurs outside any |
.Ic \&Bl |
.Ic \&Bl |
list. |
list, or an |
|
.Xr eqn 7 |
|
.Ic above |
|
delimiter occurs outside any pile. |
It is discarded including its arguments. |
It is discarded including its arguments. |
.It Sy "skipping column outside column list" |
.It Sy "skipping column outside column list" |
.Pq mdoc |
.Pq mdoc |
Line 1267 block closing macro, a |
|
Line 1348 block closing macro, a |
|
.Ic \&RE |
.Ic \&RE |
or |
or |
.Ic \&UE |
.Ic \&UE |
macro, or the end of an equation, table, or |
macro, an |
|
.Xr eqn 7 |
|
right delimiter or closing brace, or the end of an equation, table, or |
.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. |
Line 1335 The indicated request or macro has too few or too many |
|
Line 1418 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 \&St |
.Ic \&St |
macro has an unknown argument and is discarded. |
macro has an unknown argument and is discarded. |
.It Sy "skipping request without numeric argument" |
.It Sy "skipping request without numeric argument" |
.Pq roff |
.Pq roff , eqn |
An |
An |
.Ic \&it |
.Ic \&it |
request has a non-numeric or negative argument or no argument at all. |
request or an |
The invalid request is ignored. |
.Xr eqn 7 |
|
.Ic \&size |
|
or |
|
.Ic \&gsize |
|
statement has a non-numeric or negative argument or no argument at all. |
|
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 |
|
|
.Ic \&PP |
.Ic \&PP |
macro, an |
macro, an |
.Xr eqn 7 |
.Xr eqn 7 |
|
.Ic \&EQ |
|
or |
.Ic \&EN |
.Ic \&EN |
macro, or a |
macro, or a |
.Xr roff 7 |
.Xr roff 7 |
Line 1406 macro is invoked with more than one argument, or a req |
|
Line 1530 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 |
|
.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 "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 parser exits immediately. |
|
.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. |
|
The parser exits immediately. |
|
.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 |
|
.Sh COMPATIBILITY |
.Sh COMPATIBILITY |
This section summarises |
This section summarises |
.Nm |
.Nm |
|
|
.It |
.It |
Words aren't hyphenated. |
Words aren't hyphenated. |
.El |
.El |
.Ss HTML/XHTML Compatibility |
.Ss HTML Compatibility |
.Bl -bullet -compact |
.Bl -bullet -compact |
.It |
.It |
The |
The |