1 .\" $OpenBSD: mandoc.1,v 1.166 2020/02/15 15:28:01 schwarze Exp $
3 .\" Copyright (c) 2012, 2014-2021 Ingo Schwarze <schwarze@openbsd.org>
4 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
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: August 14 2021 $
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 are also supported and are documented in
233 also supports the options
240 are mutually exclusive and override each other.
244 to force text output in 7-bit ASCII character encoding documented in the
246 manual page, ignoring the
248 set in the environment.
250 Font styles are applied by using back-spaced encoding such that an
254 .Sq _ Ns \e[bs] Ns c ,
257 is the back-space character number 8.
258 Emboldened characters are rendered as
259 .Sq c Ns \e[bs] Ns c .
260 This markup is typically converted to appropriate terminal sequences by
263 To remove the markup, pipe the output to
268 The special characters documented in
270 are rendered best-effort in an ASCII equivalent.
271 In particular, opening and closing
273 are represented as characters number 0x60 and 0x27, respectively,
274 which agrees with all ASCII standards from 1965 to the latest
275 revision (2012) and which matches the traditional way in which
277 formatters represent single quotes in ASCII output.
278 This correct ASCII rendering may look strange with modern
279 Unicode-compatible fonts because contrary to ASCII, Unicode uses
280 the code point U+0060 for the grave accent only, never for an opening
285 arguments are accepted:
287 .It Cm indent Ns = Ns Ar indent
288 The left margin for normal text is set to
290 blank characters instead of the default of five for
294 Increasing this is not recommended; it may result in degraded formatting,
295 for example overfull lines or ugly line breaks.
296 When output is to a pager on a terminal that is less than 66 columns
297 wide, the default is reduced to three columns.
304 This prints the operating system name rather than the page title
305 on the right side of the footer line, and it implies
306 .Fl O Cm indent Ns =5 .
307 One useful application is for checking that
309 output formats in the same way as the
311 source it was generated from.
312 .It Cm tag Ns Op = Ns Ar term
313 If the formatted manual page is opened in a pager,
314 go to the definition of the
316 rather than showing the manual page from the beginning.
319 is specified, reuse the first command line argument that is not a
322 If that argument is in
324 .Ar key Ns = Ns Ar val
327 is used rather than the argument as a whole.
328 This is useful for commands like
329 .Ql man -akO tag Ic=ulimit
330 to search for a keyword and jump right to its definition
331 in the matching manual pages.
332 .It Cm width Ns = Ns Ar width
333 The output width is set to
335 instead of the default of 78.
336 When output is to a pager on a terminal that is less than 79 columns
337 wide, the default is reduced to one less than the terminal width.
338 In any case, lines that are output in literal mode are never wrapped
339 and may exceed the output width.
344 conforms to HTML5 using optional self-closing tags.
345 Default styles use only CSS1.
346 Equations rendered from
351 .Pa /usr/share/misc/mandoc.css
352 documents style-sheet classes available for customising output.
353 If a style-sheet is not specified with
356 defaults to simple output (via an embedded style-sheet)
357 readable in any graphical or text-based web
360 Non-ASCII characters are rendered
361 as hexadecimal Unicode character references.
365 arguments are accepted:
368 Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body>
369 elements and only emit the subtree below the <body> element.
372 argument will be ignored.
373 This is useful when embedding manual content within existing documents.
374 .It Cm includes Ns = Ns Ar fmt
379 is used as a template for linked header files (usually via the
384 are replaced with the include filename.
385 The default is not to present a
387 .It Cm man Ns = Ns Ar fmt Ns Op ; Ns Ar fmt
391 .Ar ../html%S/%N.%S.html ,
392 is used as a template for linked manuals (usually via the
399 are replaced with the linked manual's name and section, respectively.
400 If no section is included, section 1 is assumed.
401 The default is not to
403 If two formats are given and a file
405 exists in the current directory, the first format is used;
406 otherwise, the second format is used.
407 .It Cm style Ns = Ns Ar style.css
410 is used for an external style-sheet.
411 This must be a valid absolute or
413 .It Cm tag Ns Op = Ns Ar term
414 Same syntax and semantics as for
416 This is implemented by passing a
418 URI ending in a fragment identifier to the pager
419 rather than passing merely a file name.
420 When using this argument, use a pager supporting such URIs, for example
421 .Bd -literal -offset 3n
422 MANPAGER='lynx -force_html' man -T html -O tag=MANPAGER man
423 MANPAGER='w3m -T text/html' man -T html -O tag=toc mandoc
426 Consequently, for HTML output, this argument does not work with
431 .Ql MANPAGER=less man -T html -O tag=toc mandoc
432 does not work because
438 If an input file contains at least two non-standard sections,
439 print a table of contents near the beginning of the output.
444 automatically selects UTF-8 or ASCII output according to the current
446 If any of the environment variables
451 are set and the first one that is set
452 selects the UTF-8 character encoding, it produces
454 otherwise, it falls back to
456 This output mode can also be selected explicitly with
466 This is useful for distributing manual sources to legacy systems
474 code is not supported.
476 If the input format of a file is
478 the input is copied to the output.
479 The parser is also run, and as usual, the
483 are displayed before copying the input to the output.
489 input to the markdown format conforming to
490 .Lk http://daringfireball.net/projects/markdown/syntax.text\
491 "John Gruber's 2004 specification" .
492 The output also almost conforms to the
493 .Lk http://commonmark.org/ CommonMark
496 The character set used for the markdown output is ASCII.
497 Non-ASCII characters are encoded as HTML entities.
498 Since that is not possible in literal font contexts, because these
499 are rendered as code spans and code blocks in the markdown output,
500 non-ASCII characters are transliterated to ASCII approximations in
503 Markdown is a very weak markup language, so all semantic markup is
504 lost, and even part of the presentational markup may be lost.
505 Do not use this as an intermediate step in converting to HTML;
515 input languages are not supported by
519 PDF-1.1 output may be generated by
522 .Sx PostScript Output
525 arguments and defaults.
526 .Ss PostScript Output
529 Level-2 pages may be generated by
531 Output pages default to letter sized and are rendered in the Times font
533 Margins are calculated as 1/9 the page length and width.
536 Special characters are rendered as in
541 arguments are accepted:
543 .It Cm paper Ns = Ns Ar name
553 You may also manually specify dimensions as
555 width by height in millimetres.
556 If an unknown value is encountered,
563 to force text output in UTF-8 multi-byte character encoding,
566 settings in the environment.
569 regarding font styles and
573 On operating systems lacking locale or wide character support, and
574 on those where the internal character representation is not UCS-4,
578 .Ss Syntax tree output
581 to show a human readable representation of the syntax tree.
582 It is useful for debugging the source code of manual pages.
583 The exact format is subject to change, so don't write parsers for it.
585 The first paragraph shows meta data found in the
590 line, or the fallbacks used.
592 In the tree dump, each output line shows one syntax tree node.
593 Child nodes are indented with respect to their parent node.
598 For macro nodes, the macro name; for text and
601 There is a special format for
605 Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
610 An opening parenthesis if the node is an opening delimiter.
612 An asterisk if the node starts a new input line.
614 The input line number (starting at one).
618 The input column number (starting at one).
620 A closing parenthesis if the node is a closing delimiter.
622 A full stop if the node ends a sentence.
624 BROKEN if the node is a block broken by another block.
626 NOSRC if the node is not in the input file,
627 but automatically generated from macros.
629 NOPRT if the node is not supposed to generate output
630 for any output format.
636 argument is accepted:
639 Skip validation and show the unvalidated syntax tree.
640 This can help to find out whether a given behaviour is caused by
641 the parser or by the validator.
642 Meta data is not available in this case.
645 .Bl -tag -width MANPAGER
647 The character encoding
651 is selected, it decides whether to use ASCII or UTF-8 output format.
652 It never affects the interpretation of input files.
654 Any non-empty value of the environment variable
656 is used instead of the standard pagination program,
667 Specifies the pagination program to use when
670 If neither PAGER nor MANPAGER is defined,
682 utility exits with one of the following values, controlled by the message
688 .Bl -tag -width Ds -compact
690 No base system convention violations, style suggestions, warnings,
691 or errors occurred, or those that did were ignored because they
692 were lower than the requested
695 At least one base system convention violation or style suggestion
696 occurred, but no warning or error, and
702 At least one warning occurred, but no error, and
708 At least one parsing error occurred,
709 but no unsupported feature was encountered, and
715 At least one unsupported feature was encountered, and
721 Invalid command line arguments were specified.
722 No input files have been read.
724 An operating system error occurred, for example exhaustion
725 of memory, file descriptors, or process table entries.
726 Such errors may cause
728 to exit at once, possibly in the middle of parsing or formatting a file.
736 To page manuals to the terminal:
738 .Dl $ mandoc -l mandoc.1 man.1 apropos.1 makewhatis.8
740 To produce HTML manuals with
741 .Pa /usr/share/misc/mandoc.css
744 .Dl $ mandoc \-T html -O style=/usr/share/misc/mandoc.css mdoc.7 > mdoc.7.html
746 To check over a large set of manuals:
748 .Dl $ mandoc \-T lint \(gafind /usr/src -name \e*\e.[1-9]\(ga
750 To produce a series of PostScript manuals for A4 paper:
752 .Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 > manuals.ps
758 format, for use on systems lacking an
762 .Dl $ mandoc \-T man foo.mdoc > foo.man
764 Messages displayed by
767 .Bd -ragged -offset indent
769 .Ar file : Ns Ar line : Ns Ar column : level : message : macro arguments
773 The first three fields identify the
779 number of the input file where the message was triggered.
780 The line and column numbers start at 1.
781 Both are omitted for messages referring to an input file as a whole.
786 strings are explained below.
789 triggering the message and its
791 are omitted where meaningless.
794 operating system specifier is omitted for messages that are relevant
795 for all operating systems.
796 Fatal messages about invalid command line arguments
797 or operating system errors, for example when memory is exhausted,
804 Message levels have the following meanings:
805 .Bl -tag -width "warning"
807 An operating system error occurred.
808 There isn't necessarily anything wrong with the input files.
809 Output may all the same be missing or incomplete.
811 Invalid command line arguments were specified.
812 No input files have been read and no output is produced.
814 An input file uses unsupported low-level
817 The output may be incomplete and/or misformatted,
818 so using GNU troff instead of
820 to process the file may be preferable.
822 Indicates a risk of information loss or severe misformatting,
823 in most cases caused by serious syntax errors.
825 Indicates a risk that the information shown or its formatting
826 may mismatch the author's intent in minor ways.
827 Additionally, syntax errors are classified at least as warnings,
828 even if they do not usually cause misformatting.
830 An input file uses dubious or discouraged style.
831 This is not a complaint about the syntax, and probably neither
832 formatting nor portability are in danger.
833 While great care is taken to avoid false positives on the higher
836 level tries to reduce the probability that issues go unnoticed,
837 so it may occasionally issue bogus suggestions.
838 Please use your good judgement to decide whether any particular
840 suggestion really justifies a change to the input file.
842 A convention used in the base system of a specific operating system
844 These are not markup mistakes, and neither the quality of formatting
845 nor portability are in danger.
848 level are printed with the more intuitive
861 levels are hidden unless their level, or a lower level, is requested using a
867 As indicated below, all
871 checks are only performed if a specific operating system name occurs
872 in the arguments of the
874 command line option, of the
878 command line option, or, if neither are present, in the return value
882 .Ss Conventions for base system manuals
884 .It Sy "Mdocdate found"
890 keyword substitution, which is not supported by the
893 Consider using the conventional
896 .It Sy "Mdocdate missing"
900 macro does not use CVS
902 keyword substitution, but using it is conventionally expected in the
905 .It Sy "unknown architecture"
907 The third argument of the
909 macro does not match any of the architectures this operating system
911 .It Sy "operating system explicitly specified"
915 macro has an argument.
916 In the base system, it is conventionally left blank.
917 .It Sy "RCS id missing"
919 The manual page lacks the comment line with the RCS identifier
924 keyword substitution as conventionally used in these operating systems.
926 .Ss Style suggestions
928 .It Sy "legacy man(7) date format"
932 macro uses the legacy
936 Consider using the conventional
941 .It Sy "normalizing date format to" : No ...
947 macro provides an abbreviated month name or a day number with a
949 In the formatted output, the month name is written out in full
950 and the leading zero is omitted.
951 .It Sy "lower case character in document title"
953 The title is still used as given in the
958 .It Sy "duplicate RCS id"
959 A single manual page contains two copies of the RCS identifier for
960 the same operating system.
961 Consider deleting the later instance and moving the first one up
962 to the top of the page.
963 .It Sy "possible typo in section name"
965 Fuzzy string matching revealed that the argument of an
967 macro is similar, but not identical to a standard section name.
968 .It Sy "unterminated quoted argument"
970 Macro arguments can be enclosed in double quote characters
971 such that space characters and macro names contained in the quoted
972 argument need not be escaped.
973 The closing quote of the last argument of a macro can be omitted.
974 However, omitting it is not recommended because it makes the code
976 .It Sy "useless macro"
984 Simply delete it: it serves no useful purpose.
985 .It Sy "consider using OS macro"
987 A string was found in plain text or in a
989 macro that could be represented using
995 .It Sy "errnos out of order"
1001 list are not in alphabetical order.
1002 .It Sy "duplicate errno"
1006 list contains two consecutive
1008 entries describing the same
1011 .It Sy "referenced manual not found"
1015 macro references a manual page that was not found.
1018 the search is restricted to the base system, by default to
1019 .Pa /usr/share/man : Ns Pa /usr/X11R6/man .
1020 This path can be configured at compile time using the
1025 the search is done along the full search path as described in the
1027 manual page, respecting the
1031 command line options, the
1033 environment variable, the
1035 file and falling back to the default of
1036 .Pa /usr/share/man : Ns Pa /usr/X11R6/man : Ns Pa /usr/local/man ,
1037 also configurable at compile time using the
1040 .It Sy "trailing delimiter"
1042 The last argument of an
1043 .Ic \&Ex , \&Fo , \&Nd , \&Nm , \&Os , \&Sh , \&Ss , \&St ,
1046 macro ends with a trailing delimiter.
1047 This is usually bad style and often indicates typos.
1048 Most likely, the delimiter can be removed.
1049 .It Sy "no blank before trailing delimiter"
1051 The last argument of a macro that supports trailing delimiter
1052 arguments is longer than one byte and ends with a trailing delimiter.
1053 Consider inserting a blank such that the delimiter becomes a separate
1054 argument, thus moving it out of the scope of the macro.
1055 .It Sy "fill mode already enabled, skipping"
1059 request occurs even though the document is still in fill mode,
1060 or already switched back to fill mode.
1062 .It Sy "fill mode already disabled, skipping"
1066 request occurs even though the document already switched to no-fill mode
1067 and did not switch back to fill mode yet.
1069 .It Sy "input text line longer than 80 bytes"
1070 Consider breaking the input text line
1071 at one of the blank characters before column 80.
1072 .It Sy "verbatim \(dq--\(dq, maybe consider using \e(em"
1074 Even though the ASCII output device renders an em-dash as
1076 that is not a good way to write it in an input file
1077 because it renders poorly on all other output devices.
1078 .It Sy "function name without markup"
1080 A word followed by an empty pair of parentheses occurs on a text line.
1086 .It Sy "whitespace at end of input line"
1087 .Pq mdoc , man , roff
1088 Whitespace at the end of input lines is almost never semantically
1089 significant \(em but in the odd case where it might be, it is
1090 extremely confusing when reviewing and maintaining documents.
1091 .It Sy "bad comment style"
1093 Comment lines start with a dot, a backslash, and a double-quote character.
1096 utility treats the line as a comment line even without the backslash,
1097 but leaving out the backslash might not be portable.
1099 .Ss Warnings related to the document prologue
1101 .It Sy "missing manual title, using UNTITLED"
1105 macro has no arguments, or there is no
1107 macro before the first non-prologue macro.
1108 .It Sy "missing manual title, using \(dq\(dq"
1112 macro, or it has no arguments.
1113 .It Sy "missing manual section, using \(dq\(dq"
1119 macro lacks the mandatory section argument.
1120 .It Sy "unknown manual section"
1122 The section number in a
1124 line is invalid, but still used.
1125 .It Sy "filename/section mismatch"
1127 The name of the input file being processed is known and its file
1128 name extension starts with a non-zero digit, but the
1134 argument that starts with a different non-zero digit.
1137 argument is used as provided anyway.
1138 Consider checking whether the file name or the argument need a correction.
1139 .It Sy "missing date, using \(dq\(dq"
1141 The document was parsed as
1147 macro has no arguments or only empty arguments;
1148 or the document was parsed as
1154 macro has less than three arguments or its third argument is empty.
1155 .It Sy "cannot parse date, using it verbatim"
1161 macro does not follow the conventional format.
1162 .It Sy "date in the future, using it anyway"
1168 macro is more than a day ahead of the current system
1170 .It Sy "missing Os macro, using \(dq\(dq"
1172 The default or current system is not shown in this case.
1173 .It Sy "late prologue macro"
1179 macro occurs after some non-prologue macro, but still takes effect.
1180 .It Sy "prologue macros out of order"
1182 The prologue macros are not given in the conventional order
1186 All three macros are used even when given in another order.
1188 .Ss Warnings regarding document structure
1190 .It Sy ".so is fragile, better use ln(1)"
1192 Including files only works when the parser program runs with the correct
1193 current working directory.
1194 .It Sy "no document body"
1196 The document body contains neither text nor macros.
1197 An empty document is shown, consisting only of a header and a footer line.
1198 .It Sy "content before first section header"
1200 Some macros or text precede the first
1205 The offending macros and text are parsed and added to the top level
1206 of the syntax tree, outside any section block.
1207 .It Sy "first section is not NAME"
1209 The argument of the first
1217 .It Sy "NAME section without Nm before Nd"
1219 The NAME section does not contain any
1221 child macro before the first
1224 .It Sy "NAME section without description"
1226 The NAME section lacks the mandatory
1229 .It Sy "description not at the end of NAME"
1231 The NAME section does contain an
1233 child macro, but other content follows it.
1234 .It Sy "bad NAME section content"
1236 The NAME section contains plain text or macros other than
1240 .It Sy "missing comma before name"
1242 The NAME section contains an
1244 macro that is neither the first one nor preceded by a comma.
1245 .It Sy "missing description line, using \(dq\(dq"
1249 macro lacks the required argument.
1250 The title line of the manual will end after the dash.
1251 .It Sy "description line outside NAME section"
1255 macro appears outside the NAME section.
1256 The arguments are printed anyway and the following text is used for
1258 but none of that behaviour is portable.
1259 .It Sy "sections out of conventional order"
1261 A standard section occurs after another section it usually precedes.
1262 All section titles are used as given,
1263 and the order of sections is not changed.
1264 .It Sy "duplicate section title"
1266 The same standard section title occurs more than once.
1267 .It Sy "unexpected section"
1269 A standard section header occurs in a section of the manual
1270 where it normally isn't useful.
1271 .It Sy "cross reference to self"
1275 macro refers to a name and section matching the section of the present
1276 manual page and a name mentioned in an
1278 macro in the NAME or SYNOPSIS section, or in an
1282 macro in the SYNOPSIS.
1289 .It Sy "unusual Xr order"
1291 In the SEE ALSO section, an
1293 macro with a lower section number follows one with a higher number,
1296 macros referring to the same section are out of alphabetical order.
1297 .It Sy "unusual Xr punctuation"
1299 In the SEE ALSO section, punctuation between two
1301 macros differs from a single comma, or there is trailing punctuation
1305 .It Sy "AUTHORS section without An macro"
1307 An AUTHORS sections contains no
1309 macros, or only empty ones.
1310 Probably, there are author names lacking markup.
1312 .Ss "Warnings related to macros and nesting"
1314 .It Sy "obsolete macro"
1318 manual for replacements.
1319 .It Sy "macro neither callable nor escaped"
1321 The name of a macro that is not callable appears on a macro line.
1322 It is printed verbatim.
1323 If the intention is to call it, move it to its own input line;
1324 otherwise, escape it by prepending
1326 .It Sy "skipping paragraph macro"
1329 documents, this happens
1332 at the beginning and end of sections and subsections
1334 right before non-compact lists and displays
1336 at the end of items in non-column, non-compact lists
1338 and for multiple consecutive paragraph macros.
1342 documents, it happens
1354 macros having neither head nor body arguments
1365 .It Sy "moving paragraph macro out of list"
1369 list contains a trailing paragraph macro.
1370 The paragraph macro is moved after the end of the list.
1371 .It Sy "skipping no-space macro"
1373 An input line begins with an
1375 macro, or the next argument after an
1377 macro is an isolated closing delimiter.
1378 The macro is ignored.
1379 .It Sy "blocks badly nested"
1381 If two blocks intersect, one should completely contain the other.
1382 Otherwise, rendered output is likely to look strange in any output
1383 format, and rendering in SGML-based output formats is likely to be
1384 outright wrong because such languages do not support badly nested
1386 Typical examples of badly nested blocks are
1387 .Qq Ic \&Ao \&Bo \&Ac \&Bc
1389 .Qq Ic \&Ao \&Bq \&Ac .
1397 .It Sy "nested displays are not portable"
1404 display occurs nested inside another
1409 but fails with most other implementations.
1410 .It Sy "moving content out of list"
1414 list block contains text or macros before the first
1417 The offending children are moved before the beginning of the list.
1418 .It Sy "first macro on line"
1423 macro occurs as the first macro on a line, which is not portable.
1424 .It Sy "line scope broken"
1426 While parsing the next-line scope of the previous macro,
1427 another macro is found that prematurely terminates the previous one.
1428 The previous, interrupted macro is deleted from the parse tree.
1430 .Ss "Warnings related to missing arguments"
1432 .It Sy "skipping empty request"
1434 The macro name is missing from a macro definition request,
1437 control statement or operation keyword lacks its required argument.
1438 .It Sy "conditional request controls empty scope"
1440 A conditional request is only useful if any of the following
1441 follows it on the same logical input line:
1446 keyword to open a multi-line scope.
1448 A request or macro or some text, resulting in a single-line scope.
1450 The immediate end of the logical line without any intervening whitespace,
1451 resulting in next-line scope.
1453 Here, a conditional request is followed by trailing whitespace only,
1454 and there is no other content on its logical input line.
1455 Note that it doesn't matter whether the logical input line is split
1456 across multiple physical input lines using
1458 line continuation characters.
1459 This is one of the rare cases
1460 where trailing whitespace is syntactically significant.
1461 The conditional request controls a scope containing whitespace only,
1462 so it is unlikely to have a significant effect,
1463 except that it may control a following
1466 .It Sy "skipping empty macro"
1468 The indicated macro has no arguments and hence no effect.
1469 .It Sy "empty block"
1481 block contains nothing in its body and will produce no output.
1482 .It Sy "empty argument, using 0n"
1484 The required width is missing after
1491 .It Sy "missing display type, using -ragged"
1495 macro is invoked without the required display type.
1496 .It Sy "list type is not the first argument"
1500 macro, at least one other argument precedes the type argument.
1503 utility copes with any argument order, but some other
1505 implementations do not.
1506 .It Sy "missing -width in -tag list, using 8n"
1515 .It Sy "missing utility name, using \(dq\(dq"
1519 macro is called without an argument before
1521 has first been called with an argument.
1522 .It Sy "missing function name, using \(dq\(dq"
1526 macro is called without an argument.
1527 No function name is printed.
1528 .It Sy "empty head in list item"
1540 macro lacks the required argument.
1541 The item head is left empty.
1542 .It Sy "empty list item"
1554 An empty list item is shown.
1555 .It Sy "missing argument, using next line"
1561 list has no arguments.
1564 uses the text or macros of the following line, if any, for the cell,
1565 other formatters may misformat the list.
1566 .It Sy "missing font type, using \efR"
1570 macro has no argument.
1571 It switches to the default font.
1572 .It Sy "unknown font type, using \efR"
1576 argument is invalid.
1577 The default font is used instead.
1578 .It Sy "nothing follows prefix"
1582 macro has no argument, or only one argument and no macro follows
1583 on the same input line.
1584 This defeats its purpose; in particular, spacing is not suppressed
1585 before the text or macros following on the next input line.
1586 .It Sy "empty reference block"
1590 macro is immediately followed by an
1592 macro on the next input line.
1593 Such an empty block does not produce any output.
1594 .It Sy "missing section argument"
1598 macro lacks its second, section number argument.
1599 The first argument, i.e. the name, is printed, but without subsequent
1601 .It Sy "missing -std argument, adding it"
1607 macro lacks the required
1614 even when it is not specified, but other implementations may not.
1615 .It Sy "missing option string, using \(dq\(dq"
1619 macro is invoked without any argument.
1620 An empty pair of square brackets is shown.
1621 .It Sy "missing resource identifier, using \(dq\(dq"
1627 macro is invoked without any argument.
1628 An empty pair of angle brackets is shown.
1629 .It Sy "missing eqn box, using \(dq\(dq"
1631 A diacritic mark or a binary operator is found,
1632 but there is nothing to the left of it.
1633 An empty box is inserted.
1635 .Ss "Warnings related to bad macro arguments"
1637 .It Sy "duplicate argument"
1643 macro has more than one
1650 All but the last instances of these arguments are ignored.
1651 .It Sy "skipping duplicate argument"
1655 macro has more than one
1660 All but the first of these arguments are ignored.
1661 .It Sy "skipping duplicate display type"
1665 macro has more than one type argument; the first one is used.
1666 .It Sy "skipping duplicate list type"
1670 macro has more than one type argument; the first one is used.
1671 .It Sy "skipping -width argument"
1685 .It Sy "wrong number of cells"
1688 list, the number of tabs or
1690 macros is less than the number expected from the list header line
1691 or exceeds the expected number by more than one.
1692 Missing cells remain empty, and all cells exceeding the number of
1693 columns are joined into one single cell.
1694 .It Sy "unknown AT&T UNIX version"
1698 macro has an invalid argument.
1699 It is used verbatim, with
1702 .It Sy "comma in function argument"
1708 macro contains a comma; it should probably be split into two arguments.
1709 .It Sy "parenthesis in function name"
1711 The first argument of an
1715 macro contains an opening or closing parenthesis; that's probably wrong,
1716 parentheses are added automatically.
1717 .It Sy "unknown library name"
1721 macro has an unknown name argument and will be rendered as
1722 .Qq library Dq Ar name .
1723 .It Sy "invalid content in Rs block"
1727 block contains plain text or non-% macros.
1728 The bogus content is left in the syntax tree.
1729 Formatting may be poor.
1730 .It Sy "invalid Boolean argument"
1734 macro has an argument other than
1738 The invalid argument is moved out of the macro, which leaves the macro
1739 empty, causing it to toggle the spacing mode.
1740 .It Sy "argument contains two font escapes"
1742 The second argument of a
1744 request contains more than one font escape sequence.
1745 A wrong font may remain active after using the character.
1746 .It Sy "unknown font, skipping request"
1754 layout modifier has an unknown
1757 .It Sy "odd number of characters in request"
1761 request contains an odd number of characters.
1762 The last character is mapped to the blank character.
1764 .Ss "Warnings related to plain text"
1766 .It Sy "blank line in fill mode, using .sp"
1768 The meaning of blank input lines is only well-defined in non-fill mode:
1769 In fill mode, line breaks of text input lines are not supposed to be
1771 However, for compatibility with groff, blank lines in fill mode
1775 To request a paragraph break, use
1777 instead of a blank line.
1778 .It Sy "tab in filled text"
1780 The meaning of tab characters is only well-defined in non-fill mode:
1781 In fill mode, whitespace is not supposed to be significant
1782 on text input lines.
1783 As an implementation dependent choice, tab characters on text lines
1784 are passed through to the formatters in any case.
1785 Given that the text before the tab character will be filled,
1786 it is hard to predict which tab stop position the tab will advance to.
1787 .It Sy "new sentence, new line"
1789 A new sentence starts in the middle of a text line.
1790 Start it on a new input line to help formatters produce correct spacing.
1791 .It Sy "invalid escape sequence"
1793 An escape sequence has an invalid opening argument delimiter, lacks the
1794 closing argument delimiter, the argument is of an invalid form, or it is
1795 a character escape sequence with an invalid name.
1796 If the argument is incomplete,
1800 expand to an empty string,
1806 to the length of the incomplete argument.
1807 All other invalid escape sequences are ignored.
1808 .It Sy "undefined escape, printing literally"
1810 In an escape sequence, the first character
1811 right after the leading backslash is invalid.
1812 That character is printed literally,
1813 which is equivalent to ignoring the backslash.
1814 .It Sy "undefined string, using \(dq\(dq"
1816 If a string is used without being defined before,
1817 its value is implicitly set to the empty string.
1818 However, defining strings explicitly before use
1819 keeps the code more readable.
1821 .Ss "Warnings related to tables"
1823 .It Sy "tbl line starts with span"
1825 The first cell in a table layout line is a horizontal span
1827 Data provided for this cell is ignored, and nothing is printed in the cell.
1828 .It Sy "tbl column starts with span"
1830 The first line of a table layout specification
1831 requests a vertical span
1833 Data provided for this cell is ignored, and nothing is printed in the cell.
1834 .It Sy "skipping vertical bar in tbl layout"
1836 A table layout specification contains more than two consecutive vertical bars.
1837 A double bar is printed, all additional bars are discarded.
1839 .Ss "Errors related to tables"
1841 .It Sy "non-alphabetic character in tbl options"
1843 The table options line contains a character other than a letter,
1844 blank, or comma where the beginning of an option name is expected.
1845 The character is ignored.
1846 .It Sy "skipping unknown tbl option"
1848 The table options line contains a string of letters that does not
1849 match any known option name.
1850 The word is ignored.
1851 .It Sy "missing tbl option argument"
1853 A table option that requires an argument is not followed by an
1854 opening parenthesis, or the opening parenthesis is immediately
1855 followed by a closing parenthesis.
1856 The option is ignored.
1857 .It Sy "wrong tbl option argument size"
1859 A table option argument contains an invalid number of characters.
1860 Both the option and the argument are ignored.
1861 .It Sy "empty tbl layout"
1863 A table layout specification is completely empty,
1864 specifying zero lines and zero columns.
1865 As a fallback, a single left-justified column is used.
1866 .It Sy "invalid character in tbl layout"
1868 A table layout specification contains a character that can neither
1869 be interpreted as a layout key character nor as a layout modifier,
1870 or a modifier precedes the first key.
1871 The invalid character is discarded.
1872 .It Sy "unmatched parenthesis in tbl layout"
1874 A table layout specification contains an opening parenthesis,
1875 but no matching closing parenthesis.
1876 The rest of the input line, starting from the parenthesis, has no effect.
1877 .It Sy "ignoring excessive spacing in tbl layout"
1879 A spacing modifier in a table layout is unreasonably large.
1880 The default spacing of 3n is used instead.
1881 .It Sy "tbl without any data cells"
1883 A table does not contain any data cells.
1884 It will probably produce no output.
1885 .It Sy "ignoring data in spanned tbl cell"
1887 A table cell is marked as a horizontal span
1891 in the table layout, but it contains data.
1892 The data is ignored.
1893 .It Sy "ignoring extra tbl data cells"
1895 A data line contains more cells than the corresponding layout line.
1896 The data in the extra cells is ignored.
1897 .It Sy "data block open at end of tbl"
1899 A data block is opened with
1901 but never closed with a matching
1903 The remaining data lines of the table are all put into one cell,
1904 and any remaining cells stay empty.
1906 .Ss "Errors related to roff, mdoc, and man code"
1908 .It Sy "duplicate prologue macro"
1910 One of the prologue macros occurs more than once.
1911 The last instance overrides all previous ones.
1912 .It Sy "skipping late title macro"
1916 macro appears after the first non-prologue macro.
1917 Traditional formatters cannot handle this because
1918 they write the page header before parsing the document body.
1919 Even though this technical restriction does not apply to
1921 traditional semantics is preserved.
1922 The late macro is discarded including its arguments.
1923 .It Sy "input stack limit exceeded, infinite loop?"
1925 Explicit recursion limits are implemented for the following features,
1926 in order to prevent infinite loops:
1929 expansion of nested escape sequences
1930 including expansion of strings and number registers,
1932 expansion of nested user-defined macros,
1938 When a limit is hit, the output is incorrect, typically losing
1939 some content, but the parser can continue.
1940 .It Sy "skipping bad character"
1941 .Pq mdoc , man , roff
1942 The input file contains a byte that is not a printable
1945 The message mentions the character number.
1946 The offending byte is replaced with a question mark
1948 Consider editing the input file to replace the byte with an ASCII
1949 transliteration of the intended character.
1950 .It Sy "skipping unknown macro"
1951 .Pq mdoc , man , roff
1952 The first identifier on a request or macro line is neither recognized as a
1954 request, nor as a user-defined macro, nor, respectively, as an
1959 It may be mistyped or unsupported.
1960 The request or macro is discarded including its arguments.
1961 .It Sy "skipping request outside macro"
1967 request occurs outside any macro definition and has no effect.
1968 .It Sy "skipping insecure request"
1970 An input file attempted to run a shell command
1971 or to read or write an external file.
1972 Such attempts are denied for security reasons.
1973 .It Sy "skipping item outside list"
1977 macro occurs outside any
1982 delimiter occurs outside any pile.
1983 It is discarded including its arguments.
1984 .It Sy "skipping column outside column list"
1988 macro occurs outside any
1991 It is discarded including its arguments.
1992 .It Sy "skipping end of block that is not open"
1993 .Pq mdoc , man , eqn , tbl , roff
1994 Various syntax elements can only be used to explicitly close blocks
1995 that have previously been opened.
1998 block closing macro, a
2005 right delimiter or closing brace, or the end of an equation, table, or
2007 conditional request is encountered but no matching block is open.
2008 The offending request or macro is discarded.
2009 .It Sy "fewer RS blocks open, skipping"
2013 macro is invoked with an argument, but less than the specified number of
2019 .It Sy "inserting missing end of block"
2023 macros as well as tables require explicit closing by dedicated macros.
2024 A block that doesn't support bad nesting
2025 ends before all of its children are properly closed.
2026 The open child nodes are closed implicitly.
2027 .It Sy "appending missing end of block"
2028 .Pq mdoc , man , eqn , tbl , roff
2029 At the end of the document, an explicit
2037 block, an equation, table, or
2039 conditional or ignore block is still open.
2040 The open block is closed implicitly.
2041 .It Sy "escaped character not allowed in a name"
2043 Macro, string and register identifiers consist of printable,
2044 non-whitespace ASCII characters.
2045 Escape sequences and characters and strings expressed in terms of them
2046 cannot form part of a name.
2047 The first argument of an
2055 request, or any argument of an
2057 request, or the name of a request or user defined macro being called,
2058 is terminated by an escape sequence.
2064 the request has no effect at all.
2071 what was parsed up to this point is used as the arguments to the request,
2072 and the rest of the input line is discarded including the escape sequence.
2073 When parsing for a request or a user-defined macro name to be called,
2074 only the escape sequence is discarded.
2075 The characters preceding it are used as the request or macro name,
2076 the characters following it are used as the arguments to the request or macro.
2077 .It Sy "using macro argument outside macro"
2079 The escape sequence \e$ occurs outside any macro definition
2080 and expands to the empty string.
2081 .It Sy "argument number is not numeric"
2083 The argument of the escape sequence \e$ is not a digit;
2084 the escape sequence expands to the empty string.
2085 .It Sy "NOT IMPLEMENTED: Bd -file"
2087 For security reasons, the
2089 macro does not support the
2092 By requesting the inclusion of a sensitive file, a malicious document
2093 might otherwise trick a privileged user into inadvertently displaying
2094 the file on the screen, revealing the file content to bystanders.
2095 The argument is ignored including the file name following it.
2096 .It Sy "skipping display without arguments"
2100 block macro does not have any arguments.
2101 The block is discarded, and the block content is displayed in
2102 whatever mode was active before the block.
2103 .It Sy "missing list type, using -item"
2107 macro fails to specify the list type.
2108 .It Sy "argument is not numeric, using 1"
2112 request is not a number.
2113 .It Sy "argument is not a character"
2115 The first argument of a
2117 request is neither a single ASCII character
2118 nor a single character escape sequence.
2119 The request is ignored including all its arguments.
2120 .It Sy "missing manual name, using \(dq\(dq"
2124 or any call in the NAME section, lacks the required argument.
2125 .It Sy "uname(3) system call failed, using UNKNOWN"
2129 macro is called without arguments, and the
2134 can be compiled with
2136 .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
2138 .It Sy "unknown standard specifier"
2142 macro has an unknown argument and is discarded.
2143 .It Sy "skipping request without numeric argument"
2152 statement has a non-numeric or negative argument or no argument at all.
2153 The invalid request or statement is ignored.
2154 .It Sy "excessive shift"
2158 request is larger than the number of arguments of the macro that is
2159 currently being executed.
2160 All macro arguments are deleted and \en(.$ is set to zero.
2161 .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
2163 For security reasons,
2167 file inclusion requests only with relative paths
2168 and only without ascending to any parent directory.
2169 By requesting the inclusion of a sensitive file, a malicious document
2170 might otherwise trick a privileged user into inadvertently displaying
2171 the file on the screen, revealing the file content to bystanders.
2173 only shows the path as it appears behind
2175 .It Sy ".so request failed"
2179 request requires reading an external file, but the file could not be
2182 only shows the path as it appears behind
2184 .It Sy "skipping all arguments"
2185 .Pq mdoc , man , eqn , roff
2201 macro in a list that don't support item heads, a
2220 block closing request is invoked with at least one argument.
2221 All arguments are ignored.
2222 .It Sy "skipping excess arguments"
2223 .Pq mdoc , man , roff
2224 A macro or request is invoked with too many arguments:
2225 .Bl -dash -offset 2n -width 2n -compact
2235 with more than one argument
2238 with another argument after
2244 with more than one argument or with a non-integer argument
2249 family with more than two arguments
2252 with more than three arguments
2255 with more than five arguments
2261 with invalid arguments
2263 The excess arguments are ignored.
2265 .Ss Unsupported features
2267 .It Sy "input too large"
2271 cannot handle input files larger than its arbitrary size limit
2272 of 2^31 bytes (2 Gigabytes).
2273 Since useful manuals are always small, this is not a problem in practice.
2274 Parsing is aborted as soon as the condition is detected.
2275 .It Sy "unsupported control character"
2277 An ASCII control character supported by other
2279 implementations but not by
2281 was found in an input file.
2282 It is replaced by a question mark.
2283 .It Sy "unsupported escape sequence"
2285 An input file contains an escape sequence supported by GNU troff
2286 or Heirloom troff but not by
2288 and it is likely that this will cause information loss
2289 or considerable misformatting.
2290 .It Sy "unsupported roff request"
2292 An input file contains a
2294 request supported by GNU troff or Heirloom troff but not by
2296 and it is likely that this will cause information loss
2297 or considerable misformatting.
2298 .It Sy "eqn delim option in tbl"
2300 The options line of a table defines equation delimiters.
2301 Any equation source code contained in the table will be printed unformatted.
2302 .It Sy "unsupported table layout modifier"
2304 A table layout specification contains an
2307 The modifier is discarded.
2308 .It Sy "ignoring macro in table"
2309 .Pq tbl , mdoc , man
2310 A table contains an invocation of an
2314 macro or of an undefined macro.
2315 The macro is ignored, and its arguments are handled
2316 as if they were a text line.
2317 .It Sy "skipping tbl in -Tman mode"
2319 An input file contains the
2322 This message is only generated in
2326 input is not supported.
2327 .It Sy "skipping eqn in -Tman mode"
2329 An input file contains the
2332 This message is only generated in
2336 input is not supported.
2338 .Ss Bad command line arguments
2340 .It Sy "bad command line argument"
2341 The argument following one of the
2343 command line options is invalid, or a
2345 given as a command line argument cannot be opened.
2346 .It Sy "duplicate command line argument"
2349 command line option was specified twice.
2350 .It Sy "option has a superfluous value"
2353 option has a value but does not accept one.
2354 .It Sy "missing option value"
2357 option has no argument but requires one.
2358 .It Sy "bad option value"
2364 option has an invalid value.
2365 .It Sy "duplicate option value"
2368 option is specified more than once.
2369 .It Sy "no such tag"
2372 option was specified but the tag was not found in any of the displayed
2374 .It Sy "\-Tmarkdown unsupported for man(7) input"
2378 option was specified but an input file uses the
2381 No output is produced for that input file.
2395 utility first appeared in
2409 utility was written by
2410 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
2411 and is maintained by
2412 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .