=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.135 retrieving revision 1.148 diff -u -p -r1.135 -r1.148 --- mandoc/mandoc.1 2015/01/24 01:58:33 1.135 +++ mandoc/mandoc.1 2015/02/06 08:28:35 1.148 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.1,v 1.135 2015/01/24 01:58:33 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 24 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 @@ -1273,20 +1296,86 @@ its value is implicitly set to the empty string. However, defining strings explicitly before use keeps the code more readable. .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" +.Ss "Warnings related to tables" +.Bl -ohang +.It Sy "tbl line starts with span" +.Pq tbl +The first cell in a table layout line is a horizontal span +.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 .Ss "Errors related to tables" -.Bl -inset -compact -.It "no table layout cells specified" -.It "no table data cells specified" -.It "ignore data in cell" -.It "data block still open" -.It "ignoring extra data cells" +.Bl -ohang +.It Sy "non-alphabetic character in tbl options" +.Pq tbl +The table options line contains a character other than a letter, +blank, or comma where the beginning of an option name is expected. +The character is ignored. +.It Sy "skipping unknown tbl option" +.Pq tbl +The table options line contains a string of letters that does not +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 .Ss "Errors related to roff, mdoc, and man code" .Bl -ohang @@ -1525,7 +1614,10 @@ An .Ic \&Ef , .Ic \&Ek , .Ic \&El , +.Ic \&Lp , +.Ic \&Pp , .Ic \&Re , +.Ic \&Rs , or .Ic \&Ud macro, an @@ -1543,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. @@ -1568,6 +1677,14 @@ cannot handle input files larger than its arbitrary si 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 "unsupported control character" +.Pq roff +An ASCII control character supported by other +.Xr roff 7 +implementations but not by +.Nm +was found in an input file. +It is replaced by a question mark. .It Sy "unsupported roff request" .Pq roff An input file contains a @@ -1576,93 +1693,29 @@ request supported by GNU troff or Heirloom troff but n .Nm , and it is likely that this will cause information loss or considerable misformatting. -.It Sy "bad table syntax" -.It Sy "bad table option" -.It Sy "bad table layout" +.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" -.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 +.Pq tbl , mdoc , man +A table contains an invocation of an .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 +or .Xr man 7 -macro in -.Fl T Ns Cm ascii -has no effect. -.It -Words aren't hyphenated. +macro or of an undefined macro. +The macro is ignored, and its arguments are handled +as if they were a text line. .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 , @@ -1673,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.