Annotation of mandoc/mandoc.1, Revision 1.109
1.109 ! schwarze 1: .\" $Id: mandoc.1,v 1.108 2014/08/22 04:52:55 schwarze Exp $
1.1 kristaps 2: .\"
1.92 schwarze 3: .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
1.105 schwarze 4: .\" Copyright (c) 2012, 2014 Ingo Schwarze <schwarze@openbsd.org>
1.1 kristaps 5: .\"
6: .\" Permission to use, copy, modify, and distribute this software for any
1.16 kristaps 7: .\" purpose with or without fee is hereby granted, provided that the above
8: .\" copyright notice and this permission notice appear in all copies.
1.1 kristaps 9: .\"
1.16 kristaps 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.
1.1 kristaps 17: .\"
1.108 schwarze 18: .Dd $Mdocdate: August 22 2014 $
1.14 kristaps 19: .Dt MANDOC 1
1.1 kristaps 20: .Os
21: .Sh NAME
22: .Nm mandoc
1.8 kristaps 23: .Nd format and display UNIX manuals
1.1 kristaps 24: .Sh SYNOPSIS
25: .Nm mandoc
1.109 ! schwarze 26: .Op Fl acfklV
1.101 schwarze 27: .Sm off
28: .Op Fl I Cm os Li = Ar name
29: .Sm on
1.8 kristaps 30: .Op Fl m Ns Ar format
1.58 kristaps 31: .Op Fl O Ns Ar option
1.37 kristaps 32: .Op Fl T Ns Ar output
1.77 schwarze 33: .Op Fl W Ns Ar level
1.89 kristaps 34: .Op Ar
1.1 kristaps 35: .Sh DESCRIPTION
36: The
37: .Nm
1.26 kristaps 38: utility formats
1.8 kristaps 39: .Ux
1.57 kristaps 40: manual pages for display.
1.100 kristaps 41: .Pp
42: By default,
43: .Nm
44: reads
45: .Xr mdoc 7
46: or
47: .Xr man 7
48: text from stdin, implying
49: .Fl m Ns Cm andoc ,
50: and produces
51: .Fl T Ns Cm ascii
52: output.
53: .Pp
1.109 ! schwarze 54: The options are as follows:
1.19 kristaps 55: .Bl -tag -width Ds
1.107 schwarze 56: .It Fl a
57: If the standard output is a terminal device and
58: .Fl c
59: is not specified, use
60: .Xr more 1
61: to paginate the output, just like
62: .Xr man 1
63: would.
64: .It Fl c
65: Copy the formatted manual pages to the standard output without using
66: .Xr more 1
67: to paginate them.
68: This is the default.
69: It can be specified to override
70: .Fl a .
1.109 ! schwarze 71: .It Fl f
! 72: A synonym for
! 73: .Xr whatis 1 .
! 74: This overrides any earlier
! 75: .Fl k
! 76: and
! 77: .Fl l
! 78: options.
1.101 schwarze 79: .Sm off
80: .It Fl I Cm os Li = Ar name
81: .Sm on
82: Override the default operating system
83: .Ar name
84: for the
85: .Xr mdoc 7
86: .Sq \&Os
87: macro.
1.109 ! schwarze 88: .It Fl k
! 89: A synonym for
! 90: .Xr apropos 1 .
! 91: This overrides any earlier
! 92: .Fl f
! 93: and
! 94: .Fl l
! 95: options.
! 96: .It Fl l
! 97: A synonym for
! 98: .Fl a .
! 99: Also reverts any earlier
! 100: .Fl f
! 101: and
! 102: .Fl k
! 103: options.
1.19 kristaps 104: .It Fl m Ns Ar format
1.57 kristaps 105: Input format.
106: See
1.8 kristaps 107: .Sx Input Formats
1.57 kristaps 108: for available formats.
109: Defaults to
1.58 kristaps 110: .Fl m Ns Cm andoc .
111: .It Fl O Ns Ar option
1.57 kristaps 112: Comma-separated output options.
1.19 kristaps 113: .It Fl T Ns Ar output
1.57 kristaps 114: Output format.
115: See
1.1 kristaps 116: .Sx Output Formats
1.57 kristaps 117: for available formats.
118: Defaults to
1.58 kristaps 119: .Fl T Ns Cm ascii .
1.1 kristaps 120: .It Fl V
121: Print version and exit.
1.77 schwarze 122: .It Fl W Ns Ar level
123: Specify the minimum message
124: .Ar level
125: to be reported on the standard error output and to affect the exit status.
126: The
127: .Ar level
128: can be
129: .Cm warning ,
130: .Cm error ,
131: or
132: .Cm fatal .
133: The default is
134: .Fl W Ns Cm fatal ;
1.58 kristaps 135: .Fl W Ns Cm all
1.77 schwarze 136: is an alias for
137: .Fl W Ns Cm warning .
138: See
139: .Sx EXIT STATUS
140: and
141: .Sx DIAGNOSTICS
142: for details.
143: .Pp
144: The special option
145: .Fl W Ns Cm stop
146: tells
147: .Nm
148: to exit after parsing a file that causes warnings or errors of at least
149: the requested level.
150: No formatted output will be produced from that file.
151: If both a
152: .Ar level
153: and
154: .Cm stop
155: are requested, they can be joined with a comma, for example
156: .Fl W Ns Cm error , Ns Cm stop .
1.58 kristaps 157: .It Ar file
158: Read input from zero or more files.
1.57 kristaps 159: If unspecified, reads from stdin.
160: If multiple files are specified,
1.2 kristaps 161: .Nm
162: will halt with the first failed parse.
1.1 kristaps 163: .El
1.109 ! schwarze 164: .Pp
! 165: In
! 166: .Fl f
! 167: and
! 168: .Fl k
! 169: mode,
! 170: .Nm
! 171: also supports the options
! 172: .Fl CMmOSsw
! 173: described in the
! 174: .Xr apropos 1
! 175: manual.
1.8 kristaps 176: .Ss Input Formats
177: The
178: .Nm
179: utility accepts
180: .Xr mdoc 7
181: and
182: .Xr man 7
183: input with
1.58 kristaps 184: .Fl m Ns Cm doc
1.8 kristaps 185: and
1.58 kristaps 186: .Fl m Ns Cm an ,
1.57 kristaps 187: respectively.
188: The
1.8 kristaps 189: .Xr mdoc 7
190: format is
191: .Em strongly
1.26 kristaps 192: recommended;
1.8 kristaps 193: .Xr man 7
194: should only be used for legacy manuals.
1.11 kristaps 195: .Pp
1.12 kristaps 196: A third option,
1.58 kristaps 197: .Fl m Ns Cm andoc ,
1.13 kristaps 198: which is also the default, determines encoding on-the-fly: if the first
1.26 kristaps 199: non-comment macro is
1.27 kristaps 200: .Sq \&Dd
1.13 kristaps 201: or
1.27 kristaps 202: .Sq \&Dt ,
1.26 kristaps 203: the
1.13 kristaps 204: .Xr mdoc 7
205: parser is used; otherwise, the
206: .Xr man 7
207: parser is used.
208: .Pp
209: If multiple
1.26 kristaps 210: files are specified with
1.58 kristaps 211: .Fl m Ns Cm andoc ,
1.57 kristaps 212: each has its file-type determined this way.
213: If multiple files are
1.13 kristaps 214: specified and
1.58 kristaps 215: .Fl m Ns Cm doc
1.12 kristaps 216: or
1.58 kristaps 217: .Fl m Ns Cm an
1.12 kristaps 218: is specified, then this format is used exclusively.
1.1 kristaps 219: .Ss Output Formats
220: The
221: .Nm
222: utility accepts the following
223: .Fl T
1.66 kristaps 224: arguments, which correspond to output modes:
1.93 schwarze 225: .Bl -tag -width "-Tlocale"
1.58 kristaps 226: .It Fl T Ns Cm ascii
1.81 kristaps 227: Produce 7-bit ASCII output.
1.57 kristaps 228: This is the default.
229: See
1.48 kristaps 230: .Sx ASCII Output .
1.58 kristaps 231: .It Fl T Ns Cm html
1.81 kristaps 232: Produce strict CSS1/HTML-4.01 output.
1.57 kristaps 233: See
1.48 kristaps 234: .Sx HTML Output .
1.58 kristaps 235: .It Fl T Ns Cm lint
236: Parse only: produce no output.
237: Implies
1.77 schwarze 238: .Fl W Ns Cm warning .
1.93 schwarze 239: .It Fl T Ns Cm locale
240: Encode output using the current locale.
241: See
242: .Sx Locale Output .
1.91 schwarze 243: .It Fl T Ns Cm man
1.95 kristaps 244: Produce
1.91 schwarze 245: .Xr man 7
1.95 kristaps 246: format output.
247: See
248: .Sx Man Output .
1.73 kristaps 249: .It Fl T Ns Cm pdf
250: Produce PDF output.
251: See
252: .Sx PDF Output .
1.62 kristaps 253: .It Fl T Ns Cm ps
254: Produce PostScript output.
255: See
256: .Sx PostScript Output .
1.58 kristaps 257: .It Fl T Ns Cm tree
258: Produce an indented parse tree.
1.93 schwarze 259: .It Fl T Ns Cm utf8
260: Encode output in the UTF\-8 multi-byte format.
261: See
262: .Sx UTF\-8 Output .
1.58 kristaps 263: .It Fl T Ns Cm xhtml
1.81 kristaps 264: Produce strict CSS1/XHTML-1.0 output.
1.57 kristaps 265: See
1.50 kristaps 266: .Sx XHTML Output .
1.1 kristaps 267: .El
1.13 kristaps 268: .Pp
269: If multiple input files are specified, these will be processed by the
270: corresponding filter in-order.
1.66 kristaps 271: .Ss ASCII Output
272: Output produced by
273: .Fl T Ns Cm ascii ,
274: which is the default, is rendered in standard 7-bit ASCII documented in
275: .Xr ascii 7 .
276: .Pp
277: Font styles are applied by using back-spaced encoding such that an
278: underlined character
279: .Sq c
280: is rendered as
281: .Sq _ Ns \e[bs] Ns c ,
282: where
283: .Sq \e[bs]
284: is the back-space character number 8.
285: Emboldened characters are rendered as
286: .Sq c Ns \e[bs] Ns c .
287: .Pp
288: The special characters documented in
289: .Xr mandoc_char 7
290: are rendered best-effort in an ASCII equivalent.
1.87 kristaps 291: If no equivalent is found,
292: .Sq \&?
293: is used instead.
1.66 kristaps 294: .Pp
295: Output width is limited to 78 visible columns unless literal input lines
296: exceed this limit.
297: .Pp
298: The following
299: .Fl O
300: arguments are accepted:
1.19 kristaps 301: .Bl -tag -width Ds
1.98 schwarze 302: .It Cm indent Ns = Ns Ar indent
303: The left margin for normal text is set to
304: .Ar indent
305: blank characters instead of the default of five for
306: .Xr mdoc 7
307: and seven for
308: .Xr man 7 .
309: Increasing this is not recommended; it may result in degraded formatting,
1.99 schwarze 310: for example overfull lines or ugly line breaks.
1.66 kristaps 311: .It Cm width Ns = Ns Ar width
312: The output width is set to
313: .Ar width ,
314: which will normalise to \(>=60.
1.1 kristaps 315: .El
1.66 kristaps 316: .Ss HTML Output
317: Output produced by
318: .Fl T Ns Cm html
319: conforms to HTML-4.01 strict.
320: .Pp
1.61 kristaps 321: The
1.66 kristaps 322: .Pa example.style.css
1.83 kristaps 323: file documents style-sheet classes available for customising output.
324: If a style-sheet is not specified with
325: .Fl O Ns Ar style ,
326: .Fl T Ns Cm html
327: defaults to simple output readable in any graphical or text-based web
328: browser.
1.66 kristaps 329: .Pp
1.89 kristaps 330: Special characters are rendered in decimal-encoded UTF\-8.
1.66 kristaps 331: .Pp
332: The following
1.64 kristaps 333: .Fl O
1.66 kristaps 334: arguments are accepted:
1.37 kristaps 335: .Bl -tag -width Ds
1.94 kristaps 336: .It Cm fragment
1.97 schwarze 337: Omit the
338: .Aq !DOCTYPE
339: declaration and the
340: .Aq html ,
341: .Aq head ,
342: and
343: .Aq body
344: elements and only emit the subtree below the
345: .Aq body
346: element.
1.94 kristaps 347: The
348: .Cm style
1.97 schwarze 349: argument will be ignored.
1.94 kristaps 350: This is useful when embedding manual content within existing documents.
1.64 kristaps 351: .It Cm includes Ns = Ns Ar fmt
1.40 kristaps 352: The string
353: .Ar fmt ,
1.49 kristaps 354: for example,
1.40 kristaps 355: .Ar ../src/%I.html ,
356: is used as a template for linked header files (usually via the
357: .Sq \&In
1.57 kristaps 358: macro).
359: Instances of
1.43 kristaps 360: .Sq \&%I
1.57 kristaps 361: are replaced with the include filename.
362: The default is not to present a
1.40 kristaps 363: hyperlink.
1.64 kristaps 364: .It Cm man Ns = Ns Ar fmt
1.39 kristaps 365: The string
366: .Ar fmt ,
1.49 kristaps 367: for example,
1.39 kristaps 368: .Ar ../html%S/%N.%S.html ,
369: is used as a template for linked manuals (usually via the
1.37 kristaps 370: .Sq \&Xr
1.57 kristaps 371: macro).
372: Instances of
1.43 kristaps 373: .Sq \&%N
1.40 kristaps 374: and
375: .Sq %S
376: are replaced with the linked manual's name and section, respectively.
1.57 kristaps 377: If no section is included, section 1 is assumed.
378: The default is not to
1.40 kristaps 379: present a hyperlink.
1.64 kristaps 380: .It Cm style Ns = Ns Ar style.css
1.58 kristaps 381: The file
382: .Ar style.css
383: is used for an external style-sheet.
384: This must be a valid absolute or
385: relative URI.
1.61 kristaps 386: .El
1.93 schwarze 387: .Ss Locale Output
388: Locale-depending output encoding is triggered with
389: .Fl T Ns Cm locale .
390: This option is not available on all systems: systems without locale
391: support, or those whose internal representation is not natively UCS-4,
392: will fall back to
393: .Fl T Ns Cm ascii .
394: See
395: .Sx ASCII Output
396: for font style specification and available command-line arguments.
1.95 kristaps 397: .Ss Man Output
398: Translate input format into
399: .Xr man 7
400: output format.
1.102 schwarze 401: This is useful for distributing manual sources to legacy systems
1.96 kristaps 402: lacking
1.95 kristaps 403: .Xr mdoc 7
404: formatters.
405: .Pp
406: If
407: .Xr mdoc 7
408: is passed as input, it is translated into
1.97 schwarze 409: .Xr man 7 .
410: If the input format is
1.95 kristaps 411: .Xr man 7 ,
1.97 schwarze 412: the input is copied to the output, expanding any
1.95 kristaps 413: .Xr roff 7
414: .Sq so
1.97 schwarze 415: requests.
416: The parser is also run, and as usual, the
417: .Fl W
418: level controls which
419: .Sx DIAGNOSTICS
420: are displayed before copying the input to the output.
1.93 schwarze 421: .Ss PDF Output
422: PDF-1.1 output may be generated by
423: .Fl T Ns Cm pdf .
424: See
425: .Sx PostScript Output
426: for
427: .Fl O
428: arguments and defaults.
1.62 kristaps 429: .Ss PostScript Output
1.65 kristaps 430: PostScript
431: .Qq Adobe-3.0
432: Level-2 pages may be generated by
1.62 kristaps 433: .Fl T Ns Cm ps .
1.67 kristaps 434: Output pages default to letter sized and are rendered in the Times font
1.70 kristaps 435: family, 11-point.
436: Margins are calculated as 1/9 the page length and width.
1.71 kristaps 437: Line-height is 1.4m.
1.66 kristaps 438: .Pp
439: Special characters are rendered as in
440: .Sx ASCII Output .
441: .Pp
442: The following
443: .Fl O
444: arguments are accepted:
445: .Bl -tag -width Ds
446: .It Cm paper Ns = Ns Ar name
447: The paper size
448: .Ar name
449: may be one of
1.68 kristaps 450: .Ar a3 ,
451: .Ar a4 ,
452: .Ar a5 ,
453: .Ar legal ,
1.66 kristaps 454: or
455: .Ar letter .
1.68 kristaps 456: You may also manually specify dimensions as
457: .Ar NNxNN ,
458: width by height in millimetres.
459: If an unknown value is encountered,
460: .Ar letter
461: is used.
1.66 kristaps 462: .El
1.93 schwarze 463: .Ss UTF\-8 Output
464: Use
465: .Fl T Ns Cm utf8
466: to force a UTF\-8 locale.
1.73 kristaps 467: See
1.93 schwarze 468: .Sx Locale Output
469: for details and options.
1.50 kristaps 470: .Ss XHTML Output
471: Output produced by
1.58 kristaps 472: .Fl T Ns Cm xhtml
1.50 kristaps 473: conforms to XHTML-1.0 strict.
474: .Pp
475: See
476: .Sx HTML Output
477: for details; beyond generating XHTML tags instead of HTML tags, these
478: output modes are identical.
1.108 schwarze 479: .Sh ENVIRONMENT
480: .Bl -tag -width MANPAGER
481: .It Ev MANPAGER
482: Any non-empty value of the environment variable
483: .Ev MANPAGER
484: will be used instead of the standard pagination program,
485: .Xr more 1 .
486: .It Ev PAGER
487: Specifies the pagination program to use when
488: .Ev MANPAGER
489: is not defined.
490: If neither PAGER nor MANPAGER is defined,
491: .Pa /usr/bin/more Fl s
492: will be used.
493: .El
1.77 schwarze 494: .Sh EXIT STATUS
495: The
496: .Nm
497: utility exits with one of the following values, controlled by the message
498: .Ar level
499: associated with the
500: .Fl W
501: option:
502: .Pp
503: .Bl -tag -width Ds -compact
504: .It 0
505: No warnings or errors occurred, or those that did were ignored because
506: they were lower than the requested
507: .Ar level .
508: .It 2
509: At least one warning occurred, but no error, and
510: .Fl W Ns Cm warning
511: was specified.
512: .It 3
513: At least one parsing error occurred, but no fatal error, and
514: .Fl W Ns Cm error
515: or
516: .Fl W Ns Cm warning
517: was specified.
518: .It 4
519: A fatal parsing error occurred.
520: .It 5
521: Invalid command line arguments were specified.
522: No input files have been read.
523: .It 6
524: An operating system error occurred, for example memory exhaustion or an
525: error accessing input files.
526: Such errors cause
527: .Nm
528: to exit at once, possibly in the middle of parsing or formatting a file.
529: .El
530: .Pp
531: Note that selecting
532: .Fl T Ns Cm lint
533: output mode implies
534: .Fl W Ns Cm warning .
1.1 kristaps 535: .Sh EXAMPLES
1.13 kristaps 536: To page manuals to the terminal:
1.1 kristaps 537: .Pp
1.82 kristaps 538: .Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less
539: .Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
1.28 kristaps 540: .Pp
1.41 kristaps 541: To produce HTML manuals with
542: .Ar style.css
543: as the style-sheet:
1.38 kristaps 544: .Pp
1.82 kristaps 545: .Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
1.38 kristaps 546: .Pp
1.28 kristaps 547: To check over a large set of manuals:
548: .Pp
1.77 schwarze 549: .Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]`
1.66 kristaps 550: .Pp
551: To produce a series of PostScript manuals for A4 paper:
552: .Pp
1.82 kristaps 553: .Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
1.91 schwarze 554: .Pp
555: Convert a modern
556: .Xr mdoc 7
557: manual to the older
558: .Xr man 7
559: format, for use on systems lacking an
560: .Xr mdoc 7
561: parser:
562: .Pp
563: .Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man
1.77 schwarze 564: .Sh DIAGNOSTICS
1.106 schwarze 565: Messages displayed by
566: .Nm
567: follow this format:
1.77 schwarze 568: .Pp
1.106 schwarze 569: .D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args
1.77 schwarze 570: .Pp
1.106 schwarze 571: Line and column numbers start at 1.
572: Both are omitted for messages referring to an input file as a whole.
573: Macro names and arguments are omitted where meaningless.
574: Fatal messages about invalid command line arguments
575: or operating system errors, for example when memory is exhausted,
576: may also omit the
577: .Ar file
1.104 schwarze 578: and
1.106 schwarze 579: .Ar level
580: fields.
1.104 schwarze 581: .Pp
1.77 schwarze 582: Message levels have the following meanings:
583: .Bl -tag -width "warning"
1.105 schwarze 584: .It Cm syserr
585: Opening or reading an input file failed, so the parser cannot
586: even be started and no output is produced from that input file.
1.77 schwarze 587: .It Cm fatal
588: The parser is unable to parse a given input file at all.
589: No formatted output is produced from that input file.
590: .It Cm error
591: An input file contains syntax that cannot be safely interpreted,
592: either because it is invalid or because
593: .Nm
594: does not implement it yet.
595: By discarding part of the input or inserting missing tokens,
596: the parser is able to continue, and the error does not prevent
597: generation of formatted output, but typically, preparing that
598: output involves information loss, broken document structure
599: or unintended formatting.
600: .It Cm warning
601: An input file uses obsolete, discouraged or non-portable syntax.
602: All the same, the meaning of the input is unambiguous and a correct
603: rendering can be produced.
604: Documents causing warnings may render poorly when using other
605: formatting tools instead of
606: .Nm .
607: .El
608: .Pp
609: Messages of the
610: .Cm warning
611: and
612: .Cm error
613: levels are hidden unless their level, or a lower level, is requested using a
614: .Fl W
615: option or
616: .Fl T Ns Cm lint
617: output mode.
1.106 schwarze 618: .Ss Warnings related to the document prologue
619: .Bl -ohang
620: .It Sy "missing manual title, using UNTITLED"
621: .Pq mdoc
622: A
623: .Ic \&Dt
624: macro has no arguments, or there is no
625: .Ic \&Dt
626: macro before the first non-prologue macro.
627: .It Sy "missing manual title, using \(dq\(dq"
628: .Pq man
629: There is no
630: .Ic \&TH
631: macro, or it has no arguments.
632: .It Sy "lower case character in document title"
633: .Pq mdoc , man
634: The title is still used as given in the
635: .Ic \&Dt
636: or
637: .Ic \&TH
638: macro.
639: .It Sy "missing manual section, using \(dq\(dq"
640: .Pq mdoc , man
641: A
642: .Ic \&Dt
643: or
644: .Ic \&TH
645: macro lacks the mandatory section argument.
646: .It Sy "unknown manual section"
647: .Pq mdoc
648: The section number in a
649: .Ic \&Dt
650: line is invalid, but still used.
651: .It Sy "unknown manual volume or arch"
652: .Pq mdoc
653: The volume name in a
654: .Ic \&Dt
655: line is invalid, but still used.
656: The manual is assumed to be architecture-independent.
657: .It Sy "missing date, using today's date"
658: .Pq mdoc, man
659: The document was parsed as
660: .Xr mdoc 7
661: and it has no
662: .Ic \&Dd
663: macro, or the
664: .Ic \&Dd
665: macro has no arguments or only empty arguments;
666: or the document was parsed as
667: .Xr man 7
668: and it has no
669: .Ic \&TH
670: macro, or the
671: .Ic \&TH
672: macro has less than three arguments or its third argument is empty.
673: .It Sy "cannot parse date, using it verbatim"
674: .Pq mdoc , man
675: The date given in a
676: .Ic \&Dd
677: or
678: .Ic \&TH
679: macro does not follow the conventional format.
680: .It Sy "missing Os macro, using \(dq\(dq"
681: .Pq mdoc
682: The default or current system is not shown in this case.
683: .It Sy "duplicate prologue macro"
684: .Pq mdoc
685: One of the prologue macros occurs more than once.
686: The last instance overrides all previous ones.
687: .It Sy "late prologue macro"
688: .Pq mdoc
689: A
690: .Ic \&Dd
691: or
692: .Ic \&Os
693: macro occurs after some non-prologue macro, but still takes effect.
694: .It Sy "skipping late title macro"
695: .Pq mdoc
696: The
697: .Ic \&Dt
698: macro can only occur before the first non-prologue macro
699: because traditional formatters write the page header
700: before parsing the document body.
701: Even though this technical restriction does not apply to
702: .Nm ,
703: traditional semantics is preserved.
704: The late macro is discarded including its arguments.
705: .It Sy "prologue macros out of order"
706: .Pq mdoc
707: The prologue macros are not given in the conventional order
708: .Ic \&Dd ,
709: .Ic \&Dt ,
710: .Ic \&Os .
711: All three macros are used even when given in another order.
712: .El
713: .Ss Warnings regarding document structure
714: .Bl -ohang
715: .It Sy ".so is fragile, better use ln(1)"
716: .Pq roff
717: Including files only works when the parser program runs with the correct
718: current working directory.
719: .It Sy "no document body"
720: .Pq mdoc , man
721: The document body contains neither text nor macros.
722: An empty document is shown, consisting only of a header and a footer line.
723: .It Sy "content before first section header"
724: .Pq mdoc , man
725: Some macros or text precede the first
726: .Ic \&Sh
727: or
728: .Ic \&SH
729: section header.
730: The offending macros and text are parsed and added to the top level
731: of the syntax tree, outside any section block.
732: .It Sy "first section is not NAME"
733: .Pq mdoc
734: The argument of the first
735: .Ic \&Sh
736: macro is not
737: .Sq NAME .
738: This may confuse
739: .Xr makewhatis 8
740: and
741: .Xr apropos 1 .
742: .It Sy "bad NAME section contents"
743: .Pq mdoc
744: The last node in the NAME section is not an
745: .Ic \&Nd
746: macro, or any preceding macro is not
747: .Ic \&Nm ,
748: or the NAME section is completely empty.
749: This may confuse
750: .Xr makewhatis 8
751: and
752: .Xr apropos 1 .
753: .It Sy "sections out of conventional order"
754: .Pq mdoc
755: A standard section occurs after another section it usually precedes.
756: All section titles are used as given,
757: and the order of sections is not changed.
758: .It Sy "duplicate section title"
759: .Pq mdoc
760: The same standard section title occurs more than once.
761: .It Sy "unexpected section"
762: .Pq mdoc
763: A standard section header occurs in a section of the manual
764: where it normally isn't useful.
765: .El
766: .Ss "Warnings related to macros and nesting"
767: .Bl -ohang
768: .It Sy "obsolete macro"
769: .Pq mdoc
770: See the
771: .Xr mdoc 7
772: manual for replacements.
773: .It Sy "skipping paragraph macro"
774: In
775: .Xr mdoc 7
776: documents, this happens
777: .Bl -dash -compact
778: .It
779: at the beginning and end of sections and subsections
780: .It
781: right before non-compact lists and displays
782: .It
783: at the end of items in non-column, non-compact lists
784: .It
785: and for multiple consecutive paragraph macros.
786: .El
787: In
788: .Xr man 7
789: documents, it happens
790: .Bl -dash -compact
791: .It
792: for empty
793: .Ic \&P ,
794: .Ic \&PP ,
795: and
796: .Ic \&LP
797: macros
798: .It
799: for
800: .Ic \&IP
801: macros having neither head nor body arguments
802: .It
803: for
804: .Ic \&br
805: or
806: .Ic \&sp
807: right after
808: .Ic \&SH
809: or
810: .Ic \&SS
811: .El
812: .It Sy "moving paragraph macro out of list"
813: .Pq mdoc
814: A list item in a
815: .Ic \&Bl
816: list contains a trailing paragraph macro.
817: The paragraph macro is moved after the end of the list.
818: .It Sy "skipping no-space macro"
819: .Pq mdoc
820: An input line begins with an
821: .Ic \&Ns
822: macro.
823: The macro is ignored.
824: .It Sy "blocks badly nested"
825: .Pq mdoc
826: If two blocks intersect, one should completely contain the other.
827: Otherwise, rendered output is likely to look strange in any output
828: format, and rendering in SGML-based output formats is likely to be
829: outright wrong because such languages do not support badly nested
830: blocks at all.
831: Typical examples of badly nested blocks are
832: .Qq Ic \&Ao \&Bo \&Ac \&Bc
833: and
834: .Qq Ic \&Ao \&Bq \&Ac .
835: In these examples,
836: .Ic \&Ac
837: breaks
838: .Ic \&Bo
839: and
840: .Ic \&Bq ,
841: respectively.
842: .It Sy "nested displays are not portable"
843: .Pq mdoc
844: A
845: .Ic \&Bd ,
846: .Ic \&D1 ,
847: or
848: .Ic \&Dl
849: display occurs nested inside another
850: .Ic \&Bd
851: display.
852: This works with
853: .Nm ,
854: but fails with most other implementations.
855: .It Sy "moving content out of list"
856: .Pq mdoc
857: A
858: .Ic \&Bl
859: list block contains text or macros before the first
860: .Ic \&It
861: macro.
862: The offending children are moved before the beginning of the list.
863: .It Sy ".Vt block has child macro"
864: .Pq mdoc
865: The
866: .Ic \&Vt
867: macro supports plain text arguments only.
868: Formatting may be ugly and semantic searching
869: for the affected content might not work.
870: .It Sy "fill mode already enabled, skipping"
871: .Pq man
872: A
873: .Ic \&fi
874: request occurs even though the document is still in fill mode,
875: or already switched back to fill mode.
876: It has no effect.
877: .It Sy "fill mode already disabled, skipping"
878: .Pq man
879: An
880: .Ic \&nf
881: request occurs even though the document already switched to no-fill mode
882: and did not switch back to fill mode yet.
883: It has no effect.
884: .It Sy "line scope broken"
885: .Pq man
886: While parsing the next-line scope of the previous macro,
887: another macro is found that prematurely terminates the previous one.
888: The previous, interrupted macro is deleted from the parse tree.
889: .El
890: .Ss "Warnings related to missing arguments"
891: .Bl -ohang
892: .It Sy "skipping empty request"
893: .Pq roff
894: The macro name is missing from a macro definition request.
895: .It Sy "conditional request controls empty scope"
896: .Pq roff
897: A conditional request is only useful if any of the following
898: follows it on the same logical input line:
899: .Bl -dash -compact
900: .It
901: The
902: .Sq \e{
903: keyword to open a multi-line scope.
904: .It
905: A request or macro or some text, resulting in a single-line scope.
906: .It
907: The immediate end of the logical line without any intervening whitespace,
908: resulting in next-line scope.
909: .El
910: Here, a conditional request is followed by trailing whitespace only,
911: and there is no other content on its logical input line.
912: Note that it doesn't matter whether the logical input line is split
913: across multiple physical input lines using
914: .Sq \e
915: line continuation characters.
916: This is one of the rare cases
917: where trailing whitespace is syntactically significant.
918: The conditional request controls a scope containing whitespace only,
919: so it is unlikely to have a significant effect,
920: except that it may control a following
921: .Ic \&el
922: clause.
923: .It Sy "skipping empty macro"
924: .Pq mdoc
925: The indicated macro has no arguments and hence no effect.
926: .It Sy "empty argument, using 0n"
927: .Pq mdoc
928: The required width is missing after
929: .Ic \&Bd
930: or
931: .Ic \&Bl
932: .Fl offset
933: or
934: .Fl width.
935: .It Sy "argument count wrong"
936: .Pq mdoc , man
937: The indicated macro has too few or too many arguments.
938: The syntax tree will contain the wrong number of arguments as given.
939: Formatting behaviour depends on the specific macro in question.
940: Note that the same message may also occur as an ERROR, see below.
941: .It Sy "missing display type, using -ragged"
942: .Pq mdoc
943: The
944: .Ic \&Bd
945: macro is invoked without the required display type.
946: .It Sy "list type is not the first argument"
947: .Pq mdoc
948: In a
949: .Ic \&Bl
950: macro, at least one other argument precedes the type argument.
951: The
952: .Nm
953: utility copes with any argument order, but some other
954: .Xr mdoc 7
955: implementations do not.
956: .It Sy "missing -width in -tag list, using 8n"
957: .Pq mdoc
958: Every
959: .Ic \&Bl
960: macro having the
961: .Fl tag
962: argument requires
963: .Fl width ,
964: too.
965: .It Sy "missing utility name, using \(dq\(dq"
966: .Pq mdoc
967: The
968: .Ic \&Ex Fl std
969: macro is called without an argument before
970: .Ic \&Nm
971: has first been called with an argument.
972: .It Sy "empty head in list item"
973: .Pq mdoc
974: In a
975: .Ic \&Bl
976: .Fl diag ,
977: .Fl hang ,
978: .Fl inset ,
979: .Fl ohang ,
980: or
981: .Fl tag
982: list, an
983: .Ic \&It
984: macro lacks the required argument.
985: The item head is left empty.
986: .It Sy "empty list item"
987: .Pq mdoc
988: In a
989: .Ic \&Bl
990: .Fl bullet ,
991: .Fl dash ,
992: .Fl enum ,
993: or
994: .Fl hyphen
995: list, an
996: .Ic \&It
997: block is empty.
998: An empty list item is shown.
999: .It Sy "missing font type"
1000: .Pq mdoc
1001: A
1002: .Ic \&Bf
1003: macro has no argument.
1004: It switches to the default font,
1005: .Cm \efR .
1006: .It Sy "unknown font type"
1007: .Pq mdoc
1008: The
1009: .Ic \&Bf
1010: argument is invalid.
1011: The default font
1012: .Cm \efR
1013: is used instead.
1014: .It Sy "missing -std argument, adding it"
1015: .Pq mdoc
1016: An
1017: .Ic \&Ex
1018: or
1019: .Ic \&Rv
1020: macro lacks the required
1021: .Fl std
1022: argument.
1023: The
1024: .Nm
1025: utility assumes
1026: .Fl std
1027: even when it is not specified, but other implementations may not.
1028: .El
1029: .Ss "Warnings related to bad macro arguments"
1030: .Bl -ohang
1031: .It Sy "unterminated quoted argument"
1032: .Pq roff
1033: Macro arguments can be enclosed in double quote characters
1034: such that space characters and macro names contained in the quoted
1035: argument need not be escaped.
1036: The closing quote of the last argument of a macro can be omitted.
1037: However, omitting it is not recommended because it makes the code
1038: harder to read.
1039: .It Sy "duplicate argument"
1040: .Pq mdoc
1041: A
1042: .Ic \&Bd
1043: or
1044: .Ic \&Bl
1045: macro has more than one
1046: .Fl compact ,
1047: more than one
1048: .Fl offset ,
1049: or more than one
1050: .Fl width
1051: argument.
1052: All but the last instances of these arguments are ignored.
1053: .It Sy "skipping duplicate argument"
1054: .Pq mdoc
1055: An
1056: .Ic \&An
1057: macro has more than one
1058: .Fl split
1059: or
1060: .Fl nosplit
1061: argument.
1062: All but the first of these arguments are ignored.
1063: .It Sy "skipping duplicate display type"
1064: .Pq mdoc
1065: A
1066: .Ic \&Bd
1067: macro has more than one type argument; the first one is used.
1068: .It Sy "skipping duplicate list type"
1069: .Pq mdoc
1070: A
1071: .Ic \&Bl
1072: macro has more than one type argument; the first one is used.
1073: .It Sy "skipping -width argument"
1074: .Pq mdoc
1075: A
1076: .Ic \&Bl
1077: .Fl column ,
1078: .Fl diag ,
1079: .Fl ohang ,
1080: .Fl inset ,
1081: or
1082: .Fl item
1083: list has a
1084: .Fl width
1085: argument.
1086: That has no effect.
1087: .It Sy "unknown AT&T UNIX version"
1088: .Pq mdoc
1089: An
1090: .Ic \&At
1091: macro has an invalid argument.
1092: It is used verbatim, with
1093: .Qq "AT&T UNIX "
1094: prefixed to it.
1095: .It Sy "invalid content in Rs block"
1096: .Pq mdoc
1097: An
1098: .Ic \&Rs
1099: block contains plain text or non-% macros.
1100: The bogus content is left in the syntax tree.
1101: Formatting may be poor.
1102: .It Sy "invalid Boolean argument"
1103: .Pq mdoc
1104: An
1105: .Ic \&Sm
1106: macro has an argument other than
1107: .Cm on
1108: or
1109: .Cm off .
1110: The invalid argument is moved out of the macro, which leaves the macro
1111: empty, causing it to toggle the spacing mode.
1112: .It Sy "unknown font, skipping request"
1113: .Pq man
1114: A
1115: .Xr roff 7
1116: .Ic \&ft
1117: request has an invalid argument.
1118: .El
1119: .Ss "Warnings related to plain text"
1120: .Bl -ohang
1121: .It Sy "blank line in fill mode, using .sp"
1122: .Pq mdoc
1123: The meaning of blank input lines is only well-defined in non-fill mode:
1124: In fill mode, line breaks of text input lines are not supposed to be
1125: significant.
1126: However, for compatibility with groff, blank lines in fill mode
1127: are replaced with
1128: .Ic \&sp
1129: requests.
1130: .It Sy "tab in filled text"
1131: .Pq mdoc , man
1132: The meaning of tab characters is only well-defined in non-fill mode:
1133: In fill mode, whitespace is not supposed to be significant
1134: on text input lines.
1135: As an implementation dependent choice, tab characters on text lines
1136: are passed through to the formatters in any case.
1137: Given that the text before the tab character will be filled,
1138: it is hard to predict which tab stop position the tab will advance to.
1139: .It Sy "whitespace at end of input line"
1140: .Pq mdoc , man , roff
1141: Whitespace at the end of input lines is almost never semantically
1142: significant \(em but in the odd case where it might be, it is
1143: extremely confusing when reviewing and maintaining documents.
1144: .It Sy "bad comment style"
1145: .Pq roff
1146: Comment lines start with a dot, a backslash, and a double-quote character.
1147: The
1148: .Nm
1149: utility treats the line as a comment line even without the backslash,
1150: but leaving out the backslash might not be portable.
1151: .It Sy "invalid escape sequence"
1152: .Pq roff
1153: An escape sequence has an invalid opening argument delimiter, lacks the
1154: closing argument delimiter, or the argument has too few characters.
1155: If the argument is incomplete,
1156: .Ic \e*
1157: and
1158: .Ic \en
1159: expand to an empty string,
1160: .Ic \eB
1161: to the digit
1162: .Sq 0 ,
1163: and
1164: .Ic \ew
1165: to the length of the incomplete argument.
1166: All other invalid escape sequences are ignored.
1167: .It Sy "undefined string, using \(dq\(dq"
1168: .Pq roff
1169: If a string is used without being defined before,
1170: its value is implicitly set to the empty string.
1171: However, defining strings explicitly before use
1172: keeps the code more readable.
1173: .El
1174: .Ss "Errors related to equations"
1175: .Bl -inset -compact
1176: .It "unexpected equation scope closure"
1177: .It "equation scope open on exit"
1178: .It "overlapping equation scopes"
1179: .It "unexpected end of equation"
1180: .It "equation syntax error"
1181: .El
1182: .Ss "Errors related to tables"
1183: .Bl -inset -compact
1184: .It "bad table syntax"
1185: .It "bad table option"
1186: .It "bad table layout"
1187: .It "no table layout cells specified"
1188: .It "no table data cells specified"
1189: .It "ignore data in cell"
1190: .It "data block still open"
1191: .It "ignoring extra data cells"
1192: .El
1193: .Ss "Errors related to roff, mdoc, and man code"
1194: .Bl -ohang
1195: .It Sy "input stack limit exceeded, infinite loop?"
1196: .Pq roff
1197: Explicit recursion limits are implemented for the following features,
1198: in order to prevent infinite loops:
1199: .Bl -dash -compact
1200: .It
1201: expansion of nested escape sequences
1202: including expansion of strings and number registers,
1203: .It
1204: expansion of nested user-defined macros,
1205: .It
1206: and
1207: .Ic \&so
1208: file inclusion.
1209: .El
1210: When a limit is hit, the output is incorrect, typically losing
1211: some content, but the parser can continue.
1212: .It Sy "skipping bad character"
1213: .Pq mdoc , man , roff
1214: The input file contains a byte that is not a printable
1215: .Xr ascii 7
1216: character.
1217: The message mentions the character number.
1218: The offending byte is replaced with a question mark
1219: .Pq Sq \&? .
1220: Consider editing the input file to replace the byte with an ASCII
1221: transliteration of the intended character.
1222: .It Sy "skipping unknown macro"
1223: .Pq mdoc , man , roff
1224: The first identifier on a request or macro line is neither recognized as a
1225: .Xr roff 7
1226: request, nor as a user-defined macro, nor, respectively, as an
1227: .Xr mdoc 7
1228: or
1229: .Xr man 7
1230: macro.
1231: It may be mistyped or unsupported.
1232: The request or macro is discarded including its arguments.
1233: .It Sy "skipping item outside list"
1234: .Pq mdoc
1235: An
1236: .Ic \&It
1237: macro occurs outside any
1238: .Ic \&Bl
1239: list.
1240: It is discarded including its arguments.
1241: .It Sy "skipping column outside column list"
1242: .Pq mdoc
1243: A
1244: .Ic \&Ta
1245: macro occurs outside any
1246: .Ic \&Bl Fl column
1247: block.
1248: It is discarded including its arguments.
1249: .It Sy "skipping end of block that is not open"
1250: .Pq mdoc , man , eqn , tbl , roff
1251: Various syntax elements can only be used to explicitly close blocks
1252: that have previously been opened.
1253: An
1254: .Xr mdoc 7
1255: block closing macro, a
1256: .Xr man 7
1257: .Ic \&RE
1258: or
1259: .Ic \&UE
1260: macro, or the end of an equation, table, or
1261: .Xr roff 7
1262: conditional request is encountered but no matching block is open.
1263: The offending request or macro is discarded.
1264: .It Sy "inserting missing end of block"
1265: .Pq mdoc , tbl
1266: Various
1267: .Xr mdoc 7
1268: macros as well as tables require explicit closing by dedicated macros.
1269: A block that doesn't support bad nesting
1270: ends before all of its children are properly closed.
1271: The open child nodes are closed implicitly.
1272: .It Sy "scope open on exit"
1273: .Pq mdoc , man , eqn , tbl , roff
1274: At the end of the document, an explicit
1275: .Xr mdoc 7
1276: block, a
1277: .Xr man 7
1278: next-line scope or
1279: .Ic \&RS
1280: or
1281: .Ic \&UR
1282: block, an equation, table, or
1283: .Xr roff 7
1284: conditional or ignore block is still open.
1285: The open block is closed implicitly.
1286: .It Sy "escaped character not allowed in a name"
1287: .Pq roff
1288: Macro, string and register identifiers consist of printable,
1289: non-whitespace ASCII characters.
1290: Escape sequences and characters and strings expressed in terms of them
1291: cannot form part of a name.
1292: The first argument of an
1293: .Ic \&am ,
1294: .Ic \&as ,
1295: .Ic \&de ,
1296: .Ic \&ds ,
1297: .Ic \&nr ,
1298: or
1299: .Ic \&rr
1300: request, or any argument of an
1301: .Ic \&rm
1302: request, or the name of a request or user defined macro being called,
1303: is terminated by an escape sequence.
1304: In the cases of
1305: .Ic \&as ,
1306: .Ic \&ds ,
1307: and
1308: .Ic \&nr ,
1309: the request has no effect at all.
1310: In the cases of
1311: .Ic \&am ,
1312: .Ic \&de ,
1313: .Ic \&rr ,
1314: and
1315: .Ic \&rm ,
1316: what was parsed up to this point is used as the arguments to the request,
1317: and the rest of the input line is discarded including the escape sequence.
1318: When parsing for a request or a user-defined macro name to be called,
1319: only the escape sequence is discarded.
1320: The characters preceding it are used as the request or macro name,
1321: the characters following it are used as the arguments to the request or macro.
1322: .It Sy "argument count wrong"
1323: .Pq mdoc , man , roff
1324: The indicated request or macro has too few or too many arguments.
1325: The syntax tree will contain the wrong number of arguments as given.
1326: Formatting behaviour depends on the specific request or macro in question.
1327: Note that the same message may also occur as a WARNING, see above.
1328: .It Sy "missing list type, using -item"
1329: .Pq mdoc
1330: A
1331: .Ic \&Bl
1332: macro fails to specify the list type.
1333: .It Sy "missing manual name, using \(dq\(dq"
1334: .Pq mdoc
1335: The first call to
1336: .Ic \&Nm
1337: lacks the required argument.
1338: .It Sy "uname(3) system call failed, using UNKNOWN"
1339: .Pq mdoc
1340: The
1341: .Ic \&Os
1342: macro is called without arguments, and the
1343: .Xr uname 3
1344: system call failed.
1345: As a workaround,
1346: .Nm
1347: can be compiled with
1348: .Sm off
1349: .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
1350: .Sm on
1351: .It Sy "unknown standard specifier"
1352: .Pq mdoc
1353: An
1354: .Ic \&St
1355: macro has an unknown argument and is discarded.
1356: .It Sy "skipping request without numeric argument"
1357: .Pq roff
1358: An
1359: .Ic \&it
1360: request has a non-numeric or negative argument or no argument at all.
1361: The invalid request is ignored.
1362: .It Sy "skipping all arguments"
1363: .Pq mdoc , man , eqn , roff
1364: An
1365: .Xr mdoc 7
1366: .Ic \&Bt ,
1367: .Ic \&Ed ,
1368: .Ic \&Ef ,
1369: .Ic \&Ek ,
1370: .Ic \&El ,
1371: .Ic \&Re ,
1372: or
1373: .Ic \&Ud
1374: macro, an
1375: .Ic \&It
1376: macro in a list that don't support item heads, a
1377: .Xr man 7
1378: .Ic \&LP ,
1379: .Ic \&P ,
1380: or
1381: .Ic \&PP
1382: macro, an
1383: .Xr eqn 7
1384: .Ic \&EN
1385: macro, or a
1386: .Xr roff 7
1387: .Sq \&..
1388: block closing request is invoked with at least one argument.
1389: All arguments are ignored.
1390: .It Sy "skipping excess arguments"
1391: .Pq mdoc , roff
1.77 schwarze 1392: The
1.106 schwarze 1393: .Ic \&Bf
1394: macro is invoked with more than one argument, or a request of the
1395: .Ic \&de
1396: family is invoked with more than two arguments.
1397: The excess arguments are ignored.
1398: .El
1399: .Ss FATAL errors
1400: .Bl -ohang
1401: .It Sy "input too large"
1402: .Pq mdoc , man
1403: Currently,
1404: .Nm
1405: cannot handle input files larger than its arbitrary size limit
1406: of 2^31 bytes (2 Gigabytes).
1407: Since useful manuals are always small, this is not a problem in practice.
1408: Parsing is aborted as soon as the condition is detected.
1409: .It Sy "NOT IMPLEMENTED: Bd -file"
1410: .Pq mdoc
1411: For security reasons, the
1412: .Ic \&Bd
1413: macro does not support the
1414: .Fl file
1415: argument.
1416: By requesting the inclusion of a sensitive file, a malicious document
1417: might otherwise trick a privileged user into inadvertently displaying
1418: the file on the screen, revealing the file content to bystanders.
1419: The parser exits immediately.
1420: .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
1421: .Pq roff
1422: For security reasons,
1.77 schwarze 1423: .Nm
1.106 schwarze 1424: allows
1425: .Ic \&so
1426: file inclusion requests only with relative paths
1427: and only without ascending to any parent directory.
1428: By requesting the inclusion of a sensitive file, a malicious document
1429: might otherwise trick a privileged user into inadvertently displaying
1430: the file on the screen, revealing the file content to bystanders.
1431: The parser exits immediately.
1432: .It Sy ".so request failed"
1433: .Pq roff
1434: Servicing a
1435: .Ic \&so
1436: request requires reading an external file.
1437: While trying to do so, an
1438: .Xr open 2 ,
1439: .Xr stat 2 ,
1440: or
1441: .Xr read 2
1442: system call failed.
1443: The parser exits immediately.
1444: Before showing this message,
1445: .Nm
1446: always shows another message explaining why the system call failed.
1447: .El
1.20 kristaps 1448: .Sh COMPATIBILITY
1.26 kristaps 1449: This section summarises
1.20 kristaps 1450: .Nm
1.76 kristaps 1451: compatibility with GNU troff.
1.32 kristaps 1452: Each input and output format is separately noted.
1.48 kristaps 1453: .Ss ASCII Compatibility
1.37 kristaps 1454: .Bl -bullet -compact
1.29 kristaps 1455: .It
1.87 kristaps 1456: Unrenderable unicode codepoints specified with
1.86 kristaps 1457: .Sq \e[uNNNN]
1458: escapes are printed as
1459: .Sq \&?
1460: in mandoc.
1461: In GNU troff, these raise an error.
1462: .It
1.49 kristaps 1463: The
1.33 kristaps 1464: .Sq \&Bd \-literal
1.49 kristaps 1465: and
1.32 kristaps 1466: .Sq \&Bd \-unfilled
1467: macros of
1468: .Xr mdoc 7
1469: in
1.58 kristaps 1470: .Fl T Ns Cm ascii
1.32 kristaps 1471: are synonyms, as are \-filled and \-ragged.
1.26 kristaps 1472: .It
1.86 kristaps 1473: In historic GNU troff, the
1.27 kristaps 1474: .Sq \&Pa
1.32 kristaps 1475: .Xr mdoc 7
1476: macro does not underline when scoped under an
1.30 kristaps 1477: .Sq \&It
1.57 kristaps 1478: in the FILES section.
1479: This behaves correctly in
1.27 kristaps 1480: .Nm .
1481: .It
1.58 kristaps 1482: A list or display following the
1.27 kristaps 1483: .Sq \&Ss
1.32 kristaps 1484: .Xr mdoc 7
1485: macro in
1.58 kristaps 1486: .Fl T Ns Cm ascii
1.20 kristaps 1487: does not assert a prior vertical break, just as it doesn't with
1.27 kristaps 1488: .Sq \&Sh .
1.20 kristaps 1489: .It
1.32 kristaps 1490: The
1491: .Sq \&na
1492: .Xr man 7
1.34 kristaps 1493: macro in
1.58 kristaps 1494: .Fl T Ns Cm ascii
1.34 kristaps 1495: has no effect.
1.20 kristaps 1496: .It
1497: Words aren't hyphenated.
1498: .El
1.50 kristaps 1499: .Ss HTML/XHTML Compatibility
1.42 kristaps 1500: .Bl -bullet -compact
1501: .It
1502: The
1.47 kristaps 1503: .Sq \efP
1504: escape will revert the font to the previous
1505: .Sq \ef
1506: escape, not to the last rendered decoration, which is now dictated by
1.57 kristaps 1507: CSS instead of hard-coded.
1508: It also will not span past the current scope,
1509: for the same reason.
1510: Note that in
1.47 kristaps 1511: .Sx ASCII Output
1512: mode, this will work fine.
1513: .It
1514: The
1.42 kristaps 1515: .Xr mdoc 7
1516: .Sq \&Bl \-hang
1517: and
1518: .Sq \&Bl \-tag
1519: list types render similarly (no break following overreached left-hand
1520: side) due to the expressive constraints of HTML.
1521: .It
1522: The
1523: .Xr man 7
1524: .Sq IP
1525: and
1526: .Sq TP
1527: lists render similarly.
1528: .El
1.1 kristaps 1529: .Sh SEE ALSO
1.85 kristaps 1530: .Xr eqn 7 ,
1.57 kristaps 1531: .Xr man 7 ,
1.13 kristaps 1532: .Xr mandoc_char 7 ,
1.84 kristaps 1533: .Xr mdoc 7 ,
1534: .Xr roff 7 ,
1535: .Xr tbl 7
1.1 kristaps 1536: .Sh AUTHORS
1537: The
1538: .Nm
1.26 kristaps 1539: utility was written by
1.103 schwarze 1540: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
1.39 kristaps 1541: .Sh CAVEATS
1542: In
1.58 kristaps 1543: .Fl T Ns Cm html
1.50 kristaps 1544: and
1.58 kristaps 1545: .Fl T Ns Cm xhtml ,
1.39 kristaps 1546: the maximum size of an element attribute is determined by
1547: .Dv BUFSIZ ,
1.57 kristaps 1548: which is usually 1024 bytes.
1549: Be aware of this when setting long link
1.58 kristaps 1550: formats such as
1551: .Fl O Ns Cm style Ns = Ns Ar really/long/link .
1.51 kristaps 1552: .Pp
1553: Nesting elements within next-line element scopes of
1.58 kristaps 1554: .Fl m Ns Cm an ,
1.51 kristaps 1555: such as
1556: .Sq br
1557: within an empty
1558: .Sq B ,
1559: will confuse
1.58 kristaps 1560: .Fl T Ns Cm html
1.51 kristaps 1561: and
1.58 kristaps 1562: .Fl T Ns Cm xhtml
1.52 kristaps 1563: and cause them to forget the formatting of the prior next-line scope.
1.53 kristaps 1564: .Pp
1.54 kristaps 1565: The
1566: .Sq \(aq
1.55 kristaps 1567: control character is an alias for the standard macro control character
1568: and does not emit a line-break as stipulated in GNU troff.
CVSweb