1 .\" $Id: mandoc.1,v 1.164 2015/11/05 17:47:51 schwarze Exp $
3 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2012, 2014, 2015 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: November 5 2015 $
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
78 .It Fl I Cm os Ns = Ns Ar name
79 Override the default operating system
89 Display only the SYNOPSIS lines.
93 Specify the input encoding.
101 If not specified, autodetection uses the first match:
102 .Bl -tag -width iso-8859-1
104 if the first three bytes of the input file
105 are the UTF-8 byte order mark (BOM, 0xefbbbf)
107 if the first or second line of the input file matches the
111 .D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*-
113 if the first non-ASCII byte in the file introduces a valid UTF-8 sequence
120 This overrides any earlier
128 Also reverts any earlier
133 .It Fl m Ns Ar format
137 for available formats.
141 Comma-separated output options.
146 for available formats.
150 Specify the minimum message
152 to be reported on the standard error output and to affect the exit status.
176 to exit after parsing a file that causes warnings or errors of at least
178 No formatted output will be produced from that file.
183 are requested, they can be joined with a comma, for example
184 .Fl W Cm error , Ns Cm stop .
186 Read input from zero or more files.
187 If unspecified, reads from stdin.
188 If multiple files are specified,
190 will halt with the first failed parse.
199 also supports the options
222 should only be used for legacy manuals.
226 which is also the default, determines encoding on-the-fly: if the first
233 parser is used; otherwise, the
238 files are specified with
240 each has its file-type determined this way.
241 If multiple files are
246 is specified, then this format is used exclusively.
250 utility accepts the following
252 arguments, which correspond to output modes:
253 .Bl -tag -width "-T locale"
255 Produce 7-bit ASCII output.
259 Produce HTML5, CSS1, and MathML output.
263 Parse only: produce no output.
267 Encode output using the current locale.
282 Produce PostScript output.
284 .Sx PostScript Output .
286 Produce an indented parse tree.
288 .Sx Syntax tree output .
290 Encode output in the UTF\-8 multi-byte format.
294 This is a synonym for
298 If multiple input files are specified, these will be processed by the
299 corresponding filter in-order.
303 is rendered in standard 7-bit ASCII documented in
306 Font styles are applied by using back-spaced encoding such that an
310 .Sq _ Ns \e[bs] Ns c ,
313 is the back-space character number 8.
314 Emboldened characters are rendered as
315 .Sq c Ns \e[bs] Ns c .
317 The special characters documented in
319 are rendered best-effort in an ASCII equivalent.
321 Output width is limited to 78 visible columns unless literal input lines
326 arguments are accepted:
328 .It Cm indent Ns = Ns Ar indent
329 The left margin for normal text is set to
331 blank characters instead of the default of five for
335 Increasing this is not recommended; it may result in degraded formatting,
336 for example overfull lines or ugly line breaks.
337 .It Cm width Ns = Ns Ar width
338 The output width is set to
340 which will normalise to \(>=58.
345 conforms to HTML5 using optional self-closing tags.
346 Default styles use only CSS1.
347 Equations rendered from
353 file documents style-sheet classes available for customising output.
354 If a style-sheet is not specified with
357 defaults to simple output (via an embedded style-sheet)
358 readable in any graphical or text-based web
361 Special characters are rendered in decimal-encoded UTF\-8.
365 arguments are accepted:
368 Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body>
369 elements and only emit the subtree below the <body> element.
372 argument will be ignored.
373 This is useful when embedding manual content within existing documents.
374 .It Cm includes Ns = Ns Ar fmt
379 is used as a template for linked header files (usually via the
384 are replaced with the include filename.
385 The default is not to present a
387 .It Cm man Ns = Ns Ar fmt
391 .Ar ../html%S/%N.%S.html ,
392 is used as a template for linked manuals (usually via the
399 are replaced with the linked manual's name and section, respectively.
400 If no section is included, section 1 is assumed.
401 The default is not to
403 .It Cm style Ns = Ns Ar style.css
406 is used for an external style-sheet.
407 This must be a valid absolute or
411 Locale-depending output encoding is triggered with
415 This option is not available on all systems: systems without locale
416 support, or those whose internal representation is not natively UCS-4,
421 for font style specification and available command-line arguments.
423 Translate input format into
426 This is useful for distributing manual sources to legacy systems
433 is passed as input, it is translated into
435 If the input format is
437 the input is copied to the output, expanding any
441 The parser is also run, and as usual, the
445 are displayed before copying the input to the output.
447 PDF-1.1 output may be generated by
450 .Sx PostScript Output
453 arguments and defaults.
454 .Ss PostScript Output
457 Level-2 pages may be generated by
459 Output pages default to letter sized and are rendered in the Times font
461 Margins are calculated as 1/9 the page length and width.
464 Special characters are rendered as in
469 arguments are accepted:
471 .It Cm paper Ns = Ns Ar name
481 You may also manually specify dimensions as
483 width by height in millimetres.
484 If an unknown value is encountered,
491 to force a UTF\-8 locale.
494 for details and options.
495 .Ss Syntax tree output
498 to show a human readable representation of the syntax tree.
499 It is useful for debugging the source code of manual pages.
500 The exact format is subject to change, so don't write parsers for it.
501 Each output line shows one syntax tree node.
502 Child nodes are indented with respect to their parent node.
507 For macro nodes, the macro name; for text and
510 There is a special format for
514 Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
519 An opening parenthesis if the node is an opening delimiter.
521 An asterisk if the node starts a new input line.
523 The input line number (starting at one).
527 The input column number (starting at one).
529 A closing parenthesis if the node is a closing delimiter.
531 A full stop if the node ends a sentence.
535 .Bl -tag -width MANPAGER
537 Any non-empty value of the environment variable
539 will be used instead of the standard pagination program,
542 Specifies the pagination program to use when
545 If neither PAGER nor MANPAGER is defined,
553 utility exits with one of the following values, controlled by the message
559 .Bl -tag -width Ds -compact
561 No warnings or errors occurred, or those that did were ignored because
562 they were lower than the requested
565 At least one warning occurred, but no error, and
569 At least one parsing error occurred,
570 but no unsupported feature was encountered, and
576 At least one unsupported feature was encountered, and
583 Invalid command line arguments were specified.
584 No input files have been read.
586 An operating system error occurred, for example exhaustion
587 of memory, file descriptors, or process table entries.
590 to exit at once, possibly in the middle of parsing or formatting a file.
598 To page manuals to the terminal:
600 .Dl $ mandoc \-W all,stop mandoc.1 2\*(Gt&1 | less
601 .Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
603 To produce HTML manuals with
607 .Dl $ mandoc \-T html -O style=mandoc.css mdoc.7 \*(Gt mdoc.7.html
609 To check over a large set of manuals:
611 .Dl $ mandoc \-T lint \(gafind /usr/src -name \e*\e.[1-9]\(ga
613 To produce a series of PostScript manuals for A4 paper:
615 .Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 \*(Gt manuals.ps
621 format, for use on systems lacking an
625 .Dl $ mandoc \-T man foo.mdoc \*(Gt foo.man
627 Messages displayed by
631 .D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args
633 Line and column numbers start at 1.
634 Both are omitted for messages referring to an input file as a whole.
635 Macro names and arguments are omitted where meaningless.
636 Fatal messages about invalid command line arguments
637 or operating system errors, for example when memory is exhausted,
644 Message levels have the following meanings:
645 .Bl -tag -width "warning"
647 An input file uses unsupported low-level
650 The output may be incomplete and/or misformatted,
651 so using GNU troff instead of
653 to process the file may be preferable.
655 An input file contains invalid syntax that cannot be safely interpreted.
656 By discarding part of the input or inserting missing tokens,
657 the parser is able to continue, and the error does not prevent
658 generation of formatted output, but typically, preparing that
659 output involves information loss, broken document structure
660 or unintended formatting, no matter whether
662 or GNU troff is used.
663 In many cases, the output of
665 and GNU troff is identical, but in some,
667 is more resilient than GNU troff with respect to malformed input.
669 Non-existent or unreadable input files are also reported on the
672 In that case, the parser cannot even be started and no output
673 is produced from those input files.
675 An input file uses obsolete, discouraged or non-portable syntax.
676 All the same, the meaning of the input is unambiguous and a correct
677 rendering can be produced.
678 Documents causing warnings may render poorly when using other
679 formatting tools instead of
688 levels except those about non-existent or unreadable input files
689 are hidden unless their level, or a lower level, is requested using a
694 .Ss Warnings related to the document prologue
696 .It Sy "missing manual title, using UNTITLED"
700 macro has no arguments, or there is no
702 macro before the first non-prologue macro.
703 .It Sy "missing manual title, using \(dq\(dq"
707 macro, or it has no arguments.
708 .It Sy "lower case character in document title"
710 The title is still used as given in the
715 .It Sy "missing manual section, using \(dq\(dq"
721 macro lacks the mandatory section argument.
722 .It Sy "unknown manual section"
724 The section number in a
726 line is invalid, but still used.
727 .It Sy "missing date, using today's date"
729 The document was parsed as
735 macro has no arguments or only empty arguments;
736 or the document was parsed as
742 macro has less than three arguments or its third argument is empty.
743 .It Sy "cannot parse date, using it verbatim"
749 macro does not follow the conventional format.
750 .It Sy "missing Os macro, using \(dq\(dq"
752 The default or current system is not shown in this case.
753 .It Sy "duplicate prologue macro"
755 One of the prologue macros occurs more than once.
756 The last instance overrides all previous ones.
757 .It Sy "late prologue macro"
763 macro occurs after some non-prologue macro, but still takes effect.
764 .It Sy "skipping late title macro"
768 macro appears after the first non-prologue macro.
769 Traditional formatters cannot handle this because
770 they write the page header before parsing the document body.
771 Even though this technical restriction does not apply to
773 traditional semantics is preserved.
774 The late macro is discarded including its arguments.
775 .It Sy "prologue macros out of order"
777 The prologue macros are not given in the conventional order
781 All three macros are used even when given in another order.
783 .Ss Warnings regarding document structure
785 .It Sy ".so is fragile, better use ln(1)"
787 Including files only works when the parser program runs with the correct
788 current working directory.
789 .It Sy "no document body"
791 The document body contains neither text nor macros.
792 An empty document is shown, consisting only of a header and a footer line.
793 .It Sy "content before first section header"
795 Some macros or text precede the first
800 The offending macros and text are parsed and added to the top level
801 of the syntax tree, outside any section block.
802 .It Sy "first section is not NAME"
804 The argument of the first
812 .It Sy "NAME section without name"
814 The NAME section does not contain any
817 .It Sy "NAME section without description"
819 The NAME section lacks the mandatory
822 .It Sy "description not at the end of NAME"
824 The NAME section does contain an
826 child macro, but other content follows it.
827 .It Sy "bad NAME section content"
829 The NAME section contains plain text or macros other than
833 .It Sy "missing description line, using \(dq\(dq"
837 macro lacks the required argument.
838 The title line of the manual will end after the dash.
839 .It Sy "sections out of conventional order"
841 A standard section occurs after another section it usually precedes.
842 All section titles are used as given,
843 and the order of sections is not changed.
844 .It Sy "duplicate section title"
846 The same standard section title occurs more than once.
847 .It Sy "unexpected section"
849 A standard section header occurs in a section of the manual
850 where it normally isn't useful.
851 .It Sy "unusual Xr order"
853 In the SEE ALSO section, an
855 macro with a lower section number follows one with a higher number,
858 macros referring to the same section are out of alphabetical order.
859 .It Sy "unusual Xr punctuation"
861 In the SEE ALSO section, punctuation between two
863 macros differs from a single comma, or there is trailing punctuation
867 .It Sy "AUTHORS section without An macro"
869 An AUTHORS sections contains no
871 macros, or only empty ones.
872 Probably, there are author names lacking markup.
874 .Ss "Warnings related to macros and nesting"
876 .It Sy "obsolete macro"
880 manual for replacements.
881 .It Sy "macro neither callable nor escaped"
883 The name of a macro that is not callable appears on a macro line.
884 It is printed verbatim.
885 If the intention is to call it, move it to its own input line;
886 otherwise, escape it by prepending
888 .It Sy "skipping paragraph macro"
891 documents, this happens
894 at the beginning and end of sections and subsections
896 right before non-compact lists and displays
898 at the end of items in non-column, non-compact lists
900 and for multiple consecutive paragraph macros.
904 documents, it happens
916 macros having neither head nor body arguments
927 .It Sy "moving paragraph macro out of list"
931 list contains a trailing paragraph macro.
932 The paragraph macro is moved after the end of the list.
933 .It Sy "skipping no-space macro"
935 An input line begins with an
938 The macro is ignored.
939 .It Sy "blocks badly nested"
941 If two blocks intersect, one should completely contain the other.
942 Otherwise, rendered output is likely to look strange in any output
943 format, and rendering in SGML-based output formats is likely to be
944 outright wrong because such languages do not support badly nested
946 Typical examples of badly nested blocks are
947 .Qq Ic \&Ao \&Bo \&Ac \&Bc
949 .Qq Ic \&Ao \&Bq \&Ac .
957 .It Sy "nested displays are not portable"
964 display occurs nested inside another
969 but fails with most other implementations.
970 .It Sy "moving content out of list"
974 list block contains text or macros before the first
977 The offending children are moved before the beginning of the list.
978 .It Sy "fill mode already enabled, skipping"
982 request occurs even though the document is still in fill mode,
983 or already switched back to fill mode.
985 .It Sy "fill mode already disabled, skipping"
989 request occurs even though the document already switched to no-fill mode
990 and did not switch back to fill mode yet.
992 .It Sy "line scope broken"
994 While parsing the next-line scope of the previous macro,
995 another macro is found that prematurely terminates the previous one.
996 The previous, interrupted macro is deleted from the parse tree.
998 .Ss "Warnings related to missing arguments"
1000 .It Sy "skipping empty request"
1002 The macro name is missing from a macro definition request,
1005 control statement or operation keyword lacks its required argument.
1006 .It Sy "conditional request controls empty scope"
1008 A conditional request is only useful if any of the following
1009 follows it on the same logical input line:
1014 keyword to open a multi-line scope.
1016 A request or macro or some text, resulting in a single-line scope.
1018 The immediate end of the logical line without any intervening whitespace,
1019 resulting in next-line scope.
1021 Here, a conditional request is followed by trailing whitespace only,
1022 and there is no other content on its logical input line.
1023 Note that it doesn't matter whether the logical input line is split
1024 across multiple physical input lines using
1026 line continuation characters.
1027 This is one of the rare cases
1028 where trailing whitespace is syntactically significant.
1029 The conditional request controls a scope containing whitespace only,
1030 so it is unlikely to have a significant effect,
1031 except that it may control a following
1034 .It Sy "skipping empty macro"
1036 The indicated macro has no arguments and hence no effect.
1037 .It Sy "empty block"
1048 block contains nothing in its body and will produce no output.
1049 .It Sy "empty argument, using 0n"
1051 The required width is missing after
1058 .It Sy "missing display type, using -ragged"
1062 macro is invoked without the required display type.
1063 .It Sy "list type is not the first argument"
1067 macro, at least one other argument precedes the type argument.
1070 utility copes with any argument order, but some other
1072 implementations do not.
1073 .It Sy "missing -width in -tag list, using 8n"
1082 .It Sy "missing utility name, using \(dq\(dq"
1086 macro is called without an argument before
1088 has first been called with an argument.
1089 .It Sy "missing function name, using \(dq\(dq"
1093 macro is called without an argument.
1094 No function name is printed.
1095 .It Sy "empty head in list item"
1107 macro lacks the required argument.
1108 The item head is left empty.
1109 .It Sy "empty list item"
1121 An empty list item is shown.
1122 .It Sy "missing font type, using \efR"
1126 macro has no argument.
1127 It switches to the default font.
1128 .It Sy "unknown font type, using \efR"
1132 argument is invalid.
1133 The default font is used instead.
1134 .It Sy "nothing follows prefix"
1138 macro has no argument, or only one argument and no macro follows
1139 on the same input line.
1140 This defeats its purpose; in particular, spacing is not suppressed
1141 before the text or macros following on the next input line.
1142 .It Sy "empty reference block"
1146 macro is immediately followed by an
1148 macro on the next input line.
1149 Such an empty block does not produce any output.
1150 .It Sy "missing -std argument, adding it"
1156 macro lacks the required
1163 even when it is not specified, but other implementations may not.
1164 .It Sy "missing option string, using \(dq\(dq"
1168 macro is invoked without any argument.
1169 An empty pair of square brackets is shown.
1170 .It Sy "missing resource identifier, using \(dq\(dq"
1174 macro is invoked without any argument.
1175 An empty pair of angle brackets is shown.
1176 .It Sy "missing eqn box, using \(dq\(dq"
1178 A diacritic mark or a binary operator is found,
1179 but there is nothing to the left of it.
1180 An empty box is inserted.
1182 .Ss "Warnings related to bad macro arguments"
1184 .It Sy "unterminated quoted argument"
1186 Macro arguments can be enclosed in double quote characters
1187 such that space characters and macro names contained in the quoted
1188 argument need not be escaped.
1189 The closing quote of the last argument of a macro can be omitted.
1190 However, omitting it is not recommended because it makes the code
1192 .It Sy "duplicate argument"
1198 macro has more than one
1205 All but the last instances of these arguments are ignored.
1206 .It Sy "skipping duplicate argument"
1210 macro has more than one
1215 All but the first of these arguments are ignored.
1216 .It Sy "skipping duplicate display type"
1220 macro has more than one type argument; the first one is used.
1221 .It Sy "skipping duplicate list type"
1225 macro has more than one type argument; the first one is used.
1226 .It Sy "skipping -width argument"
1240 .It Sy "wrong number of cells"
1243 list, the number of tabs or
1245 macros is less than the number expected from the list header line
1246 or exceeds the expected number by more than one.
1247 Missing cells remain empty, and all cells exceeding the number of
1248 columns are joined into one single cell.
1249 .It Sy "unknown AT&T UNIX version"
1253 macro has an invalid argument.
1254 It is used verbatim, with
1257 .It Sy "comma in function argument"
1263 macro contains a comma; it should probably be split into two arguments.
1264 .It Sy "parenthesis in function name"
1266 The first argument of an
1270 macro contains an opening or closing parenthesis; that's probably wrong,
1271 parentheses are added automatically.
1272 .It Sy "invalid content in Rs block"
1276 block contains plain text or non-% macros.
1277 The bogus content is left in the syntax tree.
1278 Formatting may be poor.
1279 .It Sy "invalid Boolean argument"
1283 macro has an argument other than
1287 The invalid argument is moved out of the macro, which leaves the macro
1288 empty, causing it to toggle the spacing mode.
1289 .It Sy "unknown font, skipping request"
1297 layout modifier has an unknown
1300 .It Sy "odd number of characters in request"
1304 request contains an odd number of characters.
1305 The last character is mapped to the blank character.
1307 .Ss "Warnings related to plain text"
1309 .It Sy "blank line in fill mode, using .sp"
1311 The meaning of blank input lines is only well-defined in non-fill mode:
1312 In fill mode, line breaks of text input lines are not supposed to be
1314 However, for compatibility with groff, blank lines in fill mode
1318 .It Sy "tab in filled text"
1320 The meaning of tab characters is only well-defined in non-fill mode:
1321 In fill mode, whitespace is not supposed to be significant
1322 on text input lines.
1323 As an implementation dependent choice, tab characters on text lines
1324 are passed through to the formatters in any case.
1325 Given that the text before the tab character will be filled,
1326 it is hard to predict which tab stop position the tab will advance to.
1327 .It Sy "whitespace at end of input line"
1328 .Pq mdoc , man , roff
1329 Whitespace at the end of input lines is almost never semantically
1330 significant \(em but in the odd case where it might be, it is
1331 extremely confusing when reviewing and maintaining documents.
1332 .It Sy "bad comment style"
1334 Comment lines start with a dot, a backslash, and a double-quote character.
1337 utility treats the line as a comment line even without the backslash,
1338 but leaving out the backslash might not be portable.
1339 .It Sy "invalid escape sequence"
1341 An escape sequence has an invalid opening argument delimiter, lacks the
1342 closing argument delimiter, or the argument has too few characters.
1343 If the argument is incomplete,
1347 expand to an empty string,
1353 to the length of the incomplete argument.
1354 All other invalid escape sequences are ignored.
1355 .It Sy "undefined string, using \(dq\(dq"
1357 If a string is used without being defined before,
1358 its value is implicitly set to the empty string.
1359 However, defining strings explicitly before use
1360 keeps the code more readable.
1362 .Ss "Warnings related to tables"
1364 .It Sy "tbl line starts with span"
1366 The first cell in a table layout line is a horizontal span
1368 Data provided for this cell is ignored, and nothing is printed in the cell.
1369 .It Sy "tbl column starts with span"
1371 The first line of a table layout specification
1372 requests a vertical span
1374 Data provided for this cell is ignored, and nothing is printed in the cell.
1375 .It Sy "skipping vertical bar in tbl layout"
1377 A table layout specification contains more than two consecutive vertical bars.
1378 A double bar is printed, all additional bars are discarded.
1380 .Ss "Errors related to tables"
1382 .It Sy "non-alphabetic character in tbl options"
1384 The table options line contains a character other than a letter,
1385 blank, or comma where the beginning of an option name is expected.
1386 The character is ignored.
1387 .It Sy "skipping unknown tbl option"
1389 The table options line contains a string of letters that does not
1390 match any known option name.
1391 The word is ignored.
1392 .It Sy "missing tbl option argument"
1394 A table option that requires an argument is not followed by an
1395 opening parenthesis, or the opening parenthesis is immediately
1396 followed by a closing parenthesis.
1397 The option is ignored.
1398 .It Sy "wrong tbl option argument size"
1400 A table option argument contains an invalid number of characters.
1401 Both the option and the argument are ignored.
1402 .It Sy "empty tbl layout"
1404 A table layout specification is completely empty,
1405 specifying zero lines and zero columns.
1406 As a fallback, a single left-justified column is used.
1407 .It Sy "invalid character in tbl layout"
1409 A table layout specification contains a character that can neither
1410 be interpreted as a layout key character nor as a layout modifier,
1411 or a modifier precedes the first key.
1412 The invalid character is discarded.
1413 .It Sy "unmatched parenthesis in tbl layout"
1415 A table layout specification contains an opening parenthesis,
1416 but no matching closing parenthesis.
1417 The rest of the input line, starting from the parenthesis, has no effect.
1418 .It Sy "tbl without any data cells"
1420 A table does not contain any data cells.
1421 It will probably produce no output.
1422 .It Sy "ignoring data in spanned tbl cell"
1424 A table cell is marked as a horizontal span
1428 in the table layout, but it contains data.
1429 The data is ignored.
1430 .It Sy "ignoring extra tbl data cells"
1432 A data line contains more cells than the corresponding layout line.
1433 The data in the extra cells is ignored.
1434 .It Sy "data block open at end of tbl"
1436 A data block is opened with
1438 but never closed with a matching
1440 The remaining data lines of the table are all put into one cell,
1441 and any remaining cells stay empty.
1443 .Ss "Errors related to roff, mdoc, and man code"
1445 .It Sy "input stack limit exceeded, infinite loop?"
1447 Explicit recursion limits are implemented for the following features,
1448 in order to prevent infinite loops:
1451 expansion of nested escape sequences
1452 including expansion of strings and number registers,
1454 expansion of nested user-defined macros,
1460 When a limit is hit, the output is incorrect, typically losing
1461 some content, but the parser can continue.
1462 .It Sy "skipping bad character"
1463 .Pq mdoc , man , roff
1464 The input file contains a byte that is not a printable
1467 The message mentions the character number.
1468 The offending byte is replaced with a question mark
1470 Consider editing the input file to replace the byte with an ASCII
1471 transliteration of the intended character.
1472 .It Sy "skipping unknown macro"
1473 .Pq mdoc , man , roff
1474 The first identifier on a request or macro line is neither recognized as a
1476 request, nor as a user-defined macro, nor, respectively, as an
1481 It may be mistyped or unsupported.
1482 The request or macro is discarded including its arguments.
1483 .It Sy "skipping insecure request"
1485 An input file attempted to run a shell command
1486 or to read or write an external file.
1487 Such attempts are denied for security reasons.
1488 .It Sy "skipping item outside list"
1492 macro occurs outside any
1497 delimiter occurs outside any pile.
1498 It is discarded including its arguments.
1499 .It Sy "skipping column outside column list"
1503 macro occurs outside any
1506 It is discarded including its arguments.
1507 .It Sy "skipping end of block that is not open"
1508 .Pq mdoc , man , eqn , tbl , roff
1509 Various syntax elements can only be used to explicitly close blocks
1510 that have previously been opened.
1513 block closing macro, a
1520 right delimiter or closing brace, or the end of an equation, table, or
1522 conditional request is encountered but no matching block is open.
1523 The offending request or macro is discarded.
1524 .It Sy "fewer RS blocks open, skipping"
1528 macro is invoked with an argument, but less than the specified number of
1534 .It Sy "inserting missing end of block"
1538 macros as well as tables require explicit closing by dedicated macros.
1539 A block that doesn't support bad nesting
1540 ends before all of its children are properly closed.
1541 The open child nodes are closed implicitly.
1542 .It Sy "appending missing end of block"
1543 .Pq mdoc , man , eqn , tbl , roff
1544 At the end of the document, an explicit
1552 block, an equation, table, or
1554 conditional or ignore block is still open.
1555 The open block is closed implicitly.
1556 .It Sy "escaped character not allowed in a name"
1558 Macro, string and register identifiers consist of printable,
1559 non-whitespace ASCII characters.
1560 Escape sequences and characters and strings expressed in terms of them
1561 cannot form part of a name.
1562 The first argument of an
1570 request, or any argument of an
1572 request, or the name of a request or user defined macro being called,
1573 is terminated by an escape sequence.
1579 the request has no effect at all.
1586 what was parsed up to this point is used as the arguments to the request,
1587 and the rest of the input line is discarded including the escape sequence.
1588 When parsing for a request or a user-defined macro name to be called,
1589 only the escape sequence is discarded.
1590 The characters preceding it are used as the request or macro name,
1591 the characters following it are used as the arguments to the request or macro.
1592 .It Sy "NOT IMPLEMENTED: Bd -file"
1594 For security reasons, the
1596 macro does not support the
1599 By requesting the inclusion of a sensitive file, a malicious document
1600 might otherwise trick a privileged user into inadvertently displaying
1601 the file on the screen, revealing the file content to bystanders.
1602 The argument is ignored including the file name following it.
1603 .It Sy "skipping display without arguments"
1607 block macro does not have any arguments.
1608 The block is discarded, and the block content is displayed in
1609 whatever mode was active before the block.
1610 .It Sy "missing list type, using -item"
1614 macro fails to specify the list type.
1615 .It Sy "missing manual name, using \(dq\(dq"
1619 lacks the required argument.
1620 .It Sy "uname(3) system call failed, using UNKNOWN"
1624 macro is called without arguments, and the
1629 can be compiled with
1631 .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
1633 .It Sy "unknown standard specifier"
1637 macro has an unknown argument and is discarded.
1638 .It Sy "skipping request without numeric argument"
1647 statement has a non-numeric or negative argument or no argument at all.
1648 The invalid request or statement is ignored.
1649 .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
1651 For security reasons,
1655 file inclusion requests only with relative paths
1656 and only without ascending to any parent directory.
1657 By requesting the inclusion of a sensitive file, a malicious document
1658 might otherwise trick a privileged user into inadvertently displaying
1659 the file on the screen, revealing the file content to bystanders.
1661 only shows the path as it appears behind
1663 .It Sy ".so request failed"
1667 request requires reading an external file, but the file could not be
1670 only shows the path as it appears behind
1672 .It Sy "skipping all arguments"
1673 .Pq mdoc , man , eqn , roff
1689 macro in a list that don't support item heads, a
1708 block closing request is invoked with at least one argument.
1709 All arguments are ignored.
1710 .It Sy "skipping excess arguments"
1711 .Pq mdoc , man , roff
1712 A macro or request is invoked with too many arguments:
1713 .Bl -dash -offset 2n -width 2n -compact
1722 with more than one argument
1725 with another argument after
1731 with more than one argument or with a non-integer argument
1736 family with more than two arguments
1739 with more than three arguments
1742 with more than five arguments
1748 with invalid arguments
1750 The excess arguments are ignored.
1752 .Ss Unsupported features
1754 .It Sy "input too large"
1758 cannot handle input files larger than its arbitrary size limit
1759 of 2^31 bytes (2 Gigabytes).
1760 Since useful manuals are always small, this is not a problem in practice.
1761 Parsing is aborted as soon as the condition is detected.
1762 .It Sy "unsupported control character"
1764 An ASCII control character supported by other
1766 implementations but not by
1768 was found in an input file.
1769 It is replaced by a question mark.
1770 .It Sy "unsupported roff request"
1772 An input file contains a
1774 request supported by GNU troff or Heirloom troff but not by
1776 and it is likely that this will cause information loss
1777 or considerable misformatting.
1778 .It Sy "eqn delim option in tbl"
1780 The options line of a table defines equation delimiters.
1781 Any equation source code contained in the table will be printed unformatted.
1782 .It Sy "unsupported table layout modifier"
1784 A table layout specification contains an
1787 The modifier is discarded.
1788 .It Sy "ignoring macro in table"
1789 .Pq tbl , mdoc , man
1790 A table contains an invocation of an
1794 macro or of an undefined macro.
1795 The macro is ignored, and its arguments are handled
1796 as if they were a text line.
1811 utility was written by
1812 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1813 and is maintained by
1814 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
1818 the maximum size of an element attribute is determined by
1820 which is usually 1024 bytes.
1821 Be aware of this when setting long link
1823 .Fl O Cm style Ns = Ns Ar really/long/link .
projects / FreeBSD / FreeBSD.git / blob