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

Diff for /mandoc/mandoc.1 between version 1.139 and 1.151

version 1.139, 2015/01/28 17:32:07 version 1.151, 2015/02/06 16:06:25
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 992  clause.
Line 995  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 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
Line 1001  or
Line 1016  or
 .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
Line 1038  The
Line 1047  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
Line 1102  The
Line 1125  The
 utility assumes  utility assumes
 .Fl std  .Fl std
 even when it is not specified, but other implementations may not.  even when it is not specified, but other implementations may not.
   .It Sy "missing option string, using \(dq\(dq"
   .Pq man
   The
   .Ic \&OP
   macro is invoked without any argument.
   An empty pair of square brackets is shown.
   .It Sy "missing resource identifier, using \(dq\(dq"
   .Pq man
   The
   .Ic \&UR
   macro is invoked without any argument.
   An empty pair of angle brackets is shown.
 .It Sy "missing eqn box, using \(dq\(dq"  .It Sy "missing eqn box, using \(dq\(dq"
 .Pq eqn  .Pq eqn
 A diacritic mark or a binary operator is found,  A diacritic mark or a binary operator is found,
Line 1166  list has a
Line 1201  list has a
 .Fl width  .Fl width
 argument.  argument.
 That has no effect.  That has no effect.
   .It Sy "wrong number of cells"
   In a line of a
   .Ic \&Bl Fl column
   list, the number of tabs or
   .Ic \&Ta
   macros is less than the number expected from the list header line
   or exceeds the expected number by more than one.
   Missing cells remain empty, and all cells exceeding the number of
   columns are joined into one single cell.
 .It Sy "unknown AT&T UNIX version"  .It Sy "unknown AT&T UNIX version"
 .Pq mdoc  .Pq mdoc
 An  An
Line 1217  request or a
Line 1261  request or a
 layout modifier has an unknown  layout modifier has an unknown
 .Ar font  .Ar font
 argument.  argument.
   .It Sy "odd number of characters in request"
   .Pq roff
   A
   .Ic \&tr
   request contains an odd number of characters.
   The last character is mapped to the blank character.
 .El  .El
 .Ss "Warnings related to plain text"  .Ss "Warnings related to plain text"
 .Bl -ohang  .Bl -ohang
Line 1291  Data provided for this cell is ignored, and nothing is
Line 1341  Data provided for this cell is ignored, and nothing is
 A table layout specification contains more than two consecutive vertical bars.  A table layout specification contains more than two consecutive vertical bars.
 A double bar is printed, all additional bars are discarded.  A double bar is printed, all additional bars are discarded.
 .El  .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"  .Ss "Errors related to tables"
 .Bl -ohang  .Bl -ohang
 .It Sy "non-alphabetic character in tbl options"  .It Sy "non-alphabetic character in tbl options"
Line 1510  When parsing for a request or a user-defined macro nam
Line 1553  When parsing for a request or a user-defined macro nam
 only the escape sequence is discarded.  only the escape sequence is discarded.
 The characters preceding it are used as the request or macro name,  The characters preceding it are used as the request or macro name,
 the characters following it are used as the arguments to the request or macro.  the characters following it are used as the arguments to the request or macro.
 .It Sy "argument count wrong"  
 .Pq mdoc , man , roff  
 The indicated request or 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 request or macro in question.  
 Note that the same message may also occur as a WARNING, see above.  
 .It Sy "NOT IMPLEMENTED: Bd -file"  .It Sy "NOT IMPLEMENTED: Bd -file"
 .Pq mdoc  .Pq mdoc
 For security reasons, the  For security reasons, the
Line 1598  An
Line 1635  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 1616  or
Line 1656  or
 .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  A macro or request is invoked with too many arguments:
 .Ic \&Bf  .Bl -dash -offset 2n -width 2n -compact
 macro is invoked with more than one argument, the  .It
   .Ic \&Fo ,
   .Ic \&PD ,
   .Ic \&RS ,
   .Ic \&UR ,
   .Ic \&ft ,
   or
   .Ic \&sp
   with more than one argument
   .It
   .Ic \&An
   with another argument after
   .Fl split
   or
   .Fl nosplit
   .It
 .Ic \&RE  .Ic \&RE
 macro is invoked with more than one argument  with more than one argument or with a non-integer argument
 or with a non-integer argument, or a request of the  .It
   .Ic \&OP
   or a request of the
 .Ic \&de  .Ic \&de
 family is invoked with more than two arguments.  family with more than two arguments
   .It
   .Ic \&TH
   with more than five arguments
   .It
   .Ic \&Bd ,
   .Ic \&Bk ,
   or
   .Ic \&Bl
   with invalid arguments
   .El
 The excess arguments are ignored.  The excess arguments are ignored.
 .El  .El
 .Ss Unsupported features  .Ss Unsupported features
Line 1677  macro or of an undefined macro.
Line 1749  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 1769  lists render similarly.
Line 1762  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.139  
changed lines
  Added in v.1.151
CVSweb