Annotation of mandoc/mandoc.1, Revision 1.182
1.182 ! schwarze 1: .\" $Id: mandoc.1,v 1.181 2017/03/21 18:25:51 schwarze Exp $
1.1 kristaps 2: .\"
1.92 schwarze 3: .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
1.168 schwarze 4: .\" Copyright (c) 2012, 2014-2017 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.182 ! schwarze 18: .Dd $Mdocdate: March 21 2017 $
1.14 kristaps 19: .Dt MANDOC 1
1.1 kristaps 20: .Os
21: .Sh NAME
22: .Nm mandoc
1.181 schwarze 23: .Nd format manual pages
1.1 kristaps 24: .Sh SYNOPSIS
25: .Nm mandoc
1.153 schwarze 26: .Op Fl acfhkl
1.156 schwarze 27: .Op Fl I Cm os Ns = Ns Ar name
28: .Op Fl K Ar encoding
1.180 schwarze 29: .Op Fl mdoc | man
1.156 schwarze 30: .Op Fl O Ar option
31: .Op Fl T Ar output
32: .Op Fl W Ar level
1.89 kristaps 33: .Op Ar
1.1 kristaps 34: .Sh DESCRIPTION
35: The
36: .Nm
1.26 kristaps 37: utility formats
1.8 kristaps 38: .Ux
1.57 kristaps 39: manual pages for display.
1.100 kristaps 40: .Pp
41: By default,
42: .Nm
43: reads
44: .Xr mdoc 7
45: or
46: .Xr man 7
1.180 schwarze 47: text from stdin and produces
1.156 schwarze 48: .Fl T Cm locale
1.100 kristaps 49: output.
50: .Pp
1.109 schwarze 51: The options are as follows:
1.19 kristaps 52: .Bl -tag -width Ds
1.107 schwarze 53: .It Fl a
54: If the standard output is a terminal device and
55: .Fl c
56: is not specified, use
57: .Xr more 1
58: to paginate the output, just like
59: .Xr man 1
60: would.
61: .It Fl c
62: Copy the formatted manual pages to the standard output without using
63: .Xr more 1
64: to paginate them.
65: This is the default.
66: It can be specified to override
67: .Fl a .
1.109 schwarze 68: .It Fl f
69: A synonym for
70: .Xr whatis 1 .
1.167 schwarze 71: .It Fl h
72: Display only the SYNOPSIS lines.
73: Implies
74: .Fl c .
1.156 schwarze 75: .It Fl I Cm os Ns = Ns Ar name
1.101 schwarze 76: Override the default operating system
77: .Ar name
78: for the
79: .Xr mdoc 7
1.180 schwarze 80: .Ic \&Os
1.130 schwarze 81: and for the
82: .Xr man 7
1.180 schwarze 83: .Ic \&TH
1.101 schwarze 84: macro.
1.156 schwarze 85: .It Fl K Ar encoding
1.119 schwarze 86: Specify the input encoding.
87: The supported
88: .Ar encoding
89: arguments are
90: .Cm us-ascii ,
91: .Cm iso-8859-1 ,
92: and
93: .Cm utf-8 .
1.176 schwarze 94: If not specified, autodetection uses the first match in the following
95: list:
96: .Bl -enum
97: .It
98: If the first three bytes of the input file are the UTF-8 byte order
99: mark (BOM, 0xefbbbf), input is interpreted as
100: .Cm utf-8 .
101: .It
102: If the first or second line of the input file matches the
1.119 schwarze 103: .Sy emacs
104: mode line format
105: .Pp
106: .D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*-
1.176 schwarze 107: .Pp
108: then input is interpreted according to
109: .Ar encoding .
110: .It
111: If the first non-ASCII byte in the file introduces a valid UTF-8
112: sequence, input is interpreted as
113: .Cm utf-8 .
114: .It
115: Otherwise, input is interpreted as
116: .Cm iso-8859-1 .
1.119 schwarze 117: .El
1.109 schwarze 118: .It Fl k
119: A synonym for
120: .Xr apropos 1 .
121: .It Fl l
122: A synonym for
123: .Fl a .
1.180 schwarze 124: .It Fl mdoc | man
125: With
126: .Fl mdoc ,
127: all input files are interpreted as
128: .Xr mdoc 7 .
129: With
130: .Fl man ,
131: all input files are interpreted as
132: .Xr man 7 .
133: By default, the input language is automatically detected for each file:
134: if the the first macro is
135: .Ic \&Dd
136: or
137: .Ic \&Dt ,
138: the
139: .Xr mdoc 7
140: parser is used; otherwise, the
141: .Xr man 7
142: parser is used.
143: With other arguments,
144: .Fl m
145: is silently ignored.
1.156 schwarze 146: .It Fl O Ar option
1.57 kristaps 147: Comma-separated output options.
1.156 schwarze 148: .It Fl T Ar output
1.57 kristaps 149: Output format.
150: See
1.1 kristaps 151: .Sx Output Formats
1.57 kristaps 152: for available formats.
153: Defaults to
1.156 schwarze 154: .Fl T Cm locale .
155: .It Fl W Ar level
1.77 schwarze 156: Specify the minimum message
157: .Ar level
158: to be reported on the standard error output and to affect the exit status.
159: The
160: .Ar level
161: can be
1.133 schwarze 162: .Cm warning ,
163: .Cm error ,
1.77 schwarze 164: or
1.133 schwarze 165: .Cm unsupp ;
1.132 schwarze 166: .Cm all
1.77 schwarze 167: is an alias for
1.132 schwarze 168: .Cm warning .
169: By default,
170: .Nm
171: is silent.
1.77 schwarze 172: See
173: .Sx EXIT STATUS
174: and
175: .Sx DIAGNOSTICS
176: for details.
177: .Pp
178: The special option
1.156 schwarze 179: .Fl W Cm stop
1.77 schwarze 180: tells
181: .Nm
182: to exit after parsing a file that causes warnings or errors of at least
183: the requested level.
184: No formatted output will be produced from that file.
185: If both a
186: .Ar level
187: and
188: .Cm stop
189: are requested, they can be joined with a comma, for example
1.156 schwarze 190: .Fl W Cm error , Ns Cm stop .
1.58 kristaps 191: .It Ar file
192: Read input from zero or more files.
1.57 kristaps 193: If unspecified, reads from stdin.
194: If multiple files are specified,
1.2 kristaps 195: .Nm
196: will halt with the first failed parse.
1.1 kristaps 197: .El
1.109 schwarze 198: .Pp
199: In
200: .Fl f
201: and
202: .Fl k
203: mode,
204: .Nm
205: also supports the options
206: .Fl CMmOSsw
207: described in the
208: .Xr apropos 1
209: manual.
1.182 ! schwarze 210: The options
! 211: .Fl fkl
! 212: are mutually exclusive and override each other.
1.1 kristaps 213: .Ss Output Formats
214: The
215: .Nm
216: utility accepts the following
217: .Fl T
1.66 kristaps 218: arguments, which correspond to output modes:
1.175 schwarze 219: .Bl -tag -width "-T markdown"
1.156 schwarze 220: .It Fl T Cm ascii
1.81 kristaps 221: Produce 7-bit ASCII output.
1.57 kristaps 222: See
1.48 kristaps 223: .Sx ASCII Output .
1.156 schwarze 224: .It Fl T Cm html
1.116 kristaps 225: Produce HTML5, CSS1, and MathML output.
1.57 kristaps 226: See
1.48 kristaps 227: .Sx HTML Output .
1.156 schwarze 228: .It Fl T Cm lint
1.58 kristaps 229: Parse only: produce no output.
230: Implies
1.156 schwarze 231: .Fl W Cm warning .
232: .It Fl T Cm locale
1.93 schwarze 233: Encode output using the current locale.
1.128 schwarze 234: This is the default.
1.93 schwarze 235: See
236: .Sx Locale Output .
1.156 schwarze 237: .It Fl T Cm man
1.95 kristaps 238: Produce
1.91 schwarze 239: .Xr man 7
1.95 kristaps 240: format output.
241: See
242: .Sx Man Output .
1.175 schwarze 243: .It Fl T Cm markdown
244: Produce output in
245: .Sy markdown
246: format.
247: See
248: .Sx Markdown Output .
1.156 schwarze 249: .It Fl T Cm pdf
1.73 kristaps 250: Produce PDF output.
251: See
252: .Sx PDF Output .
1.156 schwarze 253: .It Fl T Cm ps
1.62 kristaps 254: Produce PostScript output.
255: See
256: .Sx PostScript Output .
1.156 schwarze 257: .It Fl T Cm tree
1.58 kristaps 258: Produce an indented parse tree.
1.161 schwarze 259: See
260: .Sx Syntax tree output .
1.156 schwarze 261: .It Fl T Cm utf8
1.93 schwarze 262: Encode output in the UTF\-8 multi-byte format.
263: See
264: .Sx UTF\-8 Output .
1.156 schwarze 265: .It Fl T Cm xhtml
1.114 kristaps 266: This is a synonym for
1.156 schwarze 267: .Fl T Cm html .
1.1 kristaps 268: .El
1.13 kristaps 269: .Pp
270: If multiple input files are specified, these will be processed by the
271: corresponding filter in-order.
1.66 kristaps 272: .Ss ASCII Output
273: Output produced by
1.156 schwarze 274: .Fl T Cm ascii
1.128 schwarze 275: is rendered in standard 7-bit ASCII documented in
1.66 kristaps 276: .Xr ascii 7 .
277: .Pp
278: Font styles are applied by using back-spaced encoding such that an
279: underlined character
280: .Sq c
281: is rendered as
282: .Sq _ Ns \e[bs] Ns c ,
283: where
284: .Sq \e[bs]
285: is the back-space character number 8.
286: Emboldened characters are rendered as
287: .Sq c Ns \e[bs] Ns c .
288: .Pp
289: The special characters documented in
290: .Xr mandoc_char 7
291: are rendered best-effort in an ASCII equivalent.
292: .Pp
293: Output width is limited to 78 visible columns unless literal input lines
294: exceed this limit.
295: .Pp
296: The following
297: .Fl O
298: arguments are accepted:
1.19 kristaps 299: .Bl -tag -width Ds
1.98 schwarze 300: .It Cm indent Ns = Ns Ar indent
301: The left margin for normal text is set to
302: .Ar indent
303: blank characters instead of the default of five for
304: .Xr mdoc 7
305: and seven for
306: .Xr man 7 .
307: Increasing this is not recommended; it may result in degraded formatting,
1.99 schwarze 308: for example overfull lines or ugly line breaks.
1.66 kristaps 309: .It Cm width Ns = Ns Ar width
310: The output width is set to
311: .Ar width ,
1.141 schwarze 312: which will normalise to \(>=58.
1.1 kristaps 313: .El
1.66 kristaps 314: .Ss HTML Output
315: Output produced by
1.156 schwarze 316: .Fl T Cm html
1.114 kristaps 317: conforms to HTML5 using optional self-closing tags.
1.116 kristaps 318: Default styles use only CSS1.
319: Equations rendered from
320: .Xr eqn 7
321: blocks use MathML.
1.66 kristaps 322: .Pp
1.61 kristaps 323: The
1.164 schwarze 324: .Pa mandoc.css
1.83 kristaps 325: file documents style-sheet classes available for customising output.
326: If a style-sheet is not specified with
1.156 schwarze 327: .Fl O Cm style ,
328: .Fl T Cm html
1.114 kristaps 329: defaults to simple output (via an embedded style-sheet)
330: readable in any graphical or text-based web
1.83 kristaps 331: browser.
1.66 kristaps 332: .Pp
1.89 kristaps 333: Special characters are rendered in decimal-encoded UTF\-8.
1.66 kristaps 334: .Pp
335: The following
1.64 kristaps 336: .Fl O
1.66 kristaps 337: arguments are accepted:
1.37 kristaps 338: .Bl -tag -width Ds
1.94 kristaps 339: .It Cm fragment
1.123 schwarze 340: Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body>
341: elements and only emit the subtree below the <body> element.
1.94 kristaps 342: The
343: .Cm style
1.97 schwarze 344: argument will be ignored.
1.94 kristaps 345: This is useful when embedding manual content within existing documents.
1.64 kristaps 346: .It Cm includes Ns = Ns Ar fmt
1.40 kristaps 347: The string
348: .Ar fmt ,
1.49 kristaps 349: for example,
1.40 kristaps 350: .Ar ../src/%I.html ,
351: is used as a template for linked header files (usually via the
1.180 schwarze 352: .Ic \&In
1.57 kristaps 353: macro).
354: Instances of
1.43 kristaps 355: .Sq \&%I
1.57 kristaps 356: are replaced with the include filename.
357: The default is not to present a
1.40 kristaps 358: hyperlink.
1.64 kristaps 359: .It Cm man Ns = Ns Ar fmt
1.39 kristaps 360: The string
361: .Ar fmt ,
1.49 kristaps 362: for example,
1.39 kristaps 363: .Ar ../html%S/%N.%S.html ,
364: is used as a template for linked manuals (usually via the
1.180 schwarze 365: .Ic \&Xr
1.57 kristaps 366: macro).
367: Instances of
1.43 kristaps 368: .Sq \&%N
1.40 kristaps 369: and
370: .Sq %S
371: are replaced with the linked manual's name and section, respectively.
1.57 kristaps 372: If no section is included, section 1 is assumed.
373: The default is not to
1.40 kristaps 374: present a hyperlink.
1.64 kristaps 375: .It Cm style Ns = Ns Ar style.css
1.58 kristaps 376: The file
377: .Ar style.css
378: is used for an external style-sheet.
379: This must be a valid absolute or
380: relative URI.
1.61 kristaps 381: .El
1.93 schwarze 382: .Ss Locale Output
383: Locale-depending output encoding is triggered with
1.156 schwarze 384: .Fl T Cm locale .
1.128 schwarze 385: This is the default.
386: .Pp
1.93 schwarze 387: This option is not available on all systems: systems without locale
388: support, or those whose internal representation is not natively UCS-4,
389: will fall back to
1.156 schwarze 390: .Fl T Cm ascii .
1.93 schwarze 391: See
392: .Sx ASCII Output
393: for font style specification and available command-line arguments.
1.95 kristaps 394: .Ss Man Output
395: Translate input format into
396: .Xr man 7
397: output format.
1.102 schwarze 398: This is useful for distributing manual sources to legacy systems
1.96 kristaps 399: lacking
1.95 kristaps 400: .Xr mdoc 7
401: formatters.
402: .Pp
403: If
404: .Xr mdoc 7
405: is passed as input, it is translated into
1.97 schwarze 406: .Xr man 7 .
407: If the input format is
1.95 kristaps 408: .Xr man 7 ,
1.97 schwarze 409: the input is copied to the output, expanding any
1.95 kristaps 410: .Xr roff 7
1.180 schwarze 411: .Ic so
1.97 schwarze 412: requests.
413: The parser is also run, and as usual, the
414: .Fl W
415: level controls which
416: .Sx DIAGNOSTICS
417: are displayed before copying the input to the output.
1.175 schwarze 418: .Ss Markdown Output
419: Translate
420: .Xr mdoc 7
421: input to the
422: .Sy markdown
423: format conforming to
424: .Lk http://daringfireball.net/projects/markdown/syntax.text\
425: "John Gruber's 2004 specification" .
1.178 schwarze 426: The output also almost conforms to the
427: .Lk http://commonmark.org/ CommonMark
428: specification.
429: .Pp
430: The character set used for the markdown output is ASCII.
431: Non-ASCII characters are encoded as HTML entities.
432: Since that is not possible in literal font contexts, because these
433: are rendered as code spans and code blocks in the markdown output,
434: non-ASCII characters are transliterated to ASCII approximations in
435: these contexts.
1.175 schwarze 436: .Pp
437: Markdown is a very weak markup language, so all semantic markup is
438: lost, and even part of the presentational markup may be lost.
439: Do not use this as an intermediate step in converting to HTML;
440: instead, use
441: .Fl T Cm html
442: directly.
443: .Pp
444: The
445: .Xr man 7 ,
446: .Xr tbl 7 ,
447: and
448: .Xr eqn 7
449: input languages are not supported by
450: .Fl T Cm markdown
451: output mode.
1.93 schwarze 452: .Ss PDF Output
453: PDF-1.1 output may be generated by
1.156 schwarze 454: .Fl T Cm pdf .
1.93 schwarze 455: See
456: .Sx PostScript Output
457: for
458: .Fl O
459: arguments and defaults.
1.62 kristaps 460: .Ss PostScript Output
1.65 kristaps 461: PostScript
462: .Qq Adobe-3.0
463: Level-2 pages may be generated by
1.156 schwarze 464: .Fl T Cm ps .
1.67 kristaps 465: Output pages default to letter sized and are rendered in the Times font
1.70 kristaps 466: family, 11-point.
467: Margins are calculated as 1/9 the page length and width.
1.71 kristaps 468: Line-height is 1.4m.
1.66 kristaps 469: .Pp
470: Special characters are rendered as in
471: .Sx ASCII Output .
472: .Pp
473: The following
474: .Fl O
475: arguments are accepted:
476: .Bl -tag -width Ds
477: .It Cm paper Ns = Ns Ar name
478: The paper size
479: .Ar name
480: may be one of
1.68 kristaps 481: .Ar a3 ,
482: .Ar a4 ,
483: .Ar a5 ,
484: .Ar legal ,
1.66 kristaps 485: or
486: .Ar letter .
1.68 kristaps 487: You may also manually specify dimensions as
488: .Ar NNxNN ,
489: width by height in millimetres.
490: If an unknown value is encountered,
491: .Ar letter
492: is used.
1.66 kristaps 493: .El
1.93 schwarze 494: .Ss UTF\-8 Output
495: Use
1.156 schwarze 496: .Fl T Cm utf8
1.93 schwarze 497: to force a UTF\-8 locale.
1.73 kristaps 498: See
1.93 schwarze 499: .Sx Locale Output
500: for details and options.
1.161 schwarze 501: .Ss Syntax tree output
502: Use
503: .Fl T Cm tree
504: to show a human readable representation of the syntax tree.
505: It is useful for debugging the source code of manual pages.
1.162 schwarze 506: The exact format is subject to change, so don't write parsers for it.
1.170 schwarze 507: .Pp
508: The first paragraph shows meta data found in the
509: .Xr mdoc 7
510: prologue, on the
511: .Xr man 7
512: .Ic \&TH
513: line, or the fallbacks used.
514: .Pp
515: In the tree dump, each output line shows one syntax tree node.
1.161 schwarze 516: Child nodes are indented with respect to their parent node.
517: The columns are:
518: .Pp
519: .Bl -enum -compact
520: .It
521: For macro nodes, the macro name; for text and
522: .Xr tbl 7
1.162 schwarze 523: nodes, the content.
524: There is a special format for
1.161 schwarze 525: .Xr eqn 7
526: nodes.
527: .It
528: Node type (text, elem, block, head, body, body-end, tail, tbl, eqn).
529: .It
530: Flags:
531: .Bl -dash -compact
532: .It
533: An opening parenthesis if the node is an opening delimiter.
534: .It
535: An asterisk if the node starts a new input line.
536: .It
537: The input line number (starting at one).
538: .It
539: A colon.
540: .It
541: The input column number (starting at one).
542: .It
543: A closing parenthesis if the node is a closing delimiter.
544: .It
545: A full stop if the node ends a sentence.
1.169 schwarze 546: .It
1.174 schwarze 547: BROKEN if the node is a block broken by another block.
548: .It
1.169 schwarze 549: NOSRC if the node is not in the input file,
550: but automatically generated from macros.
551: .It
552: NOPRT if the node is not supposed to generate output
553: for any output format.
1.161 schwarze 554: .El
1.174 schwarze 555: .El
556: .Pp
557: The following
558: .Fl O
559: argument is accepted:
560: .Bl -tag -width Ds
561: .It Cm noval
562: Skip validation and show the unvalidated syntax tree.
563: This can help to find out whether a given behaviour is caused by
564: the parser or by the validator.
565: Meta data is not available in this case.
1.161 schwarze 566: .El
1.108 schwarze 567: .Sh ENVIRONMENT
568: .Bl -tag -width MANPAGER
569: .It Ev MANPAGER
570: Any non-empty value of the environment variable
571: .Ev MANPAGER
1.179 schwarze 572: is used instead of the standard pagination program,
573: .Xr more 1 ;
574: see
575: .Xr man 1
576: for details.
577: Only used if
578: .Fl a
579: or
580: .Fl l
581: is specified.
1.108 schwarze 582: .It Ev PAGER
583: Specifies the pagination program to use when
584: .Ev MANPAGER
585: is not defined.
586: If neither PAGER nor MANPAGER is defined,
1.159 schwarze 587: .Xr more 1
588: .Fl s
1.179 schwarze 589: is used.
590: Only used if
591: .Fl a
592: or
593: .Fl l
594: is specified.
1.108 schwarze 595: .El
1.77 schwarze 596: .Sh EXIT STATUS
597: The
598: .Nm
599: utility exits with one of the following values, controlled by the message
600: .Ar level
601: associated with the
602: .Fl W
603: option:
604: .Pp
605: .Bl -tag -width Ds -compact
606: .It 0
607: No warnings or errors occurred, or those that did were ignored because
608: they were lower than the requested
609: .Ar level .
610: .It 2
611: At least one warning occurred, but no error, and
1.156 schwarze 612: .Fl W Cm warning
1.77 schwarze 613: was specified.
614: .It 3
1.133 schwarze 615: At least one parsing error occurred,
616: but no unsupported feature was encountered, and
1.156 schwarze 617: .Fl W Cm error
1.133 schwarze 618: or
1.156 schwarze 619: .Fl W Cm warning
1.133 schwarze 620: was specified.
621: .It 4
1.134 schwarze 622: At least one unsupported feature was encountered, and
1.156 schwarze 623: .Fl W Cm unsupp ,
624: .Fl W Cm error
1.77 schwarze 625: or
1.156 schwarze 626: .Fl W Cm warning
1.77 schwarze 627: was specified.
628: .It 5
629: Invalid command line arguments were specified.
630: No input files have been read.
631: .It 6
1.131 schwarze 632: An operating system error occurred, for example exhaustion
633: of memory, file descriptors, or process table entries.
1.77 schwarze 634: Such errors cause
635: .Nm
636: to exit at once, possibly in the middle of parsing or formatting a file.
637: .El
638: .Pp
639: Note that selecting
1.156 schwarze 640: .Fl T Cm lint
1.77 schwarze 641: output mode implies
1.156 schwarze 642: .Fl W Cm warning .
1.1 kristaps 643: .Sh EXAMPLES
1.13 kristaps 644: To page manuals to the terminal:
1.1 kristaps 645: .Pp
1.156 schwarze 646: .Dl $ mandoc \-W all,stop mandoc.1 2\*(Gt&1 | less
1.82 kristaps 647: .Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
1.28 kristaps 648: .Pp
1.41 kristaps 649: To produce HTML manuals with
1.164 schwarze 650: .Pa mandoc.css
1.41 kristaps 651: as the style-sheet:
1.38 kristaps 652: .Pp
1.164 schwarze 653: .Dl $ mandoc \-T html -O style=mandoc.css mdoc.7 \*(Gt mdoc.7.html
1.38 kristaps 654: .Pp
1.28 kristaps 655: To check over a large set of manuals:
656: .Pp
1.158 schwarze 657: .Dl $ mandoc \-T lint \(gafind /usr/src -name \e*\e.[1-9]\(ga
1.66 kristaps 658: .Pp
659: To produce a series of PostScript manuals for A4 paper:
660: .Pp
1.156 schwarze 661: .Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 \*(Gt manuals.ps
1.91 schwarze 662: .Pp
663: Convert a modern
664: .Xr mdoc 7
665: manual to the older
666: .Xr man 7
667: format, for use on systems lacking an
668: .Xr mdoc 7
669: parser:
670: .Pp
1.156 schwarze 671: .Dl $ mandoc \-T man foo.mdoc \*(Gt foo.man
1.77 schwarze 672: .Sh DIAGNOSTICS
1.106 schwarze 673: Messages displayed by
674: .Nm
675: follow this format:
1.77 schwarze 676: .Pp
1.106 schwarze 677: .D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args
1.77 schwarze 678: .Pp
1.106 schwarze 679: Line and column numbers start at 1.
680: Both are omitted for messages referring to an input file as a whole.
681: Macro names and arguments are omitted where meaningless.
682: Fatal messages about invalid command line arguments
683: or operating system errors, for example when memory is exhausted,
684: may also omit the
685: .Ar file
1.104 schwarze 686: and
1.106 schwarze 687: .Ar level
688: fields.
1.104 schwarze 689: .Pp
1.77 schwarze 690: Message levels have the following meanings:
691: .Bl -tag -width "warning"
1.133 schwarze 692: .It Cm unsupp
693: An input file uses unsupported low-level
694: .Xr roff 7
695: features.
696: The output may be incomplete and/or misformatted,
697: so using GNU troff instead of
698: .Nm
699: to process the file may be preferable.
1.77 schwarze 700: .It Cm error
1.133 schwarze 701: An input file contains invalid syntax that cannot be safely interpreted.
1.77 schwarze 702: By discarding part of the input or inserting missing tokens,
703: the parser is able to continue, and the error does not prevent
704: generation of formatted output, but typically, preparing that
705: output involves information loss, broken document structure
1.133 schwarze 706: or unintended formatting, no matter whether
707: .Nm
708: or GNU troff is used.
709: In many cases, the output of
710: .Nm
711: and GNU troff is identical, but in some,
712: .Nm
713: is more resilient than GNU troff with respect to malformed input.
1.131 schwarze 714: .Pp
715: Non-existent or unreadable input files are also reported on the
716: .Cm error
717: level.
718: In that case, the parser cannot even be started and no output
719: is produced from those input files.
1.77 schwarze 720: .It Cm warning
721: An input file uses obsolete, discouraged or non-portable syntax.
722: All the same, the meaning of the input is unambiguous and a correct
723: rendering can be produced.
724: Documents causing warnings may render poorly when using other
725: formatting tools instead of
726: .Nm .
727: .El
728: .Pp
729: Messages of the
1.133 schwarze 730: .Cm warning ,
731: .Cm error ,
1.77 schwarze 732: and
1.133 schwarze 733: .Cm unsupp
1.131 schwarze 734: levels except those about non-existent or unreadable input files
735: are hidden unless their level, or a lower level, is requested using a
1.77 schwarze 736: .Fl W
737: option or
1.156 schwarze 738: .Fl T Cm lint
1.77 schwarze 739: output mode.
1.106 schwarze 740: .Ss Warnings related to the document prologue
741: .Bl -ohang
742: .It Sy "missing manual title, using UNTITLED"
743: .Pq mdoc
744: A
745: .Ic \&Dt
746: macro has no arguments, or there is no
747: .Ic \&Dt
748: macro before the first non-prologue macro.
749: .It Sy "missing manual title, using \(dq\(dq"
750: .Pq man
751: There is no
752: .Ic \&TH
753: macro, or it has no arguments.
754: .It Sy "lower case character in document title"
755: .Pq mdoc , man
756: The title is still used as given in the
757: .Ic \&Dt
758: or
759: .Ic \&TH
760: macro.
761: .It Sy "missing manual section, using \(dq\(dq"
762: .Pq mdoc , man
763: A
764: .Ic \&Dt
765: or
766: .Ic \&TH
767: macro lacks the mandatory section argument.
768: .It Sy "unknown manual section"
769: .Pq mdoc
770: The section number in a
771: .Ic \&Dt
772: line is invalid, but still used.
773: .It Sy "missing date, using today's date"
774: .Pq mdoc, man
775: The document was parsed as
776: .Xr mdoc 7
777: and it has no
778: .Ic \&Dd
779: macro, or the
780: .Ic \&Dd
781: macro has no arguments or only empty arguments;
782: or the document was parsed as
783: .Xr man 7
784: and it has no
785: .Ic \&TH
786: macro, or the
787: .Ic \&TH
788: macro has less than three arguments or its third argument is empty.
789: .It Sy "cannot parse date, using it verbatim"
790: .Pq mdoc , man
791: The date given in a
792: .Ic \&Dd
793: or
794: .Ic \&TH
795: macro does not follow the conventional format.
796: .It Sy "missing Os macro, using \(dq\(dq"
797: .Pq mdoc
798: The default or current system is not shown in this case.
799: .It Sy "duplicate prologue macro"
800: .Pq mdoc
801: One of the prologue macros occurs more than once.
802: The last instance overrides all previous ones.
803: .It Sy "late prologue macro"
804: .Pq mdoc
805: A
806: .Ic \&Dd
807: or
808: .Ic \&Os
809: macro occurs after some non-prologue macro, but still takes effect.
810: .It Sy "skipping late title macro"
811: .Pq mdoc
812: The
813: .Ic \&Dt
1.152 schwarze 814: macro appears after the first non-prologue macro.
815: Traditional formatters cannot handle this because
816: they write the page header before parsing the document body.
1.106 schwarze 817: Even though this technical restriction does not apply to
818: .Nm ,
819: traditional semantics is preserved.
820: The late macro is discarded including its arguments.
821: .It Sy "prologue macros out of order"
822: .Pq mdoc
823: The prologue macros are not given in the conventional order
824: .Ic \&Dd ,
825: .Ic \&Dt ,
826: .Ic \&Os .
827: All three macros are used even when given in another order.
828: .El
829: .Ss Warnings regarding document structure
830: .Bl -ohang
831: .It Sy ".so is fragile, better use ln(1)"
832: .Pq roff
833: Including files only works when the parser program runs with the correct
834: current working directory.
835: .It Sy "no document body"
836: .Pq mdoc , man
837: The document body contains neither text nor macros.
838: An empty document is shown, consisting only of a header and a footer line.
839: .It Sy "content before first section header"
840: .Pq mdoc , man
841: Some macros or text precede the first
842: .Ic \&Sh
843: or
844: .Ic \&SH
845: section header.
846: The offending macros and text are parsed and added to the top level
847: of the syntax tree, outside any section block.
848: .It Sy "first section is not NAME"
849: .Pq mdoc
850: The argument of the first
851: .Ic \&Sh
852: macro is not
853: .Sq NAME .
854: This may confuse
855: .Xr makewhatis 8
856: and
857: .Xr apropos 1 .
1.168 schwarze 858: .It Sy "NAME section without Nm before Nd"
1.106 schwarze 859: .Pq mdoc
1.155 schwarze 860: The NAME section does not contain any
861: .Ic \&Nm
1.168 schwarze 862: child macro before the first
863: .Ic \&Nd
864: macro.
1.155 schwarze 865: .It Sy "NAME section without description"
866: .Pq mdoc
867: The NAME section lacks the mandatory
868: .Ic \&Nd
869: child macro.
870: .It Sy "description not at the end of NAME"
871: .Pq mdoc
872: The NAME section does contain an
1.106 schwarze 873: .Ic \&Nd
1.155 schwarze 874: child macro, but other content follows it.
875: .It Sy "bad NAME section content"
876: .Pq mdoc
877: The NAME section contains plain text or macros other than
878: .Ic \&Nm
1.106 schwarze 879: and
1.155 schwarze 880: .Ic \&Nd .
1.168 schwarze 881: .It Sy "missing comma before name"
882: .Pq mdoc
883: The NAME section contains an
884: .Ic \&Nm
885: macro that is neither the first one nor preceded by a comma.
1.142 schwarze 886: .It Sy "missing description line, using \(dq\(dq"
887: .Pq mdoc
888: The
889: .Ic \&Nd
890: macro lacks the required argument.
891: The title line of the manual will end after the dash.
1.177 schwarze 892: .It Sy "description line outside NAME section"
893: .Pq mdoc
894: An
895: .Ic \&Nd
896: macro appears outside the NAME section.
897: The arguments are printed anyway and the following text is used for
898: .Xr apropos 1 ,
899: but none of that behaviour is portable.
1.106 schwarze 900: .It Sy "sections out of conventional order"
901: .Pq mdoc
902: A standard section occurs after another section it usually precedes.
903: All section titles are used as given,
904: and the order of sections is not changed.
905: .It Sy "duplicate section title"
906: .Pq mdoc
907: The same standard section title occurs more than once.
908: .It Sy "unexpected section"
909: .Pq mdoc
910: A standard section header occurs in a section of the manual
911: where it normally isn't useful.
1.112 schwarze 912: .It Sy "unusual Xr order"
913: .Pq mdoc
914: In the SEE ALSO section, an
915: .Ic \&Xr
916: macro with a lower section number follows one with a higher number,
917: or two
918: .Ic \&Xr
1.157 schwarze 919: macros referring to the same section are out of alphabetical order.
1.112 schwarze 920: .It Sy "unusual Xr punctuation"
921: .Pq mdoc
922: In the SEE ALSO section, punctuation between two
923: .Ic \&Xr
924: macros differs from a single comma, or there is trailing punctuation
925: after the last
926: .Ic \&Xr
927: macro.
1.111 schwarze 928: .It Sy "AUTHORS section without An macro"
929: .Pq mdoc
930: An AUTHORS sections contains no
931: .Ic \&An
932: macros, or only empty ones.
933: Probably, there are author names lacking markup.
1.106 schwarze 934: .El
935: .Ss "Warnings related to macros and nesting"
936: .Bl -ohang
937: .It Sy "obsolete macro"
938: .Pq mdoc
939: See the
940: .Xr mdoc 7
941: manual for replacements.
1.126 schwarze 942: .It Sy "macro neither callable nor escaped"
943: .Pq mdoc
944: The name of a macro that is not callable appears on a macro line.
945: It is printed verbatim.
1.152 schwarze 946: If the intention is to call it, move it to its own input line;
1.126 schwarze 947: otherwise, escape it by prepending
948: .Sq \e& .
1.106 schwarze 949: .It Sy "skipping paragraph macro"
950: In
951: .Xr mdoc 7
952: documents, this happens
953: .Bl -dash -compact
954: .It
955: at the beginning and end of sections and subsections
956: .It
957: right before non-compact lists and displays
958: .It
959: at the end of items in non-column, non-compact lists
960: .It
961: and for multiple consecutive paragraph macros.
962: .El
963: In
964: .Xr man 7
965: documents, it happens
966: .Bl -dash -compact
967: .It
968: for empty
969: .Ic \&P ,
970: .Ic \&PP ,
971: and
972: .Ic \&LP
973: macros
974: .It
975: for
976: .Ic \&IP
977: macros having neither head nor body arguments
978: .It
979: for
980: .Ic \&br
981: or
982: .Ic \&sp
983: right after
984: .Ic \&SH
985: or
986: .Ic \&SS
987: .El
988: .It Sy "moving paragraph macro out of list"
989: .Pq mdoc
990: A list item in a
991: .Ic \&Bl
992: list contains a trailing paragraph macro.
993: The paragraph macro is moved after the end of the list.
994: .It Sy "skipping no-space macro"
995: .Pq mdoc
996: An input line begins with an
997: .Ic \&Ns
998: macro.
999: The macro is ignored.
1000: .It Sy "blocks badly nested"
1001: .Pq mdoc
1002: If two blocks intersect, one should completely contain the other.
1003: Otherwise, rendered output is likely to look strange in any output
1004: format, and rendering in SGML-based output formats is likely to be
1005: outright wrong because such languages do not support badly nested
1006: blocks at all.
1007: Typical examples of badly nested blocks are
1008: .Qq Ic \&Ao \&Bo \&Ac \&Bc
1009: and
1010: .Qq Ic \&Ao \&Bq \&Ac .
1011: In these examples,
1012: .Ic \&Ac
1013: breaks
1014: .Ic \&Bo
1015: and
1016: .Ic \&Bq ,
1017: respectively.
1018: .It Sy "nested displays are not portable"
1019: .Pq mdoc
1020: A
1021: .Ic \&Bd ,
1022: .Ic \&D1 ,
1023: or
1024: .Ic \&Dl
1025: display occurs nested inside another
1026: .Ic \&Bd
1027: display.
1028: This works with
1029: .Nm ,
1030: but fails with most other implementations.
1031: .It Sy "moving content out of list"
1032: .Pq mdoc
1033: A
1034: .Ic \&Bl
1035: list block contains text or macros before the first
1036: .Ic \&It
1037: macro.
1038: The offending children are moved before the beginning of the list.
1039: .It Sy "fill mode already enabled, skipping"
1040: .Pq man
1041: A
1042: .Ic \&fi
1043: request occurs even though the document is still in fill mode,
1044: or already switched back to fill mode.
1045: It has no effect.
1046: .It Sy "fill mode already disabled, skipping"
1047: .Pq man
1048: An
1049: .Ic \&nf
1050: request occurs even though the document already switched to no-fill mode
1051: and did not switch back to fill mode yet.
1052: It has no effect.
1053: .It Sy "line scope broken"
1054: .Pq man
1055: While parsing the next-line scope of the previous macro,
1056: another macro is found that prematurely terminates the previous one.
1057: The previous, interrupted macro is deleted from the parse tree.
1058: .El
1059: .Ss "Warnings related to missing arguments"
1060: .Bl -ohang
1061: .It Sy "skipping empty request"
1.118 schwarze 1062: .Pq roff , eqn
1063: The macro name is missing from a macro definition request,
1064: or an
1065: .Xr eqn 7
1066: control statement or operation keyword lacks its required argument.
1.106 schwarze 1067: .It Sy "conditional request controls empty scope"
1068: .Pq roff
1069: A conditional request is only useful if any of the following
1070: follows it on the same logical input line:
1071: .Bl -dash -compact
1072: .It
1073: The
1074: .Sq \e{
1075: keyword to open a multi-line scope.
1076: .It
1077: A request or macro or some text, resulting in a single-line scope.
1078: .It
1079: The immediate end of the logical line without any intervening whitespace,
1080: resulting in next-line scope.
1081: .El
1082: Here, a conditional request is followed by trailing whitespace only,
1083: and there is no other content on its logical input line.
1084: Note that it doesn't matter whether the logical input line is split
1085: across multiple physical input lines using
1086: .Sq \e
1087: line continuation characters.
1088: This is one of the rare cases
1089: where trailing whitespace is syntactically significant.
1090: The conditional request controls a scope containing whitespace only,
1091: so it is unlikely to have a significant effect,
1092: except that it may control a following
1093: .Ic \&el
1094: clause.
1095: .It Sy "skipping empty macro"
1096: .Pq mdoc
1.147 schwarze 1097: The indicated macro has no arguments and hence no effect.
1098: .It Sy "empty block"
1099: .Pq mdoc , man
1100: A
1101: .Ic \&Bd ,
1102: .Ic \&Bk ,
1103: .Ic \&Bl ,
1104: .Ic \&D1 ,
1105: .Ic \&Dl ,
1106: .Ic \&RS ,
1107: or
1108: .Ic \&UR
1109: block contains nothing in its body and will produce no output.
1.106 schwarze 1110: .It Sy "empty argument, using 0n"
1111: .Pq mdoc
1112: The required width is missing after
1113: .Ic \&Bd
1114: or
1115: .Ic \&Bl
1116: .Fl offset
1117: or
1118: .Fl width.
1119: .It Sy "missing display type, using -ragged"
1120: .Pq mdoc
1121: The
1122: .Ic \&Bd
1123: macro is invoked without the required display type.
1124: .It Sy "list type is not the first argument"
1125: .Pq mdoc
1126: In a
1127: .Ic \&Bl
1128: macro, at least one other argument precedes the type argument.
1129: The
1130: .Nm
1131: utility copes with any argument order, but some other
1132: .Xr mdoc 7
1133: implementations do not.
1134: .It Sy "missing -width in -tag list, using 8n"
1135: .Pq mdoc
1136: Every
1137: .Ic \&Bl
1138: macro having the
1139: .Fl tag
1140: argument requires
1141: .Fl width ,
1142: too.
1143: .It Sy "missing utility name, using \(dq\(dq"
1144: .Pq mdoc
1145: The
1146: .Ic \&Ex Fl std
1147: macro is called without an argument before
1148: .Ic \&Nm
1149: has first been called with an argument.
1.146 schwarze 1150: .It Sy "missing function name, using \(dq\(dq"
1151: .Pq mdoc
1152: The
1153: .Ic \&Fo
1154: macro is called without an argument.
1155: No function name is printed.
1.106 schwarze 1156: .It Sy "empty head in list item"
1157: .Pq mdoc
1158: In a
1159: .Ic \&Bl
1160: .Fl diag ,
1161: .Fl hang ,
1162: .Fl inset ,
1163: .Fl ohang ,
1164: or
1165: .Fl tag
1166: list, an
1167: .Ic \&It
1168: macro lacks the required argument.
1169: The item head is left empty.
1170: .It Sy "empty list item"
1171: .Pq mdoc
1172: In a
1173: .Ic \&Bl
1174: .Fl bullet ,
1175: .Fl dash ,
1176: .Fl enum ,
1177: or
1178: .Fl hyphen
1179: list, an
1180: .Ic \&It
1181: block is empty.
1182: An empty list item is shown.
1.152 schwarze 1183: .It Sy "missing font type, using \efR"
1.106 schwarze 1184: .Pq mdoc
1185: A
1186: .Ic \&Bf
1187: macro has no argument.
1.152 schwarze 1188: It switches to the default font.
1189: .It Sy "unknown font type, using \efR"
1.106 schwarze 1190: .Pq mdoc
1191: The
1192: .Ic \&Bf
1193: argument is invalid.
1.152 schwarze 1194: The default font is used instead.
1.127 schwarze 1195: .It Sy "nothing follows prefix"
1196: .Pq mdoc
1197: A
1198: .Ic \&Pf
1199: macro has no argument, or only one argument and no macro follows
1200: on the same input line.
1201: This defeats its purpose; in particular, spacing is not suppressed
1202: before the text or macros following on the next input line.
1.143 schwarze 1203: .It Sy "empty reference block"
1204: .Pq mdoc
1205: An
1206: .Ic \&Rs
1207: macro is immediately followed by an
1208: .Ic \&Re
1209: macro on the next input line.
1210: Such an empty block does not produce any output.
1.165 schwarze 1211: .It Sy "missing section argument"
1212: .Pq mdoc
1213: An
1214: .Ic \&Xr
1215: macro lacks its second, section number argument.
1216: The first argument, i.e. the name, is printed, but without subsequent
1.166 schwarze 1217: parentheses.
1.106 schwarze 1218: .It Sy "missing -std argument, adding it"
1219: .Pq mdoc
1220: An
1221: .Ic \&Ex
1222: or
1223: .Ic \&Rv
1224: macro lacks the required
1225: .Fl std
1226: argument.
1227: The
1228: .Nm
1229: utility assumes
1230: .Fl std
1231: even when it is not specified, but other implementations may not.
1.150 schwarze 1232: .It Sy "missing option string, using \(dq\(dq"
1233: .Pq man
1234: The
1235: .Ic \&OP
1236: macro is invoked without any argument.
1237: An empty pair of square brackets is shown.
1238: .It Sy "missing resource identifier, using \(dq\(dq"
1239: .Pq man
1240: The
1241: .Ic \&UR
1242: macro is invoked without any argument.
1243: An empty pair of angle brackets is shown.
1.118 schwarze 1244: .It Sy "missing eqn box, using \(dq\(dq"
1245: .Pq eqn
1246: A diacritic mark or a binary operator is found,
1247: but there is nothing to the left of it.
1248: An empty box is inserted.
1.106 schwarze 1249: .El
1250: .Ss "Warnings related to bad macro arguments"
1251: .Bl -ohang
1252: .It Sy "unterminated quoted argument"
1253: .Pq roff
1254: Macro arguments can be enclosed in double quote characters
1255: such that space characters and macro names contained in the quoted
1256: argument need not be escaped.
1257: The closing quote of the last argument of a macro can be omitted.
1258: However, omitting it is not recommended because it makes the code
1259: harder to read.
1260: .It Sy "duplicate argument"
1261: .Pq mdoc
1262: A
1263: .Ic \&Bd
1264: or
1265: .Ic \&Bl
1266: macro has more than one
1267: .Fl compact ,
1268: more than one
1269: .Fl offset ,
1270: or more than one
1271: .Fl width
1272: argument.
1273: All but the last instances of these arguments are ignored.
1274: .It Sy "skipping duplicate argument"
1275: .Pq mdoc
1276: An
1277: .Ic \&An
1278: macro has more than one
1279: .Fl split
1280: or
1281: .Fl nosplit
1282: argument.
1283: All but the first of these arguments are ignored.
1284: .It Sy "skipping duplicate display type"
1285: .Pq mdoc
1286: A
1287: .Ic \&Bd
1288: macro has more than one type argument; the first one is used.
1289: .It Sy "skipping duplicate list type"
1290: .Pq mdoc
1291: A
1292: .Ic \&Bl
1293: macro has more than one type argument; the first one is used.
1294: .It Sy "skipping -width argument"
1295: .Pq mdoc
1296: A
1297: .Ic \&Bl
1298: .Fl column ,
1299: .Fl diag ,
1300: .Fl ohang ,
1301: .Fl inset ,
1302: or
1303: .Fl item
1304: list has a
1305: .Fl width
1306: argument.
1307: That has no effect.
1.151 schwarze 1308: .It Sy "wrong number of cells"
1309: In a line of a
1310: .Ic \&Bl Fl column
1311: list, the number of tabs or
1312: .Ic \&Ta
1313: macros is less than the number expected from the list header line
1314: or exceeds the expected number by more than one.
1315: Missing cells remain empty, and all cells exceeding the number of
1316: columns are joined into one single cell.
1.106 schwarze 1317: .It Sy "unknown AT&T UNIX version"
1318: .Pq mdoc
1319: An
1320: .Ic \&At
1321: macro has an invalid argument.
1322: It is used verbatim, with
1323: .Qq "AT&T UNIX "
1324: prefixed to it.
1.113 schwarze 1325: .It Sy "comma in function argument"
1326: .Pq mdoc
1327: An argument of an
1328: .Ic \&Fa
1329: or
1330: .Ic \&Fn
1331: macro contains a comma; it should probably be split into two arguments.
1.117 schwarze 1332: .It Sy "parenthesis in function name"
1333: .Pq mdoc
1334: The first argument of an
1335: .Ic \&Fc
1336: or
1337: .Ic \&Fn
1338: macro contains an opening or closing parenthesis; that's probably wrong,
1339: parentheses are added automatically.
1.106 schwarze 1340: .It Sy "invalid content in Rs block"
1341: .Pq mdoc
1342: An
1343: .Ic \&Rs
1344: block contains plain text or non-% macros.
1345: The bogus content is left in the syntax tree.
1346: Formatting may be poor.
1347: .It Sy "invalid Boolean argument"
1348: .Pq mdoc
1349: An
1350: .Ic \&Sm
1351: macro has an argument other than
1352: .Cm on
1353: or
1354: .Cm off .
1355: The invalid argument is moved out of the macro, which leaves the macro
1356: empty, causing it to toggle the spacing mode.
1357: .It Sy "unknown font, skipping request"
1.115 schwarze 1358: .Pq man , tbl
1.106 schwarze 1359: A
1360: .Xr roff 7
1361: .Ic \&ft
1.115 schwarze 1362: request or a
1363: .Xr tbl 7
1364: .Ic \&f
1365: layout modifier has an unknown
1366: .Ar font
1367: argument.
1.151 schwarze 1368: .It Sy "odd number of characters in request"
1369: .Pq roff
1370: A
1371: .Ic \&tr
1372: request contains an odd number of characters.
1373: The last character is mapped to the blank character.
1.106 schwarze 1374: .El
1375: .Ss "Warnings related to plain text"
1376: .Bl -ohang
1377: .It Sy "blank line in fill mode, using .sp"
1378: .Pq mdoc
1379: The meaning of blank input lines is only well-defined in non-fill mode:
1380: In fill mode, line breaks of text input lines are not supposed to be
1381: significant.
1382: However, for compatibility with groff, blank lines in fill mode
1383: are replaced with
1384: .Ic \&sp
1385: requests.
1386: .It Sy "tab in filled text"
1387: .Pq mdoc , man
1388: The meaning of tab characters is only well-defined in non-fill mode:
1389: In fill mode, whitespace is not supposed to be significant
1390: on text input lines.
1391: As an implementation dependent choice, tab characters on text lines
1392: are passed through to the formatters in any case.
1393: Given that the text before the tab character will be filled,
1394: it is hard to predict which tab stop position the tab will advance to.
1395: .It Sy "whitespace at end of input line"
1396: .Pq mdoc , man , roff
1397: Whitespace at the end of input lines is almost never semantically
1398: significant \(em but in the odd case where it might be, it is
1399: extremely confusing when reviewing and maintaining documents.
1.172 schwarze 1400: .It Sy "new sentence, new line"
1401: .Pq mdoc
1402: A new sentence starts in the middle of a text line.
1403: Start it on a new input line to help formatters produce correct spacing.
1.106 schwarze 1404: .It Sy "bad comment style"
1405: .Pq roff
1406: Comment lines start with a dot, a backslash, and a double-quote character.
1407: The
1408: .Nm
1409: utility treats the line as a comment line even without the backslash,
1410: but leaving out the backslash might not be portable.
1411: .It Sy "invalid escape sequence"
1412: .Pq roff
1413: An escape sequence has an invalid opening argument delimiter, lacks the
1414: closing argument delimiter, or the argument has too few characters.
1415: If the argument is incomplete,
1416: .Ic \e*
1417: and
1418: .Ic \en
1419: expand to an empty string,
1420: .Ic \eB
1421: to the digit
1422: .Sq 0 ,
1423: and
1424: .Ic \ew
1425: to the length of the incomplete argument.
1426: All other invalid escape sequences are ignored.
1427: .It Sy "undefined string, using \(dq\(dq"
1428: .Pq roff
1429: If a string is used without being defined before,
1430: its value is implicitly set to the empty string.
1431: However, defining strings explicitly before use
1432: keeps the code more readable.
1433: .El
1.138 schwarze 1434: .Ss "Warnings related to tables"
1435: .Bl -ohang
1436: .It Sy "tbl line starts with span"
1437: .Pq tbl
1438: The first cell in a table layout line is a horizontal span
1439: .Pq Sq Cm s .
1440: Data provided for this cell is ignored, and nothing is printed in the cell.
1441: .It Sy "tbl column starts with span"
1442: .Pq tbl
1443: The first line of a table layout specification
1444: requests a vertical span
1445: .Pq Sq Cm ^ .
1446: Data provided for this cell is ignored, and nothing is printed in the cell.
1447: .It Sy "skipping vertical bar in tbl layout"
1448: .Pq tbl
1449: A table layout specification contains more than two consecutive vertical bars.
1450: A double bar is printed, all additional bars are discarded.
1.106 schwarze 1451: .El
1452: .Ss "Errors related to tables"
1.136 schwarze 1453: .Bl -ohang
1454: .It Sy "non-alphabetic character in tbl options"
1455: .Pq tbl
1456: The table options line contains a character other than a letter,
1457: blank, or comma where the beginning of an option name is expected.
1458: The character is ignored.
1459: .It Sy "skipping unknown tbl option"
1460: .Pq tbl
1461: The table options line contains a string of letters that does not
1462: match any known option name.
1463: The word is ignored.
1464: .It Sy "missing tbl option argument"
1465: .Pq tbl
1466: A table option that requires an argument is not followed by an
1467: opening parenthesis, or the opening parenthesis is immediately
1468: followed by a closing parenthesis.
1469: The option is ignored.
1470: .It Sy "wrong tbl option argument size"
1471: .Pq tbl
1472: A table option argument contains an invalid number of characters.
1473: Both the option and the argument are ignored.
1.138 schwarze 1474: .It Sy "empty tbl layout"
1475: .Pq tbl
1476: A table layout specification is completely empty,
1477: specifying zero lines and zero columns.
1478: As a fallback, a single left-justified column is used.
1479: .It Sy "invalid character in tbl layout"
1480: .Pq tbl
1481: A table layout specification contains a character that can neither
1482: be interpreted as a layout key character nor as a layout modifier,
1483: or a modifier precedes the first key.
1484: The invalid character is discarded.
1485: .It Sy "unmatched parenthesis in tbl layout"
1486: .Pq tbl
1487: A table layout specification contains an opening parenthesis,
1488: but no matching closing parenthesis.
1489: The rest of the input line, starting from the parenthesis, has no effect.
1.139 schwarze 1490: .It Sy "tbl without any data cells"
1491: .Pq tbl
1492: A table does not contain any data cells.
1493: It will probably produce no output.
1494: .It Sy "ignoring data in spanned tbl cell"
1495: .Pq tbl
1496: A table cell is marked as a horizontal span
1497: .Pq Sq Cm s
1498: or vertical span
1499: .Pq Sq Cm ^
1500: in the table layout, but it contains data.
1501: The data is ignored.
1502: .It Sy "ignoring extra tbl data cells"
1503: .Pq tbl
1504: A data line contains more cells than the corresponding layout line.
1505: The data in the extra cells is ignored.
1506: .It Sy "data block open at end of tbl"
1507: .Pq tbl
1508: A data block is opened with
1509: .Cm T{ ,
1510: but never closed with a matching
1511: .Cm T} .
1512: The remaining data lines of the table are all put into one cell,
1513: and any remaining cells stay empty.
1.106 schwarze 1514: .El
1515: .Ss "Errors related to roff, mdoc, and man code"
1516: .Bl -ohang
1517: .It Sy "input stack limit exceeded, infinite loop?"
1518: .Pq roff
1519: Explicit recursion limits are implemented for the following features,
1520: in order to prevent infinite loops:
1521: .Bl -dash -compact
1522: .It
1523: expansion of nested escape sequences
1524: including expansion of strings and number registers,
1525: .It
1526: expansion of nested user-defined macros,
1527: .It
1528: and
1529: .Ic \&so
1530: file inclusion.
1531: .El
1532: When a limit is hit, the output is incorrect, typically losing
1533: some content, but the parser can continue.
1534: .It Sy "skipping bad character"
1535: .Pq mdoc , man , roff
1536: The input file contains a byte that is not a printable
1537: .Xr ascii 7
1538: character.
1539: The message mentions the character number.
1540: The offending byte is replaced with a question mark
1541: .Pq Sq \&? .
1542: Consider editing the input file to replace the byte with an ASCII
1543: transliteration of the intended character.
1544: .It Sy "skipping unknown macro"
1545: .Pq mdoc , man , roff
1546: The first identifier on a request or macro line is neither recognized as a
1547: .Xr roff 7
1548: request, nor as a user-defined macro, nor, respectively, as an
1549: .Xr mdoc 7
1550: or
1551: .Xr man 7
1552: macro.
1553: It may be mistyped or unsupported.
1554: The request or macro is discarded including its arguments.
1.133 schwarze 1555: .It Sy "skipping insecure request"
1556: .Pq roff
1557: An input file attempted to run a shell command
1558: or to read or write an external file.
1559: Such attempts are denied for security reasons.
1.106 schwarze 1560: .It Sy "skipping item outside list"
1.118 schwarze 1561: .Pq mdoc , eqn
1.106 schwarze 1562: An
1563: .Ic \&It
1564: macro occurs outside any
1565: .Ic \&Bl
1.118 schwarze 1566: list, or an
1567: .Xr eqn 7
1568: .Ic above
1569: delimiter occurs outside any pile.
1.106 schwarze 1570: It is discarded including its arguments.
1571: .It Sy "skipping column outside column list"
1572: .Pq mdoc
1573: A
1574: .Ic \&Ta
1575: macro occurs outside any
1576: .Ic \&Bl Fl column
1577: block.
1578: It is discarded including its arguments.
1579: .It Sy "skipping end of block that is not open"
1580: .Pq mdoc , man , eqn , tbl , roff
1581: Various syntax elements can only be used to explicitly close blocks
1582: that have previously been opened.
1583: An
1584: .Xr mdoc 7
1585: block closing macro, a
1586: .Xr man 7
1587: .Ic \&RE
1588: or
1589: .Ic \&UE
1.118 schwarze 1590: macro, an
1591: .Xr eqn 7
1592: right delimiter or closing brace, or the end of an equation, table, or
1.106 schwarze 1593: .Xr roff 7
1594: conditional request is encountered but no matching block is open.
1595: The offending request or macro is discarded.
1.135 schwarze 1596: .It Sy "fewer RS blocks open, skipping"
1597: .Pq man
1598: The
1599: .Ic \&RE
1600: macro is invoked with an argument, but less than the specified number of
1601: .Ic \&RS
1602: blocks is open.
1603: The
1604: .Ic \&RE
1605: macro is discarded.
1.106 schwarze 1606: .It Sy "inserting missing end of block"
1607: .Pq mdoc , tbl
1608: Various
1609: .Xr mdoc 7
1610: macros as well as tables require explicit closing by dedicated macros.
1611: A block that doesn't support bad nesting
1612: ends before all of its children are properly closed.
1613: The open child nodes are closed implicitly.
1.152 schwarze 1614: .It Sy "appending missing end of block"
1.106 schwarze 1615: .Pq mdoc , man , eqn , tbl , roff
1616: At the end of the document, an explicit
1617: .Xr mdoc 7
1618: block, a
1619: .Xr man 7
1620: next-line scope or
1621: .Ic \&RS
1622: or
1623: .Ic \&UR
1624: block, an equation, table, or
1625: .Xr roff 7
1626: conditional or ignore block is still open.
1627: The open block is closed implicitly.
1628: .It Sy "escaped character not allowed in a name"
1629: .Pq roff
1630: Macro, string and register identifiers consist of printable,
1631: non-whitespace ASCII characters.
1632: Escape sequences and characters and strings expressed in terms of them
1633: cannot form part of a name.
1634: The first argument of an
1635: .Ic \&am ,
1636: .Ic \&as ,
1637: .Ic \&de ,
1638: .Ic \&ds ,
1639: .Ic \&nr ,
1640: or
1641: .Ic \&rr
1642: request, or any argument of an
1643: .Ic \&rm
1644: request, or the name of a request or user defined macro being called,
1645: is terminated by an escape sequence.
1646: In the cases of
1647: .Ic \&as ,
1648: .Ic \&ds ,
1649: and
1650: .Ic \&nr ,
1651: the request has no effect at all.
1652: In the cases of
1653: .Ic \&am ,
1654: .Ic \&de ,
1655: .Ic \&rr ,
1656: and
1657: .Ic \&rm ,
1658: what was parsed up to this point is used as the arguments to the request,
1659: and the rest of the input line is discarded including the escape sequence.
1660: When parsing for a request or a user-defined macro name to be called,
1661: only the escape sequence is discarded.
1662: The characters preceding it are used as the request or macro name,
1663: the characters following it are used as the arguments to the request or macro.
1.124 schwarze 1664: .It Sy "NOT IMPLEMENTED: Bd -file"
1665: .Pq mdoc
1666: For security reasons, the
1667: .Ic \&Bd
1668: macro does not support the
1669: .Fl file
1670: argument.
1671: By requesting the inclusion of a sensitive file, a malicious document
1672: might otherwise trick a privileged user into inadvertently displaying
1673: the file on the screen, revealing the file content to bystanders.
1674: The argument is ignored including the file name following it.
1.163 schwarze 1675: .It Sy "skipping display without arguments"
1676: .Pq mdoc
1677: A
1678: .Ic \&Bd
1679: block macro does not have any arguments.
1680: The block is discarded, and the block content is displayed in
1681: whatever mode was active before the block.
1.106 schwarze 1682: .It Sy "missing list type, using -item"
1683: .Pq mdoc
1684: A
1685: .Ic \&Bl
1686: macro fails to specify the list type.
1687: .It Sy "missing manual name, using \(dq\(dq"
1688: .Pq mdoc
1689: The first call to
1.168 schwarze 1690: .Ic \&Nm ,
1691: or any call in the NAME section, lacks the required argument.
1.106 schwarze 1692: .It Sy "uname(3) system call failed, using UNKNOWN"
1693: .Pq mdoc
1694: The
1695: .Ic \&Os
1696: macro is called without arguments, and the
1697: .Xr uname 3
1698: system call failed.
1699: As a workaround,
1700: .Nm
1701: can be compiled with
1702: .Sm off
1703: .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
1704: .Sm on
1705: .It Sy "unknown standard specifier"
1706: .Pq mdoc
1707: An
1708: .Ic \&St
1709: macro has an unknown argument and is discarded.
1710: .It Sy "skipping request without numeric argument"
1.118 schwarze 1711: .Pq roff , eqn
1.106 schwarze 1712: An
1713: .Ic \&it
1.118 schwarze 1714: request or an
1715: .Xr eqn 7
1716: .Ic \&size
1717: or
1718: .Ic \&gsize
1719: statement has a non-numeric or negative argument or no argument at all.
1720: The invalid request or statement is ignored.
1.132 schwarze 1721: .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
1722: .Pq roff
1723: For security reasons,
1724: .Nm
1725: allows
1726: .Ic \&so
1727: file inclusion requests only with relative paths
1728: and only without ascending to any parent directory.
1729: By requesting the inclusion of a sensitive file, a malicious document
1730: might otherwise trick a privileged user into inadvertently displaying
1731: the file on the screen, revealing the file content to bystanders.
1732: .Nm
1733: only shows the path as it appears behind
1734: .Ic \&so .
1735: .It Sy ".so request failed"
1736: .Pq roff
1737: Servicing a
1738: .Ic \&so
1739: request requires reading an external file, but the file could not be
1740: opened.
1741: .Nm
1742: only shows the path as it appears behind
1743: .Ic \&so .
1.106 schwarze 1744: .It Sy "skipping all arguments"
1745: .Pq mdoc , man , eqn , roff
1746: An
1747: .Xr mdoc 7
1748: .Ic \&Bt ,
1749: .Ic \&Ed ,
1750: .Ic \&Ef ,
1751: .Ic \&Ek ,
1752: .Ic \&El ,
1.144 schwarze 1753: .Ic \&Lp ,
1754: .Ic \&Pp ,
1.106 schwarze 1755: .Ic \&Re ,
1.143 schwarze 1756: .Ic \&Rs ,
1.106 schwarze 1757: or
1758: .Ic \&Ud
1759: macro, an
1760: .Ic \&It
1761: macro in a list that don't support item heads, a
1762: .Xr man 7
1763: .Ic \&LP ,
1764: .Ic \&P ,
1765: or
1766: .Ic \&PP
1767: macro, an
1768: .Xr eqn 7
1.120 schwarze 1769: .Ic \&EQ
1770: or
1.106 schwarze 1771: .Ic \&EN
1772: macro, or a
1773: .Xr roff 7
1.148 schwarze 1774: .Ic \&br ,
1775: .Ic \&fi ,
1776: or
1777: .Ic \&nf
1.144 schwarze 1778: request or
1.106 schwarze 1779: .Sq \&..
1780: block closing request is invoked with at least one argument.
1781: All arguments are ignored.
1782: .It Sy "skipping excess arguments"
1.135 schwarze 1783: .Pq mdoc , man , roff
1.150 schwarze 1784: A macro or request is invoked with too many arguments:
1785: .Bl -dash -offset 2n -width 2n -compact
1786: .It
1787: .Ic \&Fo ,
1788: .Ic \&PD ,
1789: .Ic \&RS ,
1790: .Ic \&UR ,
1791: .Ic \&ft ,
1792: or
1793: .Ic \&sp
1794: with more than one argument
1795: .It
1.144 schwarze 1796: .Ic \&An
1.150 schwarze 1797: with another argument after
1.144 schwarze 1798: .Fl split
1799: or
1.150 schwarze 1800: .Fl nosplit
1801: .It
1802: .Ic \&RE
1803: with more than one argument or with a non-integer argument
1804: .It
1805: .Ic \&OP
1806: or a request of the
1807: .Ic \&de
1808: family with more than two arguments
1.154 schwarze 1809: .It
1810: .Ic \&Dt
1811: with more than three arguments
1.150 schwarze 1812: .It
1813: .Ic \&TH
1814: with more than five arguments
1815: .It
1.145 schwarze 1816: .Ic \&Bd ,
1817: .Ic \&Bk ,
1818: or
1819: .Ic \&Bl
1.150 schwarze 1820: with invalid arguments
1821: .El
1.106 schwarze 1822: The excess arguments are ignored.
1.133 schwarze 1823: .El
1824: .Ss Unsupported features
1825: .Bl -ohang
1826: .It Sy "input too large"
1827: .Pq mdoc , man
1828: Currently,
1829: .Nm
1830: cannot handle input files larger than its arbitrary size limit
1831: of 2^31 bytes (2 Gigabytes).
1832: Since useful manuals are always small, this is not a problem in practice.
1833: Parsing is aborted as soon as the condition is detected.
1.136 schwarze 1834: .It Sy "unsupported control character"
1835: .Pq roff
1836: An ASCII control character supported by other
1837: .Xr roff 7
1838: implementations but not by
1839: .Nm
1840: was found in an input file.
1841: It is replaced by a question mark.
1.133 schwarze 1842: .It Sy "unsupported roff request"
1843: .Pq roff
1844: An input file contains a
1845: .Xr roff 7
1846: request supported by GNU troff or Heirloom troff but not by
1847: .Nm ,
1848: and it is likely that this will cause information loss
1849: or considerable misformatting.
1.139 schwarze 1850: .It Sy "eqn delim option in tbl"
1851: .Pq eqn , tbl
1852: The options line of a table defines equation delimiters.
1853: Any equation source code contained in the table will be printed unformatted.
1854: .It Sy "unsupported table layout modifier"
1.138 schwarze 1855: .Pq tbl
1856: A table layout specification contains an
1857: .Sq Cm m
1858: modifier.
1859: The modifier is discarded.
1.133 schwarze 1860: .It Sy "ignoring macro in table"
1.139 schwarze 1861: .Pq tbl , mdoc , man
1862: A table contains an invocation of an
1863: .Xr mdoc 7
1864: or
1865: .Xr man 7
1866: macro or of an undefined macro.
1867: The macro is ignored, and its arguments are handled
1868: as if they were a text line.
1.106 schwarze 1869: .El
1.1 kristaps 1870: .Sh SEE ALSO
1.141 schwarze 1871: .Xr apropos 1 ,
1872: .Xr man 1 ,
1.85 kristaps 1873: .Xr eqn 7 ,
1.57 kristaps 1874: .Xr man 7 ,
1.13 kristaps 1875: .Xr mandoc_char 7 ,
1.84 kristaps 1876: .Xr mdoc 7 ,
1877: .Xr roff 7 ,
1878: .Xr tbl 7
1.173 schwarze 1879: .Sh HISTORY
1880: The
1881: .Nm
1882: utility first appeared in
1883: .Ox 4.8 .
1884: The option
1885: .Fl I
1886: appeared in
1887: .Ox 5.2 ,
1888: and
1889: .Fl aCcfhKklMSsw
1890: in
1891: .Ox 5.7 .
1.1 kristaps 1892: .Sh AUTHORS
1.156 schwarze 1893: .An -nosplit
1.1 kristaps 1894: The
1895: .Nm
1.26 kristaps 1896: utility was written by
1.141 schwarze 1897: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1898: and is maintained by
1899: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
CVSweb