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