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