version 1.132, 2015/01/15 04:26:40 |
version 1.141, 2015/01/29 00:33:57 |
Line 159 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 error ; |
.Cm unsupp ; |
.Cm all |
.Cm all |
is an alias for |
is an alias for |
.Cm warning . |
.Cm warning . |
Line 320 Emboldened characters are rendered as |
|
Line 321 Emboldened characters are rendered as |
|
The special characters documented in |
The special characters documented in |
.Xr mandoc_char 7 |
.Xr mandoc_char 7 |
are rendered best-effort in an ASCII equivalent. |
are rendered best-effort in an ASCII equivalent. |
If no equivalent is found, |
|
.Sq \&? |
|
is used instead. |
|
.Pp |
.Pp |
Output width is limited to 78 visible columns unless literal input lines |
Output width is limited to 78 visible columns unless literal input lines |
exceed this limit. |
exceed this limit. |
Line 343 for example overfull lines or ugly line breaks. |
|
Line 341 for example overfull lines or ugly line breaks. |
|
.It Cm width Ns = Ns Ar width |
.It Cm width Ns = Ns Ar width |
The output width is set to |
The output width is set to |
.Ar width , |
.Ar width , |
which will normalise to \(>=60. |
which will normalise to \(>=58. |
.El |
.El |
.Ss HTML Output |
.Ss HTML Output |
Output produced by |
Output produced by |
Line 532 At least one warning occurred, but no error, and |
|
Line 530 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, 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 |
|
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. |
|
|
.Pp |
.Pp |
Message levels have the following meanings: |
Message levels have the following meanings: |
.Bl -tag -width "warning" |
.Bl -tag -width "warning" |
.It Cm error |
.It Cm unsupp |
An input file contains syntax that cannot be safely interpreted, |
An input file uses unsupported low-level |
either because it is invalid or because |
.Xr roff 7 |
|
features. |
|
The output may be incomplete and/or misformatted, |
|
so using GNU troff instead of |
.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 |
.Pp |
Non-existent or unreadable input files are also reported on the |
Non-existent or unreadable input files are also reported on the |
.Cm error |
.Cm error |
Line 627 formatting tools instead of |
|
Line 645 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 except those about non-existent or unreadable input files |
levels except those about non-existent or unreadable input files |
are hidden unless their level, or a lower level, is requested using a |
are hidden unless their level, or a lower level, is requested using a |
.Fl W |
.Fl W |
Line 1251 its value is implicitly set to the empty string. |
|
Line 1270 its value is implicitly set to the empty string. |
|
However, defining strings explicitly before use |
However, defining strings explicitly before use |
keeps the code more readable. |
keeps the code more readable. |
.El |
.El |
.Ss "Errors related to equations" |
.Ss "Warnings related to tables" |
.Bl -inset -compact |
.Bl -ohang |
.It "unexpected equation scope closure" |
.It Sy "tbl line starts with span" |
.It "equation scope open on exit" |
.Pq tbl |
.It "overlapping equation scopes" |
The first cell in a table layout line is a horizontal span |
.It "unexpected end of equation" |
.Pq Sq Cm s . |
|
Data provided for this cell is ignored, and nothing is printed in the cell. |
|
.It Sy "tbl column starts with span" |
|
.Pq tbl |
|
The first line of a table layout specification |
|
requests a vertical span |
|
.Pq Sq Cm ^ . |
|
Data provided for this cell is ignored, and nothing is printed in the cell. |
|
.It Sy "skipping vertical bar in tbl layout" |
|
.Pq tbl |
|
A table layout specification contains more than two consecutive vertical bars. |
|
A double bar is printed, all additional bars are discarded. |
.El |
.El |
.Ss "Errors related to tables" |
.Ss "Errors related to tables" |
.Bl -inset -compact |
.Bl -ohang |
.It "bad table syntax" |
.It Sy "non-alphabetic character in tbl options" |
.It "bad table option" |
.Pq tbl |
.It "bad table layout" |
The table options line contains a character other than a letter, |
.It "no table layout cells specified" |
blank, or comma where the beginning of an option name is expected. |
.It "no table data cells specified" |
The character is ignored. |
.It "ignore data in cell" |
.It Sy "skipping unknown tbl option" |
.It "data block still open" |
.Pq tbl |
.It "ignoring extra data cells" |
The table options line contains a string of letters that does not |
.It "ignoring macro in table" |
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. |
|
.It Sy "empty tbl layout" |
|
.Pq tbl |
|
A table layout specification is completely empty, |
|
specifying zero lines and zero columns. |
|
As a fallback, a single left-justified column is used. |
|
.It Sy "invalid character in tbl layout" |
|
.Pq tbl |
|
A table layout specification contains a character that can neither |
|
be interpreted as a layout key character nor as a layout modifier, |
|
or a modifier precedes the first key. |
|
The invalid character is discarded. |
|
.It Sy "unmatched parenthesis in tbl layout" |
|
.Pq tbl |
|
A table layout specification contains an opening parenthesis, |
|
but no matching closing parenthesis. |
|
The rest of the input line, starting from the parenthesis, has no effect. |
|
.It Sy "tbl without any data cells" |
|
.Pq tbl |
|
A table does not contain any data cells. |
|
It will probably produce no output. |
|
.It Sy "ignoring data in spanned tbl cell" |
|
.Pq tbl |
|
A table cell is marked as a horizontal span |
|
.Pq Sq Cm s |
|
or vertical span |
|
.Pq Sq Cm ^ |
|
in the table layout, but it contains data. |
|
The data is ignored. |
|
.It Sy "ignoring extra tbl data cells" |
|
.Pq tbl |
|
A data line contains more cells than the corresponding layout line. |
|
The data in the extra cells is ignored. |
|
.It Sy "data block open at end of tbl" |
|
.Pq tbl |
|
A data block is opened with |
|
.Cm T{ , |
|
but never closed with a matching |
|
.Cm T} . |
|
The remaining data lines of the table are all put into one cell, |
|
and any remaining cells stay empty. |
.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, |
|
|
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 1354 right delimiter or closing brace, or the end of an equ |
|
Line 1432 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 |
|
|
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 |
.Sh COMPATIBILITY |
.Ss Unsupported features |
This section summarises |
.Bl -ohang |
|
.It Sy "input too large" |
|
.Pq mdoc , man |
|
Currently, |
.Nm |
.Nm |
compatibility with GNU troff. |
cannot handle input files larger than its arbitrary size limit |
Each input and output format is separately noted. |
of 2^31 bytes (2 Gigabytes). |
.Ss ASCII Compatibility |
Since useful manuals are always small, this is not a problem in practice. |
.Bl -bullet -compact |
Parsing is aborted as soon as the condition is detected. |
.It |
.It Sy "unsupported control character" |
Unrenderable unicode codepoints specified with |
.Pq roff |
.Sq \e[uNNNN] |
An ASCII control character supported by other |
escapes are printed as |
.Xr roff 7 |
.Sq \&? |
implementations but not by |
in mandoc. |
.Nm |
In GNU troff, these raise an error. |
was found in an input file. |
.It |
It is replaced by a question mark. |
The |
.It Sy "unsupported roff request" |
.Sq \&Bd \-literal |
.Pq roff |
and |
An input file contains a |
.Sq \&Bd \-unfilled |
.Xr roff 7 |
macros of |
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 "eqn delim option in tbl" |
|
.Pq eqn , tbl |
|
The options line of a table defines equation delimiters. |
|
Any equation source code contained in the table will be printed unformatted. |
|
.It Sy "unsupported table layout modifier" |
|
.Pq tbl |
|
A table layout specification contains an |
|
.Sq Cm m |
|
modifier. |
|
The modifier is discarded. |
|
.It Sy "ignoring macro in table" |
|
.Pq tbl , mdoc , man |
|
A table contains an invocation of an |
.Xr mdoc 7 |
.Xr mdoc 7 |
in |
or |
.Fl T Ns Cm ascii |
|
are synonyms, as are \-filled and \-ragged. |
|
.It |
|
In historic GNU troff, the |
|
.Sq \&Pa |
|
.Xr mdoc 7 |
|
macro does not underline when scoped under an |
|
.Sq \&It |
|
in the FILES section. |
|
This behaves correctly in |
|
.Nm . |
|
.It |
|
A list or display following the |
|
.Sq \&Ss |
|
.Xr mdoc 7 |
|
macro in |
|
.Fl T Ns Cm ascii |
|
does not assert a prior vertical break, just as it doesn't with |
|
.Sq \&Sh . |
|
.It |
|
The |
|
.Sq \&na |
|
.Xr man 7 |
.Xr man 7 |
macro in |
macro or of an undefined macro. |
.Fl T Ns Cm ascii |
The macro is ignored, and its arguments are handled |
has no effect. |
as if they were a text line. |
.It |
|
Words aren't hyphenated. |
|
.El |
.El |
.Ss HTML Compatibility |
|
.Bl -bullet -compact |
|
.It |
|
The |
|
.Sq \efP |
|
escape will revert the font to the previous |
|
.Sq \ef |
|
escape, not to the last rendered decoration, which is now dictated by |
|
CSS instead of hard-coded. |
|
It also will not span past the current scope, |
|
for the same reason. |
|
Note that in |
|
.Sx ASCII Output |
|
mode, this will work fine. |
|
.It |
|
The |
|
.Xr mdoc 7 |
|
.Sq \&Bl \-hang |
|
and |
|
.Sq \&Bl \-tag |
|
list types render similarly (no break following overreached left-hand |
|
side) due to the expressive constraints of HTML. |
|
.It |
|
The |
|
.Xr man 7 |
|
.Sq IP |
|
and |
|
.Sq TP |
|
lists render similarly. |
|
.El |
|
.Sh SEE ALSO |
.Sh SEE ALSO |
|
.Xr apropos 1 , |
|
.Xr man 1 , |
.Xr eqn 7 , |
.Xr eqn 7 , |
.Xr man 7 , |
.Xr man 7 , |
.Xr mandoc_char 7 , |
.Xr mandoc_char 7 , |
Line 1622 lists render similarly. |
|
Line 1680 lists render similarly. |
|
The |
The |
.Nm |
.Nm |
utility was written by |
utility was written by |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . |
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv |
.Sh CAVEATS |
and is maintained by |
|
.An Ingo Schwarze Aq Mt schwarze@openbsd.org . |
|
.Sh BUGS |
In |
In |
.Fl T Ns Cm html |
.Fl T Ns Cm html , |
and |
|
.Fl T Ns Cm xhtml , |
|
the maximum size of an element attribute is determined by |
the maximum size of an element attribute is determined by |
.Dv BUFSIZ , |
.Dv BUFSIZ , |
which is usually 1024 bytes. |
which is usually 1024 bytes. |
Be aware of this when setting long link |
Be aware of this when setting long link |
formats such as |
formats such as |
.Fl O Ns Cm style Ns = Ns Ar really/long/link . |
.Fl O Ns Cm style Ns = Ns Ar really/long/link . |
.Pp |
|
Nesting elements within next-line element scopes of |
|
.Fl m Ns Cm an , |
|
such as |
|
.Sq br |
|
within an empty |
|
.Sq B , |
|
will confuse |
|
.Fl T Ns Cm html |
|
and |
|
.Fl T Ns Cm xhtml |
|
and cause them to forget the formatting of the prior next-line scope. |
|
.Pp |
|
The |
|
.Sq \(aq |
|
control character is an alias for the standard macro control character |
|
and does not emit a line-break as stipulated in GNU troff. |
|