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