1 .\" $Id: mandoc.1,v 1.141 2015/01/29 00:33:57 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: January 29 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 This overrides any earlier
132 Also reverts any earlier
137 .It Fl m Ns Ar format
141 for available formats.
144 .It Fl O Ns Ar option
145 Comma-separated output options.
146 .It Fl T Ns Ar output
150 for available formats.
154 Print version and exit.
156 Specify the minimum message
158 to be reported on the standard error output and to affect the exit status.
182 to exit after parsing a file that causes warnings or errors of at least
184 No formatted output will be produced from that file.
189 are requested, they can be joined with a comma, for example
190 .Fl W Ns Cm error , Ns Cm stop .
192 Read input from zero or more files.
193 If unspecified, reads from stdin.
194 If multiple files are specified,
196 will halt with the first failed parse.
205 also supports the options
228 should only be used for legacy manuals.
232 which is also the default, determines encoding on-the-fly: if the first
239 parser is used; otherwise, the
244 files are specified with
246 each has its file-type determined this way.
247 If multiple files are
252 is specified, then this format is used exclusively.
256 utility accepts the following
258 arguments, which correspond to output modes:
259 .Bl -tag -width "-Tlocale"
261 Produce 7-bit ASCII output.
265 Produce HTML5, CSS1, and MathML output.
269 Parse only: produce no output.
271 .Fl W Ns Cm warning .
272 .It Fl T Ns Cm locale
273 Encode output using the current locale.
288 Produce PostScript output.
290 .Sx PostScript Output .
292 Produce an indented parse tree.
294 Encode output in the UTF\-8 multi-byte format.
298 This is a synonym for
302 If multiple input files are specified, these will be processed by the
303 corresponding filter in-order.
307 is rendered in standard 7-bit ASCII documented in
310 Font styles are applied by using back-spaced encoding such that an
314 .Sq _ Ns \e[bs] Ns c ,
317 is the back-space character number 8.
318 Emboldened characters are rendered as
319 .Sq c Ns \e[bs] Ns c .
321 The special characters documented in
323 are rendered best-effort in an ASCII equivalent.
325 Output width is limited to 78 visible columns unless literal input lines
330 arguments are accepted:
332 .It Cm indent Ns = Ns Ar indent
333 The left margin for normal text is set to
335 blank characters instead of the default of five for
339 Increasing this is not recommended; it may result in degraded formatting,
340 for example overfull lines or ugly line breaks.
341 .It Cm width Ns = Ns Ar width
342 The output width is set to
344 which will normalise to \(>=58.
349 conforms to HTML5 using optional self-closing tags.
350 Default styles use only CSS1.
351 Equations rendered from
356 .Pa example.style.css
357 file documents style-sheet classes available for customising output.
358 If a style-sheet is not specified with
361 defaults to simple output (via an embedded style-sheet)
362 readable in any graphical or text-based web
365 Special characters are rendered in decimal-encoded UTF\-8.
369 arguments are accepted:
372 Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body>
373 elements and only emit the subtree below the <body> element.
376 argument will be ignored.
377 This is useful when embedding manual content within existing documents.
378 .It Cm includes Ns = Ns Ar fmt
383 is used as a template for linked header files (usually via the
388 are replaced with the include filename.
389 The default is not to present a
391 .It Cm man Ns = Ns Ar fmt
395 .Ar ../html%S/%N.%S.html ,
396 is used as a template for linked manuals (usually via the
403 are replaced with the linked manual's name and section, respectively.
404 If no section is included, section 1 is assumed.
405 The default is not to
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
415 Locale-depending output encoding is triggered with
419 This option is not available on all systems: systems without locale
420 support, or those whose internal representation is not natively UCS-4,
425 for font style specification and available command-line arguments.
427 Translate input format into
430 This is useful for distributing manual sources to legacy systems
437 is passed as input, it is translated into
439 If the input format is
441 the input is copied to the output, expanding any
445 The parser is also run, and as usual, the
449 are displayed before copying the input to the output.
451 PDF-1.1 output may be generated by
454 .Sx PostScript Output
457 arguments and defaults.
458 .Ss PostScript Output
461 Level-2 pages may be generated by
463 Output pages default to letter sized and are rendered in the Times font
465 Margins are calculated as 1/9 the page length and width.
468 Special characters are rendered as in
473 arguments are accepted:
475 .It Cm paper Ns = Ns Ar name
485 You may also manually specify dimensions as
487 width by height in millimetres.
488 If an unknown value is encountered,
495 to force a UTF\-8 locale.
498 for details and options.
500 .Bl -tag -width MANPAGER
502 Any non-empty value of the environment variable
504 will be used instead of the standard pagination program,
507 Specifies the pagination program to use when
510 If neither PAGER nor MANPAGER is defined,
511 .Pa /usr/bin/more Fl s
517 utility exits with one of the following values, controlled by the message
523 .Bl -tag -width Ds -compact
525 No warnings or errors occurred, or those that did were ignored because
526 they were lower than the requested
529 At least one warning occurred, but no error, and
533 At least one parsing error occurred,
534 but no unsupported feature was encountered, and
540 At least one unsupported feature was encountered, and
547 Invalid command line arguments were specified.
548 No input files have been read.
550 An operating system error occurred, for example exhaustion
551 of memory, file descriptors, or process table entries.
554 to exit at once, possibly in the middle of parsing or formatting a file.
560 .Fl W Ns Cm warning .
562 To page manuals to the terminal:
564 .Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less
565 .Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
567 To produce HTML manuals with
571 .Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
573 To check over a large set of manuals:
575 .Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]`
577 To produce a series of PostScript manuals for A4 paper:
579 .Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
585 format, for use on systems lacking an
589 .Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man
591 Messages displayed by
595 .D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args
597 Line and column numbers start at 1.
598 Both are omitted for messages referring to an input file as a whole.
599 Macro names and arguments are omitted where meaningless.
600 Fatal messages about invalid command line arguments
601 or operating system errors, for example when memory is exhausted,
608 Message levels have the following meanings:
609 .Bl -tag -width "warning"
611 An input file uses unsupported low-level
614 The output may be incomplete and/or misformatted,
615 so using GNU troff instead of
617 to process the file may be preferable.
619 An input file contains invalid syntax that cannot be safely interpreted.
620 By discarding part of the input or inserting missing tokens,
621 the parser is able to continue, and the error does not prevent
622 generation of formatted output, but typically, preparing that
623 output involves information loss, broken document structure
624 or unintended formatting, no matter whether
626 or GNU troff is used.
627 In many cases, the output of
629 and GNU troff is identical, but in some,
631 is more resilient than GNU troff with respect to malformed input.
633 Non-existent or unreadable input files are also reported on the
636 In that case, the parser cannot even be started and no output
637 is produced from those input files.
639 An input file uses obsolete, discouraged or non-portable syntax.
640 All the same, the meaning of the input is unambiguous and a correct
641 rendering can be produced.
642 Documents causing warnings may render poorly when using other
643 formatting tools instead of
652 levels except those about non-existent or unreadable input files
653 are hidden unless their level, or a lower level, is requested using a
658 .Ss Warnings related to the document prologue
660 .It Sy "missing manual title, using UNTITLED"
664 macro has no arguments, or there is no
666 macro before the first non-prologue macro.
667 .It Sy "missing manual title, using \(dq\(dq"
671 macro, or it has no arguments.
672 .It Sy "lower case character in document title"
674 The title is still used as given in the
679 .It Sy "missing manual section, using \(dq\(dq"
685 macro lacks the mandatory section argument.
686 .It Sy "unknown manual section"
688 The section number in a
690 line is invalid, but still used.
691 .It Sy "missing date, using today's date"
693 The document was parsed as
699 macro has no arguments or only empty arguments;
700 or the document was parsed as
706 macro has less than three arguments or its third argument is empty.
707 .It Sy "cannot parse date, using it verbatim"
713 macro does not follow the conventional format.
714 .It Sy "missing Os macro, using \(dq\(dq"
716 The default or current system is not shown in this case.
717 .It Sy "duplicate prologue macro"
719 One of the prologue macros occurs more than once.
720 The last instance overrides all previous ones.
721 .It Sy "late prologue macro"
727 macro occurs after some non-prologue macro, but still takes effect.
728 .It Sy "skipping late title macro"
732 macro can only occur before the first non-prologue macro
733 because traditional formatters write the page header
734 before parsing the document body.
735 Even though this technical restriction does not apply to
737 traditional semantics is preserved.
738 The late macro is discarded including its arguments.
739 .It Sy "prologue macros out of order"
741 The prologue macros are not given in the conventional order
745 All three macros are used even when given in another order.
747 .Ss Warnings regarding document structure
749 .It Sy ".so is fragile, better use ln(1)"
751 Including files only works when the parser program runs with the correct
752 current working directory.
753 .It Sy "no document body"
755 The document body contains neither text nor macros.
756 An empty document is shown, consisting only of a header and a footer line.
757 .It Sy "content before first section header"
759 Some macros or text precede the first
764 The offending macros and text are parsed and added to the top level
765 of the syntax tree, outside any section block.
766 .It Sy "first section is not NAME"
768 The argument of the first
776 .It Sy "bad NAME section contents"
778 The last node in the NAME section is not an
780 macro, or any preceding macro is not
782 or the NAME section is completely empty.
787 .It Sy "sections out of conventional order"
789 A standard section occurs after another section it usually precedes.
790 All section titles are used as given,
791 and the order of sections is not changed.
792 .It Sy "duplicate section title"
794 The same standard section title occurs more than once.
795 .It Sy "unexpected section"
797 A standard section header occurs in a section of the manual
798 where it normally isn't useful.
799 .It Sy "unusual Xr order"
801 In the SEE ALSO section, an
803 macro with a lower section number follows one with a higher number,
806 macros refering to the same section are out of alphabetical order.
807 .It Sy "unusual Xr punctuation"
809 In the SEE ALSO section, punctuation between two
811 macros differs from a single comma, or there is trailing punctuation
815 .It Sy "AUTHORS section without An macro"
817 An AUTHORS sections contains no
819 macros, or only empty ones.
820 Probably, there are author names lacking markup.
822 .Ss "Warnings related to macros and nesting"
824 .It Sy "obsolete macro"
828 manual for replacements.
829 .It Sy "macro neither callable nor escaped"
831 The name of a macro that is not callable appears on a macro line.
832 It is printed verbatim.
833 If the intention is to call it, move it to its own line;
834 otherwise, escape it by prepending
836 .It Sy "skipping paragraph macro"
839 documents, this happens
842 at the beginning and end of sections and subsections
844 right before non-compact lists and displays
846 at the end of items in non-column, non-compact lists
848 and for multiple consecutive paragraph macros.
852 documents, it happens
864 macros having neither head nor body arguments
875 .It Sy "moving paragraph macro out of list"
879 list contains a trailing paragraph macro.
880 The paragraph macro is moved after the end of the list.
881 .It Sy "skipping no-space macro"
883 An input line begins with an
886 The macro is ignored.
887 .It Sy "blocks badly nested"
889 If two blocks intersect, one should completely contain the other.
890 Otherwise, rendered output is likely to look strange in any output
891 format, and rendering in SGML-based output formats is likely to be
892 outright wrong because such languages do not support badly nested
894 Typical examples of badly nested blocks are
895 .Qq Ic \&Ao \&Bo \&Ac \&Bc
897 .Qq Ic \&Ao \&Bq \&Ac .
905 .It Sy "nested displays are not portable"
912 display occurs nested inside another
917 but fails with most other implementations.
918 .It Sy "moving content out of list"
922 list block contains text or macros before the first
925 The offending children are moved before the beginning of the list.
926 .It Sy ".Vt block has child macro"
930 macro supports plain text arguments only.
931 Formatting may be ugly and semantic searching
932 for the affected content might not work.
933 .It Sy "fill mode already enabled, skipping"
937 request occurs even though the document is still in fill mode,
938 or already switched back to fill mode.
940 .It Sy "fill mode already disabled, skipping"
944 request occurs even though the document already switched to no-fill mode
945 and did not switch back to fill mode yet.
947 .It Sy "line scope broken"
949 While parsing the next-line scope of the previous macro,
950 another macro is found that prematurely terminates the previous one.
951 The previous, interrupted macro is deleted from the parse tree.
953 .Ss "Warnings related to missing arguments"
955 .It Sy "skipping empty request"
957 The macro name is missing from a macro definition request,
960 control statement or operation keyword lacks its required argument.
961 .It Sy "conditional request controls empty scope"
963 A conditional request is only useful if any of the following
964 follows it on the same logical input line:
969 keyword to open a multi-line scope.
971 A request or macro or some text, resulting in a single-line scope.
973 The immediate end of the logical line without any intervening whitespace,
974 resulting in next-line scope.
976 Here, a conditional request is followed by trailing whitespace only,
977 and there is no other content on its logical input line.
978 Note that it doesn't matter whether the logical input line is split
979 across multiple physical input lines using
981 line continuation characters.
982 This is one of the rare cases
983 where trailing whitespace is syntactically significant.
984 The conditional request controls a scope containing whitespace only,
985 so it is unlikely to have a significant effect,
986 except that it may control a following
989 .It Sy "skipping empty macro"
991 The indicated macro has no arguments and hence no effect.
992 .It Sy "empty argument, using 0n"
994 The required width is missing after
1001 .It Sy "argument count wrong"
1003 The indicated macro has too few or too many arguments.
1004 The syntax tree will contain the wrong number of arguments as given.
1005 Formatting behaviour depends on the specific macro in question.
1006 Note that the same message may also occur as an ERROR, see below.
1007 .It Sy "missing display type, using -ragged"
1011 macro is invoked without the required display type.
1012 .It Sy "list type is not the first argument"
1016 macro, at least one other argument precedes the type argument.
1019 utility copes with any argument order, but some other
1021 implementations do not.
1022 .It Sy "missing -width in -tag list, using 8n"
1031 .It Sy "missing utility name, using \(dq\(dq"
1035 macro is called without an argument before
1037 has first been called with an argument.
1038 .It Sy "empty head in list item"
1050 macro lacks the required argument.
1051 The item head is left empty.
1052 .It Sy "empty list item"
1064 An empty list item is shown.
1065 .It Sy "missing font type"
1069 macro has no argument.
1070 It switches to the default font,
1072 .It Sy "unknown font type"
1076 argument is invalid.
1080 .It Sy "nothing follows prefix"
1084 macro has no argument, or only one argument and no macro follows
1085 on the same input line.
1086 This defeats its purpose; in particular, spacing is not suppressed
1087 before the text or macros following on the next input line.
1088 .It Sy "missing -std argument, adding it"
1094 macro lacks the required
1101 even when it is not specified, but other implementations may not.
1102 .It Sy "missing eqn box, using \(dq\(dq"
1104 A diacritic mark or a binary operator is found,
1105 but there is nothing to the left of it.
1106 An empty box is inserted.
1108 .Ss "Warnings related to bad macro arguments"
1110 .It Sy "unterminated quoted argument"
1112 Macro arguments can be enclosed in double quote characters
1113 such that space characters and macro names contained in the quoted
1114 argument need not be escaped.
1115 The closing quote of the last argument of a macro can be omitted.
1116 However, omitting it is not recommended because it makes the code
1118 .It Sy "duplicate argument"
1124 macro has more than one
1131 All but the last instances of these arguments are ignored.
1132 .It Sy "skipping duplicate argument"
1136 macro has more than one
1141 All but the first of these arguments are ignored.
1142 .It Sy "skipping duplicate display type"
1146 macro has more than one type argument; the first one is used.
1147 .It Sy "skipping duplicate list type"
1151 macro has more than one type argument; the first one is used.
1152 .It Sy "skipping -width argument"
1166 .It Sy "unknown AT&T UNIX version"
1170 macro has an invalid argument.
1171 It is used verbatim, with
1174 .It Sy "comma in function argument"
1180 macro contains a comma; it should probably be split into two arguments.
1181 .It Sy "parenthesis in function name"
1183 The first argument of an
1187 macro contains an opening or closing parenthesis; that's probably wrong,
1188 parentheses are added automatically.
1189 .It Sy "invalid content in Rs block"
1193 block contains plain text or non-% macros.
1194 The bogus content is left in the syntax tree.
1195 Formatting may be poor.
1196 .It Sy "invalid Boolean argument"
1200 macro has an argument other than
1204 The invalid argument is moved out of the macro, which leaves the macro
1205 empty, causing it to toggle the spacing mode.
1206 .It Sy "unknown font, skipping request"
1214 layout modifier has an unknown
1218 .Ss "Warnings related to plain text"
1220 .It Sy "blank line in fill mode, using .sp"
1222 The meaning of blank input lines is only well-defined in non-fill mode:
1223 In fill mode, line breaks of text input lines are not supposed to be
1225 However, for compatibility with groff, blank lines in fill mode
1229 .It Sy "tab in filled text"
1231 The meaning of tab characters is only well-defined in non-fill mode:
1232 In fill mode, whitespace is not supposed to be significant
1233 on text input lines.
1234 As an implementation dependent choice, tab characters on text lines
1235 are passed through to the formatters in any case.
1236 Given that the text before the tab character will be filled,
1237 it is hard to predict which tab stop position the tab will advance to.
1238 .It Sy "whitespace at end of input line"
1239 .Pq mdoc , man , roff
1240 Whitespace at the end of input lines is almost never semantically
1241 significant \(em but in the odd case where it might be, it is
1242 extremely confusing when reviewing and maintaining documents.
1243 .It Sy "bad comment style"
1245 Comment lines start with a dot, a backslash, and a double-quote character.
1248 utility treats the line as a comment line even without the backslash,
1249 but leaving out the backslash might not be portable.
1250 .It Sy "invalid escape sequence"
1252 An escape sequence has an invalid opening argument delimiter, lacks the
1253 closing argument delimiter, or the argument has too few characters.
1254 If the argument is incomplete,
1258 expand to an empty string,
1264 to the length of the incomplete argument.
1265 All other invalid escape sequences are ignored.
1266 .It Sy "undefined string, using \(dq\(dq"
1268 If a string is used without being defined before,
1269 its value is implicitly set to the empty string.
1270 However, defining strings explicitly before use
1271 keeps the code more readable.
1273 .Ss "Warnings related to tables"
1275 .It Sy "tbl line starts with span"
1277 The first cell in a table layout line is a horizontal span
1279 Data provided for this cell is ignored, and nothing is printed in the cell.
1280 .It Sy "tbl column starts with span"
1282 The first line of a table layout specification
1283 requests a vertical span
1285 Data provided for this cell is ignored, and nothing is printed in the cell.
1286 .It Sy "skipping vertical bar in tbl layout"
1288 A table layout specification contains more than two consecutive vertical bars.
1289 A double bar is printed, all additional bars are discarded.
1291 .Ss "Errors related to tables"
1293 .It Sy "non-alphabetic character in tbl options"
1295 The table options line contains a character other than a letter,
1296 blank, or comma where the beginning of an option name is expected.
1297 The character is ignored.
1298 .It Sy "skipping unknown tbl option"
1300 The table options line contains a string of letters that does not
1301 match any known option name.
1302 The word is ignored.
1303 .It Sy "missing tbl option argument"
1305 A table option that requires an argument is not followed by an
1306 opening parenthesis, or the opening parenthesis is immediately
1307 followed by a closing parenthesis.
1308 The option is ignored.
1309 .It Sy "wrong tbl option argument size"
1311 A table option argument contains an invalid number of characters.
1312 Both the option and the argument are ignored.
1313 .It Sy "empty tbl layout"
1315 A table layout specification is completely empty,
1316 specifying zero lines and zero columns.
1317 As a fallback, a single left-justified column is used.
1318 .It Sy "invalid character in tbl layout"
1320 A table layout specification contains a character that can neither
1321 be interpreted as a layout key character nor as a layout modifier,
1322 or a modifier precedes the first key.
1323 The invalid character is discarded.
1324 .It Sy "unmatched parenthesis in tbl layout"
1326 A table layout specification contains an opening parenthesis,
1327 but no matching closing parenthesis.
1328 The rest of the input line, starting from the parenthesis, has no effect.
1329 .It Sy "tbl without any data cells"
1331 A table does not contain any data cells.
1332 It will probably produce no output.
1333 .It Sy "ignoring data in spanned tbl cell"
1335 A table cell is marked as a horizontal span
1339 in the table layout, but it contains data.
1340 The data is ignored.
1341 .It Sy "ignoring extra tbl data cells"
1343 A data line contains more cells than the corresponding layout line.
1344 The data in the extra cells is ignored.
1345 .It Sy "data block open at end of tbl"
1347 A data block is opened with
1349 but never closed with a matching
1351 The remaining data lines of the table are all put into one cell,
1352 and any remaining cells stay empty.
1354 .Ss "Errors related to roff, mdoc, and man code"
1356 .It Sy "input stack limit exceeded, infinite loop?"
1358 Explicit recursion limits are implemented for the following features,
1359 in order to prevent infinite loops:
1362 expansion of nested escape sequences
1363 including expansion of strings and number registers,
1365 expansion of nested user-defined macros,
1371 When a limit is hit, the output is incorrect, typically losing
1372 some content, but the parser can continue.
1373 .It Sy "skipping bad character"
1374 .Pq mdoc , man , roff
1375 The input file contains a byte that is not a printable
1378 The message mentions the character number.
1379 The offending byte is replaced with a question mark
1381 Consider editing the input file to replace the byte with an ASCII
1382 transliteration of the intended character.
1383 .It Sy "skipping unknown macro"
1384 .Pq mdoc , man , roff
1385 The first identifier on a request or macro line is neither recognized as a
1387 request, nor as a user-defined macro, nor, respectively, as an
1392 It may be mistyped or unsupported.
1393 The request or macro is discarded including its arguments.
1394 .It Sy "skipping insecure request"
1396 An input file attempted to run a shell command
1397 or to read or write an external file.
1398 Such attempts are denied for security reasons.
1399 .It Sy "skipping item outside list"
1403 macro occurs outside any
1408 delimiter occurs outside any pile.
1409 It is discarded including its arguments.
1410 .It Sy "skipping column outside column list"
1414 macro occurs outside any
1417 It is discarded including its arguments.
1418 .It Sy "skipping end of block that is not open"
1419 .Pq mdoc , man , eqn , tbl , roff
1420 Various syntax elements can only be used to explicitly close blocks
1421 that have previously been opened.
1424 block closing macro, a
1431 right delimiter or closing brace, or the end of an equation, table, or
1433 conditional request is encountered but no matching block is open.
1434 The offending request or macro is discarded.
1435 .It Sy "fewer RS blocks open, skipping"
1439 macro is invoked with an argument, but less than the specified number of
1445 .It Sy "inserting missing end of block"
1449 macros as well as tables require explicit closing by dedicated macros.
1450 A block that doesn't support bad nesting
1451 ends before all of its children are properly closed.
1452 The open child nodes are closed implicitly.
1453 .It Sy "scope open on exit"
1454 .Pq mdoc , man , eqn , tbl , roff
1455 At the end of the document, an explicit
1463 block, an equation, table, or
1465 conditional or ignore block is still open.
1466 The open block is closed implicitly.
1467 .It Sy "escaped character not allowed in a name"
1469 Macro, string and register identifiers consist of printable,
1470 non-whitespace ASCII characters.
1471 Escape sequences and characters and strings expressed in terms of them
1472 cannot form part of a name.
1473 The first argument of an
1481 request, or any argument of an
1483 request, or the name of a request or user defined macro being called,
1484 is terminated by an escape sequence.
1490 the request has no effect at all.
1497 what was parsed up to this point is used as the arguments to the request,
1498 and the rest of the input line is discarded including the escape sequence.
1499 When parsing for a request or a user-defined macro name to be called,
1500 only the escape sequence is discarded.
1501 The characters preceding it are used as the request or macro name,
1502 the characters following it are used as the arguments to the request or macro.
1503 .It Sy "argument count wrong"
1504 .Pq mdoc , man , roff
1505 The indicated request or macro has too few or too many arguments.
1506 The syntax tree will contain the wrong number of arguments as given.
1507 Formatting behaviour depends on the specific request or macro in question.
1508 Note that the same message may also occur as a WARNING, see above.
1509 .It Sy "NOT IMPLEMENTED: Bd -file"
1511 For security reasons, the
1513 macro does not support the
1516 By requesting the inclusion of a sensitive file, a malicious document
1517 might otherwise trick a privileged user into inadvertently displaying
1518 the file on the screen, revealing the file content to bystanders.
1519 The argument is ignored including the file name following it.
1520 .It Sy "missing list type, using -item"
1524 macro fails to specify the list type.
1525 .It Sy "missing manual name, using \(dq\(dq"
1529 lacks the required argument.
1530 .It Sy "uname(3) system call failed, using UNKNOWN"
1534 macro is called without arguments, and the
1539 can be compiled with
1541 .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
1543 .It Sy "unknown standard specifier"
1547 macro has an unknown argument and is discarded.
1548 .It Sy "skipping request without numeric argument"
1557 statement has a non-numeric or negative argument or no argument at all.
1558 The invalid request or statement is ignored.
1559 .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
1561 For security reasons,
1565 file inclusion requests only with relative paths
1566 and only without ascending to any parent directory.
1567 By requesting the inclusion of a sensitive file, a malicious document
1568 might otherwise trick a privileged user into inadvertently displaying
1569 the file on the screen, revealing the file content to bystanders.
1571 only shows the path as it appears behind
1573 .It Sy ".so request failed"
1577 request requires reading an external file, but the file could not be
1580 only shows the path as it appears behind
1582 .It Sy "skipping all arguments"
1583 .Pq mdoc , man , eqn , roff
1596 macro in a list that don't support item heads, a
1610 block closing request is invoked with at least one argument.
1611 All arguments are ignored.
1612 .It Sy "skipping excess arguments"
1613 .Pq mdoc , man , roff
1616 macro is invoked with more than one argument, the
1618 macro is invoked with more than one argument
1619 or with a non-integer argument, or a request of the
1621 family is invoked with more than two arguments.
1622 The excess arguments are ignored.
1624 .Ss Unsupported features
1626 .It Sy "input too large"
1630 cannot handle input files larger than its arbitrary size limit
1631 of 2^31 bytes (2 Gigabytes).
1632 Since useful manuals are always small, this is not a problem in practice.
1633 Parsing is aborted as soon as the condition is detected.
1634 .It Sy "unsupported control character"
1636 An ASCII control character supported by other
1638 implementations but not by
1640 was found in an input file.
1641 It is replaced by a question mark.
1642 .It Sy "unsupported roff request"
1644 An input file contains a
1646 request supported by GNU troff or Heirloom troff but not by
1648 and it is likely that this will cause information loss
1649 or considerable misformatting.
1650 .It Sy "eqn delim option in tbl"
1652 The options line of a table defines equation delimiters.
1653 Any equation source code contained in the table will be printed unformatted.
1654 .It Sy "unsupported table layout modifier"
1656 A table layout specification contains an
1659 The modifier is discarded.
1660 .It Sy "ignoring macro in table"
1661 .Pq tbl , mdoc , man
1662 A table contains an invocation of an
1666 macro or of an undefined macro.
1667 The macro is ignored, and its arguments are handled
1668 as if they were a text line.
1682 utility was written by
1683 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1684 and is maintained by
1685 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
1689 the maximum size of an element attribute is determined by
1691 which is usually 1024 bytes.
1692 Be aware of this when setting long link
1694 .Fl O Ns Cm style Ns = Ns Ar really/long/link .
git.ckatri.com / mandoc.git / blob