mandoc(1): Update to 1.9.20.
[dragonfly.git] / usr.bin / mandoc / mandoc.1
CommitLineData
057fa736 1.\" $Id: mandoc.1,v 1.56 2010/03/29 10:10:35 kristaps Exp $
589e7c1d
SW
2.\"
3.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
057fa736 17.Dd March 30, 2010
589e7c1d
SW
18.Dt MANDOC 1
19.Os
20.
21.
22.Sh NAME
23.Nm mandoc
24.Nd format and display UNIX manuals
25.
26.
27.Sh SYNOPSIS
b084f4c3 28.Nm
589e7c1d
SW
29.Op Fl f Ns Ar option...
30.Op Fl m Ns Ar format
cbce6d97 31.Op Fl O Ns Ar option...
589e7c1d
SW
32.Op Fl T Ns Ar output
33.Op Fl V
34.Op Fl W Ns Ar err...
35.Op Ar infile...
36.
37.
38.Sh DESCRIPTION
39The
40.Nm
41utility formats
42.Ux
43manual pages for display. The arguments are as follows:
44.
45.Bl -tag -width Ds
46.It Fl f Ns Ar option...
47Comma-separated compiler options. See
48.Sx Compiler Options
49for details.
50.
51.It Fl m Ns Ar format
52Input format. See
53.Sx Input Formats
54for available formats. Defaults to
55.Fl m Ns Ar andoc .
56.
cbce6d97 57.It Fl O Ns Ar option...
589e7c1d
SW
58Comma-separated output options. See
59.Sx Output Options
60for details.
61.
62.It Fl T Ns Ar output
63Output format. See
64.Sx Output Formats
65for available formats. Defaults to
66.Fl T Ns Ar ascii .
67.
68.It Fl V
69Print version and exit.
70.
71.It Fl W Ns Ar err...
72Comma-separated warning options. Use
73.Fl W Ns Ar all
74to print warnings,
75.Fl W Ns Ar error
76for warnings to be considered errors and cause utility
77termination. Multiple
78.Fl W
79arguments may be comma-separated, such as
80.Fl W Ns Ar error,all .
81.
82.It Ar infile...
83Read input from zero or more
84.Ar infile .
85If unspecified, reads from stdin. If multiple files are specified,
86.Nm
87will halt with the first failed parse.
88.El
89.
90.Pp
91By default,
92.Nm
93reads
94.Xr mdoc 7
95or
96.Xr man 7
97text from stdin, implying
98.Fl m Ns Ar andoc ,
4a06b3fd 99and produces
589e7c1d 100.Fl T Ns Ar ascii
4a06b3fd 101output.
589e7c1d
SW
102.
103.Pp
104.Ex -std mandoc
105.
106.
589e7c1d
SW
107.Ss Input Formats
108The
109.Nm
110utility accepts
111.Xr mdoc 7
112and
113.Xr man 7
114input with
115.Fl m Ns Ar doc
116and
117.Fl m Ns Ar an ,
118respectively. The
119.Xr mdoc 7
120format is
121.Em strongly
122recommended;
123.Xr man 7
124should only be used for legacy manuals.
125.
126.Pp
127A third option,
128.Fl m Ns Ar andoc ,
129which is also the default, determines encoding on-the-fly: if the first
130non-comment macro is
131.Sq \&Dd
132or
133.Sq \&Dt ,
134the
135.Xr mdoc 7
136parser is used; otherwise, the
137.Xr man 7
138parser is used.
139.
140.Pp
141If multiple
142files are specified with
143.Fl m Ns Ar andoc ,
144each has its file-type determined this way. If multiple files are
145specified and
146.Fl m Ns Ar doc
147or
148.Fl m Ns Ar an
149is specified, then this format is used exclusively.
150.
151.
152.Ss Output Formats
153The
154.Nm
155utility accepts the following
156.Fl T
4a06b3fd
SW
157arguments (see
158.Sx OUTPUT ) :
589e7c1d
SW
159.
160.Bl -tag -width Ds
161.It Fl T Ns Ar ascii
162Produce 7-bit ASCII output, backspace-encoded for bold and underline
4a06b3fd
SW
163styles. This is the default. See
164.Sx ASCII Output .
589e7c1d
SW
165.
166.It Fl T Ns Ar html
4a06b3fd
SW
167Produce strict HTML-4.01 output, with a sane default style. See
168.Sx HTML Output .
589e7c1d 169.
bd9525ad
SW
170.It Fl T Ns Ar xhtml
171Produce strict XHTML-1.0 output, with a sane default style. See
172.Sx XHTML Output .
173.
589e7c1d
SW
174.It Fl T Ns Ar tree
175Produce an indented parse tree.
176.
177.It Fl T Ns Ar lint
178Parse only: produce no output.
17fcb234
SW
179Implies
180.Fl W Ns Ar all
181and
182.Fl f Ns Ar strict .
589e7c1d
SW
183.El
184.
185.Pp
186If multiple input files are specified, these will be processed by the
187corresponding filter in-order.
188.
189.
190.Ss Compiler Options
191Default compiler behaviour may be overridden with the
192.Fl f
193flag.
194.
195.Bl -tag -width Ds
196.It Fl f Ns Ar ign-scope
197When rewinding the scope of a block macro, forces the compiler to ignore
198scope violations. This can seriously mangle the resulting tree.
199.Pq mdoc only
200.
0dd4f147
SW
201.It Fl f Ns Ar ign-escape
202Ignore invalid escape sequences.
203This is the default, but the option can be used to override an earlier
204.Fl f Ns Ar strict .
205.
589e7c1d
SW
206.It Fl f Ns Ar no-ign-escape
207Don't ignore invalid escape sequences.
208.
209.It Fl f Ns Ar no-ign-macro
210Do not ignore unknown macros at the start of input lines.
211.
212.It Fl f Ns Ar no-ign-chars
213Do not ignore disallowed characters.
214.
215.It Fl f Ns Ar strict
216Implies
217.Fl f Ns Ar no-ign-escape ,
218.Fl f Ns Ar no-ign-macro
219and
220.Fl f Ns Ar no-ign-chars .
221.
222.It Fl f Ns Ar ign-errors
057fa736
SW
223When parsing multiple files, don't halt when one errors out. Useful
224with
589e7c1d
SW
225.Fl T Ns Ar lint
226over a large set of manuals passed on the command line.
227.El
228.
4a06b3fd 229.
589e7c1d
SW
230.Ss Output Options
231For the time being, only
232.Fl T Ns Ar html
17fcb234
SW
233and
234.Fl T Ns Ar xhtml
4a06b3fd 235accepts output options:
589e7c1d 236.Bl -tag -width Ds
cbce6d97 237.It Fl O Ns Ar style=style.css
589e7c1d
SW
238The file
239.Ar style.css
240is used for an external style-sheet. This must be a valid absolute or
241relative URI.
cbce6d97 242.It Fl O Ns Ar includes=fmt
589e7c1d
SW
243The string
244.Ar fmt ,
245for example,
246.Ar ../src/%I.html ,
247is used as a template for linked header files (usually via the
248.Sq \&In
249macro). Instances of
250.Sq \&%I
251are replaced with the include filename. The default is not to present a
252hyperlink.
cbce6d97 253.It Fl O Ns Ar man=fmt
589e7c1d
SW
254The string
255.Ar fmt ,
256for example,
257.Ar ../html%S/%N.%S.html ,
258is used as a template for linked manuals (usually via the
259.Sq \&Xr
260macro). Instances of
261.Sq \&%N
262and
263.Sq %S
264are replaced with the linked manual's name and section, respectively.
265If no section is included, section 1 is assumed. The default is not to
266present a hyperlink.
267.El
268.
4a06b3fd
SW
269.
270.Sh OUTPUT
271This section documents output details of
272.Nm .
273In general, output conforms to the traditional manual style of a header,
274a body composed of sections and sub-sections, and a footer.
275.Pp
276The text style of output characters (non-macro characters, punctuation,
277and white-space) is dictated by context.
278.Pp
279White-space is generally stripped from input. This can be changed with
280character escapes (specified in
281.Xr mandoc_char 7 )
282or literal modes (specified in
283.Xr mdoc 7
284and
285.Xr man 7 ) .
286.Pp
287If non-macro punctuation is set apart from words, such as in the phrase
288.Dq to be \&, or not to be ,
289it's processed by
290.Nm ,
291regardless of output format, according to the following rules: opening
292punctuation
293.Po
294.Sq \&( ,
295.Sq \&[ ,
296and
297.Sq \&{
298.Pc
299is not followed by a space; closing punctuation
300.Po
301.Sq \&. ,
302.Sq \&, ,
303.Sq \&; ,
304.Sq \&: ,
305.Sq \&? ,
306.Sq \&! ,
307.Sq \&) ,
308.Sq \&]
309and
310.Sq \&}
311.Pc
312is not preceded by white-space.
313.
314.Pp
315If the input is
316.Xr mdoc 7 ,
317however, these rules are also applied to macro arguments when appropriate.
318.
319.
320.Ss ASCII Output
321Output produced by
322.Fl T Ns Ar ascii ,
323which is the default, is rendered in standard 7-bit ASCII documented in
324.Xr ascii 7 .
325.Pp
326Font styles are applied by using back-spaced encoding such that an
327underlined character
328.Sq c
329is rendered as
330.Sq _ Ns \e[bs] Ns c ,
331where
332.Sq \e[bs]
333is the back-space character number 8. Emboldened characters are rendered as
334.Sq c Ns \e[bs] Ns c .
335.Pp
336The special characters documented in
337.Xr mandoc_char 7
338are rendered best-effort in an ASCII equivalent.
339.Pp
340Output width is limited to 78 visible columns unless literal input lines
341exceed this limit.
342.
343.
344.Ss HTML Output
345Output produced by
346.Fl T Ns Ar html
bd9525ad 347conforms to HTML-4.01 strict.
4a06b3fd
SW
348.Pp
349Font styles and page structure are applied using CSS2. By default, no
350font style is applied to any text, although CSS2 is hard-coded to format
351the basic structure of output.
352.Pp
353The
354.Pa example.style.css
355file documents the range of styles applied to output and, if used, will
356cause rendered documents to appear as they do in
357.Fl T Ns Ar ascii .
358.Pp
359Special characters are rendered in decimal-encoded UTF-8.
360.
361.
bd9525ad
SW
362.Ss XHTML Output
363Output produced by
364.Fl T Ns Ar xhtml
365conforms to XHTML-1.0 strict.
366.Pp
367See
368.Sx HTML Output
369for details; beyond generating XHTML tags instead of HTML tags, these
370output modes are identical.
371.
372.
589e7c1d
SW
373.Sh EXAMPLES
374To page manuals to the terminal:
375.
376.Pp
377.D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
378.D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
379.
380.Pp
381To produce HTML manuals with
382.Ar style.css
383as the style-sheet:
384.Pp
4a06b3fd 385.D1 % mandoc \-Thtml -Ostyle=style.css mdoc.7 > mdoc.7.html
589e7c1d
SW
386.Pp
387To check over a large set of manuals:
388.
389.Pp
390.Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
391.
392.
393.Sh COMPATIBILITY
394This section summarises
395.Nm
396compatibility with
397.Xr groff 1 .
398Each input and output format is separately noted.
399.
400.
4a06b3fd 401.Ss ASCII Compatibility
589e7c1d
SW
402.Bl -bullet -compact
403.It
404The
405.Sq \e~
406special character doesn't produce expected behaviour in
407.Fl T Ns Ar ascii .
408.
409.It
410The
411.Sq \&Bd \-literal
412and
413.Sq \&Bd \-unfilled
414macros of
415.Xr mdoc 7
416in
417.Fl T Ns Ar ascii
418are synonyms, as are \-filled and \-ragged.
419.
420.It
421In
422.Xr groff 1 ,
423the
424.Sq \&Pa
425.Xr mdoc 7
426macro does not underline when scoped under an
427.Sq \&It
428in the FILES section. This behaves correctly in
429.Nm .
430.
431.It
432A list or display following
433.Sq \&Ss
434.Xr mdoc 7
435macro in
436.Fl T Ns Ar ascii
437does not assert a prior vertical break, just as it doesn't with
438.Sq \&Sh .
439.
440.It
441The
442.Sq \&na
443.Xr man 7
444macro in
445.Fl T Ns Ar ascii
446has no effect.
447.
448.It
449Words aren't hyphenated.
450.
451.It
452In normal mode (not a literal block), blocks of spaces aren't preserved,
453so double spaces following sentence closure are reduced to a single space;
454.Xr groff 1
455retains spaces.
456.
457.It
458Sentences are unilaterally monospaced.
459.El
460.
4a06b3fd 461.
bd9525ad 462.Ss HTML/XHTML Compatibility
589e7c1d
SW
463.Bl -bullet -compact
464.It
465The
4a06b3fd
SW
466.Sq \efP
467escape will revert the font to the previous
468.Sq \ef
469escape, not to the last rendered decoration, which is now dictated by
470CSS instead of hard-coded. It also will not span past the current
471scope, for the same reason. Note that in
472.Sx ASCII Output
473mode, this will work fine.
474.It
475The
589e7c1d
SW
476.Xr mdoc 7
477.Sq \&Bl \-hang
478and
479.Sq \&Bl \-tag
480list types render similarly (no break following overreached left-hand
481side) due to the expressive constraints of HTML.
482.
483.It
484The
485.Xr man 7
486.Sq IP
487and
488.Sq TP
489lists render similarly.
490.El
4a06b3fd
SW
491.
492.
589e7c1d 493.Sh SEE ALSO
45b74f6e 494.Xr man 7 ,
589e7c1d 495.Xr mandoc_char 7 ,
45b74f6e 496.Xr mdoc 7
589e7c1d
SW
497.
498.Sh AUTHORS
499The
500.Nm
501utility was written by
502.An Kristaps Dzonsons Aq kristaps@kth.se .
503.
4a06b3fd 504.
589e7c1d 505.Sh CAVEATS
4a06b3fd
SW
506The
507.Fl T Ns Ar html
bd9525ad
SW
508and
509.Fl T Ns Ar xhtml
4a06b3fd
SW
510CSS2 styling used for
511.Fl m Ns Ar doc
17fcb234
SW
512input lists does not render properly in older browsers, such as Internet
513Explorer 6 and earlier.
514.
4a06b3fd 515.Pp
589e7c1d 516In
bd9525ad
SW
517.Fl T Ns Ar html
518and
519.Fl T Ns Ar xhtml ,
589e7c1d
SW
520the maximum size of an element attribute is determined by
521.Dv BUFSIZ ,
522which is usually 1024 bytes. Be aware of this when setting long link
4a06b3fd
SW
523formats, e.g.,
524.Fl O Ns Ar style=really/long/link .
17fcb234 525.
4a06b3fd
SW
526.Pp
527The
528.Fl T Ns Ar html
bd9525ad
SW
529and
530.Fl T Ns Ar xhtml
531output modes don't render the
4a06b3fd
SW
532.Sq \es
533font size escape documented in
534.Xr mdoc 7
535and
536.Xr man 7 .
17fcb234
SW
537.
538.Pp
539Nesting elements within next-line element scopes of
540.Fl m Ns Ar an ,
541such as
542.Sq br
543within an empty
544.Sq B ,
545will confuse
546.Fl T Ns Ar html
547and
548.Fl T Ns Ar xhtml
549and cause them to forget the formatting of the prior next-line scope.
550.
551.Pp
552The
553.Sq i
554macro in
555.Fl m Ns Ar an
556should italicise all subsequent text if a line argument is not provided.
557This behaviour is not implemented.
558.
559The
560.Sq \(aq
561control character is an alias for the standard macro control character
562and does not emit a line-break as stipulated in GNU troff.