Annotation of mandoc/mandoc.1, Revision 1.107
1.107 ! schwarze 1: .\" $Id: mandoc.1,v 1.106 2014/08/08 01:50:59 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.107 ! schwarze 18: .Dd $Mdocdate: August 8 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.77 schwarze 443: .Sh EXIT STATUS
444: The
445: .Nm
446: utility exits with one of the following values, controlled by the message
447: .Ar level
448: associated with the
449: .Fl W
450: option:
451: .Pp
452: .Bl -tag -width Ds -compact
453: .It 0
454: No warnings or errors occurred, or those that did were ignored because
455: they were lower than the requested
456: .Ar level .
457: .It 2
458: At least one warning occurred, but no error, and
459: .Fl W Ns Cm warning
460: was specified.
461: .It 3
462: At least one parsing error occurred, but no fatal error, and
463: .Fl W Ns Cm error
464: or
465: .Fl W Ns Cm warning
466: was specified.
467: .It 4
468: A fatal parsing error occurred.
469: .It 5
470: Invalid command line arguments were specified.
471: No input files have been read.
472: .It 6
473: An operating system error occurred, for example memory exhaustion or an
474: error accessing input files.
475: Such errors cause
476: .Nm
477: to exit at once, possibly in the middle of parsing or formatting a file.
478: .El
479: .Pp
480: Note that selecting
481: .Fl T Ns Cm lint
482: output mode implies
483: .Fl W Ns Cm warning .
1.1 kristaps 484: .Sh EXAMPLES
1.13 kristaps 485: To page manuals to the terminal:
1.1 kristaps 486: .Pp
1.82 kristaps 487: .Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less
488: .Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
1.28 kristaps 489: .Pp
1.41 kristaps 490: To produce HTML manuals with
491: .Ar style.css
492: as the style-sheet:
1.38 kristaps 493: .Pp
1.82 kristaps 494: .Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
1.38 kristaps 495: .Pp
1.28 kristaps 496: To check over a large set of manuals:
497: .Pp
1.77 schwarze 498: .Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]`
1.66 kristaps 499: .Pp
500: To produce a series of PostScript manuals for A4 paper:
501: .Pp
1.82 kristaps 502: .Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
1.91 schwarze 503: .Pp
504: Convert a modern
505: .Xr mdoc 7
506: manual to the older
507: .Xr man 7
508: format, for use on systems lacking an
509: .Xr mdoc 7
510: parser:
511: .Pp
512: .Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man
1.77 schwarze 513: .Sh DIAGNOSTICS
1.106 schwarze 514: Messages displayed by
515: .Nm
516: follow this format:
1.77 schwarze 517: .Pp
1.106 schwarze 518: .D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args
1.77 schwarze 519: .Pp
1.106 schwarze 520: Line and column numbers start at 1.
521: Both are omitted for messages referring to an input file as a whole.
522: Macro names and arguments are omitted where meaningless.
523: Fatal messages about invalid command line arguments
524: or operating system errors, for example when memory is exhausted,
525: may also omit the
526: .Ar file
1.104 schwarze 527: and
1.106 schwarze 528: .Ar level
529: fields.
1.104 schwarze 530: .Pp
1.77 schwarze 531: Message levels have the following meanings:
532: .Bl -tag -width "warning"
1.105 schwarze 533: .It Cm syserr
534: Opening or reading an input file failed, so the parser cannot
535: even be started and no output is produced from that input file.
1.77 schwarze 536: .It Cm fatal
537: The parser is unable to parse a given input file at all.
538: No formatted output is produced from that input file.
539: .It Cm error
540: An input file contains syntax that cannot be safely interpreted,
541: either because it is invalid or because
542: .Nm
543: does not implement it yet.
544: By discarding part of the input or inserting missing tokens,
545: the parser is able to continue, and the error does not prevent
546: generation of formatted output, but typically, preparing that
547: output involves information loss, broken document structure
548: or unintended formatting.
549: .It Cm warning
550: An input file uses obsolete, discouraged or non-portable syntax.
551: All the same, the meaning of the input is unambiguous and a correct
552: rendering can be produced.
553: Documents causing warnings may render poorly when using other
554: formatting tools instead of
555: .Nm .
556: .El
557: .Pp
558: Messages of the
559: .Cm warning
560: and
561: .Cm error
562: levels are hidden unless their level, or a lower level, is requested using a
563: .Fl W
564: option or
565: .Fl T Ns Cm lint
566: output mode.
1.106 schwarze 567: .Ss Warnings related to the document prologue
568: .Bl -ohang
569: .It Sy "missing manual title, using UNTITLED"
570: .Pq mdoc
571: A
572: .Ic \&Dt
573: macro has no arguments, or there is no
574: .Ic \&Dt
575: macro before the first non-prologue macro.
576: .It Sy "missing manual title, using \(dq\(dq"
577: .Pq man
578: There is no
579: .Ic \&TH
580: macro, or it has no arguments.
581: .It Sy "lower case character in document title"
582: .Pq mdoc , man
583: The title is still used as given in the
584: .Ic \&Dt
585: or
586: .Ic \&TH
587: macro.
588: .It Sy "missing manual section, using \(dq\(dq"
589: .Pq mdoc , man
590: A
591: .Ic \&Dt
592: or
593: .Ic \&TH
594: macro lacks the mandatory section argument.
595: .It Sy "unknown manual section"
596: .Pq mdoc
597: The section number in a
598: .Ic \&Dt
599: line is invalid, but still used.
600: .It Sy "unknown manual volume or arch"
601: .Pq mdoc
602: The volume name in a
603: .Ic \&Dt
604: line is invalid, but still used.
605: The manual is assumed to be architecture-independent.
606: .It Sy "missing date, using today's date"
607: .Pq mdoc, man
608: The document was parsed as
609: .Xr mdoc 7
610: and it has no
611: .Ic \&Dd
612: macro, or the
613: .Ic \&Dd
614: macro has no arguments or only empty arguments;
615: or the document was parsed as
616: .Xr man 7
617: and it has no
618: .Ic \&TH
619: macro, or the
620: .Ic \&TH
621: macro has less than three arguments or its third argument is empty.
622: .It Sy "cannot parse date, using it verbatim"
623: .Pq mdoc , man
624: The date given in a
625: .Ic \&Dd
626: or
627: .Ic \&TH
628: macro does not follow the conventional format.
629: .It Sy "missing Os macro, using \(dq\(dq"
630: .Pq mdoc
631: The default or current system is not shown in this case.
632: .It Sy "duplicate prologue macro"
633: .Pq mdoc
634: One of the prologue macros occurs more than once.
635: The last instance overrides all previous ones.
636: .It Sy "late prologue macro"
637: .Pq mdoc
638: A
639: .Ic \&Dd
640: or
641: .Ic \&Os
642: macro occurs after some non-prologue macro, but still takes effect.
643: .It Sy "skipping late title macro"
644: .Pq mdoc
645: The
646: .Ic \&Dt
647: macro can only occur before the first non-prologue macro
648: because traditional formatters write the page header
649: before parsing the document body.
650: Even though this technical restriction does not apply to
651: .Nm ,
652: traditional semantics is preserved.
653: The late macro is discarded including its arguments.
654: .It Sy "prologue macros out of order"
655: .Pq mdoc
656: The prologue macros are not given in the conventional order
657: .Ic \&Dd ,
658: .Ic \&Dt ,
659: .Ic \&Os .
660: All three macros are used even when given in another order.
661: .El
662: .Ss Warnings regarding document structure
663: .Bl -ohang
664: .It Sy ".so is fragile, better use ln(1)"
665: .Pq roff
666: Including files only works when the parser program runs with the correct
667: current working directory.
668: .It Sy "no document body"
669: .Pq mdoc , man
670: The document body contains neither text nor macros.
671: An empty document is shown, consisting only of a header and a footer line.
672: .It Sy "content before first section header"
673: .Pq mdoc , man
674: Some macros or text precede the first
675: .Ic \&Sh
676: or
677: .Ic \&SH
678: section header.
679: The offending macros and text are parsed and added to the top level
680: of the syntax tree, outside any section block.
681: .It Sy "first section is not NAME"
682: .Pq mdoc
683: The argument of the first
684: .Ic \&Sh
685: macro is not
686: .Sq NAME .
687: This may confuse
688: .Xr makewhatis 8
689: and
690: .Xr apropos 1 .
691: .It Sy "bad NAME section contents"
692: .Pq mdoc
693: The last node in the NAME section is not an
694: .Ic \&Nd
695: macro, or any preceding macro is not
696: .Ic \&Nm ,
697: or the NAME section is completely empty.
698: This may confuse
699: .Xr makewhatis 8
700: and
701: .Xr apropos 1 .
702: .It Sy "sections out of conventional order"
703: .Pq mdoc
704: A standard section occurs after another section it usually precedes.
705: All section titles are used as given,
706: and the order of sections is not changed.
707: .It Sy "duplicate section title"
708: .Pq mdoc
709: The same standard section title occurs more than once.
710: .It Sy "unexpected section"
711: .Pq mdoc
712: A standard section header occurs in a section of the manual
713: where it normally isn't useful.
714: .El
715: .Ss "Warnings related to macros and nesting"
716: .Bl -ohang
717: .It Sy "obsolete macro"
718: .Pq mdoc
719: See the
720: .Xr mdoc 7
721: manual for replacements.
722: .It Sy "skipping paragraph macro"
723: In
724: .Xr mdoc 7
725: documents, this happens
726: .Bl -dash -compact
727: .It
728: at the beginning and end of sections and subsections
729: .It
730: right before non-compact lists and displays
731: .It
732: at the end of items in non-column, non-compact lists
733: .It
734: and for multiple consecutive paragraph macros.
735: .El
736: In
737: .Xr man 7
738: documents, it happens
739: .Bl -dash -compact
740: .It
741: for empty
742: .Ic \&P ,
743: .Ic \&PP ,
744: and
745: .Ic \&LP
746: macros
747: .It
748: for
749: .Ic \&IP
750: macros having neither head nor body arguments
751: .It
752: for
753: .Ic \&br
754: or
755: .Ic \&sp
756: right after
757: .Ic \&SH
758: or
759: .Ic \&SS
760: .El
761: .It Sy "moving paragraph macro out of list"
762: .Pq mdoc
763: A list item in a
764: .Ic \&Bl
765: list contains a trailing paragraph macro.
766: The paragraph macro is moved after the end of the list.
767: .It Sy "skipping no-space macro"
768: .Pq mdoc
769: An input line begins with an
770: .Ic \&Ns
771: macro.
772: The macro is ignored.
773: .It Sy "blocks badly nested"
774: .Pq mdoc
775: If two blocks intersect, one should completely contain the other.
776: Otherwise, rendered output is likely to look strange in any output
777: format, and rendering in SGML-based output formats is likely to be
778: outright wrong because such languages do not support badly nested
779: blocks at all.
780: Typical examples of badly nested blocks are
781: .Qq Ic \&Ao \&Bo \&Ac \&Bc
782: and
783: .Qq Ic \&Ao \&Bq \&Ac .
784: In these examples,
785: .Ic \&Ac
786: breaks
787: .Ic \&Bo
788: and
789: .Ic \&Bq ,
790: respectively.
791: .It Sy "nested displays are not portable"
792: .Pq mdoc
793: A
794: .Ic \&Bd ,
795: .Ic \&D1 ,
796: or
797: .Ic \&Dl
798: display occurs nested inside another
799: .Ic \&Bd
800: display.
801: This works with
802: .Nm ,
803: but fails with most other implementations.
804: .It Sy "moving content out of list"
805: .Pq mdoc
806: A
807: .Ic \&Bl
808: list block contains text or macros before the first
809: .Ic \&It
810: macro.
811: The offending children are moved before the beginning of the list.
812: .It Sy ".Vt block has child macro"
813: .Pq mdoc
814: The
815: .Ic \&Vt
816: macro supports plain text arguments only.
817: Formatting may be ugly and semantic searching
818: for the affected content might not work.
819: .It Sy "fill mode already enabled, skipping"
820: .Pq man
821: A
822: .Ic \&fi
823: request occurs even though the document is still in fill mode,
824: or already switched back to fill mode.
825: It has no effect.
826: .It Sy "fill mode already disabled, skipping"
827: .Pq man
828: An
829: .Ic \&nf
830: request occurs even though the document already switched to no-fill mode
831: and did not switch back to fill mode yet.
832: It has no effect.
833: .It Sy "line scope broken"
834: .Pq man
835: While parsing the next-line scope of the previous macro,
836: another macro is found that prematurely terminates the previous one.
837: The previous, interrupted macro is deleted from the parse tree.
838: .El
839: .Ss "Warnings related to missing arguments"
840: .Bl -ohang
841: .It Sy "skipping empty request"
842: .Pq roff
843: The macro name is missing from a macro definition request.
844: .It Sy "conditional request controls empty scope"
845: .Pq roff
846: A conditional request is only useful if any of the following
847: follows it on the same logical input line:
848: .Bl -dash -compact
849: .It
850: The
851: .Sq \e{
852: keyword to open a multi-line scope.
853: .It
854: A request or macro or some text, resulting in a single-line scope.
855: .It
856: The immediate end of the logical line without any intervening whitespace,
857: resulting in next-line scope.
858: .El
859: Here, a conditional request is followed by trailing whitespace only,
860: and there is no other content on its logical input line.
861: Note that it doesn't matter whether the logical input line is split
862: across multiple physical input lines using
863: .Sq \e
864: line continuation characters.
865: This is one of the rare cases
866: where trailing whitespace is syntactically significant.
867: The conditional request controls a scope containing whitespace only,
868: so it is unlikely to have a significant effect,
869: except that it may control a following
870: .Ic \&el
871: clause.
872: .It Sy "skipping empty macro"
873: .Pq mdoc
874: The indicated macro has no arguments and hence no effect.
875: .It Sy "empty argument, using 0n"
876: .Pq mdoc
877: The required width is missing after
878: .Ic \&Bd
879: or
880: .Ic \&Bl
881: .Fl offset
882: or
883: .Fl width.
884: .It Sy "argument count wrong"
885: .Pq mdoc , man
886: The indicated macro has too few or too many arguments.
887: The syntax tree will contain the wrong number of arguments as given.
888: Formatting behaviour depends on the specific macro in question.
889: Note that the same message may also occur as an ERROR, see below.
890: .It Sy "missing display type, using -ragged"
891: .Pq mdoc
892: The
893: .Ic \&Bd
894: macro is invoked without the required display type.
895: .It Sy "list type is not the first argument"
896: .Pq mdoc
897: In a
898: .Ic \&Bl
899: macro, at least one other argument precedes the type argument.
900: The
901: .Nm
902: utility copes with any argument order, but some other
903: .Xr mdoc 7
904: implementations do not.
905: .It Sy "missing -width in -tag list, using 8n"
906: .Pq mdoc
907: Every
908: .Ic \&Bl
909: macro having the
910: .Fl tag
911: argument requires
912: .Fl width ,
913: too.
914: .It Sy "missing utility name, using \(dq\(dq"
915: .Pq mdoc
916: The
917: .Ic \&Ex Fl std
918: macro is called without an argument before
919: .Ic \&Nm
920: has first been called with an argument.
921: .It Sy "empty head in list item"
922: .Pq mdoc
923: In a
924: .Ic \&Bl
925: .Fl diag ,
926: .Fl hang ,
927: .Fl inset ,
928: .Fl ohang ,
929: or
930: .Fl tag
931: list, an
932: .Ic \&It
933: macro lacks the required argument.
934: The item head is left empty.
935: .It Sy "empty list item"
936: .Pq mdoc
937: In a
938: .Ic \&Bl
939: .Fl bullet ,
940: .Fl dash ,
941: .Fl enum ,
942: or
943: .Fl hyphen
944: list, an
945: .Ic \&It
946: block is empty.
947: An empty list item is shown.
948: .It Sy "missing font type"
949: .Pq mdoc
950: A
951: .Ic \&Bf
952: macro has no argument.
953: It switches to the default font,
954: .Cm \efR .
955: .It Sy "unknown font type"
956: .Pq mdoc
957: The
958: .Ic \&Bf
959: argument is invalid.
960: The default font
961: .Cm \efR
962: is used instead.
963: .It Sy "missing -std argument, adding it"
964: .Pq mdoc
965: An
966: .Ic \&Ex
967: or
968: .Ic \&Rv
969: macro lacks the required
970: .Fl std
971: argument.
972: The
973: .Nm
974: utility assumes
975: .Fl std
976: even when it is not specified, but other implementations may not.
977: .El
978: .Ss "Warnings related to bad macro arguments"
979: .Bl -ohang
980: .It Sy "unterminated quoted argument"
981: .Pq roff
982: Macro arguments can be enclosed in double quote characters
983: such that space characters and macro names contained in the quoted
984: argument need not be escaped.
985: The closing quote of the last argument of a macro can be omitted.
986: However, omitting it is not recommended because it makes the code
987: harder to read.
988: .It Sy "duplicate argument"
989: .Pq mdoc
990: A
991: .Ic \&Bd
992: or
993: .Ic \&Bl
994: macro has more than one
995: .Fl compact ,
996: more than one
997: .Fl offset ,
998: or more than one
999: .Fl width
1000: argument.
1001: All but the last instances of these arguments are ignored.
1002: .It Sy "skipping duplicate argument"
1003: .Pq mdoc
1004: An
1005: .Ic \&An
1006: macro has more than one
1007: .Fl split
1008: or
1009: .Fl nosplit
1010: argument.
1011: All but the first of these arguments are ignored.
1012: .It Sy "skipping duplicate display type"
1013: .Pq mdoc
1014: A
1015: .Ic \&Bd
1016: macro has more than one type argument; the first one is used.
1017: .It Sy "skipping duplicate list type"
1018: .Pq mdoc
1019: A
1020: .Ic \&Bl
1021: macro has more than one type argument; the first one is used.
1022: .It Sy "skipping -width argument"
1023: .Pq mdoc
1024: A
1025: .Ic \&Bl
1026: .Fl column ,
1027: .Fl diag ,
1028: .Fl ohang ,
1029: .Fl inset ,
1030: or
1031: .Fl item
1032: list has a
1033: .Fl width
1034: argument.
1035: That has no effect.
1036: .It Sy "unknown AT&T UNIX version"
1037: .Pq mdoc
1038: An
1039: .Ic \&At
1040: macro has an invalid argument.
1041: It is used verbatim, with
1042: .Qq "AT&T UNIX "
1043: prefixed to it.
1044: .It Sy "invalid content in Rs block"
1045: .Pq mdoc
1046: An
1047: .Ic \&Rs
1048: block contains plain text or non-% macros.
1049: The bogus content is left in the syntax tree.
1050: Formatting may be poor.
1051: .It Sy "invalid Boolean argument"
1052: .Pq mdoc
1053: An
1054: .Ic \&Sm
1055: macro has an argument other than
1056: .Cm on
1057: or
1058: .Cm off .
1059: The invalid argument is moved out of the macro, which leaves the macro
1060: empty, causing it to toggle the spacing mode.
1061: .It Sy "unknown font, skipping request"
1062: .Pq man
1063: A
1064: .Xr roff 7
1065: .Ic \&ft
1066: request has an invalid argument.
1067: .El
1068: .Ss "Warnings related to plain text"
1069: .Bl -ohang
1070: .It Sy "blank line in fill mode, using .sp"
1071: .Pq mdoc
1072: The meaning of blank input lines is only well-defined in non-fill mode:
1073: In fill mode, line breaks of text input lines are not supposed to be
1074: significant.
1075: However, for compatibility with groff, blank lines in fill mode
1076: are replaced with
1077: .Ic \&sp
1078: requests.
1079: .It Sy "tab in filled text"
1080: .Pq mdoc , man
1081: The meaning of tab characters is only well-defined in non-fill mode:
1082: In fill mode, whitespace is not supposed to be significant
1083: on text input lines.
1084: As an implementation dependent choice, tab characters on text lines
1085: are passed through to the formatters in any case.
1086: Given that the text before the tab character will be filled,
1087: it is hard to predict which tab stop position the tab will advance to.
1088: .It Sy "whitespace at end of input line"
1089: .Pq mdoc , man , roff
1090: Whitespace at the end of input lines is almost never semantically
1091: significant \(em but in the odd case where it might be, it is
1092: extremely confusing when reviewing and maintaining documents.
1093: .It Sy "bad comment style"
1094: .Pq roff
1095: Comment lines start with a dot, a backslash, and a double-quote character.
1096: The
1097: .Nm
1098: utility treats the line as a comment line even without the backslash,
1099: but leaving out the backslash might not be portable.
1100: .It Sy "invalid escape sequence"
1101: .Pq roff
1102: An escape sequence has an invalid opening argument delimiter, lacks the
1103: closing argument delimiter, or the argument has too few characters.
1104: If the argument is incomplete,
1105: .Ic \e*
1106: and
1107: .Ic \en
1108: expand to an empty string,
1109: .Ic \eB
1110: to the digit
1111: .Sq 0 ,
1112: and
1113: .Ic \ew
1114: to the length of the incomplete argument.
1115: All other invalid escape sequences are ignored.
1116: .It Sy "undefined string, using \(dq\(dq"
1117: .Pq roff
1118: If a string is used without being defined before,
1119: its value is implicitly set to the empty string.
1120: However, defining strings explicitly before use
1121: keeps the code more readable.
1122: .El
1123: .Ss "Errors related to equations"
1124: .Bl -inset -compact
1125: .It "unexpected equation scope closure"
1126: .It "equation scope open on exit"
1127: .It "overlapping equation scopes"
1128: .It "unexpected end of equation"
1129: .It "equation syntax error"
1130: .El
1131: .Ss "Errors related to tables"
1132: .Bl -inset -compact
1133: .It "bad table syntax"
1134: .It "bad table option"
1135: .It "bad table layout"
1136: .It "no table layout cells specified"
1137: .It "no table data cells specified"
1138: .It "ignore data in cell"
1139: .It "data block still open"
1140: .It "ignoring extra data cells"
1141: .El
1142: .Ss "Errors related to roff, mdoc, and man code"
1143: .Bl -ohang
1144: .It Sy "input stack limit exceeded, infinite loop?"
1145: .Pq roff
1146: Explicit recursion limits are implemented for the following features,
1147: in order to prevent infinite loops:
1148: .Bl -dash -compact
1149: .It
1150: expansion of nested escape sequences
1151: including expansion of strings and number registers,
1152: .It
1153: expansion of nested user-defined macros,
1154: .It
1155: and
1156: .Ic \&so
1157: file inclusion.
1158: .El
1159: When a limit is hit, the output is incorrect, typically losing
1160: some content, but the parser can continue.
1161: .It Sy "skipping bad character"
1162: .Pq mdoc , man , roff
1163: The input file contains a byte that is not a printable
1164: .Xr ascii 7
1165: character.
1166: The message mentions the character number.
1167: The offending byte is replaced with a question mark
1168: .Pq Sq \&? .
1169: Consider editing the input file to replace the byte with an ASCII
1170: transliteration of the intended character.
1171: .It Sy "skipping unknown macro"
1172: .Pq mdoc , man , roff
1173: The first identifier on a request or macro line is neither recognized as a
1174: .Xr roff 7
1175: request, nor as a user-defined macro, nor, respectively, as an
1176: .Xr mdoc 7
1177: or
1178: .Xr man 7
1179: macro.
1180: It may be mistyped or unsupported.
1181: The request or macro is discarded including its arguments.
1182: .It Sy "skipping item outside list"
1183: .Pq mdoc
1184: An
1185: .Ic \&It
1186: macro occurs outside any
1187: .Ic \&Bl
1188: list.
1189: It is discarded including its arguments.
1190: .It Sy "skipping column outside column list"
1191: .Pq mdoc
1192: A
1193: .Ic \&Ta
1194: macro occurs outside any
1195: .Ic \&Bl Fl column
1196: block.
1197: It is discarded including its arguments.
1198: .It Sy "skipping end of block that is not open"
1199: .Pq mdoc , man , eqn , tbl , roff
1200: Various syntax elements can only be used to explicitly close blocks
1201: that have previously been opened.
1202: An
1203: .Xr mdoc 7
1204: block closing macro, a
1205: .Xr man 7
1206: .Ic \&RE
1207: or
1208: .Ic \&UE
1209: macro, or the end of an equation, table, or
1210: .Xr roff 7
1211: conditional request is encountered but no matching block is open.
1212: The offending request or macro is discarded.
1213: .It Sy "inserting missing end of block"
1214: .Pq mdoc , tbl
1215: Various
1216: .Xr mdoc 7
1217: macros as well as tables require explicit closing by dedicated macros.
1218: A block that doesn't support bad nesting
1219: ends before all of its children are properly closed.
1220: The open child nodes are closed implicitly.
1221: .It Sy "scope open on exit"
1222: .Pq mdoc , man , eqn , tbl , roff
1223: At the end of the document, an explicit
1224: .Xr mdoc 7
1225: block, a
1226: .Xr man 7
1227: next-line scope or
1228: .Ic \&RS
1229: or
1230: .Ic \&UR
1231: block, an equation, table, or
1232: .Xr roff 7
1233: conditional or ignore block is still open.
1234: The open block is closed implicitly.
1235: .It Sy "escaped character not allowed in a name"
1236: .Pq roff
1237: Macro, string and register identifiers consist of printable,
1238: non-whitespace ASCII characters.
1239: Escape sequences and characters and strings expressed in terms of them
1240: cannot form part of a name.
1241: The first argument of an
1242: .Ic \&am ,
1243: .Ic \&as ,
1244: .Ic \&de ,
1245: .Ic \&ds ,
1246: .Ic \&nr ,
1247: or
1248: .Ic \&rr
1249: request, or any argument of an
1250: .Ic \&rm
1251: request, or the name of a request or user defined macro being called,
1252: is terminated by an escape sequence.
1253: In the cases of
1254: .Ic \&as ,
1255: .Ic \&ds ,
1256: and
1257: .Ic \&nr ,
1258: the request has no effect at all.
1259: In the cases of
1260: .Ic \&am ,
1261: .Ic \&de ,
1262: .Ic \&rr ,
1263: and
1264: .Ic \&rm ,
1265: what was parsed up to this point is used as the arguments to the request,
1266: and the rest of the input line is discarded including the escape sequence.
1267: When parsing for a request or a user-defined macro name to be called,
1268: only the escape sequence is discarded.
1269: The characters preceding it are used as the request or macro name,
1270: the characters following it are used as the arguments to the request or macro.
1271: .It Sy "argument count wrong"
1272: .Pq mdoc , man , roff
1273: The indicated request or macro has too few or too many arguments.
1274: The syntax tree will contain the wrong number of arguments as given.
1275: Formatting behaviour depends on the specific request or macro in question.
1276: Note that the same message may also occur as a WARNING, see above.
1277: .It Sy "missing list type, using -item"
1278: .Pq mdoc
1279: A
1280: .Ic \&Bl
1281: macro fails to specify the list type.
1282: .It Sy "missing manual name, using \(dq\(dq"
1283: .Pq mdoc
1284: The first call to
1285: .Ic \&Nm
1286: lacks the required argument.
1287: .It Sy "uname(3) system call failed, using UNKNOWN"
1288: .Pq mdoc
1289: The
1290: .Ic \&Os
1291: macro is called without arguments, and the
1292: .Xr uname 3
1293: system call failed.
1294: As a workaround,
1295: .Nm
1296: can be compiled with
1297: .Sm off
1298: .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
1299: .Sm on
1300: .It Sy "unknown standard specifier"
1301: .Pq mdoc
1302: An
1303: .Ic \&St
1304: macro has an unknown argument and is discarded.
1305: .It Sy "skipping request without numeric argument"
1306: .Pq roff
1307: An
1308: .Ic \&it
1309: request has a non-numeric or negative argument or no argument at all.
1310: The invalid request is ignored.
1311: .It Sy "skipping all arguments"
1312: .Pq mdoc , man , eqn , roff
1313: An
1314: .Xr mdoc 7
1315: .Ic \&Bt ,
1316: .Ic \&Ed ,
1317: .Ic \&Ef ,
1318: .Ic \&Ek ,
1319: .Ic \&El ,
1320: .Ic \&Re ,
1321: or
1322: .Ic \&Ud
1323: macro, an
1324: .Ic \&It
1325: macro in a list that don't support item heads, a
1326: .Xr man 7
1327: .Ic \&LP ,
1328: .Ic \&P ,
1329: or
1330: .Ic \&PP
1331: macro, an
1332: .Xr eqn 7
1333: .Ic \&EN
1334: macro, or a
1335: .Xr roff 7
1336: .Sq \&..
1337: block closing request is invoked with at least one argument.
1338: All arguments are ignored.
1339: .It Sy "skipping excess arguments"
1340: .Pq mdoc , roff
1.77 schwarze 1341: The
1.106 schwarze 1342: .Ic \&Bf
1343: macro is invoked with more than one argument, or a request of the
1344: .Ic \&de
1345: family is invoked with more than two arguments.
1346: The excess arguments are ignored.
1347: .El
1348: .Ss FATAL errors
1349: .Bl -ohang
1350: .It Sy "input too large"
1351: .Pq mdoc , man
1352: Currently,
1353: .Nm
1354: cannot handle input files larger than its arbitrary size limit
1355: of 2^31 bytes (2 Gigabytes).
1356: Since useful manuals are always small, this is not a problem in practice.
1357: Parsing is aborted as soon as the condition is detected.
1358: .It Sy "NOT IMPLEMENTED: Bd -file"
1359: .Pq mdoc
1360: For security reasons, the
1361: .Ic \&Bd
1362: macro does not support the
1363: .Fl file
1364: argument.
1365: By requesting the inclusion of a sensitive file, a malicious document
1366: might otherwise trick a privileged user into inadvertently displaying
1367: the file on the screen, revealing the file content to bystanders.
1368: The parser exits immediately.
1369: .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
1370: .Pq roff
1371: For security reasons,
1.77 schwarze 1372: .Nm
1.106 schwarze 1373: allows
1374: .Ic \&so
1375: file inclusion requests only with relative paths
1376: and only without ascending to any parent directory.
1377: By requesting the inclusion of a sensitive file, a malicious document
1378: might otherwise trick a privileged user into inadvertently displaying
1379: the file on the screen, revealing the file content to bystanders.
1380: The parser exits immediately.
1381: .It Sy ".so request failed"
1382: .Pq roff
1383: Servicing a
1384: .Ic \&so
1385: request requires reading an external file.
1386: While trying to do so, an
1387: .Xr open 2 ,
1388: .Xr stat 2 ,
1389: or
1390: .Xr read 2
1391: system call failed.
1392: The parser exits immediately.
1393: Before showing this message,
1394: .Nm
1395: always shows another message explaining why the system call failed.
1396: .El
1.20 kristaps 1397: .Sh COMPATIBILITY
1.26 kristaps 1398: This section summarises
1.20 kristaps 1399: .Nm
1.76 kristaps 1400: compatibility with GNU troff.
1.32 kristaps 1401: Each input and output format is separately noted.
1.48 kristaps 1402: .Ss ASCII Compatibility
1.37 kristaps 1403: .Bl -bullet -compact
1.29 kristaps 1404: .It
1.87 kristaps 1405: Unrenderable unicode codepoints specified with
1.86 kristaps 1406: .Sq \e[uNNNN]
1407: escapes are printed as
1408: .Sq \&?
1409: in mandoc.
1410: In GNU troff, these raise an error.
1411: .It
1.49 kristaps 1412: The
1.33 kristaps 1413: .Sq \&Bd \-literal
1.49 kristaps 1414: and
1.32 kristaps 1415: .Sq \&Bd \-unfilled
1416: macros of
1417: .Xr mdoc 7
1418: in
1.58 kristaps 1419: .Fl T Ns Cm ascii
1.32 kristaps 1420: are synonyms, as are \-filled and \-ragged.
1.26 kristaps 1421: .It
1.86 kristaps 1422: In historic GNU troff, the
1.27 kristaps 1423: .Sq \&Pa
1.32 kristaps 1424: .Xr mdoc 7
1425: macro does not underline when scoped under an
1.30 kristaps 1426: .Sq \&It
1.57 kristaps 1427: in the FILES section.
1428: This behaves correctly in
1.27 kristaps 1429: .Nm .
1430: .It
1.58 kristaps 1431: A list or display following the
1.27 kristaps 1432: .Sq \&Ss
1.32 kristaps 1433: .Xr mdoc 7
1434: macro in
1.58 kristaps 1435: .Fl T Ns Cm ascii
1.20 kristaps 1436: does not assert a prior vertical break, just as it doesn't with
1.27 kristaps 1437: .Sq \&Sh .
1.20 kristaps 1438: .It
1.32 kristaps 1439: The
1440: .Sq \&na
1441: .Xr man 7
1.34 kristaps 1442: macro in
1.58 kristaps 1443: .Fl T Ns Cm ascii
1.34 kristaps 1444: has no effect.
1.20 kristaps 1445: .It
1446: Words aren't hyphenated.
1447: .El
1.50 kristaps 1448: .Ss HTML/XHTML Compatibility
1.42 kristaps 1449: .Bl -bullet -compact
1450: .It
1451: The
1.47 kristaps 1452: .Sq \efP
1453: escape will revert the font to the previous
1454: .Sq \ef
1455: escape, not to the last rendered decoration, which is now dictated by
1.57 kristaps 1456: CSS instead of hard-coded.
1457: It also will not span past the current scope,
1458: for the same reason.
1459: Note that in
1.47 kristaps 1460: .Sx ASCII Output
1461: mode, this will work fine.
1462: .It
1463: The
1.42 kristaps 1464: .Xr mdoc 7
1465: .Sq \&Bl \-hang
1466: and
1467: .Sq \&Bl \-tag
1468: list types render similarly (no break following overreached left-hand
1469: side) due to the expressive constraints of HTML.
1470: .It
1471: The
1472: .Xr man 7
1473: .Sq IP
1474: and
1475: .Sq TP
1476: lists render similarly.
1477: .El
1.1 kristaps 1478: .Sh SEE ALSO
1.85 kristaps 1479: .Xr eqn 7 ,
1.57 kristaps 1480: .Xr man 7 ,
1.13 kristaps 1481: .Xr mandoc_char 7 ,
1.84 kristaps 1482: .Xr mdoc 7 ,
1483: .Xr roff 7 ,
1484: .Xr tbl 7
1.1 kristaps 1485: .Sh AUTHORS
1486: The
1487: .Nm
1.26 kristaps 1488: utility was written by
1.103 schwarze 1489: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
1.39 kristaps 1490: .Sh CAVEATS
1491: In
1.58 kristaps 1492: .Fl T Ns Cm html
1.50 kristaps 1493: and
1.58 kristaps 1494: .Fl T Ns Cm xhtml ,
1.39 kristaps 1495: the maximum size of an element attribute is determined by
1496: .Dv BUFSIZ ,
1.57 kristaps 1497: which is usually 1024 bytes.
1498: Be aware of this when setting long link
1.58 kristaps 1499: formats such as
1500: .Fl O Ns Cm style Ns = Ns Ar really/long/link .
1.51 kristaps 1501: .Pp
1502: Nesting elements within next-line element scopes of
1.58 kristaps 1503: .Fl m Ns Cm an ,
1.51 kristaps 1504: such as
1505: .Sq br
1506: within an empty
1507: .Sq B ,
1508: will confuse
1.58 kristaps 1509: .Fl T Ns Cm html
1.51 kristaps 1510: and
1.58 kristaps 1511: .Fl T Ns Cm xhtml
1.52 kristaps 1512: and cause them to forget the formatting of the prior next-line scope.
1.53 kristaps 1513: .Pp
1.54 kristaps 1514: The
1515: .Sq \(aq
1.55 kristaps 1516: control character is an alias for the standard macro control character
1517: and does not emit a line-break as stipulated in GNU troff.
CVSweb