1 .\" $Id: mandoc.1,v 1.222 2018/03/16 15:05:44 schwarze Exp $
3 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2012, 2014-2018 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 16 2018 $
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
79 Specify the input encoding.
87 If not specified, autodetection uses the first match in the following
91 If the first three bytes of the input file are the UTF-8 byte order
92 mark (BOM, 0xefbbbf), input is interpreted as
95 If the first or second line of the input file matches the
99 .D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*-
101 then input is interpreted according to
104 If the first non-ASCII byte in the file introduces a valid UTF-8
105 sequence, input is interpreted as
108 Otherwise, input is interpreted as
114 all input files are interpreted as
118 all input files are interpreted as
120 By default, the input language is automatically detected for each file:
121 if the first macro is
127 parser is used; otherwise, the
130 With other arguments,
134 Comma-separated output options.
139 for available formats.
143 Specify the minimum message
145 to be reported on the standard error output and to affect the exit status.
157 level automatically derives the operating system from the contents of the
161 command line option, or from the
170 that bypass autodetection and request validation of base system
171 conventions for a particular operating system.
189 to exit after parsing a file that causes warnings or errors of at least
191 No formatted output will be produced from that file.
196 are requested, they can be joined with a comma, for example
197 .Fl W Cm error , Ns Cm stop .
199 Read input from zero or more files.
200 If unspecified, reads from stdin.
201 If multiple files are specified,
203 will halt with the first failed parse.
208 are also supported and are documented in man(1).
215 also supports the options
222 are mutually exclusive and override each other.
226 utility accepts the following
228 arguments, which correspond to output modes:
229 .Bl -tag -width "-T markdown"
231 Produce 7-bit ASCII output.
235 Produce HTML5, CSS1, and MathML output.
239 Parse only: produce no output.
242 and redirects parser messages, which usually appear
243 on standard error output, to standard output.
245 Encode output using the current locale.
260 .Sx Markdown Output .
266 Produce PostScript output.
268 .Sx PostScript Output .
270 Produce an indented parse tree.
272 .Sx Syntax tree output .
274 Encode output in the UTF\-8 multi-byte format.
279 If multiple input files are specified, these will be processed by the
280 corresponding filter in-order.
284 is rendered in standard 7-bit ASCII documented in
287 Font styles are applied by using back-spaced encoding such that an
291 .Sq _ Ns \e[bs] Ns c ,
294 is the back-space character number 8.
295 Emboldened characters are rendered as
296 .Sq c Ns \e[bs] Ns c .
298 The special characters documented in
300 are rendered best-effort in an ASCII equivalent.
302 Output width is limited to 78 visible columns unless literal input lines
307 arguments are accepted:
309 .It Cm indent Ns = Ns Ar indent
310 The left margin for normal text is set to
312 blank characters instead of the default of five for
316 Increasing this is not recommended; it may result in degraded formatting,
317 for example overfull lines or ugly line breaks.
324 Specifically, this suppresses the two additional blank lines near the
325 top and the bottom of each page, and it implies
326 .Fl O Cm indent Ns =5 .
327 One useful application is for checking that
329 output formats in the same way as the
331 source it was generated from.
332 .It Cm width Ns = Ns Ar width
333 The output width is set to
339 conforms to HTML5 using optional self-closing tags.
340 Default styles use only CSS1.
341 Equations rendered from
347 file documents style-sheet classes available for customising output.
348 If a style-sheet is not specified with
351 defaults to simple output (via an embedded style-sheet)
352 readable in any graphical or text-based web
355 Special characters are rendered in decimal-encoded UTF\-8.
359 arguments are accepted:
362 Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body>
363 elements and only emit the subtree below the <body> element.
366 argument will be ignored.
367 This is useful when embedding manual content within existing documents.
368 .It Cm includes Ns = Ns Ar fmt
373 is used as a template for linked header files (usually via the
378 are replaced with the include filename.
379 The default is not to present a
381 .It Cm man Ns = Ns Ar fmt
385 .Ar ../html%S/%N.%S.html ,
386 is used as a template for linked manuals (usually via the
393 are replaced with the linked manual's name and section, respectively.
394 If no section is included, section 1 is assumed.
395 The default is not to
397 .It Cm style Ns = Ns Ar style.css
400 is used for an external style-sheet.
401 This must be a valid absolute or
405 Locale-depending output encoding is triggered with
409 This option is not available on all systems: systems without locale
410 support, or those whose internal representation is not natively UCS-4,
415 for font style specification and available command-line arguments.
417 Translate input format into
420 This is useful for distributing manual sources to legacy systems
427 is passed as input, it is translated into
429 If the input format is
431 the input is copied to the output, expanding any
435 The parser is also run, and as usual, the
439 are displayed before copying the input to the output.
446 .Lk http://daringfireball.net/projects/markdown/syntax.text\
447 "John Gruber's 2004 specification" .
448 The output also almost conforms to the
449 .Lk http://commonmark.org/ CommonMark
452 The character set used for the markdown output is ASCII.
453 Non-ASCII characters are encoded as HTML entities.
454 Since that is not possible in literal font contexts, because these
455 are rendered as code spans and code blocks in the markdown output,
456 non-ASCII characters are transliterated to ASCII approximations in
459 Markdown is a very weak markup language, so all semantic markup is
460 lost, and even part of the presentational markup may be lost.
461 Do not use this as an intermediate step in converting to HTML;
471 input languages are not supported by
475 PDF-1.1 output may be generated by
478 .Sx PostScript Output
481 arguments and defaults.
482 .Ss PostScript Output
485 Level-2 pages may be generated by
487 Output pages default to letter sized and are rendered in the Times font
489 Margins are calculated as 1/9 the page length and width.
492 Special characters are rendered as in
497 arguments are accepted:
499 .It Cm paper Ns = Ns Ar name
509 You may also manually specify dimensions as
511 width by height in millimetres.
512 If an unknown value is encountered,
519 to force a UTF\-8 locale.
522 for details and options.
523 .Ss Syntax tree output
526 to show a human readable representation of the syntax tree.
527 It is useful for debugging the source code of manual pages.
528 The exact format is subject to change, so don't write parsers for it.
530 The first paragraph shows meta data found in the
535 line, or the fallbacks used.
537 In the tree dump, each output line shows one syntax tree node.
538 Child nodes are indented with respect to their parent node.
543 For macro nodes, the macro name; for text and
546 There is a special format for
550 Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
555 An opening parenthesis if the node is an opening delimiter.
557 An asterisk if the node starts a new input line.
559 The input line number (starting at one).
563 The input column number (starting at one).
565 A closing parenthesis if the node is a closing delimiter.
567 A full stop if the node ends a sentence.
569 BROKEN if the node is a block broken by another block.
571 NOSRC if the node is not in the input file,
572 but automatically generated from macros.
574 NOPRT if the node is not supposed to generate output
575 for any output format.
581 argument is accepted:
584 Skip validation and show the unvalidated syntax tree.
585 This can help to find out whether a given behaviour is caused by
586 the parser or by the validator.
587 Meta data is not available in this case.
590 .Bl -tag -width MANPAGER
592 Any non-empty value of the environment variable
594 is used instead of the standard pagination program,
605 Specifies the pagination program to use when
608 If neither PAGER nor MANPAGER is defined,
621 utility exits with one of the following values, controlled by the message
627 .Bl -tag -width Ds -compact
629 No base system convention violations, style suggestions, warnings,
630 or errors occurred, or those that did were ignored because they
631 were lower than the requested
634 At least one base system convention violation or style suggestion
635 occurred, but no warning or error, and
641 At least one warning occurred, but no error, and
647 At least one parsing error occurred,
648 but no unsupported feature was encountered, and
654 At least one unsupported feature was encountered, and
660 Invalid command line arguments were specified.
661 No input files have been read.
663 An operating system error occurred, for example exhaustion
664 of memory, file descriptors, or process table entries.
667 to exit at once, possibly in the middle of parsing or formatting a file.
675 To page manuals to the terminal:
677 .Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8
679 To produce HTML manuals with
683 .Dl $ mandoc \-T html -O style=mandoc.css mdoc.7 \*(Gt mdoc.7.html
685 To check over a large set of manuals:
687 .Dl $ mandoc \-T lint \(gafind /usr/src -name \e*\e.[1-9]\(ga
689 To produce a series of PostScript manuals for A4 paper:
691 .Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 \*(Gt manuals.ps
697 format, for use on systems lacking an
701 .Dl $ mandoc \-T man foo.mdoc \*(Gt foo.man
703 Messages displayed by
706 .Bd -ragged -offset indent
708 .Ar file : Ns Ar line : Ns Ar column : level : message : macro args
712 Line and column numbers start at 1.
713 Both are omitted for messages referring to an input file as a whole.
714 Macro names and arguments are omitted where meaningless.
717 operating system specifier is omitted for messages that are relevant
718 for all operating systems.
719 Fatal messages about invalid command line arguments
720 or operating system errors, for example when memory is exhausted,
727 Message levels have the following meanings:
728 .Bl -tag -width "warning"
730 An input file uses unsupported low-level
733 The output may be incomplete and/or misformatted,
734 so using GNU troff instead of
736 to process the file may be preferable.
738 Indicates a risk of information loss or severe misformatting,
739 in most cases caused by serious syntax errors.
741 Indicates a risk that the information shown or its formatting
742 may mismatch the author's intent in minor ways.
743 Additionally, syntax errors are classified at least as warnings,
744 even if they do not usually cause misformatting.
746 An input file uses dubious or discouraged style.
747 This is not a complaint about the syntax, and probably neither
748 formatting nor portability are in danger.
749 While great care is taken to avoid false positives on the higher
752 level tries to reduce the probability that issues go unnoticed,
753 so it may occasionally issue bogus suggestions.
754 Please use your good judgement to decide whether any particular
756 suggestion really justifies a change to the input file.
758 A convention used in the base system of a specific operating system
760 These are not markup mistakes, and neither the quality of formatting
761 nor portability are in danger.
764 level are printed with the more intuitive
777 levels except those about non-existent or unreadable input files
778 are hidden unless their level, or a lower level, is requested using a
784 As indicated below, all
788 checks are only performed if a specific operating system name occurs
789 in the arguments of the
791 command line option, of the
795 command line option, or, if neither are present, in the return value
799 .Ss Conventions for base system manuals
801 .It Sy "Mdocdate found"
807 keyword substitution, which is not supported by the
810 Consider using the conventional
813 .It Sy "Mdocdate missing"
817 macro does not use CVS
819 keyword substitution, but using it is conventionally expected in the
822 .It Sy "unknown architecture"
824 The third argument of the
826 macro does not match any of the architectures this operating system
828 .It Sy "operating system explicitly specified"
832 macro has an argument.
833 In the base system, it is conventionally left blank.
834 .It Sy "RCS id missing"
836 The manual page lacks the comment line with the RCS identifier
841 keyword substitution as conventionally used in these operating systems.
842 .It Sy "referenced manual not found"
846 macro references a manual page that is not found in the base system.
847 The path to look for base system manuals is configurable at compile
849 .Pa /usr/share/man : /usr/X11R6/man .
851 .Ss Style suggestions
853 .It Sy "legacy man(7) date format"
857 macro uses the legacy
861 Consider using the conventional
866 .It Sy "lower case character in document title"
868 The title is still used as given in the
873 .It Sy "duplicate RCS id"
874 A single manual page contains two copies of the RCS identifier for
875 the same operating system.
876 Consider deleting the later instance and moving the first one up
877 to the top of the page.
878 .It Sy "possible typo in section name"
880 Fuzzy string matching revealed that the argument of an
882 macro is similar, but not identical to a standard section name.
883 .It Sy "unterminated quoted argument"
885 Macro arguments can be enclosed in double quote characters
886 such that space characters and macro names contained in the quoted
887 argument need not be escaped.
888 The closing quote of the last argument of a macro can be omitted.
889 However, omitting it is not recommended because it makes the code
891 .It Sy "useless macro"
899 Simply delete it: it serves no useful purpose.
900 .It Sy "consider using OS macro"
902 A string was found in plain text or in a
904 macro that could be represented using
910 .It Sy "errnos out of order"
916 list are not in alphabetical order.
917 .It Sy "duplicate errno"
921 list contains two consecutive
923 entries describing the same
926 .It Sy "trailing delimiter"
928 The last argument of an
929 .Ic \&Ex , \&Fo , \&Nd , \&Nm , \&Os , \&Sh , \&Ss , \&St ,
932 macro ends with a trailing delimiter.
933 This is usually bad style and often indicates typos.
934 Most likely, the delimiter can be removed.
935 .It Sy "no blank before trailing delimiter"
937 The last argument of a macro that supports trailing delimiter
938 arguments is longer than one byte and ends with a trailing delimiter.
939 Consider inserting a blank such that the delimiter becomes a separate
940 argument, thus moving it out of the scope of the macro.
941 .It Sy "fill mode already enabled, skipping"
945 request occurs even though the document is still in fill mode,
946 or already switched back to fill mode.
948 .It Sy "fill mode already disabled, skipping"
952 request occurs even though the document already switched to no-fill mode
953 and did not switch back to fill mode yet.
955 .It Sy "verbatim \(dq--\(dq, maybe consider using \e(em"
957 Even though the ASCII output device renders an em-dash as
959 that is not a good way to write it in an input file
960 because it renders poorly on all other output devices.
961 .It Sy "function name without markup"
963 A word followed by an empty pair of parentheses occurs on a text line.
969 .It Sy "whitespace at end of input line"
970 .Pq mdoc , man , roff
971 Whitespace at the end of input lines is almost never semantically
972 significant \(em but in the odd case where it might be, it is
973 extremely confusing when reviewing and maintaining documents.
974 .It Sy "bad comment style"
976 Comment lines start with a dot, a backslash, and a double-quote character.
979 utility treats the line as a comment line even without the backslash,
980 but leaving out the backslash might not be portable.
982 .Ss Warnings related to the document prologue
984 .It Sy "missing manual title, using UNTITLED"
988 macro has no arguments, or there is no
990 macro before the first non-prologue macro.
991 .It Sy "missing manual title, using \(dq\(dq"
995 macro, or it has no arguments.
996 .It Sy "missing manual section, using \(dq\(dq"
1002 macro lacks the mandatory section argument.
1003 .It Sy "unknown manual section"
1005 The section number in a
1007 line is invalid, but still used.
1008 .It Sy "missing date, using today's date"
1010 The document was parsed as
1016 macro has no arguments or only empty arguments;
1017 or the document was parsed as
1023 macro has less than three arguments or its third argument is empty.
1024 .It Sy "cannot parse date, using it verbatim"
1030 macro does not follow the conventional format.
1031 .It Sy "date in the future, using it anyway"
1037 macro is more than a day ahead of the current system
1039 .It Sy "missing Os macro, using \(dq\(dq"
1041 The default or current system is not shown in this case.
1042 .It Sy "late prologue macro"
1048 macro occurs after some non-prologue macro, but still takes effect.
1049 .It Sy "prologue macros out of order"
1051 The prologue macros are not given in the conventional order
1055 All three macros are used even when given in another order.
1057 .Ss Warnings regarding document structure
1059 .It Sy ".so is fragile, better use ln(1)"
1061 Including files only works when the parser program runs with the correct
1062 current working directory.
1063 .It Sy "no document body"
1065 The document body contains neither text nor macros.
1066 An empty document is shown, consisting only of a header and a footer line.
1067 .It Sy "content before first section header"
1069 Some macros or text precede the first
1074 The offending macros and text are parsed and added to the top level
1075 of the syntax tree, outside any section block.
1076 .It Sy "first section is not NAME"
1078 The argument of the first
1086 .It Sy "NAME section without Nm before Nd"
1088 The NAME section does not contain any
1090 child macro before the first
1093 .It Sy "NAME section without description"
1095 The NAME section lacks the mandatory
1098 .It Sy "description not at the end of NAME"
1100 The NAME section does contain an
1102 child macro, but other content follows it.
1103 .It Sy "bad NAME section content"
1105 The NAME section contains plain text or macros other than
1109 .It Sy "missing comma before name"
1111 The NAME section contains an
1113 macro that is neither the first one nor preceded by a comma.
1114 .It Sy "missing description line, using \(dq\(dq"
1118 macro lacks the required argument.
1119 The title line of the manual will end after the dash.
1120 .It Sy "description line outside NAME section"
1124 macro appears outside the NAME section.
1125 The arguments are printed anyway and the following text is used for
1127 but none of that behaviour is portable.
1128 .It Sy "sections out of conventional order"
1130 A standard section occurs after another section it usually precedes.
1131 All section titles are used as given,
1132 and the order of sections is not changed.
1133 .It Sy "duplicate section title"
1135 The same standard section title occurs more than once.
1136 .It Sy "unexpected section"
1138 A standard section header occurs in a section of the manual
1139 where it normally isn't useful.
1140 .It Sy "cross reference to self"
1144 macro refers to a name and section matching the section of the present
1145 manual page and a name mentioned in an
1147 macro in the NAME or SYNOPSIS section, or in an
1151 macro in the SYNOPSIS.
1158 .It Sy "unusual Xr order"
1160 In the SEE ALSO section, an
1162 macro with a lower section number follows one with a higher number,
1165 macros referring to the same section are out of alphabetical order.
1166 .It Sy "unusual Xr punctuation"
1168 In the SEE ALSO section, punctuation between two
1170 macros differs from a single comma, or there is trailing punctuation
1174 .It Sy "AUTHORS section without An macro"
1176 An AUTHORS sections contains no
1178 macros, or only empty ones.
1179 Probably, there are author names lacking markup.
1181 .Ss "Warnings related to macros and nesting"
1183 .It Sy "obsolete macro"
1187 manual for replacements.
1188 .It Sy "macro neither callable nor escaped"
1190 The name of a macro that is not callable appears on a macro line.
1191 It is printed verbatim.
1192 If the intention is to call it, move it to its own input line;
1193 otherwise, escape it by prepending
1195 .It Sy "skipping paragraph macro"
1198 documents, this happens
1201 at the beginning and end of sections and subsections
1203 right before non-compact lists and displays
1205 at the end of items in non-column, non-compact lists
1207 and for multiple consecutive paragraph macros.
1211 documents, it happens
1223 macros having neither head nor body arguments
1234 .It Sy "moving paragraph macro out of list"
1238 list contains a trailing paragraph macro.
1239 The paragraph macro is moved after the end of the list.
1240 .It Sy "skipping no-space macro"
1242 An input line begins with an
1244 macro, or the next argument after an
1246 macro is an isolated closing delimiter.
1247 The macro is ignored.
1248 .It Sy "blocks badly nested"
1250 If two blocks intersect, one should completely contain the other.
1251 Otherwise, rendered output is likely to look strange in any output
1252 format, and rendering in SGML-based output formats is likely to be
1253 outright wrong because such languages do not support badly nested
1255 Typical examples of badly nested blocks are
1256 .Qq Ic \&Ao \&Bo \&Ac \&Bc
1258 .Qq Ic \&Ao \&Bq \&Ac .
1266 .It Sy "nested displays are not portable"
1273 display occurs nested inside another
1278 but fails with most other implementations.
1279 .It Sy "moving content out of list"
1283 list block contains text or macros before the first
1286 The offending children are moved before the beginning of the list.
1287 .It Sy "first macro on line"
1292 macro occurs as the first macro on a line, which is not portable.
1293 .It Sy "line scope broken"
1295 While parsing the next-line scope of the previous macro,
1296 another macro is found that prematurely terminates the previous one.
1297 The previous, interrupted macro is deleted from the parse tree.
1299 .Ss "Warnings related to missing arguments"
1301 .It Sy "skipping empty request"
1303 The macro name is missing from a macro definition request,
1306 control statement or operation keyword lacks its required argument.
1307 .It Sy "conditional request controls empty scope"
1309 A conditional request is only useful if any of the following
1310 follows it on the same logical input line:
1315 keyword to open a multi-line scope.
1317 A request or macro or some text, resulting in a single-line scope.
1319 The immediate end of the logical line without any intervening whitespace,
1320 resulting in next-line scope.
1322 Here, a conditional request is followed by trailing whitespace only,
1323 and there is no other content on its logical input line.
1324 Note that it doesn't matter whether the logical input line is split
1325 across multiple physical input lines using
1327 line continuation characters.
1328 This is one of the rare cases
1329 where trailing whitespace is syntactically significant.
1330 The conditional request controls a scope containing whitespace only,
1331 so it is unlikely to have a significant effect,
1332 except that it may control a following
1335 .It Sy "skipping empty macro"
1337 The indicated macro has no arguments and hence no effect.
1338 .It Sy "empty block"
1350 block contains nothing in its body and will produce no output.
1351 .It Sy "empty argument, using 0n"
1353 The required width is missing after
1360 .It Sy "missing display type, using -ragged"
1364 macro is invoked without the required display type.
1365 .It Sy "list type is not the first argument"
1369 macro, at least one other argument precedes the type argument.
1372 utility copes with any argument order, but some other
1374 implementations do not.
1375 .It Sy "missing -width in -tag list, using 8n"
1384 .It Sy "missing utility name, using \(dq\(dq"
1388 macro is called without an argument before
1390 has first been called with an argument.
1391 .It Sy "missing function name, using \(dq\(dq"
1395 macro is called without an argument.
1396 No function name is printed.
1397 .It Sy "empty head in list item"
1409 macro lacks the required argument.
1410 The item head is left empty.
1411 .It Sy "empty list item"
1423 An empty list item is shown.
1424 .It Sy "missing argument, using next line"
1430 list has no arguments.
1433 uses the text or macros of the following line, if any, for the cell,
1434 other formatters may misformat the list.
1435 .It Sy "missing font type, using \efR"
1439 macro has no argument.
1440 It switches to the default font.
1441 .It Sy "unknown font type, using \efR"
1445 argument is invalid.
1446 The default font is used instead.
1447 .It Sy "nothing follows prefix"
1451 macro has no argument, or only one argument and no macro follows
1452 on the same input line.
1453 This defeats its purpose; in particular, spacing is not suppressed
1454 before the text or macros following on the next input line.
1455 .It Sy "empty reference block"
1459 macro is immediately followed by an
1461 macro on the next input line.
1462 Such an empty block does not produce any output.
1463 .It Sy "missing section argument"
1467 macro lacks its second, section number argument.
1468 The first argument, i.e. the name, is printed, but without subsequent
1470 .It Sy "missing -std argument, adding it"
1476 macro lacks the required
1483 even when it is not specified, but other implementations may not.
1484 .It Sy "missing option string, using \(dq\(dq"
1488 macro is invoked without any argument.
1489 An empty pair of square brackets is shown.
1490 .It Sy "missing resource identifier, using \(dq\(dq"
1496 macro is invoked without any argument.
1497 An empty pair of angle brackets is shown.
1498 .It Sy "missing eqn box, using \(dq\(dq"
1500 A diacritic mark or a binary operator is found,
1501 but there is nothing to the left of it.
1502 An empty box is inserted.
1504 .Ss "Warnings related to bad macro arguments"
1506 .It Sy "duplicate argument"
1512 macro has more than one
1519 All but the last instances of these arguments are ignored.
1520 .It Sy "skipping duplicate argument"
1524 macro has more than one
1529 All but the first of these arguments are ignored.
1530 .It Sy "skipping duplicate display type"
1534 macro has more than one type argument; the first one is used.
1535 .It Sy "skipping duplicate list type"
1539 macro has more than one type argument; the first one is used.
1540 .It Sy "skipping -width argument"
1554 .It Sy "wrong number of cells"
1557 list, the number of tabs or
1559 macros is less than the number expected from the list header line
1560 or exceeds the expected number by more than one.
1561 Missing cells remain empty, and all cells exceeding the number of
1562 columns are joined into one single cell.
1563 .It Sy "unknown AT&T UNIX version"
1567 macro has an invalid argument.
1568 It is used verbatim, with
1571 .It Sy "comma in function argument"
1577 macro contains a comma; it should probably be split into two arguments.
1578 .It Sy "parenthesis in function name"
1580 The first argument of an
1584 macro contains an opening or closing parenthesis; that's probably wrong,
1585 parentheses are added automatically.
1586 .It Sy "unknown library name"
1590 macro has an unknown name argument and will be rendered as
1591 .Qq library Dq Ar name .
1592 .It Sy "invalid content in Rs block"
1596 block contains plain text or non-% macros.
1597 The bogus content is left in the syntax tree.
1598 Formatting may be poor.
1599 .It Sy "invalid Boolean argument"
1603 macro has an argument other than
1607 The invalid argument is moved out of the macro, which leaves the macro
1608 empty, causing it to toggle the spacing mode.
1609 .It Sy "unknown font, skipping request"
1617 layout modifier has an unknown
1620 .It Sy "odd number of characters in request"
1624 request contains an odd number of characters.
1625 The last character is mapped to the blank character.
1627 .Ss "Warnings related to plain text"
1629 .It Sy "blank line in fill mode, using .sp"
1631 The meaning of blank input lines is only well-defined in non-fill mode:
1632 In fill mode, line breaks of text input lines are not supposed to be
1634 However, for compatibility with groff, blank lines in fill mode
1638 .It Sy "tab in filled text"
1640 The meaning of tab characters is only well-defined in non-fill mode:
1641 In fill mode, whitespace is not supposed to be significant
1642 on text input lines.
1643 As an implementation dependent choice, tab characters on text lines
1644 are passed through to the formatters in any case.
1645 Given that the text before the tab character will be filled,
1646 it is hard to predict which tab stop position the tab will advance to.
1647 .It Sy "new sentence, new line"
1649 A new sentence starts in the middle of a text line.
1650 Start it on a new input line to help formatters produce correct spacing.
1651 .It Sy "invalid escape sequence"
1653 An escape sequence has an invalid opening argument delimiter, lacks the
1654 closing argument delimiter, or the argument has too few characters.
1655 If the argument is incomplete,
1659 expand to an empty string,
1665 to the length of the incomplete argument.
1666 All other invalid escape sequences are ignored.
1667 .It Sy "undefined string, using \(dq\(dq"
1669 If a string is used without being defined before,
1670 its value is implicitly set to the empty string.
1671 However, defining strings explicitly before use
1672 keeps the code more readable.
1674 .Ss "Warnings related to tables"
1676 .It Sy "tbl line starts with span"
1678 The first cell in a table layout line is a horizontal span
1680 Data provided for this cell is ignored, and nothing is printed in the cell.
1681 .It Sy "tbl column starts with span"
1683 The first line of a table layout specification
1684 requests a vertical span
1686 Data provided for this cell is ignored, and nothing is printed in the cell.
1687 .It Sy "skipping vertical bar in tbl layout"
1689 A table layout specification contains more than two consecutive vertical bars.
1690 A double bar is printed, all additional bars are discarded.
1692 .Ss "Errors related to tables"
1694 .It Sy "non-alphabetic character in tbl options"
1696 The table options line contains a character other than a letter,
1697 blank, or comma where the beginning of an option name is expected.
1698 The character is ignored.
1699 .It Sy "skipping unknown tbl option"
1701 The table options line contains a string of letters that does not
1702 match any known option name.
1703 The word is ignored.
1704 .It Sy "missing tbl option argument"
1706 A table option that requires an argument is not followed by an
1707 opening parenthesis, or the opening parenthesis is immediately
1708 followed by a closing parenthesis.
1709 The option is ignored.
1710 .It Sy "wrong tbl option argument size"
1712 A table option argument contains an invalid number of characters.
1713 Both the option and the argument are ignored.
1714 .It Sy "empty tbl layout"
1716 A table layout specification is completely empty,
1717 specifying zero lines and zero columns.
1718 As a fallback, a single left-justified column is used.
1719 .It Sy "invalid character in tbl layout"
1721 A table layout specification contains a character that can neither
1722 be interpreted as a layout key character nor as a layout modifier,
1723 or a modifier precedes the first key.
1724 The invalid character is discarded.
1725 .It Sy "unmatched parenthesis in tbl layout"
1727 A table layout specification contains an opening parenthesis,
1728 but no matching closing parenthesis.
1729 The rest of the input line, starting from the parenthesis, has no effect.
1730 .It Sy "tbl without any data cells"
1732 A table does not contain any data cells.
1733 It will probably produce no output.
1734 .It Sy "ignoring data in spanned tbl cell"
1736 A table cell is marked as a horizontal span
1740 in the table layout, but it contains data.
1741 The data is ignored.
1742 .It Sy "ignoring extra tbl data cells"
1744 A data line contains more cells than the corresponding layout line.
1745 The data in the extra cells is ignored.
1746 .It Sy "data block open at end of tbl"
1748 A data block is opened with
1750 but never closed with a matching
1752 The remaining data lines of the table are all put into one cell,
1753 and any remaining cells stay empty.
1755 .Ss "Errors related to roff, mdoc, and man code"
1757 .It Sy "duplicate prologue macro"
1759 One of the prologue macros occurs more than once.
1760 The last instance overrides all previous ones.
1761 .It Sy "skipping late title macro"
1765 macro appears after the first non-prologue macro.
1766 Traditional formatters cannot handle this because
1767 they write the page header before parsing the document body.
1768 Even though this technical restriction does not apply to
1770 traditional semantics is preserved.
1771 The late macro is discarded including its arguments.
1772 .It Sy "input stack limit exceeded, infinite loop?"
1774 Explicit recursion limits are implemented for the following features,
1775 in order to prevent infinite loops:
1778 expansion of nested escape sequences
1779 including expansion of strings and number registers,
1781 expansion of nested user-defined macros,
1787 When a limit is hit, the output is incorrect, typically losing
1788 some content, but the parser can continue.
1789 .It Sy "skipping bad character"
1790 .Pq mdoc , man , roff
1791 The input file contains a byte that is not a printable
1794 The message mentions the character number.
1795 The offending byte is replaced with a question mark
1797 Consider editing the input file to replace the byte with an ASCII
1798 transliteration of the intended character.
1799 .It Sy "skipping unknown macro"
1800 .Pq mdoc , man , roff
1801 The first identifier on a request or macro line is neither recognized as a
1803 request, nor as a user-defined macro, nor, respectively, as an
1808 It may be mistyped or unsupported.
1809 The request or macro is discarded including its arguments.
1810 .It Sy "skipping insecure request"
1812 An input file attempted to run a shell command
1813 or to read or write an external file.
1814 Such attempts are denied for security reasons.
1815 .It Sy "skipping item outside list"
1819 macro occurs outside any
1824 delimiter occurs outside any pile.
1825 It is discarded including its arguments.
1826 .It Sy "skipping column outside column list"
1830 macro occurs outside any
1833 It is discarded including its arguments.
1834 .It Sy "skipping end of block that is not open"
1835 .Pq mdoc , man , eqn , tbl , roff
1836 Various syntax elements can only be used to explicitly close blocks
1837 that have previously been opened.
1840 block closing macro, a
1847 right delimiter or closing brace, or the end of an equation, table, or
1849 conditional request is encountered but no matching block is open.
1850 The offending request or macro is discarded.
1851 .It Sy "fewer RS blocks open, skipping"
1855 macro is invoked with an argument, but less than the specified number of
1861 .It Sy "inserting missing end of block"
1865 macros as well as tables require explicit closing by dedicated macros.
1866 A block that doesn't support bad nesting
1867 ends before all of its children are properly closed.
1868 The open child nodes are closed implicitly.
1869 .It Sy "appending missing end of block"
1870 .Pq mdoc , man , eqn , tbl , roff
1871 At the end of the document, an explicit
1879 block, an equation, table, or
1881 conditional or ignore block is still open.
1882 The open block is closed implicitly.
1883 .It Sy "escaped character not allowed in a name"
1885 Macro, string and register identifiers consist of printable,
1886 non-whitespace ASCII characters.
1887 Escape sequences and characters and strings expressed in terms of them
1888 cannot form part of a name.
1889 The first argument of an
1897 request, or any argument of an
1899 request, or the name of a request or user defined macro being called,
1900 is terminated by an escape sequence.
1906 the request has no effect at all.
1913 what was parsed up to this point is used as the arguments to the request,
1914 and the rest of the input line is discarded including the escape sequence.
1915 When parsing for a request or a user-defined macro name to be called,
1916 only the escape sequence is discarded.
1917 The characters preceding it are used as the request or macro name,
1918 the characters following it are used as the arguments to the request or macro.
1919 .It Sy "NOT IMPLEMENTED: Bd -file"
1921 For security reasons, the
1923 macro does not support the
1926 By requesting the inclusion of a sensitive file, a malicious document
1927 might otherwise trick a privileged user into inadvertently displaying
1928 the file on the screen, revealing the file content to bystanders.
1929 The argument is ignored including the file name following it.
1930 .It Sy "skipping display without arguments"
1934 block macro does not have any arguments.
1935 The block is discarded, and the block content is displayed in
1936 whatever mode was active before the block.
1937 .It Sy "missing list type, using -item"
1941 macro fails to specify the list type.
1942 .It Sy "argument is not numeric, using 1"
1946 request is not a number.
1947 .It Sy "missing manual name, using \(dq\(dq"
1951 or any call in the NAME section, lacks the required argument.
1952 .It Sy "uname(3) system call failed, using UNKNOWN"
1956 macro is called without arguments, and the
1961 can be compiled with
1963 .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
1965 .It Sy "unknown standard specifier"
1969 macro has an unknown argument and is discarded.
1970 .It Sy "skipping request without numeric argument"
1979 statement has a non-numeric or negative argument or no argument at all.
1980 The invalid request or statement is ignored.
1981 .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
1983 For security reasons,
1987 file inclusion requests only with relative paths
1988 and only without ascending to any parent directory.
1989 By requesting the inclusion of a sensitive file, a malicious document
1990 might otherwise trick a privileged user into inadvertently displaying
1991 the file on the screen, revealing the file content to bystanders.
1993 only shows the path as it appears behind
1995 .It Sy ".so request failed"
1999 request requires reading an external file, but the file could not be
2002 only shows the path as it appears behind
2004 .It Sy "skipping all arguments"
2005 .Pq mdoc , man , eqn , roff
2021 macro in a list that don't support item heads, a
2040 block closing request is invoked with at least one argument.
2041 All arguments are ignored.
2042 .It Sy "skipping excess arguments"
2043 .Pq mdoc , man , roff
2044 A macro or request is invoked with too many arguments:
2045 .Bl -dash -offset 2n -width 2n -compact
2055 with more than one argument
2058 with another argument after
2064 with more than one argument or with a non-integer argument
2069 family with more than two arguments
2072 with more than three arguments
2075 with more than five arguments
2081 with invalid arguments
2083 The excess arguments are ignored.
2085 .Ss Unsupported features
2087 .It Sy "input too large"
2091 cannot handle input files larger than its arbitrary size limit
2092 of 2^31 bytes (2 Gigabytes).
2093 Since useful manuals are always small, this is not a problem in practice.
2094 Parsing is aborted as soon as the condition is detected.
2095 .It Sy "unsupported control character"
2097 An ASCII control character supported by other
2099 implementations but not by
2101 was found in an input file.
2102 It is replaced by a question mark.
2103 .It Sy "unsupported roff request"
2105 An input file contains a
2107 request supported by GNU troff or Heirloom troff but not by
2109 and it is likely that this will cause information loss
2110 or considerable misformatting.
2111 .It Sy "eqn delim option in tbl"
2113 The options line of a table defines equation delimiters.
2114 Any equation source code contained in the table will be printed unformatted.
2115 .It Sy "unsupported table layout modifier"
2117 A table layout specification contains an
2120 The modifier is discarded.
2121 .It Sy "ignoring macro in table"
2122 .Pq tbl , mdoc , man
2123 A table contains an invocation of an
2127 macro or of an undefined macro.
2128 The macro is ignored, and its arguments are handled
2129 as if they were a text line.
2143 utility first appeared in
2157 utility was written by
2158 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
2159 and is maintained by
2160 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
git.ckatri.com / mandoc.git / blob