=================================================================== RCS file: /cvs/mandoc/mandoc.1,v retrieving revision 1.138 retrieving revision 1.143 diff -u -p -r1.138 -r1.143 --- mandoc/mandoc.1 2015/01/26 18:42:30 1.138 +++ mandoc/mandoc.1 2015/02/04 18:03:47 1.143 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.1,v 1.138 2015/01/26 18:42:30 schwarze Exp $ +.\" $Id: mandoc.1,v 1.143 2015/02/04 18:03:47 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 26 2015 $ +.Dd $Mdocdate: February 4 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. @@ -1088,6 +1091,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 +1302,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" @@ -1336,14 +1340,31 @@ The invalid character is discarded. 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 -.Pp -.Bl -inset -compact -.It Sy "no table data cells specified" -.It Sy "ignore data in cell" -.It Sy "data block still open" -.It Sy "ignoring extra data cells" -.El .Ss "Errors related to roff, mdoc, and man code" .Bl -ohang .It Sy "input stack limit exceeded, infinite loop?" @@ -1582,6 +1603,7 @@ An .Ic \&Ek , .Ic \&El , .Ic \&Re , +.Ic \&Rs , or .Ic \&Ud macro, an @@ -1640,100 +1662,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 "unsupported table layout modfier" +.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" -.It Sy "eqn 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. -.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 , @@ -1744,32 +1695,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.