version 1.140, 2015/01/28 21:11:53 |
version 1.149, 2015/02/06 09:38:43 |
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 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. |
|
|
.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 |
Line 1088 macro has no argument, or only one argument and no mac |
|
Line 1103 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 |
|
|
.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 |
The |
.Ic \&Bf |
.Ic \&An |
macro is invoked with more than one argument, the |
macro is invoked with another argument after |
|
.Fl split |
|
or |
|
.Fl nosplit , |
|
.Ic \&Fo |
|
is invoked with more than one argument, |
|
.Ic \&Bd , |
|
.Ic \&Bk , |
|
or |
|
.Ic \&Bl |
|
are invoked with invalid arguments, the |
.Ic \&RE |
.Ic \&RE |
macro is invoked with more than one argument |
macro is invoked with more than one argument |
or with a non-integer argument, or a request of the |
or with a non-integer argument, the |
|
.Ic \&PD |
|
macro or the |
|
.Ic \&ft |
|
or |
|
.Ic \&sp |
|
request is invoked with more than one 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. |
Line 1670 macro or of an undefined macro. |
|
Line 1717 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 1762 lists render similarly. |
|
Line 1730 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. |
|