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