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