1 .\" $Id: mandoc.1,v 1.226 2018/07/28 18:34:15 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: July 28 2018 $
23 .Nd format manual pages
27 .Op Fl I Cm os Ns = Ns Ar name
37 utility formats manual pages for display.
45 text from stdin and produces
49 The options are as follows:
52 If the standard output is a terminal device and
56 to paginate the output, just like
60 Copy the formatted manual pages to the standard output without using
64 It can be specified to override
66 .It Fl I Cm os Ns = Ns Ar name
67 Override the default operating system
77 Specify the input encoding.
85 If not specified, autodetection uses the first match in the following
89 If the first three bytes of the input file are the UTF-8 byte order
90 mark (BOM, 0xefbbbf), input is interpreted as
93 If the first or second line of the input file matches the
97 .D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*-
99 then input is interpreted according to
102 If the first non-ASCII byte in the file introduces a valid UTF-8
103 sequence, input is interpreted as
106 Otherwise, input is interpreted as
112 all input files are interpreted as
116 all input files are interpreted as
118 By default, the input language is automatically detected for each file:
119 if the first macro is
125 parser is used; otherwise, the
128 With other arguments,
132 Comma-separated output options.
133 See the descriptions of the individual output formats for supported
136 Select the output format.
137 Supported values for the
154 mode only parses the input and produces no output.
157 and redirects parser messages, which usually appear on standard
158 error output, to standard output.
160 Specify the minimum message
162 to be reported on the standard error output and to affect the exit status.
174 level automatically derives the operating system from the contents of the
178 command line option, or from the
187 that bypass autodetection and request validation of base system
188 conventions for a particular operating system.
206 to exit after parsing a file that causes warnings or errors of at least
208 No formatted output will be produced from that file.
213 are requested, they can be joined with a comma, for example
214 .Fl W Cm error , Ns Cm stop .
216 Read from the given input file.
217 If multiple files are specified, they are processed in the given order.
220 reads from standard input.
225 to force text output in 7-bit ASCII character encoding documented in the
227 manual page, ignoring the
229 set in the environment.
231 Font styles are applied by using back-spaced encoding such that an
235 .Sq _ Ns \e[bs] Ns c ,
238 is the back-space character number 8.
239 Emboldened characters are rendered as
240 .Sq c Ns \e[bs] Ns c .
242 The special characters documented in
244 are rendered best-effort in an ASCII equivalent.
248 arguments are accepted:
250 .It Cm indent Ns = Ns Ar indent
251 The left margin for normal text is set to
253 blank characters instead of the default of five for
257 Increasing this is not recommended; it may result in degraded formatting,
258 for example overfull lines or ugly line breaks.
259 When output is to a pager on a terminal that is less than 66 columns
260 wide, the default is reduced to three columns.
267 Specifically, this suppresses the two additional blank lines near the
268 top and the bottom of each page, and it implies
269 .Fl O Cm indent Ns =5 .
270 One useful application is for checking that
272 output formats in the same way as the
274 source it was generated from.
275 .It Cm width Ns = Ns Ar width
276 The output width is set to
278 instead of the default of 78.
279 When output is to a pager on a terminal that is less than 79 columns
280 wide, the default is reduced to one less than the terminal width.
281 In any case, lines that are output in literal mode are never wrapped
282 and may exceed the output width.
287 conforms to HTML5 using optional self-closing tags.
288 Default styles use only CSS1.
289 Equations rendered from
295 file documents style-sheet classes available for customising output.
296 If a style-sheet is not specified with
299 defaults to simple output (via an embedded style-sheet)
300 readable in any graphical or text-based web
303 Non-ASCII characters are rendered
304 as hexadecimal Unicode character references.
308 arguments are accepted:
311 Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body>
312 elements and only emit the subtree below the <body> element.
315 argument will be ignored.
316 This is useful when embedding manual content within existing documents.
317 .It Cm includes Ns = Ns Ar fmt
322 is used as a template for linked header files (usually via the
327 are replaced with the include filename.
328 The default is not to present a
330 .It Cm man Ns = Ns Ar fmt
334 .Ar ../html%S/%N.%S.html ,
335 is used as a template for linked manuals (usually via the
342 are replaced with the linked manual's name and section, respectively.
343 If no section is included, section 1 is assumed.
344 The default is not to
346 .It Cm style Ns = Ns Ar style.css
349 is used for an external style-sheet.
350 This must be a valid absolute or
356 automatically selects UTF-8 or ASCII output according to the current
358 If any of the environment variables
363 are set and the first one that is set
364 selects the UTF-8 character encoding, it produces
366 otherwise, it falls back to
368 This output mode can also be selected explicitly with
378 This is useful for distributing manual sources to legacy systems
383 If the input format of a file is
385 the input is copied to the output, expanding any
389 The parser is also run, and as usual, the
393 are displayed before copying the input to the output.
399 input to the markdown format conforming to
400 .Lk http://daringfireball.net/projects/markdown/syntax.text\
401 "John Gruber's 2004 specification" .
402 The output also almost conforms to the
403 .Lk http://commonmark.org/ CommonMark
406 The character set used for the markdown output is ASCII.
407 Non-ASCII characters are encoded as HTML entities.
408 Since that is not possible in literal font contexts, because these
409 are rendered as code spans and code blocks in the markdown output,
410 non-ASCII characters are transliterated to ASCII approximations in
413 Markdown is a very weak markup language, so all semantic markup is
414 lost, and even part of the presentational markup may be lost.
415 Do not use this as an intermediate step in converting to HTML;
425 input languages are not supported by
429 PDF-1.1 output may be generated by
432 .Sx PostScript Output
435 arguments and defaults.
436 .Ss PostScript Output
439 Level-2 pages may be generated by
441 Output pages default to letter sized and are rendered in the Times font
443 Margins are calculated as 1/9 the page length and width.
446 Special characters are rendered as in
451 arguments are accepted:
453 .It Cm paper Ns = Ns Ar name
463 You may also manually specify dimensions as
465 width by height in millimetres.
466 If an unknown value is encountered,
473 to force text output in UTF-8 multi-byte character encoding,
476 settings in the environment.
479 regarding font styles and
483 On operating systems lacking locale or wide character support, and
484 on those where the internal character representation is not UCS-4,
488 .Ss Syntax tree output
491 to show a human readable representation of the syntax tree.
492 It is useful for debugging the source code of manual pages.
493 The exact format is subject to change, so don't write parsers for it.
495 The first paragraph shows meta data found in the
500 line, or the fallbacks used.
502 In the tree dump, each output line shows one syntax tree node.
503 Child nodes are indented with respect to their parent node.
508 For macro nodes, the macro name; for text and
511 There is a special format for
515 Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
520 An opening parenthesis if the node is an opening delimiter.
522 An asterisk if the node starts a new input line.
524 The input line number (starting at one).
528 The input column number (starting at one).
530 A closing parenthesis if the node is a closing delimiter.
532 A full stop if the node ends a sentence.
534 BROKEN if the node is a block broken by another block.
536 NOSRC if the node is not in the input file,
537 but automatically generated from macros.
539 NOPRT if the node is not supposed to generate output
540 for any output format.
546 argument is accepted:
549 Skip validation and show the unvalidated syntax tree.
550 This can help to find out whether a given behaviour is caused by
551 the parser or by the validator.
552 Meta data is not available in this case.
557 The character encoding
561 is selected, it decides whether to use ASCII or UTF-8 output format.
562 It never affects the interpretation of input files.
567 utility exits with one of the following values, controlled by the message
573 .Bl -tag -width Ds -compact
575 No base system convention violations, style suggestions, warnings,
576 or errors occurred, or those that did were ignored because they
577 were lower than the requested
580 At least one base system convention violation or style suggestion
581 occurred, but no warning or error, and
587 At least one warning occurred, but no error, and
593 At least one parsing error occurred,
594 but no unsupported feature was encountered, and
600 At least one unsupported feature was encountered, and
606 Invalid command line arguments were specified.
607 No input files have been read.
609 An operating system error occurred, for example exhaustion
610 of memory, file descriptors, or process table entries.
613 to exit at once, possibly in the middle of parsing or formatting a file.
621 To page manuals to the terminal:
623 .Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8
625 To produce HTML manuals with
629 .Dl $ mandoc \-T html -Ostyle=mandoc.css mdoc.5 \*(Gt mdoc.5.html
631 To check over a large set of manuals:
633 .Dl $ mandoc \-T lint \(gafind /usr/src -name \e*\e.[1-9]\(ga
635 To produce a series of PostScript manuals for A4 paper:
637 .Dl $ mandoc \-T ps \-O paper=a4 mdoc.5 man.5 \*(Gt manuals.ps
643 format, for use on systems lacking an
647 .Dl $ mandoc \-T man foo.mdoc \*(Gt foo.man
649 Messages displayed by
652 .Bd -ragged -offset indent
654 .Ar file : Ns Ar line : Ns Ar column : level : message : macro args
658 Line and column numbers start at 1.
659 Both are omitted for messages referring to an input file as a whole.
660 Macro names and arguments are omitted where meaningless.
663 operating system specifier is omitted for messages that are relevant
664 for all operating systems.
665 Fatal messages about invalid command line arguments
666 or operating system errors, for example when memory is exhausted,
673 Message levels have the following meanings:
674 .Bl -tag -width "warning"
676 An input file uses unsupported low-level
679 The output may be incomplete and/or misformatted,
680 so using GNU troff instead of
682 to process the file may be preferable.
684 Indicates a risk of information loss or severe misformatting,
685 in most cases caused by serious syntax errors.
687 Indicates a risk that the information shown or its formatting
688 may mismatch the author's intent in minor ways.
689 Additionally, syntax errors are classified at least as warnings,
690 even if they do not usually cause misformatting.
692 An input file uses dubious or discouraged style.
693 This is not a complaint about the syntax, and probably neither
694 formatting nor portability are in danger.
695 While great care is taken to avoid false positives on the higher
698 level tries to reduce the probability that issues go unnoticed,
699 so it may occasionally issue bogus suggestions.
700 Please use your good judgement to decide whether any particular
702 suggestion really justifies a change to the input file.
704 A convention used in the base system of a specific operating system
706 These are not markup mistakes, and neither the quality of formatting
707 nor portability are in danger.
710 level are printed with the more intuitive
723 levels except those about non-existent or unreadable input files
724 are hidden unless their level, or a lower level, is requested using a
730 As indicated below, all
734 checks are only performed if a specific operating system name occurs
735 in the arguments of the
737 command line option, of the
741 command line option, or, if neither are present, in the return value
745 .Ss Conventions for base system manuals
747 .It Sy "Mdocdate found"
753 keyword substitution, which is not supported by the
756 Consider using the conventional
759 .It Sy "Mdocdate missing"
763 macro does not use CVS
765 keyword substitution, but using it is conventionally expected in the
768 .It Sy "unknown architecture"
770 The third argument of the
772 macro does not match any of the architectures this operating system
774 .It Sy "operating system explicitly specified"
778 macro has an argument.
779 In the base system, it is conventionally left blank.
780 .It Sy "RCS id missing"
782 The manual page lacks the comment line with the RCS identifier
787 keyword substitution as conventionally used in these operating systems.
788 .It Sy "referenced manual not found"
792 macro references a manual page that is not found in the base system.
793 The path to look for base system manuals is configurable at compile
795 .Pa /usr/share/man : /usr/X11R6/man .
797 .Ss Style suggestions
799 .It Sy "legacy man(7) date format"
803 macro uses the legacy
807 Consider using the conventional
812 .It Sy "normalizing date format to" : No ...
818 macro provides an abbreviated month name or a day number with a
820 In the formatted output, the month name is written out in full
821 and the leading zero is omitted.
822 .It Sy "lower case character in document title"
824 The title is still used as given in the
829 .It Sy "duplicate RCS id"
830 A single manual page contains two copies of the RCS identifier for
831 the same operating system.
832 Consider deleting the later instance and moving the first one up
833 to the top of the page.
834 .It Sy "possible typo in section name"
836 Fuzzy string matching revealed that the argument of an
838 macro is similar, but not identical to a standard section name.
839 .It Sy "unterminated quoted argument"
841 Macro arguments can be enclosed in double quote characters
842 such that space characters and macro names contained in the quoted
843 argument need not be escaped.
844 The closing quote of the last argument of a macro can be omitted.
845 However, omitting it is not recommended because it makes the code
847 .It Sy "useless macro"
855 Simply delete it: it serves no useful purpose.
856 .It Sy "consider using OS macro"
858 A string was found in plain text or in a
860 macro that could be represented using
866 .It Sy "errnos out of order"
872 list are not in alphabetical order.
873 .It Sy "duplicate errno"
877 list contains two consecutive
879 entries describing the same
882 .It Sy "trailing delimiter"
884 The last argument of an
885 .Ic \&Ex , \&Fo , \&Nd , \&Nm , \&Os , \&Sh , \&Ss , \&St ,
888 macro ends with a trailing delimiter.
889 This is usually bad style and often indicates typos.
890 Most likely, the delimiter can be removed.
891 .It Sy "no blank before trailing delimiter"
893 The last argument of a macro that supports trailing delimiter
894 arguments is longer than one byte and ends with a trailing delimiter.
895 Consider inserting a blank such that the delimiter becomes a separate
896 argument, thus moving it out of the scope of the macro.
897 .It Sy "fill mode already enabled, skipping"
901 request occurs even though the document is still in fill mode,
902 or already switched back to fill mode.
904 .It Sy "fill mode already disabled, skipping"
908 request occurs even though the document already switched to no-fill mode
909 and did not switch back to fill mode yet.
911 .It Sy "verbatim \(dq--\(dq, maybe consider using \e(em"
913 Even though the ASCII output device renders an em-dash as
915 that is not a good way to write it in an input file
916 because it renders poorly on all other output devices.
917 .It Sy "function name without markup"
919 A word followed by an empty pair of parentheses occurs on a text line.
925 .It Sy "whitespace at end of input line"
926 .Pq mdoc , man , roff
927 Whitespace at the end of input lines is almost never semantically
928 significant \(em but in the odd case where it might be, it is
929 extremely confusing when reviewing and maintaining documents.
930 .It Sy "bad comment style"
932 Comment lines start with a dot, a backslash, and a double-quote character.
935 utility treats the line as a comment line even without the backslash,
936 but leaving out the backslash might not be portable.
938 .Ss Warnings related to the document prologue
940 .It Sy "missing manual title, using UNTITLED"
944 macro has no arguments, or there is no
946 macro before the first non-prologue macro.
947 .It Sy "missing manual title, using \(dq\(dq"
951 macro, or it has no arguments.
952 .It Sy "missing manual section, using \(dq\(dq"
958 macro lacks the mandatory section argument.
959 .It Sy "unknown manual section"
961 The section number in a
963 line is invalid, but still used.
964 .It Sy "missing date, using today's date"
966 The document was parsed as
972 macro has no arguments or only empty arguments;
973 or the document was parsed as
979 macro has less than three arguments or its third argument is empty.
980 .It Sy "cannot parse date, using it verbatim"
986 macro does not follow the conventional format.
987 .It Sy "date in the future, using it anyway"
993 macro is more than a day ahead of the current system
995 .It Sy "missing Os macro, using \(dq\(dq"
997 The default or current system is not shown in this case.
998 .It Sy "late prologue macro"
1004 macro occurs after some non-prologue macro, but still takes effect.
1005 .It Sy "prologue macros out of order"
1007 The prologue macros are not given in the conventional order
1011 All three macros are used even when given in another order.
1013 .Ss Warnings regarding document structure
1015 .It Sy ".so is fragile, better use ln(1)"
1017 Including files only works when the parser program runs with the correct
1018 current working directory.
1019 .It Sy "no document body"
1021 The document body contains neither text nor macros.
1022 An empty document is shown, consisting only of a header and a footer line.
1023 .It Sy "content before first section header"
1025 Some macros or text precede the first
1030 The offending macros and text are parsed and added to the top level
1031 of the syntax tree, outside any section block.
1032 .It Sy "first section is not NAME"
1034 The argument of the first
1045 .It Sy "NAME section without Nm before Nd"
1047 The NAME section does not contain any
1049 child macro before the first
1052 .It Sy "NAME section without description"
1054 The NAME section lacks the mandatory
1057 .It Sy "description not at the end of NAME"
1059 The NAME section does contain an
1061 child macro, but other content follows it.
1062 .It Sy "bad NAME section content"
1064 The NAME section contains plain text or macros other than
1068 .It Sy "missing comma before name"
1070 The NAME section contains an
1072 macro that is neither the first one nor preceded by a comma.
1073 .It Sy "missing description line, using \(dq\(dq"
1077 macro lacks the required argument.
1078 The title line of the manual will end after the dash.
1079 .It Sy "description line outside NAME section"
1083 macro appears outside the NAME section.
1084 The arguments are printed anyway and the following text is used for
1086 but none of that behaviour is portable.
1087 .It Sy "sections out of conventional order"
1089 A standard section occurs after another section it usually precedes.
1090 All section titles are used as given,
1091 and the order of sections is not changed.
1092 .It Sy "duplicate section title"
1094 The same standard section title occurs more than once.
1095 .It Sy "unexpected section"
1097 A standard section header occurs in a section of the manual
1098 where it normally isn't useful.
1099 .It Sy "cross reference to self"
1103 macro refers to a name and section matching the section of the present
1104 manual page and a name mentioned in an
1106 macro in the NAME or SYNOPSIS section, or in an
1110 macro in the SYNOPSIS.
1117 .It Sy "unusual Xr order"
1119 In the SEE ALSO section, an
1121 macro with a lower section number follows one with a higher number,
1124 macros referring to the same section are out of alphabetical order.
1125 .It Sy "unusual Xr punctuation"
1127 In the SEE ALSO section, punctuation between two
1129 macros differs from a single comma, or there is trailing punctuation
1133 .It Sy "AUTHORS section without An macro"
1135 An AUTHORS sections contains no
1137 macros, or only empty ones.
1138 Probably, there are author names lacking markup.
1140 .Ss "Warnings related to macros and nesting"
1142 .It Sy "obsolete macro"
1146 manual for replacements.
1147 .It Sy "macro neither callable nor escaped"
1149 The name of a macro that is not callable appears on a macro line.
1150 It is printed verbatim.
1151 If the intention is to call it, move it to its own input line;
1152 otherwise, escape it by prepending
1154 .It Sy "skipping paragraph macro"
1157 documents, this happens
1160 at the beginning and end of sections and subsections
1162 right before non-compact lists and displays
1164 at the end of items in non-column, non-compact lists
1166 and for multiple consecutive paragraph macros.
1170 documents, it happens
1182 macros having neither head nor body arguments
1193 .It Sy "moving paragraph macro out of list"
1197 list contains a trailing paragraph macro.
1198 The paragraph macro is moved after the end of the list.
1199 .It Sy "skipping no-space macro"
1201 An input line begins with an
1203 macro, or the next argument after an
1205 macro is an isolated closing delimiter.
1206 The macro is ignored.
1207 .It Sy "blocks badly nested"
1209 If two blocks intersect, one should completely contain the other.
1210 Otherwise, rendered output is likely to look strange in any output
1211 format, and rendering in SGML-based output formats is likely to be
1212 outright wrong because such languages do not support badly nested
1214 Typical examples of badly nested blocks are
1215 .Qq Ic \&Ao \&Bo \&Ac \&Bc
1217 .Qq Ic \&Ao \&Bq \&Ac .
1225 .It Sy "nested displays are not portable"
1232 display occurs nested inside another
1237 but fails with most other implementations.
1238 .It Sy "moving content out of list"
1242 list block contains text or macros before the first
1245 The offending children are moved before the beginning of the list.
1246 .It Sy "first macro on line"
1251 macro occurs as the first macro on a line, which is not portable.
1252 .It Sy "line scope broken"
1254 While parsing the next-line scope of the previous macro,
1255 another macro is found that prematurely terminates the previous one.
1256 The previous, interrupted macro is deleted from the parse tree.
1258 .Ss "Warnings related to missing arguments"
1260 .It Sy "skipping empty request"
1262 The macro name is missing from a macro definition request,
1265 control statement or operation keyword lacks its required argument.
1266 .It Sy "conditional request controls empty scope"
1268 A conditional request is only useful if any of the following
1269 follows it on the same logical input line:
1274 keyword to open a multi-line scope.
1276 A request or macro or some text, resulting in a single-line scope.
1278 The immediate end of the logical line without any intervening whitespace,
1279 resulting in next-line scope.
1281 Here, a conditional request is followed by trailing whitespace only,
1282 and there is no other content on its logical input line.
1283 Note that it doesn't matter whether the logical input line is split
1284 across multiple physical input lines using
1286 line continuation characters.
1287 This is one of the rare cases
1288 where trailing whitespace is syntactically significant.
1289 The conditional request controls a scope containing whitespace only,
1290 so it is unlikely to have a significant effect,
1291 except that it may control a following
1294 .It Sy "skipping empty macro"
1296 The indicated macro has no arguments and hence no effect.
1297 .It Sy "empty block"
1309 block contains nothing in its body and will produce no output.
1310 .It Sy "empty argument, using 0n"
1312 The required width is missing after
1319 .It Sy "missing display type, using -ragged"
1323 macro is invoked without the required display type.
1324 .It Sy "list type is not the first argument"
1328 macro, at least one other argument precedes the type argument.
1331 utility copes with any argument order, but some other
1333 implementations do not.
1334 .It Sy "missing -width in -tag list, using 8n"
1343 .It Sy "missing utility name, using \(dq\(dq"
1347 macro is called without an argument before
1349 has first been called with an argument.
1350 .It Sy "missing function name, using \(dq\(dq"
1354 macro is called without an argument.
1355 No function name is printed.
1356 .It Sy "empty head in list item"
1368 macro lacks the required argument.
1369 The item head is left empty.
1370 .It Sy "empty list item"
1382 An empty list item is shown.
1383 .It Sy "missing argument, using next line"
1389 list has no arguments.
1392 uses the text or macros of the following line, if any, for the cell,
1393 other formatters may misformat the list.
1394 .It Sy "missing font type, using \efR"
1398 macro has no argument.
1399 It switches to the default font.
1400 .It Sy "unknown font type, using \efR"
1404 argument is invalid.
1405 The default font is used instead.
1406 .It Sy "nothing follows prefix"
1410 macro has no argument, or only one argument and no macro follows
1411 on the same input line.
1412 This defeats its purpose; in particular, spacing is not suppressed
1413 before the text or macros following on the next input line.
1414 .It Sy "empty reference block"
1418 macro is immediately followed by an
1420 macro on the next input line.
1421 Such an empty block does not produce any output.
1422 .It Sy "missing section argument"
1426 macro lacks its second, section number argument.
1427 The first argument, i.e. the name, is printed, but without subsequent
1429 .It Sy "missing -std argument, adding it"
1435 macro lacks the required
1442 even when it is not specified, but other implementations may not.
1443 .It Sy "missing option string, using \(dq\(dq"
1447 macro is invoked without any argument.
1448 An empty pair of square brackets is shown.
1449 .It Sy "missing resource identifier, using \(dq\(dq"
1455 macro is invoked without any argument.
1456 An empty pair of angle brackets is shown.
1457 .It Sy "missing eqn box, using \(dq\(dq"
1459 A diacritic mark or a binary operator is found,
1460 but there is nothing to the left of it.
1461 An empty box is inserted.
1463 .Ss "Warnings related to bad macro arguments"
1465 .It Sy "duplicate argument"
1471 macro has more than one
1478 All but the last instances of these arguments are ignored.
1479 .It Sy "skipping duplicate argument"
1483 macro has more than one
1488 All but the first of these arguments are ignored.
1489 .It Sy "skipping duplicate display type"
1493 macro has more than one type argument; the first one is used.
1494 .It Sy "skipping duplicate list type"
1498 macro has more than one type argument; the first one is used.
1499 .It Sy "skipping -width argument"
1513 .It Sy "wrong number of cells"
1516 list, the number of tabs or
1518 macros is less than the number expected from the list header line
1519 or exceeds the expected number by more than one.
1520 Missing cells remain empty, and all cells exceeding the number of
1521 columns are joined into one single cell.
1522 .It Sy "unknown AT&T UNIX version"
1526 macro has an invalid argument.
1527 It is used verbatim, with
1530 .It Sy "comma in function argument"
1536 macro contains a comma; it should probably be split into two arguments.
1537 .It Sy "parenthesis in function name"
1539 The first argument of an
1543 macro contains an opening or closing parenthesis; that's probably wrong,
1544 parentheses are added automatically.
1545 .It Sy "unknown library name"
1549 macro has an unknown name argument and will be rendered as
1550 .Qq library Dq Ar name .
1551 .It Sy "invalid content in Rs block"
1555 block contains plain text or non-% macros.
1556 The bogus content is left in the syntax tree.
1557 Formatting may be poor.
1558 .It Sy "invalid Boolean argument"
1562 macro has an argument other than
1566 The invalid argument is moved out of the macro, which leaves the macro
1567 empty, causing it to toggle the spacing mode.
1568 .It Sy "unknown font, skipping request"
1576 layout modifier has an unknown
1579 .It Sy "odd number of characters in request"
1583 request contains an odd number of characters.
1584 The last character is mapped to the blank character.
1586 .Ss "Warnings related to plain text"
1588 .It Sy "blank line in fill mode, using .sp"
1590 The meaning of blank input lines is only well-defined in non-fill mode:
1591 In fill mode, line breaks of text input lines are not supposed to be
1593 However, for compatibility with groff, blank lines in fill mode
1597 .It Sy "tab in filled text"
1599 The meaning of tab characters is only well-defined in non-fill mode:
1600 In fill mode, whitespace is not supposed to be significant
1601 on text input lines.
1602 As an implementation dependent choice, tab characters on text lines
1603 are passed through to the formatters in any case.
1604 Given that the text before the tab character will be filled,
1605 it is hard to predict which tab stop position the tab will advance to.
1606 .It Sy "new sentence, new line"
1608 A new sentence starts in the middle of a text line.
1609 Start it on a new input line to help formatters produce correct spacing.
1610 .It Sy "invalid escape sequence"
1612 An escape sequence has an invalid opening argument delimiter, lacks the
1613 closing argument delimiter, or the argument has too few characters.
1614 If the argument is incomplete,
1618 expand to an empty string,
1624 to the length of the incomplete argument.
1625 All other invalid escape sequences are ignored.
1626 .It Sy "undefined string, using \(dq\(dq"
1628 If a string is used without being defined before,
1629 its value is implicitly set to the empty string.
1630 However, defining strings explicitly before use
1631 keeps the code more readable.
1633 .Ss "Warnings related to tables"
1635 .It Sy "tbl line starts with span"
1637 The first cell in a table layout line is a horizontal span
1639 Data provided for this cell is ignored, and nothing is printed in the cell.
1640 .It Sy "tbl column starts with span"
1642 The first line of a table layout specification
1643 requests a vertical span
1645 Data provided for this cell is ignored, and nothing is printed in the cell.
1646 .It Sy "skipping vertical bar in tbl layout"
1648 A table layout specification contains more than two consecutive vertical bars.
1649 A double bar is printed, all additional bars are discarded.
1651 .Ss "Errors related to tables"
1653 .It Sy "non-alphabetic character in tbl options"
1655 The table options line contains a character other than a letter,
1656 blank, or comma where the beginning of an option name is expected.
1657 The character is ignored.
1658 .It Sy "skipping unknown tbl option"
1660 The table options line contains a string of letters that does not
1661 match any known option name.
1662 The word is ignored.
1663 .It Sy "missing tbl option argument"
1665 A table option that requires an argument is not followed by an
1666 opening parenthesis, or the opening parenthesis is immediately
1667 followed by a closing parenthesis.
1668 The option is ignored.
1669 .It Sy "wrong tbl option argument size"
1671 A table option argument contains an invalid number of characters.
1672 Both the option and the argument are ignored.
1673 .It Sy "empty tbl layout"
1675 A table layout specification is completely empty,
1676 specifying zero lines and zero columns.
1677 As a fallback, a single left-justified column is used.
1678 .It Sy "invalid character in tbl layout"
1680 A table layout specification contains a character that can neither
1681 be interpreted as a layout key character nor as a layout modifier,
1682 or a modifier precedes the first key.
1683 The invalid character is discarded.
1684 .It Sy "unmatched parenthesis in tbl layout"
1686 A table layout specification contains an opening parenthesis,
1687 but no matching closing parenthesis.
1688 The rest of the input line, starting from the parenthesis, has no effect.
1689 .It Sy "tbl without any data cells"
1691 A table does not contain any data cells.
1692 It will probably produce no output.
1693 .It Sy "ignoring data in spanned tbl cell"
1695 A table cell is marked as a horizontal span
1699 in the table layout, but it contains data.
1700 The data is ignored.
1701 .It Sy "ignoring extra tbl data cells"
1703 A data line contains more cells than the corresponding layout line.
1704 The data in the extra cells is ignored.
1705 .It Sy "data block open at end of tbl"
1707 A data block is opened with
1709 but never closed with a matching
1711 The remaining data lines of the table are all put into one cell,
1712 and any remaining cells stay empty.
1714 .Ss "Errors related to roff, mdoc, and man code"
1716 .It Sy "duplicate prologue macro"
1718 One of the prologue macros occurs more than once.
1719 The last instance overrides all previous ones.
1720 .It Sy "skipping late title macro"
1724 macro appears after the first non-prologue macro.
1725 Traditional formatters cannot handle this because
1726 they write the page header before parsing the document body.
1727 Even though this technical restriction does not apply to
1729 traditional semantics is preserved.
1730 The late macro is discarded including its arguments.
1731 .It Sy "input stack limit exceeded, infinite loop?"
1733 Explicit recursion limits are implemented for the following features,
1734 in order to prevent infinite loops:
1737 expansion of nested escape sequences
1738 including expansion of strings and number registers,
1740 expansion of nested user-defined macros,
1746 When a limit is hit, the output is incorrect, typically losing
1747 some content, but the parser can continue.
1748 .It Sy "skipping bad character"
1749 .Pq mdoc , man , roff
1750 The input file contains a byte that is not a printable
1753 The message mentions the character number.
1754 The offending byte is replaced with a question mark
1756 Consider editing the input file to replace the byte with an ASCII
1757 transliteration of the intended character.
1758 .It Sy "skipping unknown macro"
1759 .Pq mdoc , man , roff
1760 The first identifier on a request or macro line is neither recognized as a
1762 request, nor as a user-defined macro, nor, respectively, as an
1767 It may be mistyped or unsupported.
1768 The request or macro is discarded including its arguments.
1769 .It Sy "skipping insecure request"
1771 An input file attempted to run a shell command
1772 or to read or write an external file.
1773 Such attempts are denied for security reasons.
1774 .It Sy "skipping item outside list"
1778 macro occurs outside any
1783 delimiter occurs outside any pile.
1784 It is discarded including its arguments.
1785 .It Sy "skipping column outside column list"
1789 macro occurs outside any
1792 It is discarded including its arguments.
1793 .It Sy "skipping end of block that is not open"
1794 .Pq mdoc , man , eqn , tbl , roff
1795 Various syntax elements can only be used to explicitly close blocks
1796 that have previously been opened.
1799 block closing macro, a
1806 right delimiter or closing brace, or the end of an equation, table, or
1808 conditional request is encountered but no matching block is open.
1809 The offending request or macro is discarded.
1810 .It Sy "fewer RS blocks open, skipping"
1814 macro is invoked with an argument, but less than the specified number of
1820 .It Sy "inserting missing end of block"
1824 macros as well as tables require explicit closing by dedicated macros.
1825 A block that doesn't support bad nesting
1826 ends before all of its children are properly closed.
1827 The open child nodes are closed implicitly.
1828 .It Sy "appending missing end of block"
1829 .Pq mdoc , man , eqn , tbl , roff
1830 At the end of the document, an explicit
1838 block, an equation, table, or
1840 conditional or ignore block is still open.
1841 The open block is closed implicitly.
1842 .It Sy "escaped character not allowed in a name"
1844 Macro, string and register identifiers consist of printable,
1845 non-whitespace ASCII characters.
1846 Escape sequences and characters and strings expressed in terms of them
1847 cannot form part of a name.
1848 The first argument of an
1856 request, or any argument of an
1858 request, or the name of a request or user defined macro being called,
1859 is terminated by an escape sequence.
1865 the request has no effect at all.
1872 what was parsed up to this point is used as the arguments to the request,
1873 and the rest of the input line is discarded including the escape sequence.
1874 When parsing for a request or a user-defined macro name to be called,
1875 only the escape sequence is discarded.
1876 The characters preceding it are used as the request or macro name,
1877 the characters following it are used as the arguments to the request or macro.
1878 .It Sy "NOT IMPLEMENTED: Bd -file"
1880 For security reasons, the
1882 macro does not support the
1885 By requesting the inclusion of a sensitive file, a malicious document
1886 might otherwise trick a privileged user into inadvertently displaying
1887 the file on the screen, revealing the file content to bystanders.
1888 The argument is ignored including the file name following it.
1889 .It Sy "skipping display without arguments"
1893 block macro does not have any arguments.
1894 The block is discarded, and the block content is displayed in
1895 whatever mode was active before the block.
1896 .It Sy "missing list type, using -item"
1900 macro fails to specify the list type.
1901 .It Sy "argument is not numeric, using 1"
1905 request is not a number.
1906 .It Sy "missing manual name, using \(dq\(dq"
1910 or any call in the NAME section, lacks the required argument.
1911 .It Sy "uname(3) system call failed, using UNKNOWN"
1915 macro is called without arguments, and the
1920 can be compiled with
1922 .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
1924 .It Sy "unknown standard specifier"
1928 macro has an unknown argument and is discarded.
1929 .It Sy "skipping request without numeric argument"
1938 statement has a non-numeric or negative argument or no argument at all.
1939 The invalid request or statement is ignored.
1940 .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
1942 For security reasons,
1946 file inclusion requests only with relative paths
1947 and only without ascending to any parent directory.
1948 By requesting the inclusion of a sensitive file, a malicious document
1949 might otherwise trick a privileged user into inadvertently displaying
1950 the file on the screen, revealing the file content to bystanders.
1952 only shows the path as it appears behind
1954 .It Sy ".so request failed"
1958 request requires reading an external file, but the file could not be
1961 only shows the path as it appears behind
1963 .It Sy "skipping all arguments"
1964 .Pq mdoc , man , eqn , roff
1980 macro in a list that don't support item heads, a
1999 block closing request is invoked with at least one argument.
2000 All arguments are ignored.
2001 .It Sy "skipping excess arguments"
2002 .Pq mdoc , man , roff
2003 A macro or request is invoked with too many arguments:
2004 .Bl -dash -offset 2n -width 2n -compact
2014 with more than one argument
2017 with another argument after
2023 with more than one argument or with a non-integer argument
2028 family with more than two arguments
2031 with more than three arguments
2034 with more than five arguments
2040 with invalid arguments
2042 The excess arguments are ignored.
2044 .Ss Unsupported features
2046 .It Sy "input too large"
2050 cannot handle input files larger than its arbitrary size limit
2051 of 2^31 bytes (2 Gigabytes).
2052 Since useful manuals are always small, this is not a problem in practice.
2053 Parsing is aborted as soon as the condition is detected.
2054 .It Sy "unsupported control character"
2056 An ASCII control character supported by other
2058 implementations but not by
2060 was found in an input file.
2061 It is replaced by a question mark.
2062 .It Sy "unsupported roff request"
2064 An input file contains a
2066 request supported by GNU troff or Heirloom troff but not by
2068 and it is likely that this will cause information loss
2069 or considerable misformatting.
2070 .It Sy "eqn delim option in tbl"
2072 The options line of a table defines equation delimiters.
2073 Any equation source code contained in the table will be printed unformatted.
2074 .It Sy "unsupported table layout modifier"
2076 A table layout specification contains an
2079 The modifier is discarded.
2080 .It Sy "ignoring macro in table"
2081 .Pq tbl , mdoc , man
2082 A table contains an invocation of an
2086 macro or of an undefined macro.
2087 The macro is ignored, and its arguments are handled
2088 as if they were a text line.
2100 utility first appeared in
2114 utility was written by
2115 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
2116 and is maintained by
2117 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .