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