1 .\" $Id: mandoc.1,v 1.123 2014/11/25 20:18:15 schwarze Exp $
3 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2012, 2014 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: November 25 2014 $
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
90 Display only the SYNOPSIS lines.
93 .It Fl K Ns Ar encoding
94 Specify the input encoding.
102 If not specified, autodetection uses the first match:
103 .Bl -tag -width iso-8859-1
105 if the first three bytes of the input file
106 are the UTF-8 byte order mark (BOM, 0xefbbbf)
108 if the first or second line of the input file matches the
112 .D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*-
114 if the first non-ASCII byte in the file introduces a valid UTF-8 sequence
121 This overrides any earlier
129 Also reverts any earlier
134 .It Fl m Ns Ar format
138 for available formats.
141 .It Fl O Ns Ar option
142 Comma-separated output options.
143 .It Fl T Ns Ar output
147 for available formats.
151 Print version and exit.
153 Specify the minimum message
155 to be reported on the standard error output and to affect the exit status.
167 .Fl W Ns Cm warning .
178 to exit after parsing a file that causes warnings or errors of at least
180 No formatted output will be produced from that file.
185 are requested, they can be joined with a comma, for example
186 .Fl W Ns Cm error , Ns Cm stop .
188 Read input from zero or more files.
189 If unspecified, reads from stdin.
190 If multiple files are specified,
192 will halt with the first failed parse.
201 also supports the options
224 should only be used for legacy manuals.
228 which is also the default, determines encoding on-the-fly: if the first
235 parser is used; otherwise, the
240 files are specified with
242 each has its file-type determined this way.
243 If multiple files are
248 is specified, then this format is used exclusively.
252 utility accepts the following
254 arguments, which correspond to output modes:
255 .Bl -tag -width "-Tlocale"
257 Produce 7-bit ASCII output.
262 Produce HTML5, CSS1, and MathML output.
266 Parse only: produce no output.
268 .Fl W Ns Cm warning .
269 .It Fl T Ns Cm locale
270 Encode output using the current locale.
284 Produce PostScript output.
286 .Sx PostScript Output .
288 Produce an indented parse tree.
290 Encode output in the UTF\-8 multi-byte format.
294 This is a synonym for
298 If multiple input files are specified, these will be processed by the
299 corresponding filter in-order.
303 which is the default, is rendered in standard 7-bit ASCII documented in
306 Font styles are applied by using back-spaced encoding such that an
310 .Sq _ Ns \e[bs] Ns c ,
313 is the back-space character number 8.
314 Emboldened characters are rendered as
315 .Sq c Ns \e[bs] Ns c .
317 The special characters documented in
319 are rendered best-effort in an ASCII equivalent.
320 If no equivalent is found,
324 Output width is limited to 78 visible columns unless literal input lines
329 arguments are accepted:
331 .It Cm indent Ns = Ns Ar indent
332 The left margin for normal text is set to
334 blank characters instead of the default of five for
338 Increasing this is not recommended; it may result in degraded formatting,
339 for example overfull lines or ugly line breaks.
340 .It Cm width Ns = Ns Ar width
341 The output width is set to
343 which will normalise to \(>=60.
348 conforms to HTML5 using optional self-closing tags.
349 Default styles use only CSS1.
350 Equations rendered from
355 .Pa example.style.css
356 file documents style-sheet classes available for customising output.
357 If a style-sheet is not specified with
360 defaults to simple output (via an embedded style-sheet)
361 readable in any graphical or text-based web
364 Special characters are rendered in decimal-encoded UTF\-8.
368 arguments are accepted:
371 Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body>
372 elements and only emit the subtree below the <body> element.
375 argument will be ignored.
376 This is useful when embedding manual content within existing documents.
377 .It Cm includes Ns = Ns Ar fmt
382 is used as a template for linked header files (usually via the
387 are replaced with the include filename.
388 The default is not to present a
390 .It Cm man Ns = Ns Ar fmt
394 .Ar ../html%S/%N.%S.html ,
395 is used as a template for linked manuals (usually via the
402 are replaced with the linked manual's name and section, respectively.
403 If no section is included, section 1 is assumed.
404 The default is not to
406 .It Cm style Ns = Ns Ar style.css
409 is used for an external style-sheet.
410 This must be a valid absolute or
414 Locale-depending output encoding is triggered with
416 This option is not available on all systems: systems without locale
417 support, or those whose internal representation is not natively UCS-4,
422 for font style specification and available command-line arguments.
424 Translate input format into
427 This is useful for distributing manual sources to legacy systems
434 is passed as input, it is translated into
436 If the input format is
438 the input is copied to the output, expanding any
442 The parser is also run, and as usual, the
446 are displayed before copying the input to the output.
448 PDF-1.1 output may be generated by
451 .Sx PostScript Output
454 arguments and defaults.
455 .Ss PostScript Output
458 Level-2 pages may be generated by
460 Output pages default to letter sized and are rendered in the Times font
462 Margins are calculated as 1/9 the page length and width.
465 Special characters are rendered as in
470 arguments are accepted:
472 .It Cm paper Ns = Ns Ar name
482 You may also manually specify dimensions as
484 width by height in millimetres.
485 If an unknown value is encountered,
492 to force a UTF\-8 locale.
495 for details and options.
497 .Bl -tag -width MANPAGER
499 Any non-empty value of the environment variable
501 will be used instead of the standard pagination program,
504 Specifies the pagination program to use when
507 If neither PAGER nor MANPAGER is defined,
508 .Pa /usr/bin/more Fl s
514 utility exits with one of the following values, controlled by the message
520 .Bl -tag -width Ds -compact
522 No warnings or errors occurred, or those that did were ignored because
523 they were lower than the requested
526 At least one warning occurred, but no error, and
530 At least one parsing error occurred, but no fatal error, and
536 A fatal parsing error occurred.
538 Invalid command line arguments were specified.
539 No input files have been read.
541 An operating system error occurred, for example memory exhaustion or an
542 error accessing input files.
545 to exit at once, possibly in the middle of parsing or formatting a file.
551 .Fl W Ns Cm warning .
553 To page manuals to the terminal:
555 .Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less
556 .Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
558 To produce HTML manuals with
562 .Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
564 To check over a large set of manuals:
566 .Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]`
568 To produce a series of PostScript manuals for A4 paper:
570 .Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
576 format, for use on systems lacking an
580 .Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man
582 Messages displayed by
586 .D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args
588 Line and column numbers start at 1.
589 Both are omitted for messages referring to an input file as a whole.
590 Macro names and arguments are omitted where meaningless.
591 Fatal messages about invalid command line arguments
592 or operating system errors, for example when memory is exhausted,
599 Message levels have the following meanings:
600 .Bl -tag -width "warning"
602 Opening or reading an input file failed, so the parser cannot
603 even be started and no output is produced from that input file.
605 The parser is unable to parse a given input file at all.
606 No formatted output is produced from that input file.
608 An input file contains syntax that cannot be safely interpreted,
609 either because it is invalid or because
611 does not implement it yet.
612 By discarding part of the input or inserting missing tokens,
613 the parser is able to continue, and the error does not prevent
614 generation of formatted output, but typically, preparing that
615 output involves information loss, broken document structure
616 or unintended formatting.
618 An input file uses obsolete, discouraged or non-portable syntax.
619 All the same, the meaning of the input is unambiguous and a correct
620 rendering can be produced.
621 Documents causing warnings may render poorly when using other
622 formatting tools instead of
630 levels are hidden unless their level, or a lower level, is requested using a
635 .Ss Warnings related to the document prologue
637 .It Sy "missing manual title, using UNTITLED"
641 macro has no arguments, or there is no
643 macro before the first non-prologue macro.
644 .It Sy "missing manual title, using \(dq\(dq"
648 macro, or it has no arguments.
649 .It Sy "lower case character in document title"
651 The title is still used as given in the
656 .It Sy "missing manual section, using \(dq\(dq"
662 macro lacks the mandatory section argument.
663 .It Sy "unknown manual section"
665 The section number in a
667 line is invalid, but still used.
668 .It Sy "unknown manual volume or arch"
672 line is invalid, but still used.
673 The manual is assumed to be architecture-independent.
674 .It Sy "missing date, using today's date"
676 The document was parsed as
682 macro has no arguments or only empty arguments;
683 or the document was parsed as
689 macro has less than three arguments or its third argument is empty.
690 .It Sy "cannot parse date, using it verbatim"
696 macro does not follow the conventional format.
697 .It Sy "missing Os macro, using \(dq\(dq"
699 The default or current system is not shown in this case.
700 .It Sy "duplicate prologue macro"
702 One of the prologue macros occurs more than once.
703 The last instance overrides all previous ones.
704 .It Sy "late prologue macro"
710 macro occurs after some non-prologue macro, but still takes effect.
711 .It Sy "skipping late title macro"
715 macro can only occur before the first non-prologue macro
716 because traditional formatters write the page header
717 before parsing the document body.
718 Even though this technical restriction does not apply to
720 traditional semantics is preserved.
721 The late macro is discarded including its arguments.
722 .It Sy "prologue macros out of order"
724 The prologue macros are not given in the conventional order
728 All three macros are used even when given in another order.
730 .Ss Warnings regarding document structure
732 .It Sy ".so is fragile, better use ln(1)"
734 Including files only works when the parser program runs with the correct
735 current working directory.
736 .It Sy "no document body"
738 The document body contains neither text nor macros.
739 An empty document is shown, consisting only of a header and a footer line.
740 .It Sy "content before first section header"
742 Some macros or text precede the first
747 The offending macros and text are parsed and added to the top level
748 of the syntax tree, outside any section block.
749 .It Sy "first section is not NAME"
751 The argument of the first
759 .It Sy "bad NAME section contents"
761 The last node in the NAME section is not an
763 macro, or any preceding macro is not
765 or the NAME section is completely empty.
770 .It Sy "sections out of conventional order"
772 A standard section occurs after another section it usually precedes.
773 All section titles are used as given,
774 and the order of sections is not changed.
775 .It Sy "duplicate section title"
777 The same standard section title occurs more than once.
778 .It Sy "unexpected section"
780 A standard section header occurs in a section of the manual
781 where it normally isn't useful.
782 .It Sy "unusual Xr order"
784 In the SEE ALSO section, an
786 macro with a lower section number follows one with a higher number,
789 macros refering to the same section are out of alphabetical order.
790 .It Sy "unusual Xr punctuation"
792 In the SEE ALSO section, punctuation between two
794 macros differs from a single comma, or there is trailing punctuation
798 .It Sy "AUTHORS section without An macro"
800 An AUTHORS sections contains no
802 macros, or only empty ones.
803 Probably, there are author names lacking markup.
805 .Ss "Warnings related to macros and nesting"
807 .It Sy "obsolete macro"
811 manual for replacements.
812 .It Sy "skipping paragraph macro"
815 documents, this happens
818 at the beginning and end of sections and subsections
820 right before non-compact lists and displays
822 at the end of items in non-column, non-compact lists
824 and for multiple consecutive paragraph macros.
828 documents, it happens
840 macros having neither head nor body arguments
851 .It Sy "moving paragraph macro out of list"
855 list contains a trailing paragraph macro.
856 The paragraph macro is moved after the end of the list.
857 .It Sy "skipping no-space macro"
859 An input line begins with an
862 The macro is ignored.
863 .It Sy "blocks badly nested"
865 If two blocks intersect, one should completely contain the other.
866 Otherwise, rendered output is likely to look strange in any output
867 format, and rendering in SGML-based output formats is likely to be
868 outright wrong because such languages do not support badly nested
870 Typical examples of badly nested blocks are
871 .Qq Ic \&Ao \&Bo \&Ac \&Bc
873 .Qq Ic \&Ao \&Bq \&Ac .
881 .It Sy "nested displays are not portable"
888 display occurs nested inside another
893 but fails with most other implementations.
894 .It Sy "moving content out of list"
898 list block contains text or macros before the first
901 The offending children are moved before the beginning of the list.
902 .It Sy ".Vt block has child macro"
906 macro supports plain text arguments only.
907 Formatting may be ugly and semantic searching
908 for the affected content might not work.
909 .It Sy "fill mode already enabled, skipping"
913 request occurs even though the document is still in fill mode,
914 or already switched back to fill mode.
916 .It Sy "fill mode already disabled, skipping"
920 request occurs even though the document already switched to no-fill mode
921 and did not switch back to fill mode yet.
923 .It Sy "line scope broken"
925 While parsing the next-line scope of the previous macro,
926 another macro is found that prematurely terminates the previous one.
927 The previous, interrupted macro is deleted from the parse tree.
929 .Ss "Warnings related to missing arguments"
931 .It Sy "skipping empty request"
933 The macro name is missing from a macro definition request,
936 control statement or operation keyword lacks its required argument.
937 .It Sy "conditional request controls empty scope"
939 A conditional request is only useful if any of the following
940 follows it on the same logical input line:
945 keyword to open a multi-line scope.
947 A request or macro or some text, resulting in a single-line scope.
949 The immediate end of the logical line without any intervening whitespace,
950 resulting in next-line scope.
952 Here, a conditional request is followed by trailing whitespace only,
953 and there is no other content on its logical input line.
954 Note that it doesn't matter whether the logical input line is split
955 across multiple physical input lines using
957 line continuation characters.
958 This is one of the rare cases
959 where trailing whitespace is syntactically significant.
960 The conditional request controls a scope containing whitespace only,
961 so it is unlikely to have a significant effect,
962 except that it may control a following
965 .It Sy "skipping empty macro"
967 The indicated macro has no arguments and hence no effect.
968 .It Sy "empty argument, using 0n"
970 The required width is missing after
977 .It Sy "argument count wrong"
979 The indicated macro has too few or too many arguments.
980 The syntax tree will contain the wrong number of arguments as given.
981 Formatting behaviour depends on the specific macro in question.
982 Note that the same message may also occur as an ERROR, see below.
983 .It Sy "missing display type, using -ragged"
987 macro is invoked without the required display type.
988 .It Sy "list type is not the first argument"
992 macro, at least one other argument precedes the type argument.
995 utility copes with any argument order, but some other
997 implementations do not.
998 .It Sy "missing -width in -tag list, using 8n"
1007 .It Sy "missing utility name, using \(dq\(dq"
1011 macro is called without an argument before
1013 has first been called with an argument.
1014 .It Sy "empty head in list item"
1026 macro lacks the required argument.
1027 The item head is left empty.
1028 .It Sy "empty list item"
1040 An empty list item is shown.
1041 .It Sy "missing font type"
1045 macro has no argument.
1046 It switches to the default font,
1048 .It Sy "unknown font type"
1052 argument is invalid.
1056 .It Sy "missing -std argument, adding it"
1062 macro lacks the required
1069 even when it is not specified, but other implementations may not.
1070 .It Sy "missing eqn box, using \(dq\(dq"
1072 A diacritic mark or a binary operator is found,
1073 but there is nothing to the left of it.
1074 An empty box is inserted.
1076 .Ss "Warnings related to bad macro arguments"
1078 .It Sy "unterminated quoted argument"
1080 Macro arguments can be enclosed in double quote characters
1081 such that space characters and macro names contained in the quoted
1082 argument need not be escaped.
1083 The closing quote of the last argument of a macro can be omitted.
1084 However, omitting it is not recommended because it makes the code
1086 .It Sy "duplicate argument"
1092 macro has more than one
1099 All but the last instances of these arguments are ignored.
1100 .It Sy "skipping duplicate argument"
1104 macro has more than one
1109 All but the first of these arguments are ignored.
1110 .It Sy "skipping duplicate display type"
1114 macro has more than one type argument; the first one is used.
1115 .It Sy "skipping duplicate list type"
1119 macro has more than one type argument; the first one is used.
1120 .It Sy "skipping -width argument"
1134 .It Sy "unknown AT&T UNIX version"
1138 macro has an invalid argument.
1139 It is used verbatim, with
1142 .It Sy "comma in function argument"
1148 macro contains a comma; it should probably be split into two arguments.
1149 .It Sy "parenthesis in function name"
1151 The first argument of an
1155 macro contains an opening or closing parenthesis; that's probably wrong,
1156 parentheses are added automatically.
1157 .It Sy "invalid content in Rs block"
1161 block contains plain text or non-% macros.
1162 The bogus content is left in the syntax tree.
1163 Formatting may be poor.
1164 .It Sy "invalid Boolean argument"
1168 macro has an argument other than
1172 The invalid argument is moved out of the macro, which leaves the macro
1173 empty, causing it to toggle the spacing mode.
1174 .It Sy "unknown font, skipping request"
1182 layout modifier has an unknown
1186 .Ss "Warnings related to plain text"
1188 .It Sy "blank line in fill mode, using .sp"
1190 The meaning of blank input lines is only well-defined in non-fill mode:
1191 In fill mode, line breaks of text input lines are not supposed to be
1193 However, for compatibility with groff, blank lines in fill mode
1197 .It Sy "tab in filled text"
1199 The meaning of tab characters is only well-defined in non-fill mode:
1200 In fill mode, whitespace is not supposed to be significant
1201 on text input lines.
1202 As an implementation dependent choice, tab characters on text lines
1203 are passed through to the formatters in any case.
1204 Given that the text before the tab character will be filled,
1205 it is hard to predict which tab stop position the tab will advance to.
1206 .It Sy "whitespace at end of input line"
1207 .Pq mdoc , man , roff
1208 Whitespace at the end of input lines is almost never semantically
1209 significant \(em but in the odd case where it might be, it is
1210 extremely confusing when reviewing and maintaining documents.
1211 .It Sy "bad comment style"
1213 Comment lines start with a dot, a backslash, and a double-quote character.
1216 utility treats the line as a comment line even without the backslash,
1217 but leaving out the backslash might not be portable.
1218 .It Sy "invalid escape sequence"
1220 An escape sequence has an invalid opening argument delimiter, lacks the
1221 closing argument delimiter, or the argument has too few characters.
1222 If the argument is incomplete,
1226 expand to an empty string,
1232 to the length of the incomplete argument.
1233 All other invalid escape sequences are ignored.
1234 .It Sy "undefined string, using \(dq\(dq"
1236 If a string is used without being defined before,
1237 its value is implicitly set to the empty string.
1238 However, defining strings explicitly before use
1239 keeps the code more readable.
1241 .Ss "Errors related to equations"
1243 .It "unexpected equation scope closure"
1244 .It "equation scope open on exit"
1245 .It "overlapping equation scopes"
1246 .It "unexpected end of equation"
1248 .Ss "Errors related to tables"
1250 .It "bad table syntax"
1251 .It "bad table option"
1252 .It "bad table layout"
1253 .It "no table layout cells specified"
1254 .It "no table data cells specified"
1255 .It "ignore data in cell"
1256 .It "data block still open"
1257 .It "ignoring extra data cells"
1259 .Ss "Errors related to roff, mdoc, and man code"
1261 .It Sy "input stack limit exceeded, infinite loop?"
1263 Explicit recursion limits are implemented for the following features,
1264 in order to prevent infinite loops:
1267 expansion of nested escape sequences
1268 including expansion of strings and number registers,
1270 expansion of nested user-defined macros,
1276 When a limit is hit, the output is incorrect, typically losing
1277 some content, but the parser can continue.
1278 .It Sy "skipping bad character"
1279 .Pq mdoc , man , roff
1280 The input file contains a byte that is not a printable
1283 The message mentions the character number.
1284 The offending byte is replaced with a question mark
1286 Consider editing the input file to replace the byte with an ASCII
1287 transliteration of the intended character.
1288 .It Sy "skipping unknown macro"
1289 .Pq mdoc , man , roff
1290 The first identifier on a request or macro line is neither recognized as a
1292 request, nor as a user-defined macro, nor, respectively, as an
1297 It may be mistyped or unsupported.
1298 The request or macro is discarded including its arguments.
1299 .It Sy "skipping item outside list"
1303 macro occurs outside any
1308 delimiter occurs outside any pile.
1309 It is discarded including its arguments.
1310 .It Sy "skipping column outside column list"
1314 macro occurs outside any
1317 It is discarded including its arguments.
1318 .It Sy "skipping end of block that is not open"
1319 .Pq mdoc , man , eqn , tbl , roff
1320 Various syntax elements can only be used to explicitly close blocks
1321 that have previously been opened.
1324 block closing macro, a
1331 right delimiter or closing brace, or the end of an equation, table, or
1333 conditional request is encountered but no matching block is open.
1334 The offending request or macro is discarded.
1335 .It Sy "inserting missing end of block"
1339 macros as well as tables require explicit closing by dedicated macros.
1340 A block that doesn't support bad nesting
1341 ends before all of its children are properly closed.
1342 The open child nodes are closed implicitly.
1343 .It Sy "scope open on exit"
1344 .Pq mdoc , man , eqn , tbl , roff
1345 At the end of the document, an explicit
1353 block, an equation, table, or
1355 conditional or ignore block is still open.
1356 The open block is closed implicitly.
1357 .It Sy "escaped character not allowed in a name"
1359 Macro, string and register identifiers consist of printable,
1360 non-whitespace ASCII characters.
1361 Escape sequences and characters and strings expressed in terms of them
1362 cannot form part of a name.
1363 The first argument of an
1371 request, or any argument of an
1373 request, or the name of a request or user defined macro being called,
1374 is terminated by an escape sequence.
1380 the request has no effect at all.
1387 what was parsed up to this point is used as the arguments to the request,
1388 and the rest of the input line is discarded including the escape sequence.
1389 When parsing for a request or a user-defined macro name to be called,
1390 only the escape sequence is discarded.
1391 The characters preceding it are used as the request or macro name,
1392 the characters following it are used as the arguments to the request or macro.
1393 .It Sy "argument count wrong"
1394 .Pq mdoc , man , roff
1395 The indicated request or macro has too few or too many arguments.
1396 The syntax tree will contain the wrong number of arguments as given.
1397 Formatting behaviour depends on the specific request or macro in question.
1398 Note that the same message may also occur as a WARNING, see above.
1399 .It Sy "missing list type, using -item"
1403 macro fails to specify the list type.
1404 .It Sy "missing manual name, using \(dq\(dq"
1408 lacks the required argument.
1409 .It Sy "uname(3) system call failed, using UNKNOWN"
1413 macro is called without arguments, and the
1418 can be compiled with
1420 .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
1422 .It Sy "unknown standard specifier"
1426 macro has an unknown argument and is discarded.
1427 .It Sy "skipping request without numeric argument"
1436 statement has a non-numeric or negative argument or no argument at all.
1437 The invalid request or statement is ignored.
1438 .It Sy "skipping all arguments"
1439 .Pq mdoc , man , eqn , roff
1452 macro in a list that don't support item heads, a
1466 block closing request is invoked with at least one argument.
1467 All arguments are ignored.
1468 .It Sy "skipping excess arguments"
1472 macro is invoked with more than one argument, or a request of the
1474 family is invoked with more than two arguments.
1475 The excess arguments are ignored.
1479 .It Sy "input too large"
1483 cannot handle input files larger than its arbitrary size limit
1484 of 2^31 bytes (2 Gigabytes).
1485 Since useful manuals are always small, this is not a problem in practice.
1486 Parsing is aborted as soon as the condition is detected.
1487 .It Sy "NOT IMPLEMENTED: Bd -file"
1489 For security reasons, the
1491 macro does not support the
1494 By requesting the inclusion of a sensitive file, a malicious document
1495 might otherwise trick a privileged user into inadvertently displaying
1496 the file on the screen, revealing the file content to bystanders.
1497 The parser exits immediately.
1498 .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
1500 For security reasons,
1504 file inclusion requests only with relative paths
1505 and only without ascending to any parent directory.
1506 By requesting the inclusion of a sensitive file, a malicious document
1507 might otherwise trick a privileged user into inadvertently displaying
1508 the file on the screen, revealing the file content to bystanders.
1509 The parser exits immediately.
1510 .It Sy ".so request failed"
1514 request requires reading an external file.
1515 While trying to do so, an
1521 The parser exits immediately.
1522 Before showing this message,
1524 always shows another message explaining why the system call failed.
1527 This section summarises
1529 compatibility with GNU troff.
1530 Each input and output format is separately noted.
1531 .Ss ASCII Compatibility
1532 .Bl -bullet -compact
1534 Unrenderable unicode codepoints specified with
1536 escapes are printed as
1539 In GNU troff, these raise an error.
1549 are synonyms, as are \-filled and \-ragged.
1551 In historic GNU troff, the
1554 macro does not underline when scoped under an
1556 in the FILES section.
1557 This behaves correctly in
1560 A list or display following the
1565 does not assert a prior vertical break, just as it doesn't with
1575 Words aren't hyphenated.
1577 .Ss HTML Compatibility
1578 .Bl -bullet -compact
1582 escape will revert the font to the previous
1584 escape, not to the last rendered decoration, which is now dictated by
1585 CSS instead of hard-coded.
1586 It also will not span past the current scope,
1587 for the same reason.
1590 mode, this will work fine.
1597 list types render similarly (no break following overreached left-hand
1598 side) due to the expressive constraints of HTML.
1605 lists render similarly.
1617 utility was written by
1618 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
1624 the maximum size of an element attribute is determined by
1626 which is usually 1024 bytes.
1627 Be aware of this when setting long link
1629 .Fl O Ns Cm style Ns = Ns Ar really/long/link .
1631 Nesting elements within next-line element scopes of
1641 and cause them to forget the formatting of the prior next-line scope.
1645 control character is an alias for the standard macro control character
1646 and does not emit a line-break as stipulated in GNU troff.
git.ckatri.com / mandoc.git / blob