1 .\" $Id: mandoc.1,v 1.179 2017/03/18 19:51:19 schwarze Exp $
3 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2012, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18 .Dd $Mdocdate: March 18 2017 $
23 .Nd format and display UNIX manuals
27 .Op Fl I Cm os Ns = Ns Ar name
39 manual pages for display.
47 text from stdin, implying
53 The options are as follows:
56 If the standard output is a terminal device and
60 to paginate the output, just like
64 Copy the formatted manual pages to the standard output without using
68 It can be specified to override
73 This overrides any earlier
79 Display only the SYNOPSIS lines.
82 .It Fl I Cm os Ns = Ns Ar name
83 Override the default operating system
93 Specify the input encoding.
101 If not specified, autodetection uses the first match in the following
105 If the first three bytes of the input file are the UTF-8 byte order
106 mark (BOM, 0xefbbbf), input is interpreted as
109 If the first or second line of the input file matches the
113 .D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*-
115 then input is interpreted according to
118 If the first non-ASCII byte in the file introduces a valid UTF-8
119 sequence, input is interpreted as
122 Otherwise, input is interpreted as
128 This overrides any earlier
136 Also reverts any earlier
141 .It Fl m Ns Ar format
145 for available formats.
149 Comma-separated output options.
154 for available formats.
158 Specify the minimum message
160 to be reported on the standard error output and to affect the exit status.
184 to exit after parsing a file that causes warnings or errors of at least
186 No formatted output will be produced from that file.
191 are requested, they can be joined with a comma, for example
192 .Fl W Cm error , Ns Cm stop .
194 Read input from zero or more files.
195 If unspecified, reads from stdin.
196 If multiple files are specified,
198 will halt with the first failed parse.
207 also supports the options
230 should only be used for legacy manuals.
234 which is also the default, determines encoding on-the-fly: if the first
241 parser is used; otherwise, the
246 files are specified with
248 each has its file-type determined this way.
249 If multiple files are
254 is specified, then this format is used exclusively.
258 utility accepts the following
260 arguments, which correspond to output modes:
261 .Bl -tag -width "-T markdown"
263 Produce 7-bit ASCII output.
267 Produce HTML5, CSS1, and MathML output.
271 Parse only: produce no output.
275 Encode output using the current locale.
290 .Sx Markdown Output .
296 Produce PostScript output.
298 .Sx PostScript Output .
300 Produce an indented parse tree.
302 .Sx Syntax tree output .
304 Encode output in the UTF\-8 multi-byte format.
308 This is a synonym for
312 If multiple input files are specified, these will be processed by the
313 corresponding filter in-order.
317 is rendered in standard 7-bit ASCII documented in
320 Font styles are applied by using back-spaced encoding such that an
324 .Sq _ Ns \e[bs] Ns c ,
327 is the back-space character number 8.
328 Emboldened characters are rendered as
329 .Sq c Ns \e[bs] Ns c .
331 The special characters documented in
333 are rendered best-effort in an ASCII equivalent.
335 Output width is limited to 78 visible columns unless literal input lines
340 arguments are accepted:
342 .It Cm indent Ns = Ns Ar indent
343 The left margin for normal text is set to
345 blank characters instead of the default of five for
349 Increasing this is not recommended; it may result in degraded formatting,
350 for example overfull lines or ugly line breaks.
351 .It Cm width Ns = Ns Ar width
352 The output width is set to
354 which will normalise to \(>=58.
359 conforms to HTML5 using optional self-closing tags.
360 Default styles use only CSS1.
361 Equations rendered from
367 file documents style-sheet classes available for customising output.
368 If a style-sheet is not specified with
371 defaults to simple output (via an embedded style-sheet)
372 readable in any graphical or text-based web
375 Special characters are rendered in decimal-encoded UTF\-8.
379 arguments are accepted:
382 Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body>
383 elements and only emit the subtree below the <body> element.
386 argument will be ignored.
387 This is useful when embedding manual content within existing documents.
388 .It Cm includes Ns = Ns Ar fmt
393 is used as a template for linked header files (usually via the
398 are replaced with the include filename.
399 The default is not to present a
401 .It Cm man Ns = Ns Ar fmt
405 .Ar ../html%S/%N.%S.html ,
406 is used as a template for linked manuals (usually via the
413 are replaced with the linked manual's name and section, respectively.
414 If no section is included, section 1 is assumed.
415 The default is not to
417 .It Cm style Ns = Ns Ar style.css
420 is used for an external style-sheet.
421 This must be a valid absolute or
425 Locale-depending output encoding is triggered with
429 This option is not available on all systems: systems without locale
430 support, or those whose internal representation is not natively UCS-4,
435 for font style specification and available command-line arguments.
437 Translate input format into
440 This is useful for distributing manual sources to legacy systems
447 is passed as input, it is translated into
449 If the input format is
451 the input is copied to the output, expanding any
455 The parser is also run, and as usual, the
459 are displayed before copying the input to the output.
466 .Lk http://daringfireball.net/projects/markdown/syntax.text\
467 "John Gruber's 2004 specification" .
468 The output also almost conforms to the
469 .Lk http://commonmark.org/ CommonMark
472 The character set used for the markdown output is ASCII.
473 Non-ASCII characters are encoded as HTML entities.
474 Since that is not possible in literal font contexts, because these
475 are rendered as code spans and code blocks in the markdown output,
476 non-ASCII characters are transliterated to ASCII approximations in
479 Markdown is a very weak markup language, so all semantic markup is
480 lost, and even part of the presentational markup may be lost.
481 Do not use this as an intermediate step in converting to HTML;
491 input languages are not supported by
495 PDF-1.1 output may be generated by
498 .Sx PostScript Output
501 arguments and defaults.
502 .Ss PostScript Output
505 Level-2 pages may be generated by
507 Output pages default to letter sized and are rendered in the Times font
509 Margins are calculated as 1/9 the page length and width.
512 Special characters are rendered as in
517 arguments are accepted:
519 .It Cm paper Ns = Ns Ar name
529 You may also manually specify dimensions as
531 width by height in millimetres.
532 If an unknown value is encountered,
539 to force a UTF\-8 locale.
542 for details and options.
543 .Ss Syntax tree output
546 to show a human readable representation of the syntax tree.
547 It is useful for debugging the source code of manual pages.
548 The exact format is subject to change, so don't write parsers for it.
550 The first paragraph shows meta data found in the
555 line, or the fallbacks used.
557 In the tree dump, each output line shows one syntax tree node.
558 Child nodes are indented with respect to their parent node.
563 For macro nodes, the macro name; for text and
566 There is a special format for
570 Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
575 An opening parenthesis if the node is an opening delimiter.
577 An asterisk if the node starts a new input line.
579 The input line number (starting at one).
583 The input column number (starting at one).
585 A closing parenthesis if the node is a closing delimiter.
587 A full stop if the node ends a sentence.
589 BROKEN if the node is a block broken by another block.
591 NOSRC if the node is not in the input file,
592 but automatically generated from macros.
594 NOPRT if the node is not supposed to generate output
595 for any output format.
601 argument is accepted:
604 Skip validation and show the unvalidated syntax tree.
605 This can help to find out whether a given behaviour is caused by
606 the parser or by the validator.
607 Meta data is not available in this case.
610 .Bl -tag -width MANPAGER
612 Any non-empty value of the environment variable
614 is used instead of the standard pagination program,
625 Specifies the pagination program to use when
628 If neither PAGER nor MANPAGER is defined,
641 utility exits with one of the following values, controlled by the message
647 .Bl -tag -width Ds -compact
649 No warnings or errors occurred, or those that did were ignored because
650 they were lower than the requested
653 At least one warning occurred, but no error, and
657 At least one parsing error occurred,
658 but no unsupported feature was encountered, and
664 At least one unsupported feature was encountered, and
671 Invalid command line arguments were specified.
672 No input files have been read.
674 An operating system error occurred, for example exhaustion
675 of memory, file descriptors, or process table entries.
678 to exit at once, possibly in the middle of parsing or formatting a file.
686 To page manuals to the terminal:
688 .Dl $ mandoc \-W all,stop mandoc.1 2\*(Gt&1 | less
689 .Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
691 To produce HTML manuals with
695 .Dl $ mandoc \-T html -O style=mandoc.css mdoc.7 \*(Gt mdoc.7.html
697 To check over a large set of manuals:
699 .Dl $ mandoc \-T lint \(gafind /usr/src -name \e*\e.[1-9]\(ga
701 To produce a series of PostScript manuals for A4 paper:
703 .Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 \*(Gt manuals.ps
709 format, for use on systems lacking an
713 .Dl $ mandoc \-T man foo.mdoc \*(Gt foo.man
715 Messages displayed by
719 .D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args
721 Line and column numbers start at 1.
722 Both are omitted for messages referring to an input file as a whole.
723 Macro names and arguments are omitted where meaningless.
724 Fatal messages about invalid command line arguments
725 or operating system errors, for example when memory is exhausted,
732 Message levels have the following meanings:
733 .Bl -tag -width "warning"
735 An input file uses unsupported low-level
738 The output may be incomplete and/or misformatted,
739 so using GNU troff instead of
741 to process the file may be preferable.
743 An input file contains invalid syntax that cannot be safely interpreted.
744 By discarding part of the input or inserting missing tokens,
745 the parser is able to continue, and the error does not prevent
746 generation of formatted output, but typically, preparing that
747 output involves information loss, broken document structure
748 or unintended formatting, no matter whether
750 or GNU troff is used.
751 In many cases, the output of
753 and GNU troff is identical, but in some,
755 is more resilient than GNU troff with respect to malformed input.
757 Non-existent or unreadable input files are also reported on the
760 In that case, the parser cannot even be started and no output
761 is produced from those input files.
763 An input file uses obsolete, discouraged or non-portable syntax.
764 All the same, the meaning of the input is unambiguous and a correct
765 rendering can be produced.
766 Documents causing warnings may render poorly when using other
767 formatting tools instead of
776 levels except those about non-existent or unreadable input files
777 are hidden unless their level, or a lower level, is requested using a
782 .Ss Warnings related to the document prologue
784 .It Sy "missing manual title, using UNTITLED"
788 macro has no arguments, or there is no
790 macro before the first non-prologue macro.
791 .It Sy "missing manual title, using \(dq\(dq"
795 macro, or it has no arguments.
796 .It Sy "lower case character in document title"
798 The title is still used as given in the
803 .It Sy "missing manual section, using \(dq\(dq"
809 macro lacks the mandatory section argument.
810 .It Sy "unknown manual section"
812 The section number in a
814 line is invalid, but still used.
815 .It Sy "missing date, using today's date"
817 The document was parsed as
823 macro has no arguments or only empty arguments;
824 or the document was parsed as
830 macro has less than three arguments or its third argument is empty.
831 .It Sy "cannot parse date, using it verbatim"
837 macro does not follow the conventional format.
838 .It Sy "missing Os macro, using \(dq\(dq"
840 The default or current system is not shown in this case.
841 .It Sy "duplicate prologue macro"
843 One of the prologue macros occurs more than once.
844 The last instance overrides all previous ones.
845 .It Sy "late prologue macro"
851 macro occurs after some non-prologue macro, but still takes effect.
852 .It Sy "skipping late title macro"
856 macro appears after the first non-prologue macro.
857 Traditional formatters cannot handle this because
858 they write the page header before parsing the document body.
859 Even though this technical restriction does not apply to
861 traditional semantics is preserved.
862 The late macro is discarded including its arguments.
863 .It Sy "prologue macros out of order"
865 The prologue macros are not given in the conventional order
869 All three macros are used even when given in another order.
871 .Ss Warnings regarding document structure
873 .It Sy ".so is fragile, better use ln(1)"
875 Including files only works when the parser program runs with the correct
876 current working directory.
877 .It Sy "no document body"
879 The document body contains neither text nor macros.
880 An empty document is shown, consisting only of a header and a footer line.
881 .It Sy "content before first section header"
883 Some macros or text precede the first
888 The offending macros and text are parsed and added to the top level
889 of the syntax tree, outside any section block.
890 .It Sy "first section is not NAME"
892 The argument of the first
900 .It Sy "NAME section without Nm before Nd"
902 The NAME section does not contain any
904 child macro before the first
907 .It Sy "NAME section without description"
909 The NAME section lacks the mandatory
912 .It Sy "description not at the end of NAME"
914 The NAME section does contain an
916 child macro, but other content follows it.
917 .It Sy "bad NAME section content"
919 The NAME section contains plain text or macros other than
923 .It Sy "missing comma before name"
925 The NAME section contains an
927 macro that is neither the first one nor preceded by a comma.
928 .It Sy "missing description line, using \(dq\(dq"
932 macro lacks the required argument.
933 The title line of the manual will end after the dash.
934 .It Sy "description line outside NAME section"
938 macro appears outside the NAME section.
939 The arguments are printed anyway and the following text is used for
941 but none of that behaviour is portable.
942 .It Sy "sections out of conventional order"
944 A standard section occurs after another section it usually precedes.
945 All section titles are used as given,
946 and the order of sections is not changed.
947 .It Sy "duplicate section title"
949 The same standard section title occurs more than once.
950 .It Sy "unexpected section"
952 A standard section header occurs in a section of the manual
953 where it normally isn't useful.
954 .It Sy "unusual Xr order"
956 In the SEE ALSO section, an
958 macro with a lower section number follows one with a higher number,
961 macros referring to the same section are out of alphabetical order.
962 .It Sy "unusual Xr punctuation"
964 In the SEE ALSO section, punctuation between two
966 macros differs from a single comma, or there is trailing punctuation
970 .It Sy "AUTHORS section without An macro"
972 An AUTHORS sections contains no
974 macros, or only empty ones.
975 Probably, there are author names lacking markup.
977 .Ss "Warnings related to macros and nesting"
979 .It Sy "obsolete macro"
983 manual for replacements.
984 .It Sy "macro neither callable nor escaped"
986 The name of a macro that is not callable appears on a macro line.
987 It is printed verbatim.
988 If the intention is to call it, move it to its own input line;
989 otherwise, escape it by prepending
991 .It Sy "skipping paragraph macro"
994 documents, this happens
997 at the beginning and end of sections and subsections
999 right before non-compact lists and displays
1001 at the end of items in non-column, non-compact lists
1003 and for multiple consecutive paragraph macros.
1007 documents, it happens
1019 macros having neither head nor body arguments
1030 .It Sy "moving paragraph macro out of list"
1034 list contains a trailing paragraph macro.
1035 The paragraph macro is moved after the end of the list.
1036 .It Sy "skipping no-space macro"
1038 An input line begins with an
1041 The macro is ignored.
1042 .It Sy "blocks badly nested"
1044 If two blocks intersect, one should completely contain the other.
1045 Otherwise, rendered output is likely to look strange in any output
1046 format, and rendering in SGML-based output formats is likely to be
1047 outright wrong because such languages do not support badly nested
1049 Typical examples of badly nested blocks are
1050 .Qq Ic \&Ao \&Bo \&Ac \&Bc
1052 .Qq Ic \&Ao \&Bq \&Ac .
1060 .It Sy "nested displays are not portable"
1067 display occurs nested inside another
1072 but fails with most other implementations.
1073 .It Sy "moving content out of list"
1077 list block contains text or macros before the first
1080 The offending children are moved before the beginning of the list.
1081 .It Sy "fill mode already enabled, skipping"
1085 request occurs even though the document is still in fill mode,
1086 or already switched back to fill mode.
1088 .It Sy "fill mode already disabled, skipping"
1092 request occurs even though the document already switched to no-fill mode
1093 and did not switch back to fill mode yet.
1095 .It Sy "line scope broken"
1097 While parsing the next-line scope of the previous macro,
1098 another macro is found that prematurely terminates the previous one.
1099 The previous, interrupted macro is deleted from the parse tree.
1101 .Ss "Warnings related to missing arguments"
1103 .It Sy "skipping empty request"
1105 The macro name is missing from a macro definition request,
1108 control statement or operation keyword lacks its required argument.
1109 .It Sy "conditional request controls empty scope"
1111 A conditional request is only useful if any of the following
1112 follows it on the same logical input line:
1117 keyword to open a multi-line scope.
1119 A request or macro or some text, resulting in a single-line scope.
1121 The immediate end of the logical line without any intervening whitespace,
1122 resulting in next-line scope.
1124 Here, a conditional request is followed by trailing whitespace only,
1125 and there is no other content on its logical input line.
1126 Note that it doesn't matter whether the logical input line is split
1127 across multiple physical input lines using
1129 line continuation characters.
1130 This is one of the rare cases
1131 where trailing whitespace is syntactically significant.
1132 The conditional request controls a scope containing whitespace only,
1133 so it is unlikely to have a significant effect,
1134 except that it may control a following
1137 .It Sy "skipping empty macro"
1139 The indicated macro has no arguments and hence no effect.
1140 .It Sy "empty block"
1151 block contains nothing in its body and will produce no output.
1152 .It Sy "empty argument, using 0n"
1154 The required width is missing after
1161 .It Sy "missing display type, using -ragged"
1165 macro is invoked without the required display type.
1166 .It Sy "list type is not the first argument"
1170 macro, at least one other argument precedes the type argument.
1173 utility copes with any argument order, but some other
1175 implementations do not.
1176 .It Sy "missing -width in -tag list, using 8n"
1185 .It Sy "missing utility name, using \(dq\(dq"
1189 macro is called without an argument before
1191 has first been called with an argument.
1192 .It Sy "missing function name, using \(dq\(dq"
1196 macro is called without an argument.
1197 No function name is printed.
1198 .It Sy "empty head in list item"
1210 macro lacks the required argument.
1211 The item head is left empty.
1212 .It Sy "empty list item"
1224 An empty list item is shown.
1225 .It Sy "missing font type, using \efR"
1229 macro has no argument.
1230 It switches to the default font.
1231 .It Sy "unknown font type, using \efR"
1235 argument is invalid.
1236 The default font is used instead.
1237 .It Sy "nothing follows prefix"
1241 macro has no argument, or only one argument and no macro follows
1242 on the same input line.
1243 This defeats its purpose; in particular, spacing is not suppressed
1244 before the text or macros following on the next input line.
1245 .It Sy "empty reference block"
1249 macro is immediately followed by an
1251 macro on the next input line.
1252 Such an empty block does not produce any output.
1253 .It Sy "missing section argument"
1257 macro lacks its second, section number argument.
1258 The first argument, i.e. the name, is printed, but without subsequent
1260 .It Sy "missing -std argument, adding it"
1266 macro lacks the required
1273 even when it is not specified, but other implementations may not.
1274 .It Sy "missing option string, using \(dq\(dq"
1278 macro is invoked without any argument.
1279 An empty pair of square brackets is shown.
1280 .It Sy "missing resource identifier, using \(dq\(dq"
1284 macro is invoked without any argument.
1285 An empty pair of angle brackets is shown.
1286 .It Sy "missing eqn box, using \(dq\(dq"
1288 A diacritic mark or a binary operator is found,
1289 but there is nothing to the left of it.
1290 An empty box is inserted.
1292 .Ss "Warnings related to bad macro arguments"
1294 .It Sy "unterminated quoted argument"
1296 Macro arguments can be enclosed in double quote characters
1297 such that space characters and macro names contained in the quoted
1298 argument need not be escaped.
1299 The closing quote of the last argument of a macro can be omitted.
1300 However, omitting it is not recommended because it makes the code
1302 .It Sy "duplicate argument"
1308 macro has more than one
1315 All but the last instances of these arguments are ignored.
1316 .It Sy "skipping duplicate argument"
1320 macro has more than one
1325 All but the first of these arguments are ignored.
1326 .It Sy "skipping duplicate display type"
1330 macro has more than one type argument; the first one is used.
1331 .It Sy "skipping duplicate list type"
1335 macro has more than one type argument; the first one is used.
1336 .It Sy "skipping -width argument"
1350 .It Sy "wrong number of cells"
1353 list, the number of tabs or
1355 macros is less than the number expected from the list header line
1356 or exceeds the expected number by more than one.
1357 Missing cells remain empty, and all cells exceeding the number of
1358 columns are joined into one single cell.
1359 .It Sy "unknown AT&T UNIX version"
1363 macro has an invalid argument.
1364 It is used verbatim, with
1367 .It Sy "comma in function argument"
1373 macro contains a comma; it should probably be split into two arguments.
1374 .It Sy "parenthesis in function name"
1376 The first argument of an
1380 macro contains an opening or closing parenthesis; that's probably wrong,
1381 parentheses are added automatically.
1382 .It Sy "invalid content in Rs block"
1386 block contains plain text or non-% macros.
1387 The bogus content is left in the syntax tree.
1388 Formatting may be poor.
1389 .It Sy "invalid Boolean argument"
1393 macro has an argument other than
1397 The invalid argument is moved out of the macro, which leaves the macro
1398 empty, causing it to toggle the spacing mode.
1399 .It Sy "unknown font, skipping request"
1407 layout modifier has an unknown
1410 .It Sy "odd number of characters in request"
1414 request contains an odd number of characters.
1415 The last character is mapped to the blank character.
1417 .Ss "Warnings related to plain text"
1419 .It Sy "blank line in fill mode, using .sp"
1421 The meaning of blank input lines is only well-defined in non-fill mode:
1422 In fill mode, line breaks of text input lines are not supposed to be
1424 However, for compatibility with groff, blank lines in fill mode
1428 .It Sy "tab in filled text"
1430 The meaning of tab characters is only well-defined in non-fill mode:
1431 In fill mode, whitespace is not supposed to be significant
1432 on text input lines.
1433 As an implementation dependent choice, tab characters on text lines
1434 are passed through to the formatters in any case.
1435 Given that the text before the tab character will be filled,
1436 it is hard to predict which tab stop position the tab will advance to.
1437 .It Sy "whitespace at end of input line"
1438 .Pq mdoc , man , roff
1439 Whitespace at the end of input lines is almost never semantically
1440 significant \(em but in the odd case where it might be, it is
1441 extremely confusing when reviewing and maintaining documents.
1442 .It Sy "new sentence, new line"
1444 A new sentence starts in the middle of a text line.
1445 Start it on a new input line to help formatters produce correct spacing.
1446 .It Sy "bad comment style"
1448 Comment lines start with a dot, a backslash, and a double-quote character.
1451 utility treats the line as a comment line even without the backslash,
1452 but leaving out the backslash might not be portable.
1453 .It Sy "invalid escape sequence"
1455 An escape sequence has an invalid opening argument delimiter, lacks the
1456 closing argument delimiter, or the argument has too few characters.
1457 If the argument is incomplete,
1461 expand to an empty string,
1467 to the length of the incomplete argument.
1468 All other invalid escape sequences are ignored.
1469 .It Sy "undefined string, using \(dq\(dq"
1471 If a string is used without being defined before,
1472 its value is implicitly set to the empty string.
1473 However, defining strings explicitly before use
1474 keeps the code more readable.
1476 .Ss "Warnings related to tables"
1478 .It Sy "tbl line starts with span"
1480 The first cell in a table layout line is a horizontal span
1482 Data provided for this cell is ignored, and nothing is printed in the cell.
1483 .It Sy "tbl column starts with span"
1485 The first line of a table layout specification
1486 requests a vertical span
1488 Data provided for this cell is ignored, and nothing is printed in the cell.
1489 .It Sy "skipping vertical bar in tbl layout"
1491 A table layout specification contains more than two consecutive vertical bars.
1492 A double bar is printed, all additional bars are discarded.
1494 .Ss "Errors related to tables"
1496 .It Sy "non-alphabetic character in tbl options"
1498 The table options line contains a character other than a letter,
1499 blank, or comma where the beginning of an option name is expected.
1500 The character is ignored.
1501 .It Sy "skipping unknown tbl option"
1503 The table options line contains a string of letters that does not
1504 match any known option name.
1505 The word is ignored.
1506 .It Sy "missing tbl option argument"
1508 A table option that requires an argument is not followed by an
1509 opening parenthesis, or the opening parenthesis is immediately
1510 followed by a closing parenthesis.
1511 The option is ignored.
1512 .It Sy "wrong tbl option argument size"
1514 A table option argument contains an invalid number of characters.
1515 Both the option and the argument are ignored.
1516 .It Sy "empty tbl layout"
1518 A table layout specification is completely empty,
1519 specifying zero lines and zero columns.
1520 As a fallback, a single left-justified column is used.
1521 .It Sy "invalid character in tbl layout"
1523 A table layout specification contains a character that can neither
1524 be interpreted as a layout key character nor as a layout modifier,
1525 or a modifier precedes the first key.
1526 The invalid character is discarded.
1527 .It Sy "unmatched parenthesis in tbl layout"
1529 A table layout specification contains an opening parenthesis,
1530 but no matching closing parenthesis.
1531 The rest of the input line, starting from the parenthesis, has no effect.
1532 .It Sy "tbl without any data cells"
1534 A table does not contain any data cells.
1535 It will probably produce no output.
1536 .It Sy "ignoring data in spanned tbl cell"
1538 A table cell is marked as a horizontal span
1542 in the table layout, but it contains data.
1543 The data is ignored.
1544 .It Sy "ignoring extra tbl data cells"
1546 A data line contains more cells than the corresponding layout line.
1547 The data in the extra cells is ignored.
1548 .It Sy "data block open at end of tbl"
1550 A data block is opened with
1552 but never closed with a matching
1554 The remaining data lines of the table are all put into one cell,
1555 and any remaining cells stay empty.
1557 .Ss "Errors related to roff, mdoc, and man code"
1559 .It Sy "input stack limit exceeded, infinite loop?"
1561 Explicit recursion limits are implemented for the following features,
1562 in order to prevent infinite loops:
1565 expansion of nested escape sequences
1566 including expansion of strings and number registers,
1568 expansion of nested user-defined macros,
1574 When a limit is hit, the output is incorrect, typically losing
1575 some content, but the parser can continue.
1576 .It Sy "skipping bad character"
1577 .Pq mdoc , man , roff
1578 The input file contains a byte that is not a printable
1581 The message mentions the character number.
1582 The offending byte is replaced with a question mark
1584 Consider editing the input file to replace the byte with an ASCII
1585 transliteration of the intended character.
1586 .It Sy "skipping unknown macro"
1587 .Pq mdoc , man , roff
1588 The first identifier on a request or macro line is neither recognized as a
1590 request, nor as a user-defined macro, nor, respectively, as an
1595 It may be mistyped or unsupported.
1596 The request or macro is discarded including its arguments.
1597 .It Sy "skipping insecure request"
1599 An input file attempted to run a shell command
1600 or to read or write an external file.
1601 Such attempts are denied for security reasons.
1602 .It Sy "skipping item outside list"
1606 macro occurs outside any
1611 delimiter occurs outside any pile.
1612 It is discarded including its arguments.
1613 .It Sy "skipping column outside column list"
1617 macro occurs outside any
1620 It is discarded including its arguments.
1621 .It Sy "skipping end of block that is not open"
1622 .Pq mdoc , man , eqn , tbl , roff
1623 Various syntax elements can only be used to explicitly close blocks
1624 that have previously been opened.
1627 block closing macro, a
1634 right delimiter or closing brace, or the end of an equation, table, or
1636 conditional request is encountered but no matching block is open.
1637 The offending request or macro is discarded.
1638 .It Sy "fewer RS blocks open, skipping"
1642 macro is invoked with an argument, but less than the specified number of
1648 .It Sy "inserting missing end of block"
1652 macros as well as tables require explicit closing by dedicated macros.
1653 A block that doesn't support bad nesting
1654 ends before all of its children are properly closed.
1655 The open child nodes are closed implicitly.
1656 .It Sy "appending missing end of block"
1657 .Pq mdoc , man , eqn , tbl , roff
1658 At the end of the document, an explicit
1666 block, an equation, table, or
1668 conditional or ignore block is still open.
1669 The open block is closed implicitly.
1670 .It Sy "escaped character not allowed in a name"
1672 Macro, string and register identifiers consist of printable,
1673 non-whitespace ASCII characters.
1674 Escape sequences and characters and strings expressed in terms of them
1675 cannot form part of a name.
1676 The first argument of an
1684 request, or any argument of an
1686 request, or the name of a request or user defined macro being called,
1687 is terminated by an escape sequence.
1693 the request has no effect at all.
1700 what was parsed up to this point is used as the arguments to the request,
1701 and the rest of the input line is discarded including the escape sequence.
1702 When parsing for a request or a user-defined macro name to be called,
1703 only the escape sequence is discarded.
1704 The characters preceding it are used as the request or macro name,
1705 the characters following it are used as the arguments to the request or macro.
1706 .It Sy "NOT IMPLEMENTED: Bd -file"
1708 For security reasons, the
1710 macro does not support the
1713 By requesting the inclusion of a sensitive file, a malicious document
1714 might otherwise trick a privileged user into inadvertently displaying
1715 the file on the screen, revealing the file content to bystanders.
1716 The argument is ignored including the file name following it.
1717 .It Sy "skipping display without arguments"
1721 block macro does not have any arguments.
1722 The block is discarded, and the block content is displayed in
1723 whatever mode was active before the block.
1724 .It Sy "missing list type, using -item"
1728 macro fails to specify the list type.
1729 .It Sy "missing manual name, using \(dq\(dq"
1733 or any call in the NAME section, lacks the required argument.
1734 .It Sy "uname(3) system call failed, using UNKNOWN"
1738 macro is called without arguments, and the
1743 can be compiled with
1745 .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
1747 .It Sy "unknown standard specifier"
1751 macro has an unknown argument and is discarded.
1752 .It Sy "skipping request without numeric argument"
1761 statement has a non-numeric or negative argument or no argument at all.
1762 The invalid request or statement is ignored.
1763 .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
1765 For security reasons,
1769 file inclusion requests only with relative paths
1770 and only without ascending to any parent directory.
1771 By requesting the inclusion of a sensitive file, a malicious document
1772 might otherwise trick a privileged user into inadvertently displaying
1773 the file on the screen, revealing the file content to bystanders.
1775 only shows the path as it appears behind
1777 .It Sy ".so request failed"
1781 request requires reading an external file, but the file could not be
1784 only shows the path as it appears behind
1786 .It Sy "skipping all arguments"
1787 .Pq mdoc , man , eqn , roff
1803 macro in a list that don't support item heads, a
1822 block closing request is invoked with at least one argument.
1823 All arguments are ignored.
1824 .It Sy "skipping excess arguments"
1825 .Pq mdoc , man , roff
1826 A macro or request is invoked with too many arguments:
1827 .Bl -dash -offset 2n -width 2n -compact
1836 with more than one argument
1839 with another argument after
1845 with more than one argument or with a non-integer argument
1850 family with more than two arguments
1853 with more than three arguments
1856 with more than five arguments
1862 with invalid arguments
1864 The excess arguments are ignored.
1866 .Ss Unsupported features
1868 .It Sy "input too large"
1872 cannot handle input files larger than its arbitrary size limit
1873 of 2^31 bytes (2 Gigabytes).
1874 Since useful manuals are always small, this is not a problem in practice.
1875 Parsing is aborted as soon as the condition is detected.
1876 .It Sy "unsupported control character"
1878 An ASCII control character supported by other
1880 implementations but not by
1882 was found in an input file.
1883 It is replaced by a question mark.
1884 .It Sy "unsupported roff request"
1886 An input file contains a
1888 request supported by GNU troff or Heirloom troff but not by
1890 and it is likely that this will cause information loss
1891 or considerable misformatting.
1892 .It Sy "eqn delim option in tbl"
1894 The options line of a table defines equation delimiters.
1895 Any equation source code contained in the table will be printed unformatted.
1896 .It Sy "unsupported table layout modifier"
1898 A table layout specification contains an
1901 The modifier is discarded.
1902 .It Sy "ignoring macro in table"
1903 .Pq tbl , mdoc , man
1904 A table contains an invocation of an
1908 macro or of an undefined macro.
1909 The macro is ignored, and its arguments are handled
1910 as if they were a text line.
1924 utility first appeared in
1938 utility was written by
1939 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1940 and is maintained by
1941 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
git.ckatri.com / mandoc.git / blob