1 .\" $Id: mandoc.1,v 1.130 2014/12/28 14:42:27 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: December 28 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
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.
170 .Fl W Ns Cm warning .
181 to exit after parsing a file that causes warnings or errors of at least
183 No formatted output will be produced from that file.
188 are requested, they can be joined with a comma, for example
189 .Fl W Ns Cm error , Ns Cm stop .
191 Read input from zero or more files.
192 If unspecified, reads from stdin.
193 If multiple files are specified,
195 will halt with the first failed parse.
204 also supports the options
227 should only be used for legacy manuals.
231 which is also the default, determines encoding on-the-fly: if the first
238 parser is used; otherwise, the
243 files are specified with
245 each has its file-type determined this way.
246 If multiple files are
251 is specified, then this format is used exclusively.
255 utility accepts the following
257 arguments, which correspond to output modes:
258 .Bl -tag -width "-Tlocale"
260 Produce 7-bit ASCII output.
264 Produce HTML5, CSS1, and MathML output.
268 Parse only: produce no output.
270 .Fl W Ns Cm warning .
271 .It Fl T Ns Cm locale
272 Encode output using the current locale.
287 Produce PostScript output.
289 .Sx PostScript Output .
291 Produce an indented parse tree.
293 Encode output in the UTF\-8 multi-byte format.
297 This is a synonym for
301 If multiple input files are specified, these will be processed by the
302 corresponding filter in-order.
306 is rendered in standard 7-bit ASCII documented in
309 Font styles are applied by using back-spaced encoding such that an
313 .Sq _ Ns \e[bs] Ns c ,
316 is the back-space character number 8.
317 Emboldened characters are rendered as
318 .Sq c Ns \e[bs] Ns c .
320 The special characters documented in
322 are rendered best-effort in an ASCII equivalent.
323 If no equivalent is found,
327 Output width is limited to 78 visible columns unless literal input lines
332 arguments are accepted:
334 .It Cm indent Ns = Ns Ar indent
335 The left margin for normal text is set to
337 blank characters instead of the default of five for
341 Increasing this is not recommended; it may result in degraded formatting,
342 for example overfull lines or ugly line breaks.
343 .It Cm width Ns = Ns Ar width
344 The output width is set to
346 which will normalise to \(>=60.
351 conforms to HTML5 using optional self-closing tags.
352 Default styles use only CSS1.
353 Equations rendered from
358 .Pa example.style.css
359 file documents style-sheet classes available for customising output.
360 If a style-sheet is not specified with
363 defaults to simple output (via an embedded style-sheet)
364 readable in any graphical or text-based web
367 Special characters are rendered in decimal-encoded UTF\-8.
371 arguments are accepted:
374 Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body>
375 elements and only emit the subtree below the <body> element.
378 argument will be ignored.
379 This is useful when embedding manual content within existing documents.
380 .It Cm includes Ns = Ns Ar fmt
385 is used as a template for linked header files (usually via the
390 are replaced with the include filename.
391 The default is not to present a
393 .It Cm man Ns = Ns Ar fmt
397 .Ar ../html%S/%N.%S.html ,
398 is used as a template for linked manuals (usually via the
405 are replaced with the linked manual's name and section, respectively.
406 If no section is included, section 1 is assumed.
407 The default is not to
409 .It Cm style Ns = Ns Ar style.css
412 is used for an external style-sheet.
413 This must be a valid absolute or
417 Locale-depending output encoding is triggered with
421 This option is not available on all systems: systems without locale
422 support, or those whose internal representation is not natively UCS-4,
427 for font style specification and available command-line arguments.
429 Translate input format into
432 This is useful for distributing manual sources to legacy systems
439 is passed as input, it is translated into
441 If the input format is
443 the input is copied to the output, expanding any
447 The parser is also run, and as usual, the
451 are displayed before copying the input to the output.
453 PDF-1.1 output may be generated by
456 .Sx PostScript Output
459 arguments and defaults.
460 .Ss PostScript Output
463 Level-2 pages may be generated by
465 Output pages default to letter sized and are rendered in the Times font
467 Margins are calculated as 1/9 the page length and width.
470 Special characters are rendered as in
475 arguments are accepted:
477 .It Cm paper Ns = Ns Ar name
487 You may also manually specify dimensions as
489 width by height in millimetres.
490 If an unknown value is encountered,
497 to force a UTF\-8 locale.
500 for details and options.
502 .Bl -tag -width MANPAGER
504 Any non-empty value of the environment variable
506 will be used instead of the standard pagination program,
509 Specifies the pagination program to use when
512 If neither PAGER nor MANPAGER is defined,
513 .Pa /usr/bin/more Fl s
519 utility exits with one of the following values, controlled by the message
525 .Bl -tag -width Ds -compact
527 No warnings or errors occurred, or those that did were ignored because
528 they were lower than the requested
531 At least one warning occurred, but no error, and
535 At least one parsing error occurred, but no fatal error, and
541 A fatal parsing error occurred.
543 Invalid command line arguments were specified.
544 No input files have been read.
546 An operating system error occurred, for example memory exhaustion or an
547 error accessing input files.
550 to exit at once, possibly in the middle of parsing or formatting a file.
556 .Fl W Ns Cm warning .
558 To page manuals to the terminal:
560 .Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less
561 .Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
563 To produce HTML manuals with
567 .Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
569 To check over a large set of manuals:
571 .Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]`
573 To produce a series of PostScript manuals for A4 paper:
575 .Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
581 format, for use on systems lacking an
585 .Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man
587 Messages displayed by
591 .D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args
593 Line and column numbers start at 1.
594 Both are omitted for messages referring to an input file as a whole.
595 Macro names and arguments are omitted where meaningless.
596 Fatal messages about invalid command line arguments
597 or operating system errors, for example when memory is exhausted,
604 Message levels have the following meanings:
605 .Bl -tag -width "warning"
607 Opening or reading an input file failed, so the parser cannot
608 even be started and no output is produced from that input file.
610 The parser is unable to parse a given input file at all.
611 No formatted output is produced from that input file.
613 An input file contains syntax that cannot be safely interpreted,
614 either because it is invalid or because
616 does not implement it yet.
617 By discarding part of the input or inserting missing tokens,
618 the parser is able to continue, and the error does not prevent
619 generation of formatted output, but typically, preparing that
620 output involves information loss, broken document structure
621 or unintended formatting.
623 An input file uses obsolete, discouraged or non-portable syntax.
624 All the same, the meaning of the input is unambiguous and a correct
625 rendering can be produced.
626 Documents causing warnings may render poorly when using other
627 formatting tools instead of
635 levels are hidden unless their level, or a lower level, is requested using a
640 .Ss Warnings related to the document prologue
642 .It Sy "missing manual title, using UNTITLED"
646 macro has no arguments, or there is no
648 macro before the first non-prologue macro.
649 .It Sy "missing manual title, using \(dq\(dq"
653 macro, or it has no arguments.
654 .It Sy "lower case character in document title"
656 The title is still used as given in the
661 .It Sy "missing manual section, using \(dq\(dq"
667 macro lacks the mandatory section argument.
668 .It Sy "unknown manual section"
670 The section number in a
672 line is invalid, but still used.
673 .It Sy "missing date, using today's date"
675 The document was parsed as
681 macro has no arguments or only empty arguments;
682 or the document was parsed as
688 macro has less than three arguments or its third argument is empty.
689 .It Sy "cannot parse date, using it verbatim"
695 macro does not follow the conventional format.
696 .It Sy "missing Os macro, using \(dq\(dq"
698 The default or current system is not shown in this case.
699 .It Sy "duplicate prologue macro"
701 One of the prologue macros occurs more than once.
702 The last instance overrides all previous ones.
703 .It Sy "late prologue macro"
709 macro occurs after some non-prologue macro, but still takes effect.
710 .It Sy "skipping late title macro"
714 macro can only occur before the first non-prologue macro
715 because traditional formatters write the page header
716 before parsing the document body.
717 Even though this technical restriction does not apply to
719 traditional semantics is preserved.
720 The late macro is discarded including its arguments.
721 .It Sy "prologue macros out of order"
723 The prologue macros are not given in the conventional order
727 All three macros are used even when given in another order.
729 .Ss Warnings regarding document structure
731 .It Sy ".so is fragile, better use ln(1)"
733 Including files only works when the parser program runs with the correct
734 current working directory.
735 .It Sy "no document body"
737 The document body contains neither text nor macros.
738 An empty document is shown, consisting only of a header and a footer line.
739 .It Sy "content before first section header"
741 Some macros or text precede the first
746 The offending macros and text are parsed and added to the top level
747 of the syntax tree, outside any section block.
748 .It Sy "first section is not NAME"
750 The argument of the first
758 .It Sy "bad NAME section contents"
760 The last node in the NAME section is not an
762 macro, or any preceding macro is not
764 or the NAME section is completely empty.
769 .It Sy "sections out of conventional order"
771 A standard section occurs after another section it usually precedes.
772 All section titles are used as given,
773 and the order of sections is not changed.
774 .It Sy "duplicate section title"
776 The same standard section title occurs more than once.
777 .It Sy "unexpected section"
779 A standard section header occurs in a section of the manual
780 where it normally isn't useful.
781 .It Sy "unusual Xr order"
783 In the SEE ALSO section, an
785 macro with a lower section number follows one with a higher number,
788 macros refering to the same section are out of alphabetical order.
789 .It Sy "unusual Xr punctuation"
791 In the SEE ALSO section, punctuation between two
793 macros differs from a single comma, or there is trailing punctuation
797 .It Sy "AUTHORS section without An macro"
799 An AUTHORS sections contains no
801 macros, or only empty ones.
802 Probably, there are author names lacking markup.
804 .Ss "Warnings related to macros and nesting"
806 .It Sy "obsolete macro"
810 manual for replacements.
811 .It Sy "macro neither callable nor escaped"
813 The name of a macro that is not callable appears on a macro line.
814 It is printed verbatim.
815 If the intention is to call it, move it to its own line;
816 otherwise, escape it by prepending
818 .It Sy "skipping paragraph macro"
821 documents, this happens
824 at the beginning and end of sections and subsections
826 right before non-compact lists and displays
828 at the end of items in non-column, non-compact lists
830 and for multiple consecutive paragraph macros.
834 documents, it happens
846 macros having neither head nor body arguments
857 .It Sy "moving paragraph macro out of list"
861 list contains a trailing paragraph macro.
862 The paragraph macro is moved after the end of the list.
863 .It Sy "skipping no-space macro"
865 An input line begins with an
868 The macro is ignored.
869 .It Sy "blocks badly nested"
871 If two blocks intersect, one should completely contain the other.
872 Otherwise, rendered output is likely to look strange in any output
873 format, and rendering in SGML-based output formats is likely to be
874 outright wrong because such languages do not support badly nested
876 Typical examples of badly nested blocks are
877 .Qq Ic \&Ao \&Bo \&Ac \&Bc
879 .Qq Ic \&Ao \&Bq \&Ac .
887 .It Sy "nested displays are not portable"
894 display occurs nested inside another
899 but fails with most other implementations.
900 .It Sy "moving content out of list"
904 list block contains text or macros before the first
907 The offending children are moved before the beginning of the list.
908 .It Sy ".Vt block has child macro"
912 macro supports plain text arguments only.
913 Formatting may be ugly and semantic searching
914 for the affected content might not work.
915 .It Sy "fill mode already enabled, skipping"
919 request occurs even though the document is still in fill mode,
920 or already switched back to fill mode.
922 .It Sy "fill mode already disabled, skipping"
926 request occurs even though the document already switched to no-fill mode
927 and did not switch back to fill mode yet.
929 .It Sy "line scope broken"
931 While parsing the next-line scope of the previous macro,
932 another macro is found that prematurely terminates the previous one.
933 The previous, interrupted macro is deleted from the parse tree.
935 .Ss "Warnings related to missing arguments"
937 .It Sy "skipping empty request"
939 The macro name is missing from a macro definition request,
942 control statement or operation keyword lacks its required argument.
943 .It Sy "conditional request controls empty scope"
945 A conditional request is only useful if any of the following
946 follows it on the same logical input line:
951 keyword to open a multi-line scope.
953 A request or macro or some text, resulting in a single-line scope.
955 The immediate end of the logical line without any intervening whitespace,
956 resulting in next-line scope.
958 Here, a conditional request is followed by trailing whitespace only,
959 and there is no other content on its logical input line.
960 Note that it doesn't matter whether the logical input line is split
961 across multiple physical input lines using
963 line continuation characters.
964 This is one of the rare cases
965 where trailing whitespace is syntactically significant.
966 The conditional request controls a scope containing whitespace only,
967 so it is unlikely to have a significant effect,
968 except that it may control a following
971 .It Sy "skipping empty macro"
973 The indicated macro has no arguments and hence no effect.
974 .It Sy "empty argument, using 0n"
976 The required width is missing after
983 .It Sy "argument count wrong"
985 The indicated macro has too few or too many arguments.
986 The syntax tree will contain the wrong number of arguments as given.
987 Formatting behaviour depends on the specific macro in question.
988 Note that the same message may also occur as an ERROR, see below.
989 .It Sy "missing display type, using -ragged"
993 macro is invoked without the required display type.
994 .It Sy "list type is not the first argument"
998 macro, at least one other argument precedes the type argument.
1001 utility copes with any argument order, but some other
1003 implementations do not.
1004 .It Sy "missing -width in -tag list, using 8n"
1013 .It Sy "missing utility name, using \(dq\(dq"
1017 macro is called without an argument before
1019 has first been called with an argument.
1020 .It Sy "empty head in list item"
1032 macro lacks the required argument.
1033 The item head is left empty.
1034 .It Sy "empty list item"
1046 An empty list item is shown.
1047 .It Sy "missing font type"
1051 macro has no argument.
1052 It switches to the default font,
1054 .It Sy "unknown font type"
1058 argument is invalid.
1062 .It Sy "nothing follows prefix"
1066 macro has no argument, or only one argument and no macro follows
1067 on the same input line.
1068 This defeats its purpose; in particular, spacing is not suppressed
1069 before the text or macros following on the next input line.
1070 .It Sy "missing -std argument, adding it"
1076 macro lacks the required
1083 even when it is not specified, but other implementations may not.
1084 .It Sy "missing eqn box, using \(dq\(dq"
1086 A diacritic mark or a binary operator is found,
1087 but there is nothing to the left of it.
1088 An empty box is inserted.
1090 .Ss "Warnings related to bad macro arguments"
1092 .It Sy "unterminated quoted argument"
1094 Macro arguments can be enclosed in double quote characters
1095 such that space characters and macro names contained in the quoted
1096 argument need not be escaped.
1097 The closing quote of the last argument of a macro can be omitted.
1098 However, omitting it is not recommended because it makes the code
1100 .It Sy "duplicate argument"
1106 macro has more than one
1113 All but the last instances of these arguments are ignored.
1114 .It Sy "skipping duplicate argument"
1118 macro has more than one
1123 All but the first of these arguments are ignored.
1124 .It Sy "skipping duplicate display type"
1128 macro has more than one type argument; the first one is used.
1129 .It Sy "skipping duplicate list type"
1133 macro has more than one type argument; the first one is used.
1134 .It Sy "skipping -width argument"
1148 .It Sy "unknown AT&T UNIX version"
1152 macro has an invalid argument.
1153 It is used verbatim, with
1156 .It Sy "comma in function argument"
1162 macro contains a comma; it should probably be split into two arguments.
1163 .It Sy "parenthesis in function name"
1165 The first argument of an
1169 macro contains an opening or closing parenthesis; that's probably wrong,
1170 parentheses are added automatically.
1171 .It Sy "invalid content in Rs block"
1175 block contains plain text or non-% macros.
1176 The bogus content is left in the syntax tree.
1177 Formatting may be poor.
1178 .It Sy "invalid Boolean argument"
1182 macro has an argument other than
1186 The invalid argument is moved out of the macro, which leaves the macro
1187 empty, causing it to toggle the spacing mode.
1188 .It Sy "unknown font, skipping request"
1196 layout modifier has an unknown
1200 .Ss "Warnings related to plain text"
1202 .It Sy "blank line in fill mode, using .sp"
1204 The meaning of blank input lines is only well-defined in non-fill mode:
1205 In fill mode, line breaks of text input lines are not supposed to be
1207 However, for compatibility with groff, blank lines in fill mode
1211 .It Sy "tab in filled text"
1213 The meaning of tab characters is only well-defined in non-fill mode:
1214 In fill mode, whitespace is not supposed to be significant
1215 on text input lines.
1216 As an implementation dependent choice, tab characters on text lines
1217 are passed through to the formatters in any case.
1218 Given that the text before the tab character will be filled,
1219 it is hard to predict which tab stop position the tab will advance to.
1220 .It Sy "whitespace at end of input line"
1221 .Pq mdoc , man , roff
1222 Whitespace at the end of input lines is almost never semantically
1223 significant \(em but in the odd case where it might be, it is
1224 extremely confusing when reviewing and maintaining documents.
1225 .It Sy "bad comment style"
1227 Comment lines start with a dot, a backslash, and a double-quote character.
1230 utility treats the line as a comment line even without the backslash,
1231 but leaving out the backslash might not be portable.
1232 .It Sy "invalid escape sequence"
1234 An escape sequence has an invalid opening argument delimiter, lacks the
1235 closing argument delimiter, or the argument has too few characters.
1236 If the argument is incomplete,
1240 expand to an empty string,
1246 to the length of the incomplete argument.
1247 All other invalid escape sequences are ignored.
1248 .It Sy "undefined string, using \(dq\(dq"
1250 If a string is used without being defined before,
1251 its value is implicitly set to the empty string.
1252 However, defining strings explicitly before use
1253 keeps the code more readable.
1255 .Ss "Errors related to equations"
1257 .It "unexpected equation scope closure"
1258 .It "equation scope open on exit"
1259 .It "overlapping equation scopes"
1260 .It "unexpected end of equation"
1262 .Ss "Errors related to tables"
1264 .It "bad table syntax"
1265 .It "bad table option"
1266 .It "bad table layout"
1267 .It "no table layout cells specified"
1268 .It "no table data cells specified"
1269 .It "ignore data in cell"
1270 .It "data block still open"
1271 .It "ignoring extra data cells"
1272 .It "ignoring macro in table"
1274 .Ss "Errors related to roff, mdoc, and man code"
1276 .It Sy "input stack limit exceeded, infinite loop?"
1278 Explicit recursion limits are implemented for the following features,
1279 in order to prevent infinite loops:
1282 expansion of nested escape sequences
1283 including expansion of strings and number registers,
1285 expansion of nested user-defined macros,
1291 When a limit is hit, the output is incorrect, typically losing
1292 some content, but the parser can continue.
1293 .It Sy "skipping bad character"
1294 .Pq mdoc , man , roff
1295 The input file contains a byte that is not a printable
1298 The message mentions the character number.
1299 The offending byte is replaced with a question mark
1301 Consider editing the input file to replace the byte with an ASCII
1302 transliteration of the intended character.
1303 .It Sy "skipping unknown macro"
1304 .Pq mdoc , man , roff
1305 The first identifier on a request or macro line is neither recognized as a
1307 request, nor as a user-defined macro, nor, respectively, as an
1312 It may be mistyped or unsupported.
1313 The request or macro is discarded including its arguments.
1314 .It Sy "skipping item outside list"
1318 macro occurs outside any
1323 delimiter occurs outside any pile.
1324 It is discarded including its arguments.
1325 .It Sy "skipping column outside column list"
1329 macro occurs outside any
1332 It is discarded including its arguments.
1333 .It Sy "skipping end of block that is not open"
1334 .Pq mdoc , man , eqn , tbl , roff
1335 Various syntax elements can only be used to explicitly close blocks
1336 that have previously been opened.
1339 block closing macro, a
1346 right delimiter or closing brace, or the end of an equation, table, or
1348 conditional request is encountered but no matching block is open.
1349 The offending request or macro is discarded.
1350 .It Sy "inserting missing end of block"
1354 macros as well as tables require explicit closing by dedicated macros.
1355 A block that doesn't support bad nesting
1356 ends before all of its children are properly closed.
1357 The open child nodes are closed implicitly.
1358 .It Sy "scope open on exit"
1359 .Pq mdoc , man , eqn , tbl , roff
1360 At the end of the document, an explicit
1368 block, an equation, table, or
1370 conditional or ignore block is still open.
1371 The open block is closed implicitly.
1372 .It Sy "escaped character not allowed in a name"
1374 Macro, string and register identifiers consist of printable,
1375 non-whitespace ASCII characters.
1376 Escape sequences and characters and strings expressed in terms of them
1377 cannot form part of a name.
1378 The first argument of an
1386 request, or any argument of an
1388 request, or the name of a request or user defined macro being called,
1389 is terminated by an escape sequence.
1395 the request has no effect at all.
1402 what was parsed up to this point is used as the arguments to the request,
1403 and the rest of the input line is discarded including the escape sequence.
1404 When parsing for a request or a user-defined macro name to be called,
1405 only the escape sequence is discarded.
1406 The characters preceding it are used as the request or macro name,
1407 the characters following it are used as the arguments to the request or macro.
1408 .It Sy "argument count wrong"
1409 .Pq mdoc , man , roff
1410 The indicated request or macro has too few or too many arguments.
1411 The syntax tree will contain the wrong number of arguments as given.
1412 Formatting behaviour depends on the specific request or macro in question.
1413 Note that the same message may also occur as a WARNING, see above.
1414 .It Sy "NOT IMPLEMENTED: Bd -file"
1416 For security reasons, the
1418 macro does not support the
1421 By requesting the inclusion of a sensitive file, a malicious document
1422 might otherwise trick a privileged user into inadvertently displaying
1423 the file on the screen, revealing the file content to bystanders.
1424 The argument is ignored including the file name following it.
1425 .It Sy "missing list type, using -item"
1429 macro fails to specify the list type.
1430 .It Sy "missing manual name, using \(dq\(dq"
1434 lacks the required argument.
1435 .It Sy "uname(3) system call failed, using UNKNOWN"
1439 macro is called without arguments, and the
1444 can be compiled with
1446 .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
1448 .It Sy "unknown standard specifier"
1452 macro has an unknown argument and is discarded.
1453 .It Sy "skipping request without numeric argument"
1462 statement has a non-numeric or negative argument or no argument at all.
1463 The invalid request or statement is ignored.
1464 .It Sy "skipping all arguments"
1465 .Pq mdoc , man , eqn , roff
1478 macro in a list that don't support item heads, a
1492 block closing request is invoked with at least one argument.
1493 All arguments are ignored.
1494 .It Sy "skipping excess arguments"
1498 macro is invoked with more than one argument, or a request of the
1500 family is invoked with more than two arguments.
1501 The excess arguments are ignored.
1505 .It Sy "input too large"
1509 cannot handle input files larger than its arbitrary size limit
1510 of 2^31 bytes (2 Gigabytes).
1511 Since useful manuals are always small, this is not a problem in practice.
1512 Parsing is aborted as soon as the condition is detected.
1513 .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
1515 For security reasons,
1519 file inclusion requests only with relative paths
1520 and only without ascending to any parent directory.
1521 By requesting the inclusion of a sensitive file, a malicious document
1522 might otherwise trick a privileged user into inadvertently displaying
1523 the file on the screen, revealing the file content to bystanders.
1524 The parser exits immediately.
1525 .It Sy ".so request failed"
1529 request requires reading an external file.
1530 While trying to do so, an
1536 The parser exits immediately.
1537 Before showing this message,
1539 always shows another message explaining why the system call failed.
1542 This section summarises
1544 compatibility with GNU troff.
1545 Each input and output format is separately noted.
1546 .Ss ASCII Compatibility
1547 .Bl -bullet -compact
1549 Unrenderable unicode codepoints specified with
1551 escapes are printed as
1554 In GNU troff, these raise an error.
1564 are synonyms, as are \-filled and \-ragged.
1566 In historic GNU troff, the
1569 macro does not underline when scoped under an
1571 in the FILES section.
1572 This behaves correctly in
1575 A list or display following the
1580 does not assert a prior vertical break, just as it doesn't with
1590 Words aren't hyphenated.
1592 .Ss HTML Compatibility
1593 .Bl -bullet -compact
1597 escape will revert the font to the previous
1599 escape, not to the last rendered decoration, which is now dictated by
1600 CSS instead of hard-coded.
1601 It also will not span past the current scope,
1602 for the same reason.
1605 mode, this will work fine.
1612 list types render similarly (no break following overreached left-hand
1613 side) due to the expressive constraints of HTML.
1620 lists render similarly.
1632 utility was written by
1633 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
1639 the maximum size of an element attribute is determined by
1641 which is usually 1024 bytes.
1642 Be aware of this when setting long link
1644 .Fl O Ns Cm style Ns = Ns Ar really/long/link .
1646 Nesting elements within next-line element scopes of
1656 and cause them to forget the formatting of the prior next-line scope.
1660 control character is an alias for the standard macro control character
1661 and does not emit a line-break as stipulated in GNU troff.
git.ckatri.com / mandoc.git / blob