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