version 1.139, 2015/01/28 17:32:07 |
version 1.152, 2015/02/07 15:15:20 |
Line 321 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 344 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 732 macro occurs after some non-prologue macro, but still |
|
Line 729 macro occurs after some non-prologue macro, but still |
|
.Pq mdoc |
.Pq mdoc |
The |
The |
.Ic \&Dt |
.Ic \&Dt |
macro can only occur before the first non-prologue macro |
macro appears after the first non-prologue macro. |
because traditional formatters write the page header |
Traditional formatters cannot handle this because |
before parsing the document body. |
they write the page header before parsing the document body. |
Even though this technical restriction does not apply to |
Even though this technical restriction does not apply to |
.Nm , |
.Nm , |
traditional semantics is preserved. |
traditional semantics is preserved. |
Line 787 This may confuse |
|
Line 784 This may confuse |
|
.Xr makewhatis 8 |
.Xr makewhatis 8 |
and |
and |
.Xr apropos 1 . |
.Xr apropos 1 . |
|
.It Sy "missing description line, using \(dq\(dq" |
|
.Pq mdoc |
|
The |
|
.Ic \&Nd |
|
macro lacks the required argument. |
|
The title line of the manual will end after the dash. |
.It Sy "sections out of conventional order" |
.It Sy "sections out of conventional order" |
.Pq mdoc |
.Pq mdoc |
A standard section occurs after another section it usually precedes. |
A standard section occurs after another section it usually precedes. |
Line 833 manual for replacements. |
|
Line 836 manual for replacements. |
|
.Pq mdoc |
.Pq mdoc |
The name of a macro that is not callable appears on a macro line. |
The name of a macro that is not callable appears on a macro line. |
It is printed verbatim. |
It is printed verbatim. |
If the intention is to call it, move it to its own line; |
If the intention is to call it, move it to its own input line; |
otherwise, escape it by prepending |
otherwise, escape it by prepending |
.Sq \e& . |
.Sq \e& . |
.It Sy "skipping paragraph macro" |
.It Sy "skipping paragraph macro" |
|
|
.It Sy "skipping empty macro" |
.It Sy "skipping empty macro" |
.Pq mdoc |
.Pq mdoc |
The indicated macro has no arguments and hence no effect. |
The indicated macro has no arguments and hence no effect. |
|
.It Sy "empty block" |
|
.Pq mdoc , man |
|
A |
|
.Ic \&Bd , |
|
.Ic \&Bk , |
|
.Ic \&Bl , |
|
.Ic \&D1 , |
|
.Ic \&Dl , |
|
.Ic \&RS , |
|
or |
|
.Ic \&UR |
|
block contains nothing in its body and will produce no output. |
.It Sy "empty argument, using 0n" |
.It Sy "empty argument, using 0n" |
.Pq mdoc |
.Pq mdoc |
The required width is missing after |
The required width is missing after |
|
|
.Fl offset |
.Fl offset |
or |
or |
.Fl width. |
.Fl width. |
.It Sy "argument count wrong" |
|
.Pq mdoc , man |
|
The indicated macro has too few or too many arguments. |
|
The syntax tree will contain the wrong number of arguments as given. |
|
Formatting behaviour depends on the specific macro in question. |
|
Note that the same message may also occur as an ERROR, see below. |
|
.It Sy "missing display type, using -ragged" |
.It Sy "missing display type, using -ragged" |
.Pq mdoc |
.Pq mdoc |
The |
The |
|
|
macro is called without an argument before |
macro is called without an argument before |
.Ic \&Nm |
.Ic \&Nm |
has first been called with an argument. |
has first been called with an argument. |
|
.It Sy "missing function name, using \(dq\(dq" |
|
.Pq mdoc |
|
The |
|
.Ic \&Fo |
|
macro is called without an argument. |
|
No function name is printed. |
.It Sy "empty head in list item" |
.It Sy "empty head in list item" |
.Pq mdoc |
.Pq mdoc |
In a |
In a |
|
|
.Ic \&It |
.Ic \&It |
block is empty. |
block is empty. |
An empty list item is shown. |
An empty list item is shown. |
.It Sy "missing font type" |
.It Sy "missing font type, using \efR" |
.Pq mdoc |
.Pq mdoc |
A |
A |
.Ic \&Bf |
.Ic \&Bf |
macro has no argument. |
macro has no argument. |
It switches to the default font, |
It switches to the default font. |
.Cm \efR . |
.It Sy "unknown font type, using \efR" |
.It Sy "unknown font type" |
|
.Pq mdoc |
.Pq mdoc |
The |
The |
.Ic \&Bf |
.Ic \&Bf |
argument is invalid. |
argument is invalid. |
The default font |
The default font is used instead. |
.Cm \efR |
|
is used instead. |
|
.It Sy "nothing follows prefix" |
.It Sy "nothing follows prefix" |
.Pq mdoc |
.Pq mdoc |
A |
A |
Line 1088 macro has no argument, or only one argument and no mac |
|
Line 1100 macro has no argument, or only one argument and no mac |
|
on the same input line. |
on the same input line. |
This defeats its purpose; in particular, spacing is not suppressed |
This defeats its purpose; in particular, spacing is not suppressed |
before the text or macros following on the next input line. |
before the text or macros following on the next input line. |
|
.It Sy "empty reference block" |
|
.Pq mdoc |
|
An |
|
.Ic \&Rs |
|
macro is immediately followed by an |
|
.Ic \&Re |
|
macro on the next input line. |
|
Such an empty block does not produce any output. |
.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 option string, using \(dq\(dq" |
|
.Pq man |
|
The |
|
.Ic \&OP |
|
macro is invoked without any argument. |
|
An empty pair of square brackets is shown. |
|
.It Sy "missing resource identifier, using \(dq\(dq" |
|
.Pq man |
|
The |
|
.Ic \&UR |
|
macro is invoked without any argument. |
|
An empty pair of angle brackets is shown. |
.It Sy "missing eqn box, using \(dq\(dq" |
.It Sy "missing eqn box, using \(dq\(dq" |
.Pq eqn |
.Pq eqn |
A diacritic mark or a binary operator is found, |
A diacritic mark or a binary operator is found, |
|
|
.Fl width |
.Fl width |
argument. |
argument. |
That has no effect. |
That has no effect. |
|
.It Sy "wrong number of cells" |
|
In a line of a |
|
.Ic \&Bl Fl column |
|
list, the number of tabs or |
|
.Ic \&Ta |
|
macros is less than the number expected from the list header line |
|
or exceeds the expected number by more than one. |
|
Missing cells remain empty, and all cells exceeding the number of |
|
columns are joined into one single cell. |
.It Sy "unknown AT&T UNIX version" |
.It Sy "unknown AT&T UNIX version" |
.Pq mdoc |
.Pq mdoc |
An |
An |
|
|
layout modifier has an unknown |
layout modifier has an unknown |
.Ar font |
.Ar font |
argument. |
argument. |
|
.It Sy "odd number of characters in request" |
|
.Pq roff |
|
A |
|
.Ic \&tr |
|
request contains an odd number of characters. |
|
The last character is mapped to the blank character. |
.El |
.El |
.Ss "Warnings related to plain text" |
.Ss "Warnings related to plain text" |
.Bl -ohang |
.Bl -ohang |
Line 1291 Data provided for this cell is ignored, and nothing is |
|
Line 1338 Data provided for this cell is ignored, and nothing is |
|
A table layout specification contains more than two consecutive vertical bars. |
A table layout specification contains more than two consecutive vertical bars. |
A double bar is printed, all additional bars are discarded. |
A double bar is printed, all additional bars are discarded. |
.El |
.El |
.Ss "Errors related to equations" |
|
.Bl -inset -compact |
|
.It "unexpected equation scope closure" |
|
.It "equation scope open on exit" |
|
.It "overlapping equation scopes" |
|
.It "unexpected end of equation" |
|
.El |
|
.Ss "Errors related to tables" |
.Ss "Errors related to tables" |
.Bl -ohang |
.Bl -ohang |
.It Sy "non-alphabetic character in tbl options" |
.It Sy "non-alphabetic character in tbl options" |
Line 1460 macros as well as tables require explicit closing by d |
|
Line 1500 macros as well as tables require explicit closing by d |
|
A block that doesn't support bad nesting |
A block that doesn't support bad nesting |
ends before all of its children are properly closed. |
ends before all of its children are properly closed. |
The open child nodes are closed implicitly. |
The open child nodes are closed implicitly. |
.It Sy "scope open on exit" |
.It Sy "appending missing end of block" |
.Pq mdoc , man , eqn , tbl , roff |
.Pq mdoc , man , eqn , tbl , roff |
At the end of the document, an explicit |
At the end of the document, an explicit |
.Xr mdoc 7 |
.Xr mdoc 7 |
Line 1510 When parsing for a request or a user-defined macro nam |
|
Line 1550 When parsing for a request or a user-defined macro nam |
|
only the escape sequence is discarded. |
only the escape sequence is discarded. |
The characters preceding it are used as the request or macro name, |
The characters preceding it are used as the request or macro name, |
the characters following it are used as the arguments to the request or macro. |
the characters following it are used as the arguments to the request or macro. |
.It Sy "argument count wrong" |
|
.Pq mdoc , man , roff |
|
The indicated request or macro has too few or too many arguments. |
|
The syntax tree will contain the wrong number of arguments as given. |
|
Formatting behaviour depends on the specific request or macro in question. |
|
Note that the same message may also occur as a WARNING, see above. |
|
.It Sy "NOT IMPLEMENTED: Bd -file" |
.It Sy "NOT IMPLEMENTED: Bd -file" |
.Pq mdoc |
.Pq mdoc |
For security reasons, the |
For security reasons, the |
|
|
.Ic \&Ef , |
.Ic \&Ef , |
.Ic \&Ek , |
.Ic \&Ek , |
.Ic \&El , |
.Ic \&El , |
|
.Ic \&Lp , |
|
.Ic \&Pp , |
.Ic \&Re , |
.Ic \&Re , |
|
.Ic \&Rs , |
or |
or |
.Ic \&Ud |
.Ic \&Ud |
macro, an |
macro, an |
|
|
.Ic \&EN |
.Ic \&EN |
macro, or a |
macro, or a |
.Xr roff 7 |
.Xr roff 7 |
|
.Ic \&br , |
|
.Ic \&fi , |
|
or |
|
.Ic \&nf |
|
request or |
.Sq \&.. |
.Sq \&.. |
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 , man , roff |
.Pq mdoc , man , roff |
The |
A macro or request is invoked with too many arguments: |
.Ic \&Bf |
.Bl -dash -offset 2n -width 2n -compact |
macro is invoked with more than one argument, the |
.It |
|
.Ic \&Fo , |
|
.Ic \&PD , |
|
.Ic \&RS , |
|
.Ic \&UR , |
|
.Ic \&ft , |
|
or |
|
.Ic \&sp |
|
with more than one argument |
|
.It |
|
.Ic \&An |
|
with another argument after |
|
.Fl split |
|
or |
|
.Fl nosplit |
|
.It |
.Ic \&RE |
.Ic \&RE |
macro is invoked with more than one argument |
with more than one argument or with a non-integer argument |
or with a non-integer argument, or a request of the |
.It |
|
.Ic \&OP |
|
or a request of the |
.Ic \&de |
.Ic \&de |
family is invoked with more than two arguments. |
family with more than two arguments |
|
.It |
|
.Ic \&TH |
|
with more than five arguments |
|
.It |
|
.Ic \&Bd , |
|
.Ic \&Bk , |
|
or |
|
.Ic \&Bl |
|
with invalid arguments |
|
.El |
The excess arguments are ignored. |
The excess arguments are ignored. |
.El |
.El |
.Ss Unsupported features |
.Ss Unsupported features |
Line 1677 macro or of an undefined macro. |
|
Line 1746 macro or of an undefined macro. |
|
The macro is ignored, and its arguments are handled |
The macro is ignored, and its arguments are handled |
as if they were a text line. |
as if they were a text line. |
.El |
.El |
.Sh COMPATIBILITY |
|
This section summarises |
|
.Nm |
|
compatibility with GNU troff. |
|
Each input and output format is separately noted. |
|
.Ss ASCII Compatibility |
|
.Bl -bullet -compact |
|
.It |
|
Unrenderable unicode codepoints specified with |
|
.Sq \e[uNNNN] |
|
escapes are printed as |
|
.Sq \&? |
|
in mandoc. |
|
In GNU troff, these raise an error. |
|
.It |
|
The |
|
.Sq \&Bd \-literal |
|
and |
|
.Sq \&Bd \-unfilled |
|
macros of |
|
.Xr mdoc 7 |
|
in |
|
.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 |
|
macro in |
|
.Fl T Ns Cm ascii |
|
has no effect. |
|
.It |
|
Words aren't hyphenated. |
|
.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 1769 lists render similarly. |
|
Line 1759 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. |
|