1 .\" $Id: mandoc.1,v 1.155 2015/02/23 13:31:03 schwarze Exp $
3 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2012, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18 .Dd $Mdocdate: February 23 2015 $
23 .Nd format and display UNIX manuals
28 .Op Fl I Cm os Li = Ar name
30 .Op Fl K Ns Ar encoding
41 manual pages for display.
49 text from stdin, implying
55 The options are as follows:
58 If the standard output is a terminal device and
62 to paginate the output, just like
66 Copy the formatted manual pages to the standard output without using
70 It can be specified to override
75 This overrides any earlier
81 .It Fl I Cm os Li = Ar name
83 Override the default operating system
93 Display only the SYNOPSIS lines.
96 .It Fl K Ns Ar encoding
97 Specify the input encoding.
105 If not specified, autodetection uses the first match:
106 .Bl -tag -width iso-8859-1
108 if the first three bytes of the input file
109 are the UTF-8 byte order mark (BOM, 0xefbbbf)
111 if the first or second line of the input file matches the
115 .D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*-
117 if the first non-ASCII byte in the file introduces a valid UTF-8 sequence
124 .It Fl m Ns Ar format
128 for available formats.
131 .It Fl O Ns Ar option
132 Comma-separated output options.
133 .It Fl T Ns Ar output
137 for available formats.
141 Specify the minimum message
143 to be reported on the standard error output and to affect the exit status.
167 to exit after parsing a file that causes warnings or errors of at least
169 No formatted output will be produced from that file.
174 are requested, they can be joined with a comma, for example
175 .Fl W Ns Cm error , Ns Cm stop .
177 Read input from zero or more files.
178 If unspecified, reads from stdin.
179 If multiple files are specified,
181 will halt with the first failed parse.
201 should only be used for legacy manuals.
205 which is also the default, determines encoding on-the-fly: if the first
212 parser is used; otherwise, the
217 files are specified with
219 each has its file-type determined this way.
220 If multiple files are
225 is specified, then this format is used exclusively.
229 utility accepts the following
231 arguments, which correspond to output modes:
232 .Bl -tag -width "-Tlocale"
234 Produce 7-bit ASCII output.
238 Produce HTML5, CSS1, and MathML output.
242 Parse only: produce no output.
244 .Fl W Ns Cm warning .
245 .It Fl T Ns Cm locale
246 Encode output using the current locale.
261 Produce PostScript output.
263 .Sx PostScript Output .
265 Produce an indented parse tree.
267 Encode output in the UTF\-8 multi-byte format.
271 This is a synonym for
275 If multiple input files are specified, these will be processed by the
276 corresponding filter in-order.
280 is rendered in standard 7-bit ASCII documented in
283 Font styles are applied by using back-spaced encoding such that an
287 .Sq _ Ns \e[bs] Ns c ,
290 is the back-space character number 8.
291 Emboldened characters are rendered as
292 .Sq c Ns \e[bs] Ns c .
294 The special characters documented in
296 are rendered best-effort in an ASCII equivalent.
298 Output width is limited to 78 visible columns unless literal input lines
303 arguments are accepted:
305 .It Cm indent Ns = Ns Ar indent
306 The left margin for normal text is set to
308 blank characters instead of the default of five for
312 Increasing this is not recommended; it may result in degraded formatting,
313 for example overfull lines or ugly line breaks.
314 .It Cm width Ns = Ns Ar width
315 The output width is set to
317 which will normalise to \(>=58.
322 conforms to HTML5 using optional self-closing tags.
323 Default styles use only CSS1.
324 Equations rendered from
329 .Pa example.style.css
330 file documents style-sheet classes available for customising output.
331 If a style-sheet is not specified with
334 defaults to simple output (via an embedded style-sheet)
335 readable in any graphical or text-based web
338 Special characters are rendered in decimal-encoded UTF\-8.
342 arguments are accepted:
345 Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body>
346 elements and only emit the subtree below the <body> element.
349 argument will be ignored.
350 This is useful when embedding manual content within existing documents.
351 .It Cm includes Ns = Ns Ar fmt
356 is used as a template for linked header files (usually via the
361 are replaced with the include filename.
362 The default is not to present a
364 .It Cm man Ns = Ns Ar fmt
368 .Ar ../html%S/%N.%S.html ,
369 is used as a template for linked manuals (usually via the
376 are replaced with the linked manual's name and section, respectively.
377 If no section is included, section 1 is assumed.
378 The default is not to
380 .It Cm style Ns = Ns Ar style.css
383 is used for an external style-sheet.
384 This must be a valid absolute or
388 Locale-depending output encoding is triggered with
392 Translate input format into
395 This is useful for distributing manual sources to legacy systems
402 is passed as input, it is translated into
404 If the input format is
406 the input is copied to the output, expanding any
410 The parser is also run, and as usual, the
414 are displayed before copying the input to the output.
416 PDF-1.1 output may be generated by
419 .Sx PostScript Output
422 arguments and defaults.
423 .Ss PostScript Output
426 Level-2 pages may be generated by
428 Output pages default to letter sized and are rendered in the Times font
430 Margins are calculated as 1/9 the page length and width.
433 Special characters are rendered as in
438 arguments are accepted:
440 .It Cm paper Ns = Ns Ar name
450 You may also manually specify dimensions as
452 width by height in millimetres.
453 If an unknown value is encountered,
460 to force a UTF\-8 locale.
463 for details and options.
467 utility exits with one of the following values, controlled by the message
473 .Bl -tag -width Ds -compact
475 No warnings or errors occurred, or those that did were ignored because
476 they were lower than the requested
479 At least one warning occurred, but no error, and
483 At least one parsing error occurred,
484 but no unsupported feature was encountered, and
490 At least one unsupported feature was encountered, and
497 Invalid command line arguments were specified.
498 No input files have been read.
500 An operating system error occurred, for example exhaustion
501 of memory, file descriptors, or process table entries.
504 to exit at once, possibly in the middle of parsing or formatting a file.
510 .Fl W Ns Cm warning .
512 To page manuals to the terminal:
514 .Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less
515 .Dl $ mandoc mandoc.1 mdoc.3 mdoc.5 | less
517 To produce HTML manuals with
521 .Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.5 \*(Gt mdoc.5.html
523 To check over a large set of manuals:
525 .Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]`
527 To produce a series of PostScript manuals for A4 paper:
529 .Dl $ mandoc \-Tps \-Opaper=a4 mdoc.5 man.5 \*(Gt manuals.ps
535 format, for use on systems lacking an
539 .Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man
541 Messages displayed by
545 .D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args
547 Line and column numbers start at 1.
548 Both are omitted for messages referring to an input file as a whole.
549 Macro names and arguments are omitted where meaningless.
550 Fatal messages about invalid command line arguments
551 or operating system errors, for example when memory is exhausted,
558 Message levels have the following meanings:
559 .Bl -tag -width "warning"
561 An input file uses unsupported low-level
564 The output may be incomplete and/or misformatted,
565 so using GNU troff instead of
567 to process the file may be preferable.
569 An input file contains invalid syntax that cannot be safely interpreted.
570 By discarding part of the input or inserting missing tokens,
571 the parser is able to continue, and the error does not prevent
572 generation of formatted output, but typically, preparing that
573 output involves information loss, broken document structure
574 or unintended formatting, no matter whether
576 or GNU troff is used.
577 In many cases, the output of
579 and GNU troff is identical, but in some,
581 is more resilient than GNU troff with respect to malformed input.
583 Non-existent or unreadable input files are also reported on the
586 In that case, the parser cannot even be started and no output
587 is produced from those input files.
589 An input file uses obsolete, discouraged or non-portable syntax.
590 All the same, the meaning of the input is unambiguous and a correct
591 rendering can be produced.
592 Documents causing warnings may render poorly when using other
593 formatting tools instead of
602 levels except those about non-existent or unreadable input files
603 are hidden unless their level, or a lower level, is requested using a
608 .Ss Warnings related to the document prologue
610 .It Sy "missing manual title, using UNTITLED"
614 macro has no arguments, or there is no
616 macro before the first non-prologue macro.
617 .It Sy "missing manual title, using \(dq\(dq"
621 macro, or it has no arguments.
622 .It Sy "lower case character in document title"
624 The title is still used as given in the
629 .It Sy "missing manual section, using \(dq\(dq"
635 macro lacks the mandatory section argument.
636 .It Sy "unknown manual section"
638 The section number in a
640 line is invalid, but still used.
641 .It Sy "missing date, using today's date"
643 The document was parsed as
649 macro has no arguments or only empty arguments;
650 or the document was parsed as
656 macro has less than three arguments or its third argument is empty.
657 .It Sy "cannot parse date, using it verbatim"
663 macro does not follow the conventional format.
664 .It Sy "missing Os macro, using \(dq\(dq"
666 The default or current system is not shown in this case.
667 .It Sy "duplicate prologue macro"
669 One of the prologue macros occurs more than once.
670 The last instance overrides all previous ones.
671 .It Sy "late prologue macro"
677 macro occurs after some non-prologue macro, but still takes effect.
678 .It Sy "skipping late title macro"
682 macro appears after the first non-prologue macro.
683 Traditional formatters cannot handle this because
684 they write the page header before parsing the document body.
685 Even though this technical restriction does not apply to
687 traditional semantics is preserved.
688 The late macro is discarded including its arguments.
689 .It Sy "prologue macros out of order"
691 The prologue macros are not given in the conventional order
695 All three macros are used even when given in another order.
697 .Ss Warnings regarding document structure
699 .It Sy ".so is fragile, better use ln(1)"
701 Including files only works when the parser program runs with the correct
702 current working directory.
703 .It Sy "no document body"
705 The document body contains neither text nor macros.
706 An empty document is shown, consisting only of a header and a footer line.
707 .It Sy "content before first section header"
709 Some macros or text precede the first
714 The offending macros and text are parsed and added to the top level
715 of the syntax tree, outside any section block.
716 .It Sy "first section is not NAME"
718 The argument of the first
726 .It Sy "NAME section without name"
728 The NAME section does not contain any
731 .It Sy "NAME section without description"
733 The NAME section lacks the mandatory
736 .It Sy "description not at the end of NAME"
738 The NAME section does contain an
740 child macro, but other content follows it.
741 .It Sy "bad NAME section content"
743 The NAME section contains plain text or macros other than
747 .It Sy "missing description line, using \(dq\(dq"
751 macro lacks the required argument.
752 The title line of the manual will end after the dash.
753 .It Sy "sections out of conventional order"
755 A standard section occurs after another section it usually precedes.
756 All section titles are used as given,
757 and the order of sections is not changed.
758 .It Sy "duplicate section title"
760 The same standard section title occurs more than once.
761 .It Sy "unexpected section"
763 A standard section header occurs in a section of the manual
764 where it normally isn't useful.
765 .It Sy "unusual Xr order"
767 In the SEE ALSO section, an
769 macro with a lower section number follows one with a higher number,
772 macros refering to the same section are out of alphabetical order.
773 .It Sy "unusual Xr punctuation"
775 In the SEE ALSO section, punctuation between two
777 macros differs from a single comma, or there is trailing punctuation
781 .It Sy "AUTHORS section without An macro"
783 An AUTHORS sections contains no
785 macros, or only empty ones.
786 Probably, there are author names lacking markup.
788 .Ss "Warnings related to macros and nesting"
790 .It Sy "obsolete macro"
794 manual for replacements.
795 .It Sy "macro neither callable nor escaped"
797 The name of a macro that is not callable appears on a macro line.
798 It is printed verbatim.
799 If the intention is to call it, move it to its own input line;
800 otherwise, escape it by prepending
802 .It Sy "skipping paragraph macro"
805 documents, this happens
808 at the beginning and end of sections and subsections
810 right before non-compact lists and displays
812 at the end of items in non-column, non-compact lists
814 and for multiple consecutive paragraph macros.
818 documents, it happens
830 macros having neither head nor body arguments
841 .It Sy "moving paragraph macro out of list"
845 list contains a trailing paragraph macro.
846 The paragraph macro is moved after the end of the list.
847 .It Sy "skipping no-space macro"
849 An input line begins with an
852 The macro is ignored.
853 .It Sy "blocks badly nested"
855 If two blocks intersect, one should completely contain the other.
856 Otherwise, rendered output is likely to look strange in any output
857 format, and rendering in SGML-based output formats is likely to be
858 outright wrong because such languages do not support badly nested
860 Typical examples of badly nested blocks are
861 .Qq Ic \&Ao \&Bo \&Ac \&Bc
863 .Qq Ic \&Ao \&Bq \&Ac .
871 .It Sy "nested displays are not portable"
878 display occurs nested inside another
883 but fails with most other implementations.
884 .It Sy "moving content out of list"
888 list block contains text or macros before the first
891 The offending children are moved before the beginning of the list.
892 .It Sy ".Vt block has child macro"
896 macro supports plain text arguments only.
897 Formatting may be ugly and semantic searching
898 for the affected content might not work.
899 .It Sy "fill mode already enabled, skipping"
903 request occurs even though the document is still in fill mode,
904 or already switched back to fill mode.
906 .It Sy "fill mode already disabled, skipping"
910 request occurs even though the document already switched to no-fill mode
911 and did not switch back to fill mode yet.
913 .It Sy "line scope broken"
915 While parsing the next-line scope of the previous macro,
916 another macro is found that prematurely terminates the previous one.
917 The previous, interrupted macro is deleted from the parse tree.
919 .Ss "Warnings related to missing arguments"
921 .It Sy "skipping empty request"
923 The macro name is missing from a macro definition request,
926 control statement or operation keyword lacks its required argument.
927 .It Sy "conditional request controls empty scope"
929 A conditional request is only useful if any of the following
930 follows it on the same logical input line:
935 keyword to open a multi-line scope.
937 A request or macro or some text, resulting in a single-line scope.
939 The immediate end of the logical line without any intervening whitespace,
940 resulting in next-line scope.
942 Here, a conditional request is followed by trailing whitespace only,
943 and there is no other content on its logical input line.
944 Note that it doesn't matter whether the logical input line is split
945 across multiple physical input lines using
947 line continuation characters.
948 This is one of the rare cases
949 where trailing whitespace is syntactically significant.
950 The conditional request controls a scope containing whitespace only,
951 so it is unlikely to have a significant effect,
952 except that it may control a following
955 .It Sy "skipping empty macro"
957 The indicated macro has no arguments and hence no effect.
969 block contains nothing in its body and will produce no output.
970 .It Sy "empty argument, using 0n"
972 The required width is missing after
979 .It Sy "missing display type, using -ragged"
983 macro is invoked without the required display type.
984 .It Sy "list type is not the first argument"
988 macro, at least one other argument precedes the type argument.
991 utility copes with any argument order, but some other
993 implementations do not.
994 .It Sy "missing -width in -tag list, using 8n"
1003 .It Sy "missing utility name, using \(dq\(dq"
1007 macro is called without an argument before
1009 has first been called with an argument.
1010 .It Sy "missing function name, using \(dq\(dq"
1014 macro is called without an argument.
1015 No function name is printed.
1016 .It Sy "empty head in list item"
1028 macro lacks the required argument.
1029 The item head is left empty.
1030 .It Sy "empty list item"
1042 An empty list item is shown.
1043 .It Sy "missing font type, using \efR"
1047 macro has no argument.
1048 It switches to the default font.
1049 .It Sy "unknown font type, using \efR"
1053 argument is invalid.
1054 The default font is used instead.
1055 .It Sy "nothing follows prefix"
1059 macro has no argument, or only one argument and no macro follows
1060 on the same input line.
1061 This defeats its purpose; in particular, spacing is not suppressed
1062 before the text or macros following on the next input line.
1063 .It Sy "empty reference block"
1067 macro is immediately followed by an
1069 macro on the next input line.
1070 Such an empty block does not produce any output.
1071 .It Sy "missing -std argument, adding it"
1077 macro lacks the required
1084 even when it is not specified, but other implementations may not.
1085 .It Sy "missing option string, using \(dq\(dq"
1089 macro is invoked without any argument.
1090 An empty pair of square brackets is shown.
1091 .It Sy "missing resource identifier, using \(dq\(dq"
1095 macro is invoked without any argument.
1096 An empty pair of angle brackets is shown.
1097 .It Sy "missing eqn box, using \(dq\(dq"
1099 A diacritic mark or a binary operator is found,
1100 but there is nothing to the left of it.
1101 An empty box is inserted.
1103 .Ss "Warnings related to bad macro arguments"
1105 .It Sy "unterminated quoted argument"
1107 Macro arguments can be enclosed in double quote characters
1108 such that space characters and macro names contained in the quoted
1109 argument need not be escaped.
1110 The closing quote of the last argument of a macro can be omitted.
1111 However, omitting it is not recommended because it makes the code
1113 .It Sy "duplicate argument"
1119 macro has more than one
1126 All but the last instances of these arguments are ignored.
1127 .It Sy "skipping duplicate argument"
1131 macro has more than one
1136 All but the first of these arguments are ignored.
1137 .It Sy "skipping duplicate display type"
1141 macro has more than one type argument; the first one is used.
1142 .It Sy "skipping duplicate list type"
1146 macro has more than one type argument; the first one is used.
1147 .It Sy "skipping -width argument"
1161 .It Sy "wrong number of cells"
1164 list, the number of tabs or
1166 macros is less than the number expected from the list header line
1167 or exceeds the expected number by more than one.
1168 Missing cells remain empty, and all cells exceeding the number of
1169 columns are joined into one single cell.
1170 .It Sy "unknown AT&T UNIX version"
1174 macro has an invalid argument.
1175 It is used verbatim, with
1178 .It Sy "comma in function argument"
1184 macro contains a comma; it should probably be split into two arguments.
1185 .It Sy "parenthesis in function name"
1187 The first argument of an
1191 macro contains an opening or closing parenthesis; that's probably wrong,
1192 parentheses are added automatically.
1193 .It Sy "invalid content in Rs block"
1197 block contains plain text or non-% macros.
1198 The bogus content is left in the syntax tree.
1199 Formatting may be poor.
1200 .It Sy "invalid Boolean argument"
1204 macro has an argument other than
1208 The invalid argument is moved out of the macro, which leaves the macro
1209 empty, causing it to toggle the spacing mode.
1210 .It Sy "unknown font, skipping request"
1218 layout modifier has an unknown
1221 .It Sy "odd number of characters in request"
1225 request contains an odd number of characters.
1226 The last character is mapped to the blank character.
1228 .Ss "Warnings related to plain text"
1230 .It Sy "blank line in fill mode, using .sp"
1232 The meaning of blank input lines is only well-defined in non-fill mode:
1233 In fill mode, line breaks of text input lines are not supposed to be
1235 However, for compatibility with groff, blank lines in fill mode
1239 .It Sy "tab in filled text"
1241 The meaning of tab characters is only well-defined in non-fill mode:
1242 In fill mode, whitespace is not supposed to be significant
1243 on text input lines.
1244 As an implementation dependent choice, tab characters on text lines
1245 are passed through to the formatters in any case.
1246 Given that the text before the tab character will be filled,
1247 it is hard to predict which tab stop position the tab will advance to.
1248 .It Sy "whitespace at end of input line"
1249 .Pq mdoc , man , roff
1250 Whitespace at the end of input lines is almost never semantically
1251 significant \(em but in the odd case where it might be, it is
1252 extremely confusing when reviewing and maintaining documents.
1253 .It Sy "bad comment style"
1255 Comment lines start with a dot, a backslash, and a double-quote character.
1258 utility treats the line as a comment line even without the backslash,
1259 but leaving out the backslash might not be portable.
1260 .It Sy "invalid escape sequence"
1262 An escape sequence has an invalid opening argument delimiter, lacks the
1263 closing argument delimiter, or the argument has too few characters.
1264 If the argument is incomplete,
1268 expand to an empty string,
1274 to the length of the incomplete argument.
1275 All other invalid escape sequences are ignored.
1276 .It Sy "undefined string, using \(dq\(dq"
1278 If a string is used without being defined before,
1279 its value is implicitly set to the empty string.
1280 However, defining strings explicitly before use
1281 keeps the code more readable.
1283 .Ss "Warnings related to tables"
1285 .It Sy "tbl line starts with span"
1287 The first cell in a table layout line is a horizontal span
1289 Data provided for this cell is ignored, and nothing is printed in the cell.
1290 .It Sy "tbl column starts with span"
1292 The first line of a table layout specification
1293 requests a vertical span
1295 Data provided for this cell is ignored, and nothing is printed in the cell.
1296 .It Sy "skipping vertical bar in tbl layout"
1298 A table layout specification contains more than two consecutive vertical bars.
1299 A double bar is printed, all additional bars are discarded.
1301 .Ss "Errors related to tables"
1303 .It Sy "non-alphabetic character in tbl options"
1305 The table options line contains a character other than a letter,
1306 blank, or comma where the beginning of an option name is expected.
1307 The character is ignored.
1308 .It Sy "skipping unknown tbl option"
1310 The table options line contains a string of letters that does not
1311 match any known option name.
1312 The word is ignored.
1313 .It Sy "missing tbl option argument"
1315 A table option that requires an argument is not followed by an
1316 opening parenthesis, or the opening parenthesis is immediately
1317 followed by a closing parenthesis.
1318 The option is ignored.
1319 .It Sy "wrong tbl option argument size"
1321 A table option argument contains an invalid number of characters.
1322 Both the option and the argument are ignored.
1323 .It Sy "empty tbl layout"
1325 A table layout specification is completely empty,
1326 specifying zero lines and zero columns.
1327 As a fallback, a single left-justified column is used.
1328 .It Sy "invalid character in tbl layout"
1330 A table layout specification contains a character that can neither
1331 be interpreted as a layout key character nor as a layout modifier,
1332 or a modifier precedes the first key.
1333 The invalid character is discarded.
1334 .It Sy "unmatched parenthesis in tbl layout"
1336 A table layout specification contains an opening parenthesis,
1337 but no matching closing parenthesis.
1338 The rest of the input line, starting from the parenthesis, has no effect.
1339 .It Sy "tbl without any data cells"
1341 A table does not contain any data cells.
1342 It will probably produce no output.
1343 .It Sy "ignoring data in spanned tbl cell"
1345 A table cell is marked as a horizontal span
1349 in the table layout, but it contains data.
1350 The data is ignored.
1351 .It Sy "ignoring extra tbl data cells"
1353 A data line contains more cells than the corresponding layout line.
1354 The data in the extra cells is ignored.
1355 .It Sy "data block open at end of tbl"
1357 A data block is opened with
1359 but never closed with a matching
1361 The remaining data lines of the table are all put into one cell,
1362 and any remaining cells stay empty.
1364 .Ss "Errors related to roff, mdoc, and man code"
1366 .It Sy "input stack limit exceeded, infinite loop?"
1368 Explicit recursion limits are implemented for the following features,
1369 in order to prevent infinite loops:
1372 expansion of nested escape sequences
1373 including expansion of strings and number registers,
1375 expansion of nested user-defined macros,
1381 When a limit is hit, the output is incorrect, typically losing
1382 some content, but the parser can continue.
1383 .It Sy "skipping bad character"
1384 .Pq mdoc , man , roff
1385 The input file contains a byte that is not a printable
1388 The message mentions the character number.
1389 The offending byte is replaced with a question mark
1391 Consider editing the input file to replace the byte with an ASCII
1392 transliteration of the intended character.
1393 .It Sy "skipping unknown macro"
1394 .Pq mdoc , man , roff
1395 The first identifier on a request or macro line is neither recognized as a
1397 request, nor as a user-defined macro, nor, respectively, as an
1402 It may be mistyped or unsupported.
1403 The request or macro is discarded including its arguments.
1404 .It Sy "skipping insecure request"
1406 An input file attempted to run a shell command
1407 or to read or write an external file.
1408 Such attempts are denied for security reasons.
1409 .It Sy "skipping item outside list"
1413 macro occurs outside any
1418 delimiter occurs outside any pile.
1419 It is discarded including its arguments.
1420 .It Sy "skipping column outside column list"
1424 macro occurs outside any
1427 It is discarded including its arguments.
1428 .It Sy "skipping end of block that is not open"
1429 .Pq mdoc , man , eqn , tbl , roff
1430 Various syntax elements can only be used to explicitly close blocks
1431 that have previously been opened.
1434 block closing macro, a
1441 right delimiter or closing brace, or the end of an equation, table, or
1443 conditional request is encountered but no matching block is open.
1444 The offending request or macro is discarded.
1445 .It Sy "fewer RS blocks open, skipping"
1449 macro is invoked with an argument, but less than the specified number of
1455 .It Sy "inserting missing end of block"
1459 macros as well as tables require explicit closing by dedicated macros.
1460 A block that doesn't support bad nesting
1461 ends before all of its children are properly closed.
1462 The open child nodes are closed implicitly.
1463 .It Sy "appending missing end of block"
1464 .Pq mdoc , man , eqn , tbl , roff
1465 At the end of the document, an explicit
1473 block, an equation, table, or
1475 conditional or ignore block is still open.
1476 The open block is closed implicitly.
1477 .It Sy "escaped character not allowed in a name"
1479 Macro, string and register identifiers consist of printable,
1480 non-whitespace ASCII characters.
1481 Escape sequences and characters and strings expressed in terms of them
1482 cannot form part of a name.
1483 The first argument of an
1491 request, or any argument of an
1493 request, or the name of a request or user defined macro being called,
1494 is terminated by an escape sequence.
1500 the request has no effect at all.
1507 what was parsed up to this point is used as the arguments to the request,
1508 and the rest of the input line is discarded including the escape sequence.
1509 When parsing for a request or a user-defined macro name to be called,
1510 only the escape sequence is discarded.
1511 The characters preceding it are used as the request or macro name,
1512 the characters following it are used as the arguments to the request or macro.
1513 .It Sy "NOT IMPLEMENTED: Bd -file"
1515 For security reasons, the
1517 macro does not support the
1520 By requesting the inclusion of a sensitive file, a malicious document
1521 might otherwise trick a privileged user into inadvertently displaying
1522 the file on the screen, revealing the file content to bystanders.
1523 The argument is ignored including the file name following it.
1524 .It Sy "missing list type, using -item"
1528 macro fails to specify the list type.
1529 .It Sy "missing manual name, using \(dq\(dq"
1533 lacks the required argument.
1534 .It Sy "uname(3) system call failed, using UNKNOWN"
1538 macro is called without arguments, and the
1543 can be compiled with
1545 .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
1547 .It Sy "unknown standard specifier"
1551 macro has an unknown argument and is discarded.
1552 .It Sy "skipping request without numeric argument"
1561 statement has a non-numeric or negative argument or no argument at all.
1562 The invalid request or statement is ignored.
1563 .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
1565 For security reasons,
1569 file inclusion requests only with relative paths
1570 and only without ascending to any parent directory.
1571 By requesting the inclusion of a sensitive file, a malicious document
1572 might otherwise trick a privileged user into inadvertently displaying
1573 the file on the screen, revealing the file content to bystanders.
1575 only shows the path as it appears behind
1577 .It Sy ".so request failed"
1581 request requires reading an external file, but the file could not be
1584 only shows the path as it appears behind
1586 .It Sy "skipping all arguments"
1587 .Pq mdoc , man , eqn , roff
1603 macro in a list that don't support item heads, a
1622 block closing request is invoked with at least one argument.
1623 All arguments are ignored.
1624 .It Sy "skipping excess arguments"
1625 .Pq mdoc , man , roff
1626 A macro or request is invoked with too many arguments:
1627 .Bl -dash -offset 2n -width 2n -compact
1636 with more than one argument
1639 with another argument after
1645 with more than one argument or with a non-integer argument
1650 family with more than two arguments
1653 with more than three arguments
1656 with more than five arguments
1662 with invalid arguments
1664 The excess arguments are ignored.
1666 .Ss Unsupported features
1668 .It Sy "input too large"
1672 cannot handle input files larger than its arbitrary size limit
1673 of 2^31 bytes (2 Gigabytes).
1674 Since useful manuals are always small, this is not a problem in practice.
1675 Parsing is aborted as soon as the condition is detected.
1676 .It Sy "unsupported control character"
1678 An ASCII control character supported by other
1680 implementations but not by
1682 was found in an input file.
1683 It is replaced by a question mark.
1684 .It Sy "unsupported roff request"
1686 An input file contains a
1688 request supported by GNU troff or Heirloom troff but not by
1690 and it is likely that this will cause information loss
1691 or considerable misformatting.
1692 .It Sy "eqn delim option in tbl"
1694 The options line of a table defines equation delimiters.
1695 Any equation source code contained in the table will be printed unformatted.
1696 .It Sy "unsupported table layout modifier"
1698 A table layout specification contains an
1701 The modifier is discarded.
1702 .It Sy "ignoring macro in table"
1703 .Pq tbl , mdoc , man
1704 A table contains an invocation of an
1708 macro or of an undefined macro.
1709 The macro is ignored, and its arguments are handled
1710 as if they were a text line.
1722 utility was written by
1723 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1724 and is maintained by
1725 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
1729 the maximum size of an element attribute is determined by
1731 which is usually 1024 bytes.
1732 Be aware of this when setting long link
1734 .Fl O Ns Cm style Ns = Ns Ar really/long/link .