===================================================================
RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/mandoc/mandoc.1,v
retrieving revision 1.75
retrieving revision 1.76
diff -c -r1.75 -r1.76
*** src/usr.bin/mandoc/mandoc.1	2015/01/29 00:33:14	1.75
--- src/usr.bin/mandoc/mandoc.1	2015/02/10 07:40:27	1.76
***************
*** 1,4 ****
! .\"	$OpenBSD: mandoc.1,v 1.75 2015/01/29 00:33:14 schwarze Exp $
  .\"
  .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  .\" Copyright (c) 2012, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
--- 1,4 ----
! .\"	$OpenBSD: mandoc.1,v 1.76 2015/02/10 07:40:27 schwarze Exp $
  .\"
  .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  .\" Copyright (c) 2012, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
***************
*** 15,21 ****
  .\" 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 29 2015 $
  .Dt MANDOC 1
  .Os
  .Sh NAME
--- 15,21 ----
  .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  .\"
! .Dd $Mdocdate: February 10 2015 $
  .Dt MANDOC 1
  .Os
  .Sh NAME
***************
*** 655,660 ****
--- 655,1751 ----
  option or
  .Fl T Ns Cm lint
  output mode.
+ .Ss Warnings related to the document prologue
+ .Bl -ohang
+ .It Sy "missing manual title, using UNTITLED"
+ .Pq mdoc
+ A
+ .Ic \&Dt
+ macro has no arguments, or there is no
+ .Ic \&Dt
+ macro before the first non-prologue macro.
+ .It Sy "missing manual title, using \(dq\(dq"
+ .Pq man
+ There is no
+ .Ic \&TH
+ macro, or it has no arguments.
+ .It Sy "lower case character in document title"
+ .Pq mdoc , man
+ The title is still used as given in the
+ .Ic \&Dt
+ or
+ .Ic \&TH
+ macro.
+ .It Sy "missing manual section, using \(dq\(dq"
+ .Pq mdoc , man
+ A
+ .Ic \&Dt
+ or
+ .Ic \&TH
+ macro lacks the mandatory section argument.
+ .It Sy "unknown manual section"
+ .Pq mdoc
+ The section number in a
+ .Ic \&Dt
+ line is invalid, but still used.
+ .It Sy "missing date, using today's date"
+ .Pq mdoc, man
+ The document was parsed as
+ .Xr mdoc 7
+ and it has no
+ .Ic \&Dd
+ macro, or the
+ .Ic \&Dd
+ macro has no arguments or only empty arguments;
+ or the document was parsed as
+ .Xr man 7
+ and it has no
+ .Ic \&TH
+ macro, or the
+ .Ic \&TH
+ macro has less than three arguments or its third argument is empty.
+ .It Sy "cannot parse date, using it verbatim"
+ .Pq mdoc , man
+ The date given in a
+ .Ic \&Dd
+ or
+ .Ic \&TH
+ macro does not follow the conventional format.
+ .It Sy "missing Os macro, using \(dq\(dq"
+ .Pq mdoc
+ The default or current system is not shown in this case.
+ .It Sy "duplicate prologue macro"
+ .Pq mdoc
+ One of the prologue macros occurs more than once.
+ The last instance overrides all previous ones.
+ .It Sy "late prologue macro"
+ .Pq mdoc
+ A
+ .Ic \&Dd
+ or
+ .Ic \&Os
+ macro occurs after some non-prologue macro, but still takes effect.
+ .It Sy "skipping late title macro"
+ .Pq mdoc
+ The
+ .Ic \&Dt
+ macro appears after the first non-prologue macro.
+ Traditional formatters cannot handle this because
+ they write the page header before parsing the document body.
+ Even though this technical restriction does not apply to
+ .Nm ,
+ traditional semantics is preserved.
+ The late macro is discarded including its arguments.
+ .It Sy "prologue macros out of order"
+ .Pq mdoc
+ The prologue macros are not given in the conventional order
+ .Ic \&Dd ,
+ .Ic \&Dt ,
+ .Ic \&Os .
+ All three macros are used even when given in another order.
+ .El
+ .Ss Warnings regarding document structure
+ .Bl -ohang
+ .It Sy ".so is fragile, better use ln(1)"
+ .Pq roff
+ Including files only works when the parser program runs with the correct
+ current working directory.
+ .It Sy "no document body"
+ .Pq mdoc , man
+ The document body contains neither text nor macros.
+ An empty document is shown, consisting only of a header and a footer line.
+ .It Sy "content before first section header"
+ .Pq mdoc , man
+ Some macros or text precede the first
+ .Ic \&Sh
+ or
+ .Ic \&SH
+ section header.
+ The offending macros and text are parsed and added to the top level
+ of the syntax tree, outside any section block.
+ .It Sy "first section is not NAME"
+ .Pq mdoc
+ The argument of the first
+ .Ic \&Sh
+ macro is not
+ .Sq NAME .
+ This may confuse
+ .Xr makewhatis 8
+ and
+ .Xr apropos 1 .
+ .It Sy "bad NAME section contents"
+ .Pq mdoc
+ The last node in the NAME section is not an
+ .Ic \&Nd
+ macro, or any preceding macro is not
+ .Ic \&Nm ,
+ or the NAME section is completely empty.
+ 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.
+ All section titles are used as given,
+ and the order of sections is not changed.
+ .It Sy "duplicate section title"
+ .Pq mdoc
+ The same standard section title occurs more than once.
+ .It Sy "unexpected section"
+ .Pq mdoc
+ A standard section header occurs in a section of the manual
+ where it normally isn't useful.
+ .It Sy "unusual Xr order"
+ .Pq mdoc
+ In the SEE ALSO section, an
+ .Ic \&Xr
+ macro with a lower section number follows one with a higher number,
+ or two
+ .Ic \&Xr
+ macros refering to the same section are out of alphabetical order.
+ .It Sy "unusual Xr punctuation"
+ .Pq mdoc
+ In the SEE ALSO section, punctuation between two
+ .Ic \&Xr
+ macros differs from a single comma, or there is trailing punctuation
+ after the last
+ .Ic \&Xr
+ macro.
+ .It Sy "AUTHORS section without An macro"
+ .Pq mdoc
+ An AUTHORS sections contains no
+ .Ic \&An
+ macros, or only empty ones.
+ Probably, there are author names lacking markup.
+ .El
+ .Ss "Warnings related to macros and nesting"
+ .Bl -ohang
+ .It Sy "obsolete macro"
+ .Pq mdoc
+ See the
+ .Xr mdoc 7
+ manual for replacements.
+ .It Sy "macro neither callable nor escaped"
+ .Pq mdoc
+ The name of a macro that is not callable appears on a macro line.
+ It is printed verbatim.
+ If the intention is to call it, move it to its own input line;
+ otherwise, escape it by prepending
+ .Sq \e& .
+ .It Sy "skipping paragraph macro"
+ In
+ .Xr mdoc 7
+ documents, this happens
+ .Bl -dash -compact
+ .It
+ at the beginning and end of sections and subsections
+ .It
+ right before non-compact lists and displays
+ .It
+ at the end of items in non-column, non-compact lists
+ .It
+ and for multiple consecutive paragraph macros.
+ .El
+ In
+ .Xr man 7
+ documents, it happens
+ .Bl -dash -compact
+ .It
+ for empty
+ .Ic \&P ,
+ .Ic \&PP ,
+ and
+ .Ic \&LP
+ macros
+ .It
+ for
+ .Ic \&IP
+ macros having neither head nor body arguments
+ .It
+ for
+ .Ic \&br
+ or
+ .Ic \&sp
+ right after
+ .Ic \&SH
+ or
+ .Ic \&SS
+ .El
+ .It Sy "moving paragraph macro out of list"
+ .Pq mdoc
+ A list item in a
+ .Ic \&Bl
+ list contains a trailing paragraph macro.
+ The paragraph macro is moved after the end of the list.
+ .It Sy "skipping no-space macro"
+ .Pq mdoc
+ An input line begins with an
+ .Ic \&Ns
+ macro.
+ The macro is ignored.
+ .It Sy "blocks badly nested"
+ .Pq mdoc
+ If two blocks intersect, one should completely contain the other.
+ Otherwise, rendered output is likely to look strange in any output
+ format, and rendering in SGML-based output formats is likely to be
+ outright wrong because such languages do not support badly nested
+ blocks at all.
+ Typical examples of badly nested blocks are
+ .Qq Ic \&Ao \&Bo \&Ac \&Bc
+ and
+ .Qq Ic \&Ao \&Bq \&Ac .
+ In these examples,
+ .Ic \&Ac
+ breaks
+ .Ic \&Bo
+ and
+ .Ic \&Bq ,
+ respectively.
+ .It Sy "nested displays are not portable"
+ .Pq mdoc
+ A
+ .Ic \&Bd ,
+ .Ic \&D1 ,
+ or
+ .Ic \&Dl
+ display occurs nested inside another
+ .Ic \&Bd
+ display.
+ This works with
+ .Nm ,
+ but fails with most other implementations.
+ .It Sy "moving content out of list"
+ .Pq mdoc
+ A
+ .Ic \&Bl
+ list block contains text or macros before the first
+ .Ic \&It
+ macro.
+ The offending children are moved before the beginning of the list.
+ .It Sy ".Vt block has child macro"
+ .Pq mdoc
+ The
+ .Ic \&Vt
+ macro supports plain text arguments only.
+ Formatting may be ugly and semantic searching
+ for the affected content might not work.
+ .It Sy "fill mode already enabled, skipping"
+ .Pq man
+ A
+ .Ic \&fi
+ request occurs even though the document is still in fill mode,
+ or already switched back to fill mode.
+ It has no effect.
+ .It Sy "fill mode already disabled, skipping"
+ .Pq man
+ An
+ .Ic \&nf
+ request occurs even though the document already switched to no-fill mode
+ and did not switch back to fill mode yet.
+ It has no effect.
+ .It Sy "line scope broken"
+ .Pq man
+ While parsing the next-line scope of the previous macro,
+ another macro is found that prematurely terminates the previous one.
+ The previous, interrupted macro is deleted from the parse tree.
+ .El
+ .Ss "Warnings related to missing arguments"
+ .Bl -ohang
+ .It Sy "skipping empty request"
+ .Pq roff , eqn
+ The macro name is missing from a macro definition request,
+ or an
+ .Xr eqn 7
+ control statement or operation keyword lacks its required argument.
+ .It Sy "conditional request controls empty scope"
+ .Pq roff
+ A conditional request is only useful if any of the following
+ follows it on the same logical input line:
+ .Bl -dash -compact
+ .It
+ The
+ .Sq \e{
+ keyword to open a multi-line scope.
+ .It
+ A request or macro or some text, resulting in a single-line scope.
+ .It
+ The immediate end of the logical line without any intervening whitespace,
+ resulting in next-line scope.
+ .El
+ Here, a conditional request is followed by trailing whitespace only,
+ and there is no other content on its logical input line.
+ Note that it doesn't matter whether the logical input line is split
+ across multiple physical input lines using
+ .Sq \e
+ line continuation characters.
+ This is one of the rare cases
+ where trailing whitespace is syntactically significant.
+ The conditional request controls a scope containing whitespace only,
+ so it is unlikely to have a significant effect,
+ except that it may control a following
+ .Ic \&el
+ 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
+ .Ic \&Bd
+ or
+ .Ic \&Bl
+ .Fl offset
+ or
+ .Fl width.
+ .It Sy "missing display type, using -ragged"
+ .Pq mdoc
+ The
+ .Ic \&Bd
+ macro is invoked without the required display type.
+ .It Sy "list type is not the first argument"
+ .Pq mdoc
+ In a
+ .Ic \&Bl
+ macro, at least one other argument precedes the type argument.
+ The
+ .Nm
+ utility copes with any argument order, but some other
+ .Xr mdoc 7
+ implementations do not.
+ .It Sy "missing -width in -tag list, using 8n"
+ .Pq mdoc
+ Every
+ .Ic \&Bl
+ macro having the
+ .Fl tag
+ argument requires
+ .Fl width ,
+ too.
+ .It Sy "missing utility name, using \(dq\(dq"
+ .Pq mdoc
+ The
+ .Ic \&Ex Fl std
+ 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
+ .Ic \&Bl
+ .Fl diag ,
+ .Fl hang ,
+ .Fl inset ,
+ .Fl ohang ,
+ or
+ .Fl tag
+ list, an
+ .Ic \&It
+ macro lacks the required argument.
+ The item head is left empty.
+ .It Sy "empty list item"
+ .Pq mdoc
+ In a
+ .Ic \&Bl
+ .Fl bullet ,
+ .Fl dash ,
+ .Fl enum ,
+ or
+ .Fl hyphen
+ list, an
+ .Ic \&It
+ block is empty.
+ An empty list item is shown.
+ .It Sy "missing font type, using \efR"
+ .Pq mdoc
+ A
+ .Ic \&Bf
+ macro has no argument.
+ It switches to the default font.
+ .It Sy "unknown font type, using \efR"
+ .Pq mdoc
+ The
+ .Ic \&Bf
+ argument is invalid.
+ The default font is used instead.
+ .It Sy "nothing follows prefix"
+ .Pq mdoc
+ A
+ .Ic \&Pf
+ macro has no argument, or only one argument and no macro follows
+ 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
+ .Ic \&Ex
+ or
+ .Ic \&Rv
+ macro lacks the required
+ .Fl std
+ argument.
+ The
+ .Nm
+ utility assumes
+ .Fl std
+ 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"
+ .Pq eqn
+ A diacritic mark or a binary operator is found,
+ but there is nothing to the left of it.
+ An empty box is inserted.
+ .El
+ .Ss "Warnings related to bad macro arguments"
+ .Bl -ohang
+ .It Sy "unterminated quoted argument"
+ .Pq roff
+ Macro arguments can be enclosed in double quote characters
+ such that space characters and macro names contained in the quoted
+ argument need not be escaped.
+ The closing quote of the last argument of a macro can be omitted.
+ However, omitting it is not recommended because it makes the code
+ harder to read.
+ .It Sy "duplicate argument"
+ .Pq mdoc
+ A
+ .Ic \&Bd
+ or
+ .Ic \&Bl
+ macro has more than one
+ .Fl compact ,
+ more than one
+ .Fl offset ,
+ or more than one
+ .Fl width
+ argument.
+ All but the last instances of these arguments are ignored.
+ .It Sy "skipping duplicate argument"
+ .Pq mdoc
+ An
+ .Ic \&An
+ macro has more than one
+ .Fl split
+ or
+ .Fl nosplit
+ argument.
+ All but the first of these arguments are ignored.
+ .It Sy "skipping duplicate display type"
+ .Pq mdoc
+ A
+ .Ic \&Bd
+ macro has more than one type argument; the first one is used.
+ .It Sy "skipping duplicate list type"
+ .Pq mdoc
+ A
+ .Ic \&Bl
+ macro has more than one type argument; the first one is used.
+ .It Sy "skipping -width argument"
+ .Pq mdoc
+ A
+ .Ic \&Bl
+ .Fl column ,
+ .Fl diag ,
+ .Fl ohang ,
+ .Fl inset ,
+ or
+ .Fl item
+ list has a
+ .Fl width
+ argument.
+ 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"
+ .Pq mdoc
+ An
+ .Ic \&At
+ macro has an invalid argument.
+ It is used verbatim, with
+ .Qq "AT&T UNIX "
+ prefixed to it.
+ .It Sy "comma in function argument"
+ .Pq mdoc
+ An argument of an
+ .Ic \&Fa
+ or
+ .Ic \&Fn
+ macro contains a comma; it should probably be split into two arguments.
+ .It Sy "parenthesis in function name"
+ .Pq mdoc
+ The first argument of an
+ .Ic \&Fc
+ or
+ .Ic \&Fn
+ macro contains an opening or closing parenthesis; that's probably wrong,
+ parentheses are added automatically.
+ .It Sy "invalid content in Rs block"
+ .Pq mdoc
+ An
+ .Ic \&Rs
+ block contains plain text or non-% macros.
+ The bogus content is left in the syntax tree.
+ Formatting may be poor.
+ .It Sy "invalid Boolean argument"
+ .Pq mdoc
+ An
+ .Ic \&Sm
+ macro has an argument other than
+ .Cm on
+ or
+ .Cm off .
+ The invalid argument is moved out of the macro, which leaves the macro
+ empty, causing it to toggle the spacing mode.
+ .It Sy "unknown font, skipping request"
+ .Pq man , tbl
+ A
+ .Xr roff 7
+ .Ic \&ft
+ request or a
+ .Xr tbl 7
+ .Ic \&f
+ layout modifier has an unknown
+ .Ar font
+ 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
+ .Ss "Warnings related to plain text"
+ .Bl -ohang
+ .It Sy "blank line in fill mode, using .sp"
+ .Pq mdoc
+ The meaning of blank input lines is only well-defined in non-fill mode:
+ In fill mode, line breaks of text input lines are not supposed to be
+ significant.
+ However, for compatibility with groff, blank lines in fill mode
+ are replaced with
+ .Ic \&sp
+ requests.
+ .It Sy "tab in filled text"
+ .Pq mdoc , man
+ The meaning of tab characters is only well-defined in non-fill mode:
+ In fill mode, whitespace is not supposed to be significant
+ on text input lines.
+ As an implementation dependent choice, tab characters on text lines
+ are passed through to the formatters in any case.
+ Given that the text before the tab character will be filled,
+ it is hard to predict which tab stop position the tab will advance to.
+ .It Sy "whitespace at end of input line"
+ .Pq mdoc , man , roff
+ Whitespace at the end of input lines is almost never semantically
+ significant \(em but in the odd case where it might be, it is
+ extremely confusing when reviewing and maintaining documents.
+ .It Sy "bad comment style"
+ .Pq roff
+ Comment lines start with a dot, a backslash, and a double-quote character.
+ The
+ .Nm
+ utility treats the line as a comment line even without the backslash,
+ but leaving out the backslash might not be portable.
+ .It Sy "invalid escape sequence"
+ .Pq roff
+ An escape sequence has an invalid opening argument delimiter, lacks the
+ closing argument delimiter, or the argument has too few characters.
+ If the argument is incomplete,
+ .Ic \e*
+ and
+ .Ic \en
+ expand to an empty string,
+ .Ic \eB
+ to the digit
+ .Sq 0 ,
+ and
+ .Ic \ew
+ to the length of the incomplete argument.
+ All other invalid escape sequences are ignored.
+ .It Sy "undefined string, using \(dq\(dq"
+ .Pq roff
+ If a string is used without being defined before,
+ its value is implicitly set to the empty string.
+ However, defining strings explicitly before use
+ keeps the code more readable.
+ .El
+ .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 -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
+ .It Sy "input stack limit exceeded, infinite loop?"
+ .Pq roff
+ Explicit recursion limits are implemented for the following features,
+ in order to prevent infinite loops:
+ .Bl -dash -compact
+ .It
+ expansion of nested escape sequences
+ including expansion of strings and number registers,
+ .It
+ expansion of nested user-defined macros,
+ .It
+ and
+ .Ic \&so
+ file inclusion.
+ .El
+ When a limit is hit, the output is incorrect, typically losing
+ some content, but the parser can continue.
+ .It Sy "skipping bad character"
+ .Pq mdoc , man , roff
+ The input file contains a byte that is not a printable
+ .Xr ascii 7
+ character.
+ The message mentions the character number.
+ The offending byte is replaced with a question mark
+ .Pq Sq \&? .
+ Consider editing the input file to replace the byte with an ASCII
+ transliteration of the intended character.
+ .It Sy "skipping unknown macro"
+ .Pq mdoc , man , roff
+ The first identifier on a request or macro line is neither recognized as a
+ .Xr roff 7
+ request, nor as a user-defined macro, nor, respectively, as an
+ .Xr mdoc 7
+ or
+ .Xr man 7
+ macro.
+ It may be mistyped or unsupported.
+ The request or macro is discarded including its arguments.
+ .It Sy "skipping insecure request"
+ .Pq roff
+ An input file attempted to run a shell command
+ or to read or write an external file.
+ Such attempts are denied for security reasons.
+ .It Sy "skipping item outside list"
+ .Pq mdoc , eqn
+ An
+ .Ic \&It
+ macro occurs outside any
+ .Ic \&Bl
+ list, or an
+ .Xr eqn 7
+ .Ic above
+ delimiter occurs outside any pile.
+ It is discarded including its arguments.
+ .It Sy "skipping column outside column list"
+ .Pq mdoc
+ A
+ .Ic \&Ta
+ macro occurs outside any
+ .Ic \&Bl Fl column
+ block.
+ It is discarded including its arguments.
+ .It Sy "skipping end of block that is not open"
+ .Pq mdoc , man , eqn , tbl , roff
+ Various syntax elements can only be used to explicitly close blocks
+ that have previously been opened.
+ An
+ .Xr mdoc 7
+ block closing macro, a
+ .Xr man 7
+ .Ic \&RE
+ or
+ .Ic \&UE
+ macro, an
+ .Xr eqn 7
+ right delimiter or closing brace, or the end of an equation, table, or
+ .Xr roff 7
+ conditional request is encountered but no matching block is open.
+ The offending request or macro is discarded.
+ .It Sy "fewer RS blocks open, skipping"
+ .Pq man
+ The
+ .Ic \&RE
+ macro is invoked with an argument, but less than the specified number of
+ .Ic \&RS
+ blocks is open.
+ The
+ .Ic \&RE
+ macro is discarded.
+ .It Sy "inserting missing end of block"
+ .Pq mdoc , tbl
+ Various
+ .Xr mdoc 7
+ macros as well as tables require explicit closing by dedicated macros.
+ A block that doesn't support bad nesting
+ ends before all of its children are properly closed.
+ The open child nodes are closed implicitly.
+ .It Sy "appending missing end of block"
+ .Pq mdoc , man , eqn , tbl , roff
+ At the end of the document, an explicit
+ .Xr mdoc 7
+ block, a
+ .Xr man 7
+ next-line scope or
+ .Ic \&RS
+ or
+ .Ic \&UR
+ block, an equation, table, or
+ .Xr roff 7
+ conditional or ignore block is still open.
+ The open block is closed implicitly.
+ .It Sy "escaped character not allowed in a name"
+ .Pq roff
+ Macro, string and register identifiers consist of printable,
+ non-whitespace ASCII characters.
+ Escape sequences and characters and strings expressed in terms of them
+ cannot form part of a name.
+ The first argument of an
+ .Ic \&am ,
+ .Ic \&as ,
+ .Ic \&de ,
+ .Ic \&ds ,
+ .Ic \&nr ,
+ or
+ .Ic \&rr
+ request, or any argument of an
+ .Ic \&rm
+ request, or the name of a request or user defined macro being called,
+ is terminated by an escape sequence.
+ In the cases of
+ .Ic \&as ,
+ .Ic \&ds ,
+ and
+ .Ic \&nr ,
+ the request has no effect at all.
+ In the cases of
+ .Ic \&am ,
+ .Ic \&de ,
+ .Ic \&rr ,
+ and
+ .Ic \&rm ,
+ what was parsed up to this point is used as the arguments to the request,
+ and the rest of the input line is discarded including the escape sequence.
+ When parsing for a request or a user-defined macro name to be called,
+ only the escape sequence is discarded.
+ 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.
+ .It Sy "NOT IMPLEMENTED: Bd -file"
+ .Pq mdoc
+ For security reasons, the
+ .Ic \&Bd
+ macro does not support the
+ .Fl file
+ argument.
+ By requesting the inclusion of a sensitive file, a malicious document
+ might otherwise trick a privileged user into inadvertently displaying
+ the file on the screen, revealing the file content to bystanders.
+ The argument is ignored including the file name following it.
+ .It Sy "missing list type, using -item"
+ .Pq mdoc
+ A
+ .Ic \&Bl
+ macro fails to specify the list type.
+ .It Sy "missing manual name, using \(dq\(dq"
+ .Pq mdoc
+ The first call to
+ .Ic \&Nm
+ lacks the required argument.
+ .It Sy "uname(3) system call failed, using UNKNOWN"
+ .Pq mdoc
+ The
+ .Ic \&Os
+ macro is called without arguments, and the
+ .Xr uname 3
+ system call failed.
+ As a workaround,
+ .Nm
+ can be compiled with
+ .Sm off
+ .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
+ .Sm on
+ .It Sy "unknown standard specifier"
+ .Pq mdoc
+ An
+ .Ic \&St
+ macro has an unknown argument and is discarded.
+ .It Sy "skipping request without numeric argument"
+ .Pq roff , eqn
+ An
+ .Ic \&it
+ request or an
+ .Xr eqn 7
+ .Ic \&size
+ or
+ .Ic \&gsize
+ statement has a non-numeric or negative argument or no argument at all.
+ The invalid request or statement is ignored.
+ .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
+ .Pq roff
+ For security reasons,
+ .Nm
+ allows
+ .Ic \&so
+ file inclusion requests only with relative paths
+ and only without ascending to any parent directory.
+ By requesting the inclusion of a sensitive file, a malicious document
+ might otherwise trick a privileged user into inadvertently displaying
+ the file on the screen, revealing the file content to bystanders.
+ .Nm
+ only shows the path as it appears behind
+ .Ic \&so .
+ .It Sy ".so request failed"
+ .Pq roff
+ Servicing a
+ .Ic \&so
+ request requires reading an external file, but the file could not be
+ opened.
+ .Nm
+ only shows the path as it appears behind
+ .Ic \&so .
+ .It Sy "skipping all arguments"
+ .Pq mdoc , man , eqn , roff
+ An
+ .Xr mdoc 7
+ .Ic \&Bt ,
+ .Ic \&Ed ,
+ .Ic \&Ef ,
+ .Ic \&Ek ,
+ .Ic \&El ,
+ .Ic \&Lp ,
+ .Ic \&Pp ,
+ .Ic \&Re ,
+ .Ic \&Rs ,
+ or
+ .Ic \&Ud
+ macro, an
+ .Ic \&It
+ macro in a list that don't support item heads, a
+ .Xr man 7
+ .Ic \&LP ,
+ .Ic \&P ,
+ or
+ .Ic \&PP
+ macro, an
+ .Xr eqn 7
+ .Ic \&EQ
+ 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
+ A macro or request is invoked with too many arguments:
+ .Bl -dash -offset 2n -width 2n -compact
+ .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
+ with more than one argument or with a non-integer argument
+ .It
+ .Ic \&OP
+ or a request of the
+ .Ic \&de
+ 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.
+ .El
+ .Ss Unsupported features
+ .Bl -ohang
+ .It Sy "input too large"
+ .Pq mdoc , man
+ Currently,
+ .Nm
+ cannot handle input files larger than its arbitrary size limit
+ 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
+ .Xr roff 7
+ request supported by GNU troff or Heirloom troff but not by
+ .Nm ,
+ and it is likely that this will cause information loss
+ or considerable misformatting.
+ .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"
+ .Pq tbl , mdoc , man
+ A table contains an invocation of an
+ .Xr mdoc 7
+ or
+ .Xr man 7
+ macro or of an undefined macro.
+ The macro is ignored, and its arguments are handled
+ as if they were a text line.
+ .El
  .Sh SEE ALSO
  .Xr apropos 1 ,
  .Xr man 1 ,