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