=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.139 retrieving revision 1.148 diff -u -p -r1.139 -r1.148 --- mandoc/mandoc.1 2015/01/28 17:32:07 1.139 +++ mandoc/mandoc.1 2015/02/06 08:28:35 1.148 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.1,v 1.139 2015/01/28 17:32:07 schwarze Exp $ +.\" $Id: mandoc.1,v 1.148 2015/02/06 08:28:35 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons .\" Copyright (c) 2012, 2014, 2015 Ingo Schwarze @@ -15,7 +15,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: January 28 2015 $ +.Dd $Mdocdate: February 6 2015 $ .Dt MANDOC 1 .Os .Sh NAME @@ -321,9 +321,6 @@ Emboldened characters are rendered as The special characters documented in .Xr mandoc_char 7 are rendered best-effort in an ASCII equivalent. -If no equivalent is found, -.Sq \&? -is used instead. .Pp Output width is limited to 78 visible columns unless literal input lines exceed this limit. @@ -344,7 +341,7 @@ for example overfull lines or ugly line breaks. .It Cm width Ns = Ns Ar width The output width is set to .Ar width , -which will normalise to \(>=60. +which will normalise to \(>=58. .El .Ss HTML Output Output produced by @@ -787,6 +784,12 @@ This may confuse .Xr makewhatis 8 and .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" .Pq mdoc A standard section occurs after another section it usually precedes. @@ -992,6 +995,18 @@ clause. .It Sy "skipping empty macro" .Pq mdoc 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" .Pq mdoc The required width is missing after @@ -1001,12 +1016,6 @@ or .Fl offset or .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" .Pq mdoc The @@ -1038,6 +1047,12 @@ The macro is called without an argument before .Ic \&Nm 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" .Pq mdoc In a @@ -1088,6 +1103,14 @@ macro has no argument, or only one argument and no mac 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 "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" .Pq mdoc An @@ -1291,13 +1314,6 @@ Data provided for this cell is ignored, and nothing is A table layout specification contains more than two consecutive vertical bars. A double bar is printed, all additional bars are discarded. .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" .Bl -ohang .It Sy "non-alphabetic character in tbl options" @@ -1598,7 +1614,10 @@ An .Ic \&Ef , .Ic \&Ek , .Ic \&El , +.Ic \&Lp , +.Ic \&Pp , .Ic \&Re , +.Ic \&Rs , or .Ic \&Ud macro, an @@ -1616,17 +1635,34 @@ or .Ic \&EN macro, or a .Xr roff 7 +.Ic \&br , +.Ic \&fi , +or +.Ic \&nf +request or .Sq \&.. block closing request is invoked with at least one argument. All arguments are ignored. .It Sy "skipping excess arguments" .Pq mdoc , man , roff The -.Ic \&Bf -macro is invoked with more than one argument, the +.Ic \&An +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 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 \&sp +request is invoked with more than one argument, or a request of the .Ic \&de family is invoked with more than two arguments. The excess arguments are ignored. @@ -1677,88 +1713,9 @@ macro or of an undefined macro. The macro is ignored, and its arguments are handled as if they were a text line. .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 +.Xr apropos 1 , +.Xr man 1 , .Xr eqn 7 , .Xr man 7 , .Xr mandoc_char 7 , @@ -1769,32 +1726,15 @@ lists render similarly. The .Nm utility was written by -.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . -.Sh CAVEATS +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv +and is maintained by +.An Ingo Schwarze Aq Mt schwarze@openbsd.org . +.Sh BUGS In -.Fl T Ns Cm html -and -.Fl T Ns Cm xhtml , +.Fl T Ns Cm html , the maximum size of an element attribute is determined by .Dv BUFSIZ , which is usually 1024 bytes. Be aware of this when setting long link formats such as .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.