1 .\" $Id: mandoc.1,v 1.198 2017/06/11 17:16:51 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: June 11 2017 $
23 .Nd format manual pages
27 .Op Fl I Cm os Ns = Ns Ar name
39 manual pages for display.
47 text from stdin and produces
51 The options are as follows:
54 If the standard output is a terminal device and
58 to paginate the output, just like
62 Copy the formatted manual pages to the standard output without using
66 It can be specified to override
68 .It Fl I Cm os Ns = Ns Ar name
69 Override the default operating system
78 This can also be used to perform style checks according to the
79 conventions of one operating system while running on a different
84 Specify the input encoding.
92 If not specified, autodetection uses the first match in the following
96 If the first three bytes of the input file are the UTF-8 byte order
97 mark (BOM, 0xefbbbf), input is interpreted as
100 If the first or second line of the input file matches the
104 .D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*-
106 then input is interpreted according to
109 If the first non-ASCII byte in the file introduces a valid UTF-8
110 sequence, input is interpreted as
113 Otherwise, input is interpreted as
119 all input files are interpreted as
123 all input files are interpreted as
125 By default, the input language is automatically detected for each file:
126 if the the first macro is
132 parser is used; otherwise, the
135 With other arguments,
139 Comma-separated output options.
144 for available formats.
148 Specify the minimum message
150 to be reported on the standard error output and to affect the exit status.
175 to exit after parsing a file that causes warnings or errors of at least
177 No formatted output will be produced from that file.
182 are requested, they can be joined with a comma, for example
183 .Fl W Cm error , Ns Cm stop .
185 Read input from zero or more files.
186 If unspecified, reads from stdin.
187 If multiple files are specified,
189 will halt with the first failed parse.
194 are also supported and are documented in man(1).
201 also supports the options
208 are mutually exclusive and override each other.
212 utility accepts the following
214 arguments, which correspond to output modes:
215 .Bl -tag -width "-T markdown"
217 Produce 7-bit ASCII output.
221 Produce HTML5, CSS1, and MathML output.
225 Parse only: produce no output.
229 Encode output using the current locale.
244 .Sx Markdown Output .
250 Produce PostScript output.
252 .Sx PostScript Output .
254 Produce an indented parse tree.
256 .Sx Syntax tree output .
258 Encode output in the UTF\-8 multi-byte format.
263 If multiple input files are specified, these will be processed by the
264 corresponding filter in-order.
268 is rendered in standard 7-bit ASCII documented in
271 Font styles are applied by using back-spaced encoding such that an
275 .Sq _ Ns \e[bs] Ns c ,
278 is the back-space character number 8.
279 Emboldened characters are rendered as
280 .Sq c Ns \e[bs] Ns c .
282 The special characters documented in
284 are rendered best-effort in an ASCII equivalent.
286 Output width is limited to 78 visible columns unless literal input lines
291 arguments are accepted:
293 .It Cm indent Ns = Ns Ar indent
294 The left margin for normal text is set to
296 blank characters instead of the default of five for
300 Increasing this is not recommended; it may result in degraded formatting,
301 for example overfull lines or ugly line breaks.
302 .It Cm width Ns = Ns Ar width
303 The output width is set to
305 which will normalise to \(>=58.
310 conforms to HTML5 using optional self-closing tags.
311 Default styles use only CSS1.
312 Equations rendered from
318 file documents style-sheet classes available for customising output.
319 If a style-sheet is not specified with
322 defaults to simple output (via an embedded style-sheet)
323 readable in any graphical or text-based web
326 Special characters are rendered in decimal-encoded UTF\-8.
330 arguments are accepted:
333 Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body>
334 elements and only emit the subtree below the <body> element.
337 argument will be ignored.
338 This is useful when embedding manual content within existing documents.
339 .It Cm includes Ns = Ns Ar fmt
344 is used as a template for linked header files (usually via the
349 are replaced with the include filename.
350 The default is not to present a
352 .It Cm man Ns = Ns Ar fmt
356 .Ar ../html%S/%N.%S.html ,
357 is used as a template for linked manuals (usually via the
364 are replaced with the linked manual's name and section, respectively.
365 If no section is included, section 1 is assumed.
366 The default is not to
368 .It Cm style Ns = Ns Ar style.css
371 is used for an external style-sheet.
372 This must be a valid absolute or
376 Locale-depending output encoding is triggered with
380 This option is not available on all systems: systems without locale
381 support, or those whose internal representation is not natively UCS-4,
386 for font style specification and available command-line arguments.
388 Translate input format into
391 This is useful for distributing manual sources to legacy systems
398 is passed as input, it is translated into
400 If the input format is
402 the input is copied to the output, expanding any
406 The parser is also run, and as usual, the
410 are displayed before copying the input to the output.
417 .Lk http://daringfireball.net/projects/markdown/syntax.text\
418 "John Gruber's 2004 specification" .
419 The output also almost conforms to the
420 .Lk http://commonmark.org/ CommonMark
423 The character set used for the markdown output is ASCII.
424 Non-ASCII characters are encoded as HTML entities.
425 Since that is not possible in literal font contexts, because these
426 are rendered as code spans and code blocks in the markdown output,
427 non-ASCII characters are transliterated to ASCII approximations in
430 Markdown is a very weak markup language, so all semantic markup is
431 lost, and even part of the presentational markup may be lost.
432 Do not use this as an intermediate step in converting to HTML;
442 input languages are not supported by
446 PDF-1.1 output may be generated by
449 .Sx PostScript Output
452 arguments and defaults.
453 .Ss PostScript Output
456 Level-2 pages may be generated by
458 Output pages default to letter sized and are rendered in the Times font
460 Margins are calculated as 1/9 the page length and width.
463 Special characters are rendered as in
468 arguments are accepted:
470 .It Cm paper Ns = Ns Ar name
480 You may also manually specify dimensions as
482 width by height in millimetres.
483 If an unknown value is encountered,
490 to force a UTF\-8 locale.
493 for details and options.
494 .Ss Syntax tree output
497 to show a human readable representation of the syntax tree.
498 It is useful for debugging the source code of manual pages.
499 The exact format is subject to change, so don't write parsers for it.
501 The first paragraph shows meta data found in the
506 line, or the fallbacks used.
508 In the tree dump, each output line shows one syntax tree node.
509 Child nodes are indented with respect to their parent node.
514 For macro nodes, the macro name; for text and
517 There is a special format for
521 Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
526 An opening parenthesis if the node is an opening delimiter.
528 An asterisk if the node starts a new input line.
530 The input line number (starting at one).
534 The input column number (starting at one).
536 A closing parenthesis if the node is a closing delimiter.
538 A full stop if the node ends a sentence.
540 BROKEN if the node is a block broken by another block.
542 NOSRC if the node is not in the input file,
543 but automatically generated from macros.
545 NOPRT if the node is not supposed to generate output
546 for any output format.
552 argument is accepted:
555 Skip validation and show the unvalidated syntax tree.
556 This can help to find out whether a given behaviour is caused by
557 the parser or by the validator.
558 Meta data is not available in this case.
561 .Bl -tag -width MANPAGER
563 Any non-empty value of the environment variable
565 is used instead of the standard pagination program,
576 Specifies the pagination program to use when
579 If neither PAGER nor MANPAGER is defined,
592 utility exits with one of the following values, controlled by the message
598 .Bl -tag -width Ds -compact
600 No style suggestions, warnings or errors occurred, or those that
601 did were ignored because they were lower than the requested
604 At least one style suggestion occurred, but no warning or error, and
608 At least one warning occurred, but no error, and
614 At least one parsing error occurred,
615 but no unsupported feature was encountered, and
621 At least one unsupported feature was encountered, and
627 Invalid command line arguments were specified.
628 No input files have been read.
630 An operating system error occurred, for example exhaustion
631 of memory, file descriptors, or process table entries.
634 to exit at once, possibly in the middle of parsing or formatting a file.
642 To page manuals to the terminal:
644 .Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8
646 To produce HTML manuals with
650 .Dl $ mandoc \-T html -O style=mandoc.css mdoc.7 \*(Gt mdoc.7.html
652 To check over a large set of manuals:
654 .Dl $ mandoc \-T lint \(gafind /usr/src -name \e*\e.[1-9]\(ga
656 To produce a series of PostScript manuals for A4 paper:
658 .Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 \*(Gt manuals.ps
664 format, for use on systems lacking an
668 .Dl $ mandoc \-T man foo.mdoc \*(Gt foo.man
670 Messages displayed by
674 .D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args
676 Line and column numbers start at 1.
677 Both are omitted for messages referring to an input file as a whole.
678 Macro names and arguments are omitted where meaningless.
679 Fatal messages about invalid command line arguments
680 or operating system errors, for example when memory is exhausted,
687 Message levels have the following meanings:
688 .Bl -tag -width "warning"
690 An input file uses unsupported low-level
693 The output may be incomplete and/or misformatted,
694 so using GNU troff instead of
696 to process the file may be preferable.
698 An input file contains invalid syntax that cannot be safely interpreted.
699 By discarding part of the input or inserting missing tokens,
700 the parser is able to continue, and the error does not prevent
701 generation of formatted output, but typically, preparing that
702 output involves information loss, broken document structure
703 or unintended formatting, no matter whether
705 or GNU troff is used.
706 In many cases, the output of
708 and GNU troff is identical, but in some,
710 is more resilient than GNU troff with respect to malformed input.
712 Non-existent or unreadable input files are also reported on the
715 In that case, the parser cannot even be started and no output
716 is produced from those input files.
718 An input file uses obsolete, discouraged or non-portable syntax.
719 All the same, the meaning of the input is unambiguous and a correct
720 rendering can be produced.
721 Documents causing warnings may render poorly when using other
722 formatting tools instead of
725 An input file uses dubious or discouraged style.
726 This is not a complaint about the syntax, and probably neither
727 formatting nor portability are in danger.
728 While great care is taken to avoid false positives on the higher
731 level tries to reduce the probability that issues go unnoticed,
732 so it may occasionally issue bogus suggestions.
733 Please use your good judgement to decide whether any particular
735 suggestion really justifies a change to the input file.
744 levels except those about non-existent or unreadable input files
745 are hidden unless their level, or a lower level, is requested using a
751 As indicated below, some style checks are only performed if a
752 specific operating system name occurs in the arguments of the
756 command line option, or, if neither are present, in the return value
761 .It Sy "useless macro"
769 Simply delete it: it serves no useful purpose.
770 .It Sy "consider using OS macro"
772 A string was found in plain text or in a
774 macro that could be represented using
780 .It Sy "errnos out of order"
786 list are not in alphabetical order.
787 .It Sy "duplicate errno"
791 list contains two consecutive
793 entries describing the same
796 .It Sy "description line ends with a full stop"
798 Do not use punctuation at the end of an
801 .It Sy "no blank before trailing delimiter"
803 The last argument of a macro that supports trailing delimiter
804 arguments is longer than one byte and ends with a trailing delimiter.
805 Consider inserting a blank such that the delimiter becomes a separate
806 argument, thus moving it out of the scope of the macro.
807 .It Sy "function name without markup"
809 A word followed by an empty pair of parentheses occurs on a text line.
816 .Ss Warnings related to the document prologue
818 .It Sy "missing manual title, using UNTITLED"
822 macro has no arguments, or there is no
824 macro before the first non-prologue macro.
825 .It Sy "missing manual title, using \(dq\(dq"
829 macro, or it has no arguments.
830 .It Sy "lower case character in document title"
832 The title is still used as given in the
837 .It Sy "missing manual section, using \(dq\(dq"
843 macro lacks the mandatory section argument.
844 .It Sy "unknown manual section"
846 The section number in a
848 line is invalid, but still used.
849 .It Sy "missing date, using today's date"
851 The document was parsed as
857 macro has no arguments or only empty arguments;
858 or the document was parsed as
864 macro has less than three arguments or its third argument is empty.
865 .It Sy "cannot parse date, using it verbatim"
871 macro does not follow the conventional format.
872 .It Sy "missing Os macro, using \(dq\(dq"
874 The default or current system is not shown in this case.
875 .It Sy "duplicate prologue macro"
877 One of the prologue macros occurs more than once.
878 The last instance overrides all previous ones.
879 .It Sy "late prologue macro"
885 macro occurs after some non-prologue macro, but still takes effect.
886 .It Sy "skipping late title macro"
890 macro appears after the first non-prologue macro.
891 Traditional formatters cannot handle this because
892 they write the page header before parsing the document body.
893 Even though this technical restriction does not apply to
895 traditional semantics is preserved.
896 The late macro is discarded including its arguments.
897 .It Sy "prologue macros out of order"
899 The prologue macros are not given in the conventional order
903 All three macros are used even when given in another order.
905 .Ss Warnings regarding document structure
907 .It Sy ".so is fragile, better use ln(1)"
909 Including files only works when the parser program runs with the correct
910 current working directory.
911 .It Sy "no document body"
913 The document body contains neither text nor macros.
914 An empty document is shown, consisting only of a header and a footer line.
915 .It Sy "content before first section header"
917 Some macros or text precede the first
922 The offending macros and text are parsed and added to the top level
923 of the syntax tree, outside any section block.
924 .It Sy "first section is not NAME"
926 The argument of the first
934 .It Sy "NAME section without Nm before Nd"
936 The NAME section does not contain any
938 child macro before the first
941 .It Sy "NAME section without description"
943 The NAME section lacks the mandatory
946 .It Sy "description not at the end of NAME"
948 The NAME section does contain an
950 child macro, but other content follows it.
951 .It Sy "bad NAME section content"
953 The NAME section contains plain text or macros other than
957 .It Sy "missing comma before name"
959 The NAME section contains an
961 macro that is neither the first one nor preceded by a comma.
962 .It Sy "missing description line, using \(dq\(dq"
966 macro lacks the required argument.
967 The title line of the manual will end after the dash.
968 .It Sy "description line outside NAME section"
972 macro appears outside the NAME section.
973 The arguments are printed anyway and the following text is used for
975 but none of that behaviour is portable.
976 .It Sy "sections out of conventional order"
978 A standard section occurs after another section it usually precedes.
979 All section titles are used as given,
980 and the order of sections is not changed.
981 .It Sy "duplicate section title"
983 The same standard section title occurs more than once.
984 .It Sy "unexpected section"
986 A standard section header occurs in a section of the manual
987 where it normally isn't useful.
988 .It Sy "unusual Xr order"
990 In the SEE ALSO section, an
992 macro with a lower section number follows one with a higher number,
995 macros referring to the same section are out of alphabetical order.
996 .It Sy "unusual Xr punctuation"
998 In the SEE ALSO section, punctuation between two
1000 macros differs from a single comma, or there is trailing punctuation
1004 .It Sy "AUTHORS section without An macro"
1006 An AUTHORS sections contains no
1008 macros, or only empty ones.
1009 Probably, there are author names lacking markup.
1011 .Ss "Warnings related to macros and nesting"
1013 .It Sy "obsolete macro"
1017 manual for replacements.
1018 .It Sy "macro neither callable nor escaped"
1020 The name of a macro that is not callable appears on a macro line.
1021 It is printed verbatim.
1022 If the intention is to call it, move it to its own input line;
1023 otherwise, escape it by prepending
1025 .It Sy "skipping paragraph macro"
1028 documents, this happens
1031 at the beginning and end of sections and subsections
1033 right before non-compact lists and displays
1035 at the end of items in non-column, non-compact lists
1037 and for multiple consecutive paragraph macros.
1041 documents, it happens
1053 macros having neither head nor body arguments
1064 .It Sy "moving paragraph macro out of list"
1068 list contains a trailing paragraph macro.
1069 The paragraph macro is moved after the end of the list.
1070 .It Sy "skipping no-space macro"
1072 An input line begins with an
1075 The macro is ignored.
1076 .It Sy "blocks badly nested"
1078 If two blocks intersect, one should completely contain the other.
1079 Otherwise, rendered output is likely to look strange in any output
1080 format, and rendering in SGML-based output formats is likely to be
1081 outright wrong because such languages do not support badly nested
1083 Typical examples of badly nested blocks are
1084 .Qq Ic \&Ao \&Bo \&Ac \&Bc
1086 .Qq Ic \&Ao \&Bq \&Ac .
1094 .It Sy "nested displays are not portable"
1101 display occurs nested inside another
1106 but fails with most other implementations.
1107 .It Sy "moving content out of list"
1111 list block contains text or macros before the first
1114 The offending children are moved before the beginning of the list.
1115 .It Sy "fill mode already enabled, skipping"
1119 request occurs even though the document is still in fill mode,
1120 or already switched back to fill mode.
1122 .It Sy "fill mode already disabled, skipping"
1126 request occurs even though the document already switched to no-fill mode
1127 and did not switch back to fill mode yet.
1129 .It Sy "line scope broken"
1131 While parsing the next-line scope of the previous macro,
1132 another macro is found that prematurely terminates the previous one.
1133 The previous, interrupted macro is deleted from the parse tree.
1135 .Ss "Warnings related to missing arguments"
1137 .It Sy "skipping empty request"
1139 The macro name is missing from a macro definition request,
1142 control statement or operation keyword lacks its required argument.
1143 .It Sy "conditional request controls empty scope"
1145 A conditional request is only useful if any of the following
1146 follows it on the same logical input line:
1151 keyword to open a multi-line scope.
1153 A request or macro or some text, resulting in a single-line scope.
1155 The immediate end of the logical line without any intervening whitespace,
1156 resulting in next-line scope.
1158 Here, a conditional request is followed by trailing whitespace only,
1159 and there is no other content on its logical input line.
1160 Note that it doesn't matter whether the logical input line is split
1161 across multiple physical input lines using
1163 line continuation characters.
1164 This is one of the rare cases
1165 where trailing whitespace is syntactically significant.
1166 The conditional request controls a scope containing whitespace only,
1167 so it is unlikely to have a significant effect,
1168 except that it may control a following
1171 .It Sy "skipping empty macro"
1173 The indicated macro has no arguments and hence no effect.
1174 .It Sy "empty block"
1185 block contains nothing in its body and will produce no output.
1186 .It Sy "empty argument, using 0n"
1188 The required width is missing after
1195 .It Sy "missing display type, using -ragged"
1199 macro is invoked without the required display type.
1200 .It Sy "list type is not the first argument"
1204 macro, at least one other argument precedes the type argument.
1207 utility copes with any argument order, but some other
1209 implementations do not.
1210 .It Sy "missing -width in -tag list, using 8n"
1219 .It Sy "missing utility name, using \(dq\(dq"
1223 macro is called without an argument before
1225 has first been called with an argument.
1226 .It Sy "missing function name, using \(dq\(dq"
1230 macro is called without an argument.
1231 No function name is printed.
1232 .It Sy "empty head in list item"
1244 macro lacks the required argument.
1245 The item head is left empty.
1246 .It Sy "empty list item"
1258 An empty list item is shown.
1259 .It Sy "missing font type, using \efR"
1263 macro has no argument.
1264 It switches to the default font.
1265 .It Sy "unknown font type, using \efR"
1269 argument is invalid.
1270 The default font is used instead.
1271 .It Sy "nothing follows prefix"
1275 macro has no argument, or only one argument and no macro follows
1276 on the same input line.
1277 This defeats its purpose; in particular, spacing is not suppressed
1278 before the text or macros following on the next input line.
1279 .It Sy "empty reference block"
1283 macro is immediately followed by an
1285 macro on the next input line.
1286 Such an empty block does not produce any output.
1287 .It Sy "missing section argument"
1291 macro lacks its second, section number argument.
1292 The first argument, i.e. the name, is printed, but without subsequent
1294 .It Sy "missing -std argument, adding it"
1300 macro lacks the required
1307 even when it is not specified, but other implementations may not.
1308 .It Sy "missing option string, using \(dq\(dq"
1312 macro is invoked without any argument.
1313 An empty pair of square brackets is shown.
1314 .It Sy "missing resource identifier, using \(dq\(dq"
1318 macro is invoked without any argument.
1319 An empty pair of angle brackets is shown.
1320 .It Sy "missing eqn box, using \(dq\(dq"
1322 A diacritic mark or a binary operator is found,
1323 but there is nothing to the left of it.
1324 An empty box is inserted.
1326 .Ss "Warnings related to bad macro arguments"
1328 .It Sy "unterminated quoted argument"
1330 Macro arguments can be enclosed in double quote characters
1331 such that space characters and macro names contained in the quoted
1332 argument need not be escaped.
1333 The closing quote of the last argument of a macro can be omitted.
1334 However, omitting it is not recommended because it makes the code
1336 .It Sy "duplicate argument"
1342 macro has more than one
1349 All but the last instances of these arguments are ignored.
1350 .It Sy "skipping duplicate argument"
1354 macro has more than one
1359 All but the first of these arguments are ignored.
1360 .It Sy "skipping duplicate display type"
1364 macro has more than one type argument; the first one is used.
1365 .It Sy "skipping duplicate list type"
1369 macro has more than one type argument; the first one is used.
1370 .It Sy "skipping -width argument"
1384 .It Sy "wrong number of cells"
1387 list, the number of tabs or
1389 macros is less than the number expected from the list header line
1390 or exceeds the expected number by more than one.
1391 Missing cells remain empty, and all cells exceeding the number of
1392 columns are joined into one single cell.
1393 .It Sy "unknown AT&T UNIX version"
1397 macro has an invalid argument.
1398 It is used verbatim, with
1401 .It Sy "comma in function argument"
1407 macro contains a comma; it should probably be split into two arguments.
1408 .It Sy "parenthesis in function name"
1410 The first argument of an
1414 macro contains an opening or closing parenthesis; that's probably wrong,
1415 parentheses are added automatically.
1416 .It Sy "unknown library name"
1420 macro has an unknown name argument and will be rendered as
1421 .Qq library Dq Ar name .
1422 .It Sy "invalid content in Rs block"
1426 block contains plain text or non-% macros.
1427 The bogus content is left in the syntax tree.
1428 Formatting may be poor.
1429 .It Sy "invalid Boolean argument"
1433 macro has an argument other than
1437 The invalid argument is moved out of the macro, which leaves the macro
1438 empty, causing it to toggle the spacing mode.
1439 .It Sy "unknown font, skipping request"
1447 layout modifier has an unknown
1450 .It Sy "odd number of characters in request"
1454 request contains an odd number of characters.
1455 The last character is mapped to the blank character.
1457 .Ss "Warnings related to plain text"
1459 .It Sy "blank line in fill mode, using .sp"
1461 The meaning of blank input lines is only well-defined in non-fill mode:
1462 In fill mode, line breaks of text input lines are not supposed to be
1464 However, for compatibility with groff, blank lines in fill mode
1468 .It Sy "tab in filled text"
1470 The meaning of tab characters is only well-defined in non-fill mode:
1471 In fill mode, whitespace is not supposed to be significant
1472 on text input lines.
1473 As an implementation dependent choice, tab characters on text lines
1474 are passed through to the formatters in any case.
1475 Given that the text before the tab character will be filled,
1476 it is hard to predict which tab stop position the tab will advance to.
1477 .It Sy "whitespace at end of input line"
1478 .Pq mdoc , man , roff
1479 Whitespace at the end of input lines is almost never semantically
1480 significant \(em but in the odd case where it might be, it is
1481 extremely confusing when reviewing and maintaining documents.
1482 .It Sy "new sentence, new line"
1484 A new sentence starts in the middle of a text line.
1485 Start it on a new input line to help formatters produce correct spacing.
1486 .It Sy "bad comment style"
1488 Comment lines start with a dot, a backslash, and a double-quote character.
1491 utility treats the line as a comment line even without the backslash,
1492 but leaving out the backslash might not be portable.
1493 .It Sy "invalid escape sequence"
1495 An escape sequence has an invalid opening argument delimiter, lacks the
1496 closing argument delimiter, or the argument has too few characters.
1497 If the argument is incomplete,
1501 expand to an empty string,
1507 to the length of the incomplete argument.
1508 All other invalid escape sequences are ignored.
1509 .It Sy "undefined string, using \(dq\(dq"
1511 If a string is used without being defined before,
1512 its value is implicitly set to the empty string.
1513 However, defining strings explicitly before use
1514 keeps the code more readable.
1516 .Ss "Warnings related to tables"
1518 .It Sy "tbl line starts with span"
1520 The first cell in a table layout line is a horizontal span
1522 Data provided for this cell is ignored, and nothing is printed in the cell.
1523 .It Sy "tbl column starts with span"
1525 The first line of a table layout specification
1526 requests a vertical span
1528 Data provided for this cell is ignored, and nothing is printed in the cell.
1529 .It Sy "skipping vertical bar in tbl layout"
1531 A table layout specification contains more than two consecutive vertical bars.
1532 A double bar is printed, all additional bars are discarded.
1534 .Ss "Errors related to tables"
1536 .It Sy "non-alphabetic character in tbl options"
1538 The table options line contains a character other than a letter,
1539 blank, or comma where the beginning of an option name is expected.
1540 The character is ignored.
1541 .It Sy "skipping unknown tbl option"
1543 The table options line contains a string of letters that does not
1544 match any known option name.
1545 The word is ignored.
1546 .It Sy "missing tbl option argument"
1548 A table option that requires an argument is not followed by an
1549 opening parenthesis, or the opening parenthesis is immediately
1550 followed by a closing parenthesis.
1551 The option is ignored.
1552 .It Sy "wrong tbl option argument size"
1554 A table option argument contains an invalid number of characters.
1555 Both the option and the argument are ignored.
1556 .It Sy "empty tbl layout"
1558 A table layout specification is completely empty,
1559 specifying zero lines and zero columns.
1560 As a fallback, a single left-justified column is used.
1561 .It Sy "invalid character in tbl layout"
1563 A table layout specification contains a character that can neither
1564 be interpreted as a layout key character nor as a layout modifier,
1565 or a modifier precedes the first key.
1566 The invalid character is discarded.
1567 .It Sy "unmatched parenthesis in tbl layout"
1569 A table layout specification contains an opening parenthesis,
1570 but no matching closing parenthesis.
1571 The rest of the input line, starting from the parenthesis, has no effect.
1572 .It Sy "tbl without any data cells"
1574 A table does not contain any data cells.
1575 It will probably produce no output.
1576 .It Sy "ignoring data in spanned tbl cell"
1578 A table cell is marked as a horizontal span
1582 in the table layout, but it contains data.
1583 The data is ignored.
1584 .It Sy "ignoring extra tbl data cells"
1586 A data line contains more cells than the corresponding layout line.
1587 The data in the extra cells is ignored.
1588 .It Sy "data block open at end of tbl"
1590 A data block is opened with
1592 but never closed with a matching
1594 The remaining data lines of the table are all put into one cell,
1595 and any remaining cells stay empty.
1597 .Ss "Errors related to roff, mdoc, and man code"
1599 .It Sy "input stack limit exceeded, infinite loop?"
1601 Explicit recursion limits are implemented for the following features,
1602 in order to prevent infinite loops:
1605 expansion of nested escape sequences
1606 including expansion of strings and number registers,
1608 expansion of nested user-defined macros,
1614 When a limit is hit, the output is incorrect, typically losing
1615 some content, but the parser can continue.
1616 .It Sy "skipping bad character"
1617 .Pq mdoc , man , roff
1618 The input file contains a byte that is not a printable
1621 The message mentions the character number.
1622 The offending byte is replaced with a question mark
1624 Consider editing the input file to replace the byte with an ASCII
1625 transliteration of the intended character.
1626 .It Sy "skipping unknown macro"
1627 .Pq mdoc , man , roff
1628 The first identifier on a request or macro line is neither recognized as a
1630 request, nor as a user-defined macro, nor, respectively, as an
1635 It may be mistyped or unsupported.
1636 The request or macro is discarded including its arguments.
1637 .It Sy "skipping insecure request"
1639 An input file attempted to run a shell command
1640 or to read or write an external file.
1641 Such attempts are denied for security reasons.
1642 .It Sy "skipping item outside list"
1646 macro occurs outside any
1651 delimiter occurs outside any pile.
1652 It is discarded including its arguments.
1653 .It Sy "skipping column outside column list"
1657 macro occurs outside any
1660 It is discarded including its arguments.
1661 .It Sy "skipping end of block that is not open"
1662 .Pq mdoc , man , eqn , tbl , roff
1663 Various syntax elements can only be used to explicitly close blocks
1664 that have previously been opened.
1667 block closing macro, a
1674 right delimiter or closing brace, or the end of an equation, table, or
1676 conditional request is encountered but no matching block is open.
1677 The offending request or macro is discarded.
1678 .It Sy "fewer RS blocks open, skipping"
1682 macro is invoked with an argument, but less than the specified number of
1688 .It Sy "inserting missing end of block"
1692 macros as well as tables require explicit closing by dedicated macros.
1693 A block that doesn't support bad nesting
1694 ends before all of its children are properly closed.
1695 The open child nodes are closed implicitly.
1696 .It Sy "appending missing end of block"
1697 .Pq mdoc , man , eqn , tbl , roff
1698 At the end of the document, an explicit
1706 block, an equation, table, or
1708 conditional or ignore block is still open.
1709 The open block is closed implicitly.
1710 .It Sy "escaped character not allowed in a name"
1712 Macro, string and register identifiers consist of printable,
1713 non-whitespace ASCII characters.
1714 Escape sequences and characters and strings expressed in terms of them
1715 cannot form part of a name.
1716 The first argument of an
1724 request, or any argument of an
1726 request, or the name of a request or user defined macro being called,
1727 is terminated by an escape sequence.
1733 the request has no effect at all.
1740 what was parsed up to this point is used as the arguments to the request,
1741 and the rest of the input line is discarded including the escape sequence.
1742 When parsing for a request or a user-defined macro name to be called,
1743 only the escape sequence is discarded.
1744 The characters preceding it are used as the request or macro name,
1745 the characters following it are used as the arguments to the request or macro.
1746 .It Sy "NOT IMPLEMENTED: Bd -file"
1748 For security reasons, the
1750 macro does not support the
1753 By requesting the inclusion of a sensitive file, a malicious document
1754 might otherwise trick a privileged user into inadvertently displaying
1755 the file on the screen, revealing the file content to bystanders.
1756 The argument is ignored including the file name following it.
1757 .It Sy "skipping display without arguments"
1761 block macro does not have any arguments.
1762 The block is discarded, and the block content is displayed in
1763 whatever mode was active before the block.
1764 .It Sy "missing list type, using -item"
1768 macro fails to specify the list type.
1769 .It Sy "argument is not numeric, using 1"
1773 request is not a number.
1774 .It Sy "missing manual name, using \(dq\(dq"
1778 or any call in the NAME section, lacks the required argument.
1779 .It Sy "uname(3) system call failed, using UNKNOWN"
1783 macro is called without arguments, and the
1788 can be compiled with
1790 .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
1792 .It Sy "unknown standard specifier"
1796 macro has an unknown argument and is discarded.
1797 .It Sy "skipping request without numeric argument"
1806 statement has a non-numeric or negative argument or no argument at all.
1807 The invalid request or statement is ignored.
1808 .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
1810 For security reasons,
1814 file inclusion requests only with relative paths
1815 and only without ascending to any parent directory.
1816 By requesting the inclusion of a sensitive file, a malicious document
1817 might otherwise trick a privileged user into inadvertently displaying
1818 the file on the screen, revealing the file content to bystanders.
1820 only shows the path as it appears behind
1822 .It Sy ".so request failed"
1826 request requires reading an external file, but the file could not be
1829 only shows the path as it appears behind
1831 .It Sy "skipping all arguments"
1832 .Pq mdoc , man , eqn , roff
1848 macro in a list that don't support item heads, a
1867 block closing request is invoked with at least one argument.
1868 All arguments are ignored.
1869 .It Sy "skipping excess arguments"
1870 .Pq mdoc , man , roff
1871 A macro or request is invoked with too many arguments:
1872 .Bl -dash -offset 2n -width 2n -compact
1881 with more than one argument
1884 with another argument after
1890 with more than one argument or with a non-integer argument
1895 family with more than two arguments
1898 with more than three arguments
1901 with more than five arguments
1907 with invalid arguments
1909 The excess arguments are ignored.
1911 .Ss Unsupported features
1913 .It Sy "input too large"
1917 cannot handle input files larger than its arbitrary size limit
1918 of 2^31 bytes (2 Gigabytes).
1919 Since useful manuals are always small, this is not a problem in practice.
1920 Parsing is aborted as soon as the condition is detected.
1921 .It Sy "unsupported control character"
1923 An ASCII control character supported by other
1925 implementations but not by
1927 was found in an input file.
1928 It is replaced by a question mark.
1929 .It Sy "unsupported roff request"
1931 An input file contains a
1933 request supported by GNU troff or Heirloom troff but not by
1935 and it is likely that this will cause information loss
1936 or considerable misformatting.
1937 .It Sy "eqn delim option in tbl"
1939 The options line of a table defines equation delimiters.
1940 Any equation source code contained in the table will be printed unformatted.
1941 .It Sy "unsupported table layout modifier"
1943 A table layout specification contains an
1946 The modifier is discarded.
1947 .It Sy "ignoring macro in table"
1948 .Pq tbl , mdoc , man
1949 A table contains an invocation of an
1953 macro or of an undefined macro.
1954 The macro is ignored, and its arguments are handled
1955 as if they were a text line.
1969 utility first appeared in
1983 utility was written by
1984 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1985 and is maintained by
1986 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
git.ckatri.com / mandoc.git / blob