| blob | e9f7375777bcd2a878d75d4f4d760b0479652a15 |
1 .\" $Id: mandoc.1,v 1.106 2014/08/08 01:50:59 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2012, 2014 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: August 8 2014 $
19 .Dt MANDOC 1
20 .Os
21 .Sh NAME
22 .Nm mandoc
23 .Nd format and display UNIX manuals
24 .Sh SYNOPSIS
25 .Nm mandoc
26 .Op Fl V
27 .Sm off
28 .Op Fl I Cm os Li = Ar name
29 .Sm on
30 .Op Fl m Ns Ar format
31 .Op Fl O Ns Ar option
32 .Op Fl T Ns Ar output
33 .Op Fl W Ns Ar level
34 .Op Ar
35 .Sh DESCRIPTION
36 The
37 .Nm
38 utility formats
39 .Ux
40 manual pages for display.
41 .Pp
42 By default,
43 .Nm
44 reads
45 .Xr mdoc 7
46 or
47 .Xr man 7
48 text from stdin, implying
49 .Fl m Ns Cm andoc ,
50 and produces
51 .Fl T Ns Cm ascii
52 output.
53 .Pp
54 The arguments are as follows:
55 .Bl -tag -width Ds
56 .Sm off
57 .It Fl I Cm os Li = Ar name
58 .Sm on
59 Override the default operating system
60 .Ar name
61 for the
62 .Xr mdoc 7
63 .Sq \&Os
64 macro.
65 .It Fl m Ns Ar format
66 Input format.
67 See
68 .Sx Input Formats
69 for available formats.
70 Defaults to
71 .Fl m Ns Cm andoc .
72 .It Fl O Ns Ar option
73 Comma-separated output options.
74 .It Fl T Ns Ar output
75 Output format.
76 See
77 .Sx Output Formats
78 for available formats.
79 Defaults to
80 .Fl T Ns Cm ascii .
81 .It Fl V
82 Print version and exit.
83 .It Fl W Ns Ar level
84 Specify the minimum message
85 .Ar level
86 to be reported on the standard error output and to affect the exit status.
87 The
88 .Ar level
89 can be
90 .Cm warning ,
91 .Cm error ,
92 or
93 .Cm fatal .
94 The default is
95 .Fl W Ns Cm fatal ;
96 .Fl W Ns Cm all
97 is an alias for
98 .Fl W Ns Cm warning .
99 See
100 .Sx EXIT STATUS
101 and
102 .Sx DIAGNOSTICS
103 for details.
104 .Pp
105 The special option
106 .Fl W Ns Cm stop
107 tells
108 .Nm
109 to exit after parsing a file that causes warnings or errors of at least
110 the requested level.
111 No formatted output will be produced from that file.
112 If both a
113 .Ar level
114 and
115 .Cm stop
116 are requested, they can be joined with a comma, for example
117 .Fl W Ns Cm error , Ns Cm stop .
118 .It Ar file
119 Read input from zero or more files.
120 If unspecified, reads from stdin.
121 If multiple files are specified,
122 .Nm
123 will halt with the first failed parse.
124 .El
125 .Ss Input Formats
126 The
127 .Nm
128 utility accepts
129 .Xr mdoc 7
130 and
131 .Xr man 7
132 input with
133 .Fl m Ns Cm doc
134 and
135 .Fl m Ns Cm an ,
136 respectively.
137 The
138 .Xr mdoc 7
139 format is
140 .Em strongly
141 recommended;
142 .Xr man 7
143 should only be used for legacy manuals.
144 .Pp
145 A third option,
146 .Fl m Ns Cm andoc ,
147 which is also the default, determines encoding on-the-fly: if the first
148 non-comment macro is
149 .Sq \&Dd
150 or
151 .Sq \&Dt ,
152 the
153 .Xr mdoc 7
154 parser is used; otherwise, the
155 .Xr man 7
156 parser is used.
157 .Pp
158 If multiple
159 files are specified with
160 .Fl m Ns Cm andoc ,
161 each has its file-type determined this way.
162 If multiple files are
163 specified and
164 .Fl m Ns Cm doc
165 or
166 .Fl m Ns Cm an
167 is specified, then this format is used exclusively.
168 .Ss Output Formats
169 The
170 .Nm
171 utility accepts the following
172 .Fl T
173 arguments, which correspond to output modes:
174 .Bl -tag -width "-Tlocale"
175 .It Fl T Ns Cm ascii
176 Produce 7-bit ASCII output.
177 This is the default.
178 See
179 .Sx ASCII Output .
180 .It Fl T Ns Cm html
181 Produce strict CSS1/HTML-4.01 output.
182 See
183 .Sx HTML Output .
184 .It Fl T Ns Cm lint
185 Parse only: produce no output.
186 Implies
187 .Fl W Ns Cm warning .
188 .It Fl T Ns Cm locale
189 Encode output using the current locale.
190 See
191 .Sx Locale Output .
192 .It Fl T Ns Cm man
193 Produce
194 .Xr man 7
195 format output.
196 See
197 .Sx Man Output .
198 .It Fl T Ns Cm pdf
199 Produce PDF output.
200 See
201 .Sx PDF Output .
202 .It Fl T Ns Cm ps
203 Produce PostScript output.
204 See
205 .Sx PostScript Output .
206 .It Fl T Ns Cm tree
207 Produce an indented parse tree.
208 .It Fl T Ns Cm utf8
209 Encode output in the UTF\-8 multi-byte format.
210 See
211 .Sx UTF\-8 Output .
212 .It Fl T Ns Cm xhtml
213 Produce strict CSS1/XHTML-1.0 output.
214 See
215 .Sx XHTML Output .
216 .El
217 .Pp
218 If multiple input files are specified, these will be processed by the
219 corresponding filter in-order.
220 .Ss ASCII Output
221 Output produced by
222 .Fl T Ns Cm ascii ,
223 which is the default, is rendered in standard 7-bit ASCII documented in
224 .Xr ascii 7 .
225 .Pp
226 Font styles are applied by using back-spaced encoding such that an
227 underlined character
228 .Sq c
229 is rendered as
230 .Sq _ Ns \e[bs] Ns c ,
231 where
232 .Sq \e[bs]
233 is the back-space character number 8.
234 Emboldened characters are rendered as
235 .Sq c Ns \e[bs] Ns c .
236 .Pp
237 The special characters documented in
238 .Xr mandoc_char 7
239 are rendered best-effort in an ASCII equivalent.
240 If no equivalent is found,
241 .Sq \&?
242 is used instead.
243 .Pp
244 Output width is limited to 78 visible columns unless literal input lines
245 exceed this limit.
246 .Pp
247 The following
248 .Fl O
249 arguments are accepted:
250 .Bl -tag -width Ds
251 .It Cm indent Ns = Ns Ar indent
252 The left margin for normal text is set to
253 .Ar indent
254 blank characters instead of the default of five for
255 .Xr mdoc 7
256 and seven for
257 .Xr man 7 .
258 Increasing this is not recommended; it may result in degraded formatting,
259 for example overfull lines or ugly line breaks.
260 .It Cm width Ns = Ns Ar width
261 The output width is set to
262 .Ar width ,
263 which will normalise to \(>=60.
264 .El
265 .Ss HTML Output
266 Output produced by
267 .Fl T Ns Cm html
268 conforms to HTML-4.01 strict.
269 .Pp
270 The
271 .Pa example.style.css
272 file documents style-sheet classes available for customising output.
273 If a style-sheet is not specified with
274 .Fl O Ns Ar style ,
275 .Fl T Ns Cm html
276 defaults to simple output readable in any graphical or text-based web
277 browser.
278 .Pp
279 Special characters are rendered in decimal-encoded UTF\-8.
280 .Pp
281 The following
282 .Fl O
283 arguments are accepted:
284 .Bl -tag -width Ds
285 .It Cm fragment
286 Omit the
287 .Aq !DOCTYPE
288 declaration and the
289 .Aq html ,
290 .Aq head ,
291 and
292 .Aq body
293 elements and only emit the subtree below the
294 .Aq body
295 element.
296 The
297 .Cm style
298 argument will be ignored.
299 This is useful when embedding manual content within existing documents.
300 .It Cm includes Ns = Ns Ar fmt
301 The string
302 .Ar fmt ,
303 for example,
304 .Ar ../src/%I.html ,
305 is used as a template for linked header files (usually via the
306 .Sq \&In
307 macro).
308 Instances of
309 .Sq \&%I
310 are replaced with the include filename.
311 The default is not to present a
312 hyperlink.
313 .It Cm man Ns = Ns Ar fmt
314 The string
315 .Ar fmt ,
316 for example,
317 .Ar ../html%S/%N.%S.html ,
318 is used as a template for linked manuals (usually via the
319 .Sq \&Xr
320 macro).
321 Instances of
322 .Sq \&%N
323 and
324 .Sq %S
325 are replaced with the linked manual's name and section, respectively.
326 If no section is included, section 1 is assumed.
327 The default is not to
328 present a hyperlink.
329 .It Cm style Ns = Ns Ar style.css
330 The file
331 .Ar style.css
332 is used for an external style-sheet.
333 This must be a valid absolute or
334 relative URI.
335 .El
336 .Ss Locale Output
337 Locale-depending output encoding is triggered with
338 .Fl T Ns Cm locale .
339 This option is not available on all systems: systems without locale
340 support, or those whose internal representation is not natively UCS-4,
341 will fall back to
342 .Fl T Ns Cm ascii .
343 See
344 .Sx ASCII Output
345 for font style specification and available command-line arguments.
346 .Ss Man Output
347 Translate input format into
348 .Xr man 7
349 output format.
350 This is useful for distributing manual sources to legacy systems
351 lacking
352 .Xr mdoc 7
353 formatters.
354 .Pp
355 If
356 .Xr mdoc 7
357 is passed as input, it is translated into
358 .Xr man 7 .
359 If the input format is
360 .Xr man 7 ,
361 the input is copied to the output, expanding any
362 .Xr roff 7
363 .Sq so
364 requests.
365 The parser is also run, and as usual, the
366 .Fl W
367 level controls which
368 .Sx DIAGNOSTICS
369 are displayed before copying the input to the output.
370 .Ss PDF Output
371 PDF-1.1 output may be generated by
372 .Fl T Ns Cm pdf .
373 See
374 .Sx PostScript Output
375 for
376 .Fl O
377 arguments and defaults.
378 .Ss PostScript Output
379 PostScript
380 .Qq Adobe-3.0
381 Level-2 pages may be generated by
382 .Fl T Ns Cm ps .
383 Output pages default to letter sized and are rendered in the Times font
384 family, 11-point.
385 Margins are calculated as 1/9 the page length and width.
386 Line-height is 1.4m.
387 .Pp
388 Special characters are rendered as in
389 .Sx ASCII Output .
390 .Pp
391 The following
392 .Fl O
393 arguments are accepted:
394 .Bl -tag -width Ds
395 .It Cm paper Ns = Ns Ar name
396 The paper size
397 .Ar name
398 may be one of
399 .Ar a3 ,
400 .Ar a4 ,
401 .Ar a5 ,
402 .Ar legal ,
403 or
404 .Ar letter .
405 You may also manually specify dimensions as
406 .Ar NNxNN ,
407 width by height in millimetres.
408 If an unknown value is encountered,
409 .Ar letter
410 is used.
411 .El
412 .Ss UTF\-8 Output
413 Use
414 .Fl T Ns Cm utf8
415 to force a UTF\-8 locale.
416 See
417 .Sx Locale Output
418 for details and options.
419 .Ss XHTML Output
420 Output produced by
421 .Fl T Ns Cm xhtml
422 conforms to XHTML-1.0 strict.
423 .Pp
424 See
425 .Sx HTML Output
426 for details; beyond generating XHTML tags instead of HTML tags, these
427 output modes are identical.
428 .Sh EXIT STATUS
429 The
430 .Nm
431 utility exits with one of the following values, controlled by the message
432 .Ar level
433 associated with the
434 .Fl W
435 option:
436 .Pp
437 .Bl -tag -width Ds -compact
438 .It 0
439 No warnings or errors occurred, or those that did were ignored because
440 they were lower than the requested
441 .Ar level .
442 .It 2
443 At least one warning occurred, but no error, and
444 .Fl W Ns Cm warning
445 was specified.
446 .It 3
447 At least one parsing error occurred, but no fatal error, and
448 .Fl W Ns Cm error
449 or
450 .Fl W Ns Cm warning
451 was specified.
452 .It 4
453 A fatal parsing error occurred.
454 .It 5
455 Invalid command line arguments were specified.
456 No input files have been read.
457 .It 6
458 An operating system error occurred, for example memory exhaustion or an
459 error accessing input files.
460 Such errors cause
461 .Nm
462 to exit at once, possibly in the middle of parsing or formatting a file.
463 .El
464 .Pp
465 Note that selecting
466 .Fl T Ns Cm lint
467 output mode implies
468 .Fl W Ns Cm warning .
469 .Sh EXAMPLES
470 To page manuals to the terminal:
471 .Pp
472 .Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less
473 .Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
474 .Pp
475 To produce HTML manuals with
476 .Ar style.css
477 as the style-sheet:
478 .Pp
479 .Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
480 .Pp
481 To check over a large set of manuals:
482 .Pp
483 .Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]`
484 .Pp
485 To produce a series of PostScript manuals for A4 paper:
486 .Pp
487 .Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
488 .Pp
489 Convert a modern
490 .Xr mdoc 7
491 manual to the older
492 .Xr man 7
493 format, for use on systems lacking an
494 .Xr mdoc 7
495 parser:
496 .Pp
497 .Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man
498 .Sh DIAGNOSTICS
499 Messages displayed by
500 .Nm
501 follow this format:
502 .Pp
503 .D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args
504 .Pp
505 Line and column numbers start at 1.
506 Both are omitted for messages referring to an input file as a whole.
507 Macro names and arguments are omitted where meaningless.
508 Fatal messages about invalid command line arguments
509 or operating system errors, for example when memory is exhausted,
510 may also omit the
511 .Ar file
512 and
513 .Ar level
514 fields.
515 .Pp
516 Message levels have the following meanings:
517 .Bl -tag -width "warning"
518 .It Cm syserr
519 Opening or reading an input file failed, so the parser cannot
520 even be started and no output is produced from that input file.
521 .It Cm fatal
522 The parser is unable to parse a given input file at all.
523 No formatted output is produced from that input file.
524 .It Cm error
525 An input file contains syntax that cannot be safely interpreted,
526 either because it is invalid or because
527 .Nm
528 does not implement it yet.
529 By discarding part of the input or inserting missing tokens,
530 the parser is able to continue, and the error does not prevent
531 generation of formatted output, but typically, preparing that
532 output involves information loss, broken document structure
533 or unintended formatting.
534 .It Cm warning
535 An input file uses obsolete, discouraged or non-portable syntax.
536 All the same, the meaning of the input is unambiguous and a correct
537 rendering can be produced.
538 Documents causing warnings may render poorly when using other
539 formatting tools instead of
540 .Nm .
541 .El
542 .Pp
543 Messages of the
544 .Cm warning
545 and
546 .Cm error
547 levels are hidden unless their level, or a lower level, is requested using a
548 .Fl W
549 option or
550 .Fl T Ns Cm lint
551 output mode.
552 .Ss Warnings related to the document prologue
553 .Bl -ohang
554 .It Sy "missing manual title, using UNTITLED"
555 .Pq mdoc
556 A
557 .Ic \&Dt
558 macro has no arguments, or there is no
559 .Ic \&Dt
560 macro before the first non-prologue macro.
561 .It Sy "missing manual title, using \(dq\(dq"
562 .Pq man
563 There is no
564 .Ic \&TH
565 macro, or it has no arguments.
566 .It Sy "lower case character in document title"
567 .Pq mdoc , man
568 The title is still used as given in the
569 .Ic \&Dt
570 or
571 .Ic \&TH
572 macro.
573 .It Sy "missing manual section, using \(dq\(dq"
574 .Pq mdoc , man
575 A
576 .Ic \&Dt
577 or
578 .Ic \&TH
579 macro lacks the mandatory section argument.
580 .It Sy "unknown manual section"
581 .Pq mdoc
582 The section number in a
583 .Ic \&Dt
584 line is invalid, but still used.
585 .It Sy "unknown manual volume or arch"
586 .Pq mdoc
587 The volume name in a
588 .Ic \&Dt
589 line is invalid, but still used.
590 The manual is assumed to be architecture-independent.
591 .It Sy "missing date, using today's date"
592 .Pq mdoc, man
593 The document was parsed as
594 .Xr mdoc 7
595 and it has no
596 .Ic \&Dd
597 macro, or the
598 .Ic \&Dd
599 macro has no arguments or only empty arguments;
600 or the document was parsed as
601 .Xr man 7
602 and it has no
603 .Ic \&TH
604 macro, or the
605 .Ic \&TH
606 macro has less than three arguments or its third argument is empty.
607 .It Sy "cannot parse date, using it verbatim"
608 .Pq mdoc , man
609 The date given in a
610 .Ic \&Dd
611 or
612 .Ic \&TH
613 macro does not follow the conventional format.
614 .It Sy "missing Os macro, using \(dq\(dq"
615 .Pq mdoc
616 The default or current system is not shown in this case.
617 .It Sy "duplicate prologue macro"
618 .Pq mdoc
619 One of the prologue macros occurs more than once.
620 The last instance overrides all previous ones.
621 .It Sy "late prologue macro"
622 .Pq mdoc
623 A
624 .Ic \&Dd
625 or
626 .Ic \&Os
627 macro occurs after some non-prologue macro, but still takes effect.
628 .It Sy "skipping late title macro"
629 .Pq mdoc
630 The
631 .Ic \&Dt
632 macro can only occur before the first non-prologue macro
633 because traditional formatters write the page header
634 before parsing the document body.
635 Even though this technical restriction does not apply to
636 .Nm ,
637 traditional semantics is preserved.
638 The late macro is discarded including its arguments.
639 .It Sy "prologue macros out of order"
640 .Pq mdoc
641 The prologue macros are not given in the conventional order
642 .Ic \&Dd ,
643 .Ic \&Dt ,
644 .Ic \&Os .
645 All three macros are used even when given in another order.
646 .El
647 .Ss Warnings regarding document structure
648 .Bl -ohang
649 .It Sy ".so is fragile, better use ln(1)"
650 .Pq roff
651 Including files only works when the parser program runs with the correct
652 current working directory.
653 .It Sy "no document body"
654 .Pq mdoc , man
655 The document body contains neither text nor macros.
656 An empty document is shown, consisting only of a header and a footer line.
657 .It Sy "content before first section header"
658 .Pq mdoc , man
659 Some macros or text precede the first
660 .Ic \&Sh
661 or
662 .Ic \&SH
663 section header.
664 The offending macros and text are parsed and added to the top level
665 of the syntax tree, outside any section block.
666 .It Sy "first section is not NAME"
667 .Pq mdoc
668 The argument of the first
669 .Ic \&Sh
670 macro is not
671 .Sq NAME .
672 This may confuse
673 .Xr makewhatis 8
674 and
675 .Xr apropos 1 .
676 .It Sy "bad NAME section contents"
677 .Pq mdoc
678 The last node in the NAME section is not an
679 .Ic \&Nd
680 macro, or any preceding macro is not
681 .Ic \&Nm ,
682 or the NAME section is completely empty.
683 This may confuse
684 .Xr makewhatis 8
685 and
686 .Xr apropos 1 .
687 .It Sy "sections out of conventional order"
688 .Pq mdoc
689 A standard section occurs after another section it usually precedes.
690 All section titles are used as given,
691 and the order of sections is not changed.
692 .It Sy "duplicate section title"
693 .Pq mdoc
694 The same standard section title occurs more than once.
695 .It Sy "unexpected section"
696 .Pq mdoc
697 A standard section header occurs in a section of the manual
698 where it normally isn't useful.
699 .El
700 .Ss "Warnings related to macros and nesting"
701 .Bl -ohang
702 .It Sy "obsolete macro"
703 .Pq mdoc
704 See the
705 .Xr mdoc 7
706 manual for replacements.
707 .It Sy "skipping paragraph macro"
708 In
709 .Xr mdoc 7
710 documents, this happens
711 .Bl -dash -compact
712 .It
713 at the beginning and end of sections and subsections
714 .It
715 right before non-compact lists and displays
716 .It
717 at the end of items in non-column, non-compact lists
718 .It
719 and for multiple consecutive paragraph macros.
720 .El
721 In
722 .Xr man 7
723 documents, it happens
724 .Bl -dash -compact
725 .It
726 for empty
727 .Ic \&P ,
728 .Ic \&PP ,
729 and
730 .Ic \&LP
731 macros
732 .It
733 for
734 .Ic \&IP
735 macros having neither head nor body arguments
736 .It
737 for
738 .Ic \&br
739 or
740 .Ic \&sp
741 right after
742 .Ic \&SH
743 or
744 .Ic \&SS
745 .El
746 .It Sy "moving paragraph macro out of list"
747 .Pq mdoc
748 A list item in a
749 .Ic \&Bl
750 list contains a trailing paragraph macro.
751 The paragraph macro is moved after the end of the list.
752 .It Sy "skipping no-space macro"
753 .Pq mdoc
754 An input line begins with an
755 .Ic \&Ns
756 macro.
757 The macro is ignored.
758 .It Sy "blocks badly nested"
759 .Pq mdoc
760 If two blocks intersect, one should completely contain the other.
761 Otherwise, rendered output is likely to look strange in any output
762 format, and rendering in SGML-based output formats is likely to be
763 outright wrong because such languages do not support badly nested
764 blocks at all.
765 Typical examples of badly nested blocks are
766 .Qq Ic \&Ao \&Bo \&Ac \&Bc
767 and
768 .Qq Ic \&Ao \&Bq \&Ac .
769 In these examples,
770 .Ic \&Ac
771 breaks
772 .Ic \&Bo
773 and
774 .Ic \&Bq ,
775 respectively.
776 .It Sy "nested displays are not portable"
777 .Pq mdoc
778 A
779 .Ic \&Bd ,
780 .Ic \&D1 ,
781 or
782 .Ic \&Dl
783 display occurs nested inside another
784 .Ic \&Bd
785 display.
786 This works with
787 .Nm ,
788 but fails with most other implementations.
789 .It Sy "moving content out of list"
790 .Pq mdoc
791 A
792 .Ic \&Bl
793 list block contains text or macros before the first
794 .Ic \&It
795 macro.
796 The offending children are moved before the beginning of the list.
797 .It Sy ".Vt block has child macro"
798 .Pq mdoc
799 The
800 .Ic \&Vt
801 macro supports plain text arguments only.
802 Formatting may be ugly and semantic searching
803 for the affected content might not work.
804 .It Sy "fill mode already enabled, skipping"
805 .Pq man
806 A
807 .Ic \&fi
808 request occurs even though the document is still in fill mode,
809 or already switched back to fill mode.
810 It has no effect.
811 .It Sy "fill mode already disabled, skipping"
812 .Pq man
813 An
814 .Ic \&nf
815 request occurs even though the document already switched to no-fill mode
816 and did not switch back to fill mode yet.
817 It has no effect.
818 .It Sy "line scope broken"
819 .Pq man
820 While parsing the next-line scope of the previous macro,
821 another macro is found that prematurely terminates the previous one.
822 The previous, interrupted macro is deleted from the parse tree.
823 .El
824 .Ss "Warnings related to missing arguments"
825 .Bl -ohang
826 .It Sy "skipping empty request"
827 .Pq roff
828 The macro name is missing from a macro definition request.
829 .It Sy "conditional request controls empty scope"
830 .Pq roff
831 A conditional request is only useful if any of the following
832 follows it on the same logical input line:
833 .Bl -dash -compact
834 .It
835 The
836 .Sq \e{
837 keyword to open a multi-line scope.
838 .It
839 A request or macro or some text, resulting in a single-line scope.
840 .It
841 The immediate end of the logical line without any intervening whitespace,
842 resulting in next-line scope.
843 .El
844 Here, a conditional request is followed by trailing whitespace only,
845 and there is no other content on its logical input line.
846 Note that it doesn't matter whether the logical input line is split
847 across multiple physical input lines using
848 .Sq \e
849 line continuation characters.
850 This is one of the rare cases
851 where trailing whitespace is syntactically significant.
852 The conditional request controls a scope containing whitespace only,
853 so it is unlikely to have a significant effect,
854 except that it may control a following
855 .Ic \&el
856 clause.
857 .It Sy "skipping empty macro"
858 .Pq mdoc
859 The indicated macro has no arguments and hence no effect.
860 .It Sy "empty argument, using 0n"
861 .Pq mdoc
862 The required width is missing after
863 .Ic \&Bd
864 or
865 .Ic \&Bl
866 .Fl offset
867 or
868 .Fl width.
869 .It Sy "argument count wrong"
870 .Pq mdoc , man
871 The indicated macro has too few or too many arguments.
872 The syntax tree will contain the wrong number of arguments as given.
873 Formatting behaviour depends on the specific macro in question.
874 Note that the same message may also occur as an ERROR, see below.
875 .It Sy "missing display type, using -ragged"
876 .Pq mdoc
877 The
878 .Ic \&Bd
879 macro is invoked without the required display type.
880 .It Sy "list type is not the first argument"
881 .Pq mdoc
882 In a
883 .Ic \&Bl
884 macro, at least one other argument precedes the type argument.
885 The
886 .Nm
887 utility copes with any argument order, but some other
888 .Xr mdoc 7
889 implementations do not.
890 .It Sy "missing -width in -tag list, using 8n"
891 .Pq mdoc
892 Every
893 .Ic \&Bl
894 macro having the
895 .Fl tag
896 argument requires
897 .Fl width ,
898 too.
899 .It Sy "missing utility name, using \(dq\(dq"
900 .Pq mdoc
901 The
902 .Ic \&Ex Fl std
903 macro is called without an argument before
904 .Ic \&Nm
905 has first been called with an argument.
906 .It Sy "empty head in list item"
907 .Pq mdoc
908 In a
909 .Ic \&Bl
910 .Fl diag ,
911 .Fl hang ,
912 .Fl inset ,
913 .Fl ohang ,
914 or
915 .Fl tag
916 list, an
917 .Ic \&It
918 macro lacks the required argument.
919 The item head is left empty.
920 .It Sy "empty list item"
921 .Pq mdoc
922 In a
923 .Ic \&Bl
924 .Fl bullet ,
925 .Fl dash ,
926 .Fl enum ,
927 or
928 .Fl hyphen
929 list, an
930 .Ic \&It
931 block is empty.
932 An empty list item is shown.
933 .It Sy "missing font type"
934 .Pq mdoc
935 A
936 .Ic \&Bf
937 macro has no argument.
938 It switches to the default font,
939 .Cm \efR .
940 .It Sy "unknown font type"
941 .Pq mdoc
942 The
943 .Ic \&Bf
944 argument is invalid.
945 The default font
946 .Cm \efR
947 is used instead.
948 .It Sy "missing -std argument, adding it"
949 .Pq mdoc
950 An
951 .Ic \&Ex
952 or
953 .Ic \&Rv
954 macro lacks the required
955 .Fl std
956 argument.
957 The
958 .Nm
959 utility assumes
960 .Fl std
961 even when it is not specified, but other implementations may not.
962 .El
963 .Ss "Warnings related to bad macro arguments"
964 .Bl -ohang
965 .It Sy "unterminated quoted argument"
966 .Pq roff
967 Macro arguments can be enclosed in double quote characters
968 such that space characters and macro names contained in the quoted
969 argument need not be escaped.
970 The closing quote of the last argument of a macro can be omitted.
971 However, omitting it is not recommended because it makes the code
972 harder to read.
973 .It Sy "duplicate argument"
974 .Pq mdoc
975 A
976 .Ic \&Bd
977 or
978 .Ic \&Bl
979 macro has more than one
980 .Fl compact ,
981 more than one
982 .Fl offset ,
983 or more than one
984 .Fl width
985 argument.
986 All but the last instances of these arguments are ignored.
987 .It Sy "skipping duplicate argument"
988 .Pq mdoc
989 An
990 .Ic \&An
991 macro has more than one
992 .Fl split
993 or
994 .Fl nosplit
995 argument.
996 All but the first of these arguments are ignored.
997 .It Sy "skipping duplicate display type"
998 .Pq mdoc
999 A
1000 .Ic \&Bd
1001 macro has more than one type argument; the first one is used.
1002 .It Sy "skipping duplicate list type"
1003 .Pq mdoc
1004 A
1005 .Ic \&Bl
1006 macro has more than one type argument; the first one is used.
1007 .It Sy "skipping -width argument"
1008 .Pq mdoc
1009 A
1010 .Ic \&Bl
1011 .Fl column ,
1012 .Fl diag ,
1013 .Fl ohang ,
1014 .Fl inset ,
1015 or
1016 .Fl item
1017 list has a
1018 .Fl width
1019 argument.
1020 That has no effect.
1021 .It Sy "unknown AT&T UNIX version"
1022 .Pq mdoc
1023 An
1024 .Ic \&At
1025 macro has an invalid argument.
1026 It is used verbatim, with
1027 .Qq "AT&T UNIX "
1028 prefixed to it.
1029 .It Sy "invalid content in Rs block"
1030 .Pq mdoc
1031 An
1032 .Ic \&Rs
1033 block contains plain text or non-% macros.
1034 The bogus content is left in the syntax tree.
1035 Formatting may be poor.
1036 .It Sy "invalid Boolean argument"
1037 .Pq mdoc
1038 An
1039 .Ic \&Sm
1040 macro has an argument other than
1041 .Cm on
1042 or
1043 .Cm off .
1044 The invalid argument is moved out of the macro, which leaves the macro
1045 empty, causing it to toggle the spacing mode.
1046 .It Sy "unknown font, skipping request"
1047 .Pq man
1048 A
1049 .Xr roff 7
1050 .Ic \&ft
1051 request has an invalid argument.
1052 .El
1053 .Ss "Warnings related to plain text"
1054 .Bl -ohang
1055 .It Sy "blank line in fill mode, using .sp"
1056 .Pq mdoc
1057 The meaning of blank input lines is only well-defined in non-fill mode:
1058 In fill mode, line breaks of text input lines are not supposed to be
1059 significant.
1060 However, for compatibility with groff, blank lines in fill mode
1061 are replaced with
1062 .Ic \&sp
1063 requests.
1064 .It Sy "tab in filled text"
1065 .Pq mdoc , man
1066 The meaning of tab characters is only well-defined in non-fill mode:
1067 In fill mode, whitespace is not supposed to be significant
1068 on text input lines.
1069 As an implementation dependent choice, tab characters on text lines
1070 are passed through to the formatters in any case.
1071 Given that the text before the tab character will be filled,
1072 it is hard to predict which tab stop position the tab will advance to.
1073 .It Sy "whitespace at end of input line"
1074 .Pq mdoc , man , roff
1075 Whitespace at the end of input lines is almost never semantically
1076 significant \(em but in the odd case where it might be, it is
1077 extremely confusing when reviewing and maintaining documents.
1078 .It Sy "bad comment style"
1079 .Pq roff
1080 Comment lines start with a dot, a backslash, and a double-quote character.
1081 The
1082 .Nm
1083 utility treats the line as a comment line even without the backslash,
1084 but leaving out the backslash might not be portable.
1085 .It Sy "invalid escape sequence"
1086 .Pq roff
1087 An escape sequence has an invalid opening argument delimiter, lacks the
1088 closing argument delimiter, or the argument has too few characters.
1089 If the argument is incomplete,
1090 .Ic \e*
1091 and
1092 .Ic \en
1093 expand to an empty string,
1094 .Ic \eB
1095 to the digit
1096 .Sq 0 ,
1097 and
1098 .Ic \ew
1099 to the length of the incomplete argument.
1100 All other invalid escape sequences are ignored.
1101 .It Sy "undefined string, using \(dq\(dq"
1102 .Pq roff
1103 If a string is used without being defined before,
1104 its value is implicitly set to the empty string.
1105 However, defining strings explicitly before use
1106 keeps the code more readable.
1107 .El
1108 .Ss "Errors related to equations"
1109 .Bl -inset -compact
1110 .It "unexpected equation scope closure"
1111 .It "equation scope open on exit"
1112 .It "overlapping equation scopes"
1113 .It "unexpected end of equation"
1114 .It "equation syntax error"
1115 .El
1116 .Ss "Errors related to tables"
1117 .Bl -inset -compact
1118 .It "bad table syntax"
1119 .It "bad table option"
1120 .It "bad table layout"
1121 .It "no table layout cells specified"
1122 .It "no table data cells specified"
1123 .It "ignore data in cell"
1124 .It "data block still open"
1125 .It "ignoring extra data cells"
1126 .El
1127 .Ss "Errors related to roff, mdoc, and man code"
1128 .Bl -ohang
1129 .It Sy "input stack limit exceeded, infinite loop?"
1130 .Pq roff
1131 Explicit recursion limits are implemented for the following features,
1132 in order to prevent infinite loops:
1133 .Bl -dash -compact
1134 .It
1135 expansion of nested escape sequences
1136 including expansion of strings and number registers,
1137 .It
1138 expansion of nested user-defined macros,
1139 .It
1140 and
1141 .Ic \&so
1142 file inclusion.
1143 .El
1144 When a limit is hit, the output is incorrect, typically losing
1145 some content, but the parser can continue.
1146 .It Sy "skipping bad character"
1147 .Pq mdoc , man , roff
1148 The input file contains a byte that is not a printable
1149 .Xr ascii 7
1150 character.
1151 The message mentions the character number.
1152 The offending byte is replaced with a question mark
1153 .Pq Sq \&? .
1154 Consider editing the input file to replace the byte with an ASCII
1155 transliteration of the intended character.
1156 .It Sy "skipping unknown macro"
1157 .Pq mdoc , man , roff
1158 The first identifier on a request or macro line is neither recognized as a
1159 .Xr roff 7
1160 request, nor as a user-defined macro, nor, respectively, as an
1161 .Xr mdoc 7
1162 or
1163 .Xr man 7
1164 macro.
1165 It may be mistyped or unsupported.
1166 The request or macro is discarded including its arguments.
1167 .It Sy "skipping item outside list"
1168 .Pq mdoc
1169 An
1170 .Ic \&It
1171 macro occurs outside any
1172 .Ic \&Bl
1173 list.
1174 It is discarded including its arguments.
1175 .It Sy "skipping column outside column list"
1176 .Pq mdoc
1177 A
1178 .Ic \&Ta
1179 macro occurs outside any
1180 .Ic \&Bl Fl column
1181 block.
1182 It is discarded including its arguments.
1183 .It Sy "skipping end of block that is not open"
1184 .Pq mdoc , man , eqn , tbl , roff
1185 Various syntax elements can only be used to explicitly close blocks
1186 that have previously been opened.
1187 An
1188 .Xr mdoc 7
1189 block closing macro, a
1190 .Xr man 7
1191 .Ic \&RE
1192 or
1193 .Ic \&UE
1194 macro, or the end of an equation, table, or
1195 .Xr roff 7
1196 conditional request is encountered but no matching block is open.
1197 The offending request or macro is discarded.
1198 .It Sy "inserting missing end of block"
1199 .Pq mdoc , tbl
1200 Various
1201 .Xr mdoc 7
1202 macros as well as tables require explicit closing by dedicated macros.
1203 A block that doesn't support bad nesting
1204 ends before all of its children are properly closed.
1205 The open child nodes are closed implicitly.
1206 .It Sy "scope open on exit"
1207 .Pq mdoc , man , eqn , tbl , roff
1208 At the end of the document, an explicit
1209 .Xr mdoc 7
1210 block, a
1211 .Xr man 7
1212 next-line scope or
1213 .Ic \&RS
1214 or
1215 .Ic \&UR
1216 block, an equation, table, or
1217 .Xr roff 7
1218 conditional or ignore block is still open.
1219 The open block is closed implicitly.
1220 .It Sy "escaped character not allowed in a name"
1221 .Pq roff
1222 Macro, string and register identifiers consist of printable,
1223 non-whitespace ASCII characters.
1224 Escape sequences and characters and strings expressed in terms of them
1225 cannot form part of a name.
1226 The first argument of an
1227 .Ic \&am ,
1228 .Ic \&as ,
1229 .Ic \&de ,
1230 .Ic \&ds ,
1231 .Ic \&nr ,
1232 or
1233 .Ic \&rr
1234 request, or any argument of an
1235 .Ic \&rm
1236 request, or the name of a request or user defined macro being called,
1237 is terminated by an escape sequence.
1238 In the cases of
1239 .Ic \&as ,
1240 .Ic \&ds ,
1241 and
1242 .Ic \&nr ,
1243 the request has no effect at all.
1244 In the cases of
1245 .Ic \&am ,
1246 .Ic \&de ,
1247 .Ic \&rr ,
1248 and
1249 .Ic \&rm ,
1250 what was parsed up to this point is used as the arguments to the request,
1251 and the rest of the input line is discarded including the escape sequence.
1252 When parsing for a request or a user-defined macro name to be called,
1253 only the escape sequence is discarded.
1254 The characters preceding it are used as the request or macro name,
1255 the characters following it are used as the arguments to the request or macro.
1256 .It Sy "argument count wrong"
1257 .Pq mdoc , man , roff
1258 The indicated request or macro has too few or too many arguments.
1259 The syntax tree will contain the wrong number of arguments as given.
1260 Formatting behaviour depends on the specific request or macro in question.
1261 Note that the same message may also occur as a WARNING, see above.
1262 .It Sy "missing list type, using -item"
1263 .Pq mdoc
1264 A
1265 .Ic \&Bl
1266 macro fails to specify the list type.
1267 .It Sy "missing manual name, using \(dq\(dq"
1268 .Pq mdoc
1269 The first call to
1270 .Ic \&Nm
1271 lacks the required argument.
1272 .It Sy "uname(3) system call failed, using UNKNOWN"
1273 .Pq mdoc
1274 The
1275 .Ic \&Os
1276 macro is called without arguments, and the
1277 .Xr uname 3
1278 system call failed.
1279 As a workaround,
1280 .Nm
1281 can be compiled with
1282 .Sm off
1283 .Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq .
1284 .Sm on
1285 .It Sy "unknown standard specifier"
1286 .Pq mdoc
1287 An
1288 .Ic \&St
1289 macro has an unknown argument and is discarded.
1290 .It Sy "skipping request without numeric argument"
1291 .Pq roff
1292 An
1293 .Ic \&it
1294 request has a non-numeric or negative argument or no argument at all.
1295 The invalid request is ignored.
1296 .It Sy "skipping all arguments"
1297 .Pq mdoc , man , eqn , roff
1298 An
1299 .Xr mdoc 7
1300 .Ic \&Bt ,
1301 .Ic \&Ed ,
1302 .Ic \&Ef ,
1303 .Ic \&Ek ,
1304 .Ic \&El ,
1305 .Ic \&Re ,
1306 or
1307 .Ic \&Ud
1308 macro, an
1309 .Ic \&It
1310 macro in a list that don't support item heads, a
1311 .Xr man 7
1312 .Ic \&LP ,
1313 .Ic \&P ,
1314 or
1315 .Ic \&PP
1316 macro, an
1317 .Xr eqn 7
1318 .Ic \&EN
1319 macro, or a
1320 .Xr roff 7
1321 .Sq \&..
1322 block closing request is invoked with at least one argument.
1323 All arguments are ignored.
1324 .It Sy "skipping excess arguments"
1325 .Pq mdoc , roff
1326 The
1327 .Ic \&Bf
1328 macro is invoked with more than one argument, or a request of the
1329 .Ic \&de
1330 family is invoked with more than two arguments.
1331 The excess arguments are ignored.
1332 .El
1333 .Ss FATAL errors
1334 .Bl -ohang
1335 .It Sy "input too large"
1336 .Pq mdoc , man
1337 Currently,
1338 .Nm
1339 cannot handle input files larger than its arbitrary size limit
1340 of 2^31 bytes (2 Gigabytes).
1341 Since useful manuals are always small, this is not a problem in practice.
1342 Parsing is aborted as soon as the condition is detected.
1343 .It Sy "NOT IMPLEMENTED: Bd -file"
1344 .Pq mdoc
1345 For security reasons, the
1346 .Ic \&Bd
1347 macro does not support the
1348 .Fl file
1349 argument.
1350 By requesting the inclusion of a sensitive file, a malicious document
1351 might otherwise trick a privileged user into inadvertently displaying
1352 the file on the screen, revealing the file content to bystanders.
1353 The parser exits immediately.
1354 .It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq"
1355 .Pq roff
1356 For security reasons,
1357 .Nm
1358 allows
1359 .Ic \&so
1360 file inclusion requests only with relative paths
1361 and only without ascending to any parent directory.
1362 By requesting the inclusion of a sensitive file, a malicious document
1363 might otherwise trick a privileged user into inadvertently displaying
1364 the file on the screen, revealing the file content to bystanders.
1365 The parser exits immediately.
1366 .It Sy ".so request failed"
1367 .Pq roff
1368 Servicing a
1369 .Ic \&so
1370 request requires reading an external file.
1371 While trying to do so, an
1372 .Xr open 2 ,
1373 .Xr stat 2 ,
1374 or
1375 .Xr read 2
1376 system call failed.
1377 The parser exits immediately.
1378 Before showing this message,
1379 .Nm
1380 always shows another message explaining why the system call failed.
1381 .El
1382 .Sh COMPATIBILITY
1383 This section summarises
1384 .Nm
1385 compatibility with GNU troff.
1386 Each input and output format is separately noted.
1387 .Ss ASCII Compatibility
1388 .Bl -bullet -compact
1389 .It
1390 Unrenderable unicode codepoints specified with
1391 .Sq \e[uNNNN]
1392 escapes are printed as
1393 .Sq \&?
1394 in mandoc.
1395 In GNU troff, these raise an error.
1396 .It
1397 The
1398 .Sq \&Bd \-literal
1399 and
1400 .Sq \&Bd \-unfilled
1401 macros of
1402 .Xr mdoc 7
1403 in
1404 .Fl T Ns Cm ascii
1405 are synonyms, as are \-filled and \-ragged.
1406 .It
1407 In historic GNU troff, the
1408 .Sq \&Pa
1409 .Xr mdoc 7
1410 macro does not underline when scoped under an
1411 .Sq \&It
1412 in the FILES section.
1413 This behaves correctly in
1414 .Nm .
1415 .It
1416 A list or display following the
1417 .Sq \&Ss
1418 .Xr mdoc 7
1419 macro in
1420 .Fl T Ns Cm ascii
1421 does not assert a prior vertical break, just as it doesn't with
1422 .Sq \&Sh .
1423 .It
1424 The
1425 .Sq \&na
1426 .Xr man 7
1427 macro in
1428 .Fl T Ns Cm ascii
1429 has no effect.
1430 .It
1431 Words aren't hyphenated.
1432 .El
1433 .Ss HTML/XHTML Compatibility
1434 .Bl -bullet -compact
1435 .It
1436 The
1437 .Sq \efP
1438 escape will revert the font to the previous
1439 .Sq \ef
1440 escape, not to the last rendered decoration, which is now dictated by
1441 CSS instead of hard-coded.
1442 It also will not span past the current scope,
1443 for the same reason.
1444 Note that in
1445 .Sx ASCII Output
1446 mode, this will work fine.
1447 .It
1448 The
1449 .Xr mdoc 7
1450 .Sq \&Bl \-hang
1451 and
1452 .Sq \&Bl \-tag
1453 list types render similarly (no break following overreached left-hand
1454 side) due to the expressive constraints of HTML.
1455 .It
1456 The
1457 .Xr man 7
1458 .Sq IP
1459 and
1460 .Sq TP
1461 lists render similarly.
1462 .El
1463 .Sh SEE ALSO
1464 .Xr eqn 7 ,
1465 .Xr man 7 ,
1466 .Xr mandoc_char 7 ,
1467 .Xr mdoc 7 ,
1468 .Xr roff 7 ,
1469 .Xr tbl 7
1470 .Sh AUTHORS
1471 The
1472 .Nm
1473 utility was written by
1474 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
1475 .Sh CAVEATS
1476 In
1477 .Fl T Ns Cm html
1478 and
1479 .Fl T Ns Cm xhtml ,
1480 the maximum size of an element attribute is determined by
1481 .Dv BUFSIZ ,
1482 which is usually 1024 bytes.
1483 Be aware of this when setting long link
1484 formats such as
1485 .Fl O Ns Cm style Ns = Ns Ar really/long/link .
1486 .Pp
1487 Nesting elements within next-line element scopes of
1488 .Fl m Ns Cm an ,
1489 such as
1490 .Sq br
1491 within an empty
1492 .Sq B ,
1493 will confuse
1494 .Fl T Ns Cm html
1495 and
1496 .Fl T Ns Cm xhtml
1497 and cause them to forget the formatting of the prior next-line scope.
1498 .Pp
1499 The
1500 .Sq \(aq
1501 control character is an alias for the standard macro control character
1502 and does not emit a line-break as stipulated in GNU troff.