1 .\" $Id: mandoc.1,v 1.116 2014/10/10 08:44:24 kristaps 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: October 10 2014 $
23 .Nd format and display UNIX manuals
28 .Op Fl I Cm os Li = Ar name
40 manual pages for display.
48 text from stdin, implying
54 The options are as follows:
57 If the standard output is a terminal device and
61 to paginate the output, just like
65 Copy the formatted manual pages to the standard output without using
69 It can be specified to override
74 This overrides any earlier
80 .It Fl I Cm os Li = Ar name
82 Override the default operating system
89 Display only the SYNOPSIS lines.
95 This overrides any earlier
103 Also reverts any earlier
108 .It Fl m Ns Ar format
112 for available formats.
115 .It Fl O Ns Ar option
116 Comma-separated output options.
117 .It Fl T Ns Ar output
121 for available formats.
125 Print version and exit.
127 Specify the minimum message
129 to be reported on the standard error output and to affect the exit status.
141 .Fl W Ns Cm warning .
152 to exit after parsing a file that causes warnings or errors of at least
154 No formatted output will be produced from that file.
159 are requested, they can be joined with a comma, for example
160 .Fl W Ns Cm error , Ns Cm stop .
162 Read input from zero or more files.
163 If unspecified, reads from stdin.
164 If multiple files are specified,
166 will halt with the first failed parse.
175 also supports the options
198 should only be used for legacy manuals.
202 which is also the default, determines encoding on-the-fly: if the first
209 parser is used; otherwise, the
214 files are specified with
216 each has its file-type determined this way.
217 If multiple files are
222 is specified, then this format is used exclusively.
226 utility accepts the following
228 arguments, which correspond to output modes:
229 .Bl -tag -width "-Tlocale"
231 Produce 7-bit ASCII output.
236 Produce HTML5, CSS1, and MathML output.
240 Parse only: produce no output.
242 .Fl W Ns Cm warning .
243 .It Fl T Ns Cm locale
244 Encode output using the current locale.
258 Produce PostScript output.
260 .Sx PostScript Output .
262 Produce an indented parse tree.
264 Encode output in the UTF\-8 multi-byte format.
268 This is a synonym for
272 If multiple input files are specified, these will be processed by the
273 corresponding filter in-order.
277 which is the default, is rendered in standard 7-bit ASCII documented in
280 Font styles are applied by using back-spaced encoding such that an
284 .Sq _ Ns \e[bs] Ns c ,
287 is the back-space character number 8.
288 Emboldened characters are rendered as
289 .Sq c Ns \e[bs] Ns c .
291 The special characters documented in
293 are rendered best-effort in an ASCII equivalent.
294 If no equivalent is found,
298 Output width is limited to 78 visible columns unless literal input lines
303 arguments are accepted:
305 .It Cm indent Ns = Ns Ar indent
306 The left margin for normal text is set to
308 blank characters instead of the default of five for
312 Increasing this is not recommended; it may result in degraded formatting,
313 for example overfull lines or ugly line breaks.
314 .It Cm width Ns = Ns Ar width
315 The output width is set to
317 which will normalise to \(>=60.
322 conforms to HTML5 using optional self-closing tags.
323 Default styles use only CSS1.
324 Equations rendered from
329 .Pa example.style.css
330 file documents style-sheet classes available for customising output.
331 If a style-sheet is not specified with
334 defaults to simple output (via an embedded style-sheet)
335 readable in any graphical or text-based web
338 Special characters are rendered in decimal-encoded UTF\-8.
342 arguments are accepted:
352 elements and only emit the subtree below the
357 argument will be ignored.
358 This is useful when embedding manual content within existing documents.
359 .It Cm includes Ns = Ns Ar fmt
364 is used as a template for linked header files (usually via the
369 are replaced with the include filename.
370 The default is not to present a
372 .It Cm man Ns = Ns Ar fmt
376 .Ar ../html%S/%N.%S.html ,
377 is used as a template for linked manuals (usually via the
384 are replaced with the linked manual's name and section, respectively.
385 If no section is included, section 1 is assumed.
386 The default is not to
388 .It Cm style Ns = Ns Ar style.css
391 is used for an external style-sheet.
392 This must be a valid absolute or
396 Locale-depending output encoding is triggered with
398 This option is not available on all systems: systems without locale
399 support, or those whose internal representation is not natively UCS-4,
404 for font style specification and available command-line arguments.
406 Translate input format into
409 This is useful for distributing manual sources to legacy systems
416 is passed as input, it is translated into
418 If the input format is
420 the input is copied to the output, expanding any
424 The parser is also run, and as usual, the
428 are displayed before copying the input to the output.
430 PDF-1.1 output may be generated by
433 .Sx PostScript Output
436 arguments and defaults.
437 .Ss PostScript Output
440 Level-2 pages may be generated by
442 Output pages default to letter sized and are rendered in the Times font
444 Margins are calculated as 1/9 the page length and width.
447 Special characters are rendered as in
452 arguments are accepted:
454 .It Cm paper Ns = Ns Ar name
464 You may also manually specify dimensions as
466 width by height in millimetres.
467 If an unknown value is encountered,
474 to force a UTF\-8 locale.
477 for details and options.
479 .Bl -tag -width MANPAGER
481 Any non-empty value of the environment variable
483 will be used instead of the standard pagination program,
486 Specifies the pagination program to use when
489 If neither PAGER nor MANPAGER is defined,
490 .Pa /usr/bin/more Fl s
496 utility exits with one of the following values, controlled by the message
502 .Bl -tag -width Ds -compact
504 No warnings or errors occurred, or those that did were ignored because
505 they were lower than the requested
508 At least one warning occurred, but no error, and
512 At least one parsing error occurred, but no fatal error, and
518 A fatal parsing error occurred.
520 Invalid command line arguments were specified.
521 No input files have been read.
523 An operating system error occurred, for example memory exhaustion or an
524 error accessing input files.
527 to exit at once, possibly in the middle of parsing or formatting a file.
533 .Fl W Ns Cm warning .
535 To page manuals to the terminal:
537 .Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less
538 .Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
540 To produce HTML manuals with
544 .Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
546 To check over a large set of manuals:
548 .Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]`
550 To produce a series of PostScript manuals for A4 paper:
552 .Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
558 format, for use on systems lacking an
562 .Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man
564 Messages displayed by
568 .D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args
570 Line and column numbers start at 1.
571 Both are omitted for messages referring to an input file as a whole.
572 Macro names and arguments are omitted where meaningless.
573 Fatal messages about invalid command line arguments
574 or operating system errors, for example when memory is exhausted,
581 Message levels have the following meanings:
582 .Bl -tag -width "warning"
584 Opening or reading an input file failed, so the parser cannot
585 even be started and no output is produced from that input file.
587 The parser is unable to parse a given input file at all.
588 No formatted output is produced from that input file.
590 An input file contains syntax that cannot be safely interpreted,
591 either because it is invalid or because
593 does not implement it yet.
594 By discarding part of the input or inserting missing tokens,
595 the parser is able to continue, and the error does not prevent
596 generation of formatted output, but typically, preparing that
597 output involves information loss, broken document structure
598 or unintended formatting.
600 An input file uses obsolete, discouraged or non-portable syntax.
601 All the same, the meaning of the input is unambiguous and a correct
602 rendering can be produced.
603 Documents causing warnings may render poorly when using other
604 formatting tools instead of
612 levels are hidden unless their level, or a lower level, is requested using a
617 .Ss Warnings related to the document prologue
619 .It Sy "missing manual title, using UNTITLED"
623 macro has no arguments, or there is no
625 macro before the first non-prologue macro.
626 .It Sy "missing manual title, using \(dq\(dq"
630 macro, or it has no arguments.
631 .It Sy "lower case character in document title"
633 The title is still used as given in the
638 .It Sy "missing manual section, using \(dq\(dq"
644 macro lacks the mandatory section argument.
645 .It Sy "unknown manual section"
647 The section number in a
649 line is invalid, but still used.
650 .It Sy "unknown manual volume or arch"
654 line is invalid, but still used.
655 The manual is assumed to be architecture-independent.
656 .It Sy "missing date, using today's date"
658 The document was parsed as
664 macro has no arguments or only empty arguments;
665 or the document was parsed as
671 macro has less than three arguments or its third argument is empty.
672 .It Sy "cannot parse date, using it verbatim"
678 macro does not follow the conventional format.
679 .It Sy "missing Os macro, using \(dq\(dq"
681 The default or current system is not shown in this case.
682 .It Sy "duplicate prologue macro"
684 One of the prologue macros occurs more than once.
685 The last instance overrides all previous ones.
686 .It Sy "late prologue macro"
692 macro occurs after some non-prologue macro, but still takes effect.
693 .It Sy "skipping late title macro"
697 macro can only occur before the first non-prologue macro
698 because traditional formatters write the page header
699 before parsing the document body.
700 Even though this technical restriction does not apply to
702 traditional semantics is preserved.
703 The late macro is discarded including its arguments.
704 .It Sy "prologue macros out of order"
706 The prologue macros are not given in the conventional order
710 All three macros are used even when given in another order.
712 .Ss Warnings regarding document structure
714 .It Sy ".so is fragile, better use ln(1)"
716 Including files only works when the parser program runs with the correct
717 current working directory.
718 .It Sy "no document body"
720 The document body contains neither text nor macros.
721 An empty document is shown, consisting only of a header and a footer line.
722 .It Sy "content before first section header"
724 Some macros or text precede the first
729 The offending macros and text are parsed and added to the top level
730 of the syntax tree, outside any section block.
731 .It Sy "first section is not NAME"
733 The argument of the first
741 .It Sy "bad NAME section contents"
743 The last node in the NAME section is not an
745 macro, or any preceding macro is not
747 or the NAME section is completely empty.
752 .It Sy "sections out of conventional order"
754 A standard section occurs after another section it usually precedes.
755 All section titles are used as given,
756 and the order of sections is not changed.
757 .It Sy "duplicate section title"
759 The same standard section title occurs more than once.
760 .It Sy "unexpected section"
762 A standard section header occurs in a section of the manual
763 where it normally isn't useful.
764 .It Sy "unusual Xr order"
766 In the SEE ALSO section, an
768 macro with a lower section number follows one with a higher number,
771 macros refering to the same section are out of alphabetical order.
772 .It Sy "unusual Xr punctuation"
774 In the SEE ALSO section, punctuation between two
776 macros differs from a single comma, or there is trailing punctuation
780 .It Sy "AUTHORS section without An macro"
782 An AUTHORS sections contains no
784 macros, or only empty ones.
785 Probably, there are author names lacking markup.
787 .Ss "Warnings related to macros and nesting"
789 .It Sy "obsolete macro"
793 manual for replacements.
794 .It Sy "skipping paragraph macro"
797 documents, this happens
800 at the beginning and end of sections and subsections
802 right before non-compact lists and displays
804 at the end of items in non-column, non-compact lists
806 and for multiple consecutive paragraph macros.
810 documents, it happens
822 macros having neither head nor body arguments
833 .It Sy "moving paragraph macro out of list"
837 list contains a trailing paragraph macro.
838 The paragraph macro is moved after the end of the list.
839 .It Sy "skipping no-space macro"
841 An input line begins with an
844 The macro is ignored.
845 .It Sy "blocks badly nested"
847 If two blocks intersect, one should completely contain the other.
848 Otherwise, rendered output is likely to look strange in any output
849 format, and rendering in SGML-based output formats is likely to be
850 outright wrong because such languages do not support badly nested
852 Typical examples of badly nested blocks are
853 .Qq Ic \&Ao \&Bo \&Ac \&Bc
855 .Qq Ic \&Ao \&Bq \&Ac .
863 .It Sy "nested displays are not portable"
870 display occurs nested inside another
875 but fails with most other implementations.
876 .It Sy "moving content out of list"
880 list block contains text or macros before the first
883 The offending children are moved before the beginning of the list.
884 .It Sy ".Vt block has child macro"
888 macro supports plain text arguments only.
889 Formatting may be ugly and semantic searching
890 for the affected content might not work.
891 .It Sy "fill mode already enabled, skipping"
895 request occurs even though the document is still in fill mode,
896 or already switched back to fill mode.
898 .It Sy "fill mode already disabled, skipping"
902 request occurs even though the document already switched to no-fill mode
903 and did not switch back to fill mode yet.
905 .It Sy "line scope broken"
907 While parsing the next-line scope of the previous macro,
908 another macro is found that prematurely terminates the previous one.
909 The previous, interrupted macro is deleted from the parse tree.
911 .Ss "Warnings related to missing arguments"
913 .It Sy "skipping empty request"
915 The macro name is missing from a macro definition request.
916 .It Sy "conditional request controls empty scope"
918 A conditional request is only useful if any of the following
919 follows it on the same logical input line:
924 keyword to open a multi-line scope.
926 A request or macro or some text, resulting in a single-line scope.
928 The immediate end of the logical line without any intervening whitespace,
929 resulting in next-line scope.
931 Here, a conditional request is followed by trailing whitespace only,
932 and there is no other content on its logical input line.
933 Note that it doesn't matter whether the logical input line is split
934 across multiple physical input lines using
936 line continuation characters.
937 This is one of the rare cases
938 where trailing whitespace is syntactically significant.
939 The conditional request controls a scope containing whitespace only,
940 so it is unlikely to have a significant effect,
941 except that it may control a following
944 .It Sy "skipping empty macro"
946 The indicated macro has no arguments and hence no effect.
947 .It Sy "empty argument, using 0n"
949 The required width is missing after
956 .It Sy "argument count wrong"
958 The indicated macro has too few or too many arguments.
959 The syntax tree will contain the wrong number of arguments as given.
960 Formatting behaviour depends on the specific macro in question.
961 Note that the same message may also occur as an ERROR, see below.
962 .It Sy "missing display type, using -ragged"
966 macro is invoked without the required display type.
967 .It Sy "list type is not the first argument"
971 macro, at least one other argument precedes the type argument.
974 utility copes with any argument order, but some other
976 implementations do not.
977 .It Sy "missing -width in -tag list, using 8n"
986 .It Sy "missing utility name, using \(dq\(dq"
990 macro is called without an argument before
992 has first been called with an argument.
993 .It Sy "empty head in list item"
1005 macro lacks the required argument.
1006 The item head is left empty.
1007 .It Sy "empty list item"
1019 An empty list item is shown.
1020 .It Sy "missing font type"
1024 macro has no argument.
1025 It switches to the default font,
1027 .It Sy "unknown font type"
1031 argument is invalid.
1035 .It Sy "missing -std argument, adding it"
1041 macro lacks the required
1048 even when it is not specified, but other implementations may not.
1050 .Ss "Warnings related to bad macro arguments"
1052 .It Sy "unterminated quoted argument"
1054 Macro arguments can be enclosed in double quote characters
1055 such that space characters and macro names contained in the quoted
1056 argument need not be escaped.
1057 The closing quote of the last argument of a macro can be omitted.
1058 However, omitting it is not recommended because it makes the code
1060 .It Sy "duplicate argument"
1066 macro has more than one
1073 All but the last instances of these arguments are ignored.
1074 .It Sy "skipping duplicate argument"
1078 macro has more than one
1083 All but the first of these arguments are ignored.
1084 .It Sy "skipping duplicate display type"
1088 macro has more than one type argument; the first one is used.
1089 .It Sy "skipping duplicate list type"
1093 macro has more than one type argument; the first one is used.
1094 .It Sy "skipping -width argument"
1108 .It Sy "unknown AT&T UNIX version"
1112 macro has an invalid argument.
1113 It is used verbatim, with
1116 .It Sy "comma in function argument"
1122 macro contains a comma; it should probably be split into two arguments.
1123 .It Sy "invalid content in Rs block"
1127 block contains plain text or non-% macros.
1128 The bogus content is left in the syntax tree.
1129 Formatting may be poor.
1130 .It Sy "invalid Boolean argument"
1134 macro has an argument other than
1138 The invalid argument is moved out of the macro, which leaves the macro
1139 empty, causing it to toggle the spacing mode.
1140 .It Sy "unknown font, skipping request"
1148 layout modifier has an unknown
1152 .Ss "Warnings related to plain text"
1154 .It Sy "blank line in fill mode, using .sp"
1156 The meaning of blank input lines is only well-defined in non-fill mode:
1157 In fill mode, line breaks of text input lines are not supposed to be
1159 However, for compatibility with groff, blank lines in fill mode
1163 .It Sy "tab in filled text"
1165 The meaning of tab characters is only well-defined in non-fill mode:
1166 In fill mode, whitespace is not supposed to be significant
1167 on text input lines.
1168 As an implementation dependent choice, tab characters on text lines
1169 are passed through to the formatters in any case.
1170 Given that the text before the tab character will be filled,
1171 it is hard to predict which tab stop position the tab will advance to.
1172 .It Sy "whitespace at end of input line"
1173 .Pq mdoc , man , roff
1174 Whitespace at the end of input lines is almost never semantically
1175 significant \(em but in the odd case where it might be, it is
1176 extremely confusing when reviewing and maintaining documents.
1177 .It Sy "bad comment style"
1179 Comment lines start with a dot, a backslash, and a double-quote character.
1182 utility treats the line as a comment line even without the backslash,
1183 but leaving out the backslash might not be portable.
1184 .It Sy "invalid escape sequence"
1186 An escape sequence has an invalid opening argument delimiter, lacks the
1187 closing argument delimiter, or the argument has too few characters.
1188 If the argument is incomplete,
1192 expand to an empty string,
1198 to the length of the incomplete argument.
1199 All other invalid escape sequences are ignored.
1200 .It Sy "undefined string, using \(dq\(dq"
1202 If a string is used without being defined before,
1203 its value is implicitly set to the empty string.
1204 However, defining strings explicitly before use
1205 keeps the code more readable.
1207 .Ss "Errors related to equations"
1209 .It "unexpected equation scope closure"
1210 .It "equation scope open on exit"
1211 .It "overlapping equation scopes"
1212 .It "unexpected end of equation"
1213 .It "equation syntax error"
1215 .Ss "Errors related to tables"
1217 .It "bad table syntax"
1218 .It "bad table option"
1219 .It "bad table layout"
1220 .It "no table layout cells specified"
1221 .It "no table data cells specified"
1222 .It "ignore data in cell"
1223 .It "data block still open"
1224 .It "ignoring extra data cells"
1226 .Ss "Errors related to roff, mdoc, and man code"
1228 .It Sy "input stack limit exceeded, infinite loop?"
1230 Explicit recursion limits are implemented for the following features,
1231 in order to prevent infinite loops:
1234 expansion of nested escape sequences
1235 including expansion of strings and number registers,
1237 expansion of nested user-defined macros,
1243 When a limit is hit, the output is incorrect, typically losing
1244 some content, but the parser can continue.
1245 .It Sy "skipping bad character"
1246 .Pq mdoc , man , roff
1247 The input file contains a byte that is not a printable
1250 The message mentions the character number.
1251 The offending byte is replaced with a question mark
1253 Consider editing the input file to replace the byte with an ASCII
1254 transliteration of the intended character.
1255 .It Sy "skipping unknown macro"
1256 .Pq mdoc , man , roff
1257 The first identifier on a request or macro line is neither recognized as a
1259 request, nor as a user-defined macro, nor, respectively, as an
1264 It may be mistyped or unsupported.
1265 The request or macro is discarded including its arguments.
1266 .It Sy "skipping item outside list"
1270 macro occurs outside any
1273 It is discarded including its arguments.
1274 .It Sy "skipping column outside column list"
1278 macro occurs outside any
1281 It is discarded including its arguments.
1282 .It Sy "skipping end of block that is not open"
1283 .Pq mdoc , man , eqn , tbl , roff
1284 Various syntax elements can only be used to explicitly close blocks
1285 that have previously been opened.
1288 block closing macro, a
1293 macro, or the end of an equation, table, or
1295 conditional request is encountered but no matching block is open.
1296 The offending request or macro is discarded.
1297 .It Sy "inserting missing end of block"
1301 macros as well as tables require explicit closing by dedicated macros.
1302 A block that doesn't support bad nesting
1303 ends before all of its children are properly closed.
1304 The open child nodes are closed implicitly.
1305 .It Sy "scope open on exit"
1306 .Pq mdoc , man , eqn , tbl , roff
1307 At the end of the document, an explicit
1315 block, an equation, table, or
1317 conditional or ignore block is still open.
1318 The open block is closed implicitly.
1319 .It Sy "escaped character not allowed in a name"
1321 Macro, string and register identifiers consist of printable,
1322 non-whitespace ASCII characters.
1323 Escape sequences and characters and strings expressed in terms of them
1324 cannot form part of a name.
1325 The first argument of an
1333 request, or any argument of an
1335 request, or the name of a request or user defined macro being called,
1336 is terminated by an escape sequence.
1342 the request has no effect at all.
1349 what was parsed up to this point is used as the arguments to the request,
1350 and the rest of the input line is discarded including the escape sequence.
1351 When parsing for a request or a user-defined macro name to be called,
1352 only the escape sequence is discarded.
1353 The characters preceding it are used as the request or macro name,
1354 the characters following it are used as the arguments to the request or macro.
1355 .It Sy "argument count wrong"
1356 .Pq mdoc , man , roff
1357 The indicated request or macro has too few or too many arguments.
1358 The syntax tree will contain the wrong number of arguments as given.
1359 Formatting behaviour depends on the specific request or macro in question.
1360 Note that the same message may also occur as a WARNING, see above.
1361 .It Sy "missing list type, using -item"
1365 macro fails to specify the list type.
1366 .It Sy "missing manual name, using \(dq\(dq"
1370 lacks the required argument.
1371 .It Sy "uname(3) system call failed, using UNKNOWN"
1375 macro is called without arguments, and the
1380 can be compiled with
1382 .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
1384 .It Sy "unknown standard specifier"
1388 macro has an unknown argument and is discarded.
1389 .It Sy "skipping request without numeric argument"
1393 request has a non-numeric or negative argument or no argument at all.
1394 The invalid request is ignored.
1395 .It Sy "skipping all arguments"
1396 .Pq mdoc , man , eqn , roff
1409 macro in a list that don't support item heads, a
1421 block closing request is invoked with at least one argument.
1422 All arguments are ignored.
1423 .It Sy "skipping excess arguments"
1427 macro is invoked with more than one argument, or a request of the
1429 family is invoked with more than two arguments.
1430 The excess arguments are ignored.
1434 .It Sy "input too large"
1438 cannot handle input files larger than its arbitrary size limit
1439 of 2^31 bytes (2 Gigabytes).
1440 Since useful manuals are always small, this is not a problem in practice.
1441 Parsing is aborted as soon as the condition is detected.
1442 .It Sy "NOT IMPLEMENTED: Bd -file"
1444 For security reasons, the
1446 macro does not support the
1449 By requesting the inclusion of a sensitive file, a malicious document
1450 might otherwise trick a privileged user into inadvertently displaying
1451 the file on the screen, revealing the file content to bystanders.
1452 The parser exits immediately.
1453 .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
1455 For security reasons,
1459 file inclusion requests only with relative paths
1460 and only without ascending to any parent directory.
1461 By requesting the inclusion of a sensitive file, a malicious document
1462 might otherwise trick a privileged user into inadvertently displaying
1463 the file on the screen, revealing the file content to bystanders.
1464 The parser exits immediately.
1465 .It Sy ".so request failed"
1469 request requires reading an external file.
1470 While trying to do so, an
1476 The parser exits immediately.
1477 Before showing this message,
1479 always shows another message explaining why the system call failed.
1482 This section summarises
1484 compatibility with GNU troff.
1485 Each input and output format is separately noted.
1486 .Ss ASCII Compatibility
1487 .Bl -bullet -compact
1489 Unrenderable unicode codepoints specified with
1491 escapes are printed as
1494 In GNU troff, these raise an error.
1504 are synonyms, as are \-filled and \-ragged.
1506 In historic GNU troff, the
1509 macro does not underline when scoped under an
1511 in the FILES section.
1512 This behaves correctly in
1515 A list or display following the
1520 does not assert a prior vertical break, just as it doesn't with
1530 Words aren't hyphenated.
1532 .Ss HTML Compatibility
1533 .Bl -bullet -compact
1537 escape will revert the font to the previous
1539 escape, not to the last rendered decoration, which is now dictated by
1540 CSS instead of hard-coded.
1541 It also will not span past the current scope,
1542 for the same reason.
1545 mode, this will work fine.
1552 list types render similarly (no break following overreached left-hand
1553 side) due to the expressive constraints of HTML.
1560 lists render similarly.
1572 utility was written by
1573 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
1579 the maximum size of an element attribute is determined by
1581 which is usually 1024 bytes.
1582 Be aware of this when setting long link
1584 .Fl O Ns Cm style Ns = Ns Ar really/long/link .
1586 Nesting elements within next-line element scopes of
1596 and cause them to forget the formatting of the prior next-line scope.
1600 control character is an alias for the standard macro control character
1601 and does not emit a line-break as stipulated in GNU troff.
git.ckatri.com / mandoc.git / blob