[BACK]Return to mandoc.1 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/mandoc.1 between version 1.137 and 1.145

version 1.137, 2015/01/26 13:03:48 version 1.145, 2015/02/04 22:30:10
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.
Line 991  except that it may control a following
Line 994  except that it may control a following
 clause.  clause.
 .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 or no body content
   and hence no effect.
 .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
Line 1088  macro has no argument, or only one argument and no mac
Line 1092  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
Line 1273  its value is implicitly set to the empty string.
Line 1285  its value is implicitly set to the empty string.
 However, defining strings explicitly before use  However, defining strings explicitly before use
 keeps the code more readable.  keeps the code more readable.
 .El  .El
 .Ss "Errors related to equations"  .Ss "Warnings related to tables"
 .Bl -inset -compact  .Bl -ohang
 .It "unexpected equation scope closure"  .It Sy "tbl line starts with span"
 .It "equation scope open on exit"  .Pq tbl
 .It "overlapping equation scopes"  The first cell in a table layout line is a horizontal span
 .It "unexpected end of equation"  .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  .El
 .Ss "Errors related to tables"  .Ss "Errors related to tables"
 .Bl -ohang  .Bl -ohang
Line 1302  The option is ignored.
Line 1325  The option is ignored.
 .Pq tbl  .Pq tbl
 A table option argument contains an invalid number of characters.  A table option argument contains an invalid number of characters.
 Both the option and the argument are ignored.  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  .El
 .Pp  
 .Bl -inset -compact  
 .It Sy "no table layout cells specified"  
 .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"  .Ss "Errors related to roff, mdoc, and man code"
 .Bl -ohang  .Bl -ohang
 .It Sy "input stack limit exceeded, infinite loop?"  .It Sy "input stack limit exceeded, infinite loop?"
Line 1548  An
Line 1603  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
Line 1566  or
Line 1624  or
 .Ic \&EN  .Ic \&EN
 macro, or a  macro, or a
 .Xr roff 7  .Xr roff 7
   .Ic \&br
   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 \&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 \&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 1607  request supported by GNU troff or Heirloom troff but n
Line 1677  request supported by GNU troff or Heirloom troff but n
 .Nm ,  .Nm ,
 and it is likely that this will cause information loss  and it is likely that this will cause information loss
 or considerable misformatting.  or considerable misformatting.
 .It Sy "unsupported table layout"  .It Sy "eqn delim option in tbl"
 .It Sy "ignoring macro in table"  
 .It Sy "eqn in tbl"  
 .Pq eqn , tbl  .Pq eqn , tbl
 The options line of a table defines equation delimiters.  The options line of a table defines equation delimiters.
 Any equation source code contained in the table will be printed unformatted.  Any equation source code contained in the table will be printed unformatted.
 .El  .It Sy "unsupported table layout modifier"
 .Sh COMPATIBILITY  .Pq tbl
 This section summarises  A table layout specification contains an
 .Nm  .Sq Cm m
 compatibility with GNU troff.  modifier.
 Each input and output format is separately noted.  The modifier is discarded.
 .Ss ASCII Compatibility  .It Sy "ignoring macro in table"
 .Bl -bullet -compact  .Pq tbl , mdoc , man
 .It  A table contains an invocation of an
 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  .Xr mdoc 7
 in  or
 .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  .Xr man 7
 macro in  macro or of an undefined macro.
 .Fl T Ns Cm ascii  The macro is ignored, and its arguments are handled
 has no effect.  as if they were a text line.
 .It  
 Words aren't hyphenated.  
 .El  .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 1706  lists render similarly.
Line 1710  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.  
Legend:
Removed from v.1.137  
changed lines
  Added in v.1.145
CVSweb