mandoc(1): Update to 1.9.13.
[dragonfly.git] / usr.bin / mandoc / mandoc.1
CommitLineData
32c903ac 1.\" $Id: mandoc.1,v 1.45 2009/10/26 15:44:51 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.\"
32c903ac 17.Dd November 11, 2009
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
28.Nm mandoc
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 ,
99and prints 78-column backspace-encoded output to stdout as if
100.Fl T Ns Ar ascii
101were provided.
102.
103.Pp
104.Ex -std mandoc
105.
106.
107.Ss Punctuation and Spacing
108If punctuation is set apart from words, such as in the phrase
109.Dq to be \&, or not to be ,
110it's processed by
111.Nm
112according to the following rules: opening punctuation
113.Po
114.Sq \&( ,
115.Sq \&[ ,
116and
117.Sq \&{
118.Pc
119is not followed by a space; closing punctuation
120.Po
121.Sq \&. ,
122.Sq \&, ,
123.Sq \&; ,
124.Sq \&: ,
125.Sq \&? ,
126.Sq \&! ,
127.Sq \&) ,
128.Sq \&]
129and
130.Sq \&}
131.Pc
132is not preceded by whitespace.
133.
134.Pp
135If the input is
136.Xr mdoc 7 ,
137these rules are also applied to macro arguments when appropriate.
138.
139.Pp
140White-space, in non-literal (normal) mode, is stripped from input and
141replaced on output by a single space. Thus, if you wish to preserve multiple
142spaces, they must be space-escaped or used in a literal display mode, e.g.,
143.Sq \&Bd \-literal
144in
145.Xr mdoc 7 .
146.
147.
148.Ss Input Formats
149The
150.Nm
151utility accepts
152.Xr mdoc 7
153and
154.Xr man 7
155input with
156.Fl m Ns Ar doc
157and
158.Fl m Ns Ar an ,
159respectively. The
160.Xr mdoc 7
161format is
162.Em strongly
163recommended;
164.Xr man 7
165should only be used for legacy manuals.
166.
167.Pp
168A third option,
169.Fl m Ns Ar andoc ,
170which is also the default, determines encoding on-the-fly: if the first
171non-comment macro is
172.Sq \&Dd
173or
174.Sq \&Dt ,
175the
176.Xr mdoc 7
177parser is used; otherwise, the
178.Xr man 7
179parser is used.
180.
181.Pp
182If multiple
183files are specified with
184.Fl m Ns Ar andoc ,
185each has its file-type determined this way. If multiple files are
186specified and
187.Fl m Ns Ar doc
188or
189.Fl m Ns Ar an
190is specified, then this format is used exclusively.
191.
192.
193.Ss Output Formats
194The
195.Nm
196utility accepts the following
197.Fl T
198arguments:
199.
200.Bl -tag -width Ds
201.It Fl T Ns Ar ascii
202Produce 7-bit ASCII output, backspace-encoded for bold and underline
203styles. This is the default.
204.
205.It Fl T Ns Ar html
206Produce strict HTML-4.01 output, with a sane default style.
207.
208.It Fl T Ns Ar tree
209Produce an indented parse tree.
210.
211.It Fl T Ns Ar lint
212Parse only: produce no output.
213.El
214.
215.Pp
216If multiple input files are specified, these will be processed by the
217corresponding filter in-order.
218.
219.
220.Ss Compiler Options
221Default compiler behaviour may be overridden with the
222.Fl f
223flag.
224.
225.Bl -tag -width Ds
226.It Fl f Ns Ar ign-scope
227When rewinding the scope of a block macro, forces the compiler to ignore
228scope violations. This can seriously mangle the resulting tree.
229.Pq mdoc only
230.
32c903ac
SW
231.It Fl f Ns Ar ign-escape
232Ignore invalid escape sequences.
233This is the default, but the option can be used to override an earlier
234.Fl f Ns Ar strict .
235.
589e7c1d
SW
236.It Fl f Ns Ar no-ign-escape
237Don't ignore invalid escape sequences.
238.
239.It Fl f Ns Ar no-ign-macro
240Do not ignore unknown macros at the start of input lines.
241.
242.It Fl f Ns Ar no-ign-chars
243Do not ignore disallowed characters.
244.
245.It Fl f Ns Ar strict
246Implies
247.Fl f Ns Ar no-ign-escape ,
248.Fl f Ns Ar no-ign-macro
249and
250.Fl f Ns Ar no-ign-chars .
251.
252.It Fl f Ns Ar ign-errors
253Don't halt when encountering parse errors. Useful with
254.Fl T Ns Ar lint
255over a large set of manuals passed on the command line.
256.El
257.
258.Ss Output Options
259For the time being, only
260.Fl T Ns Ar html
261is the only mode with output options:
262.Bl -tag -width Ds
cbce6d97 263.It Fl O Ns Ar style=style.css
589e7c1d
SW
264The file
265.Ar style.css
266is used for an external style-sheet. This must be a valid absolute or
267relative URI.
cbce6d97 268.It Fl O Ns Ar includes=fmt
589e7c1d
SW
269The string
270.Ar fmt ,
271for example,
272.Ar ../src/%I.html ,
273is used as a template for linked header files (usually via the
274.Sq \&In
275macro). Instances of
276.Sq \&%I
277are replaced with the include filename. The default is not to present a
278hyperlink.
cbce6d97 279.It Fl O Ns Ar man=fmt
589e7c1d
SW
280The string
281.Ar fmt ,
282for example,
283.Ar ../html%S/%N.%S.html ,
284is used as a template for linked manuals (usually via the
285.Sq \&Xr
286macro). Instances of
287.Sq \&%N
288and
289.Sq %S
290are replaced with the linked manual's name and section, respectively.
291If no section is included, section 1 is assumed. The default is not to
292present a hyperlink.
293.El
294.
295.Sh EXAMPLES
296To page manuals to the terminal:
297.
298.Pp
299.D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
300.D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
301.
302.Pp
303To produce HTML manuals with
304.Ar style.css
305as the style-sheet:
306.Pp
307.D1 % mandoc \-Thtml -ostyle=style.css mdoc.7 > mdoc.7.html
308.Pp
309To check over a large set of manuals:
310.
311.Pp
312.Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
313.
314.
315.Sh COMPATIBILITY
316This section summarises
317.Nm
318compatibility with
319.Xr groff 1 .
320Each input and output format is separately noted.
321.
322.
323.Ss ASCII output
324.Bl -bullet -compact
325.It
326The
327.Sq \e~
328special character doesn't produce expected behaviour in
329.Fl T Ns Ar ascii .
330.
331.It
332The
333.Sq \&Bd \-literal
334and
335.Sq \&Bd \-unfilled
336macros of
337.Xr mdoc 7
338in
339.Fl T Ns Ar ascii
340are synonyms, as are \-filled and \-ragged.
341.
342.It
343In
344.Xr groff 1 ,
345the
346.Sq \&Pa
347.Xr mdoc 7
348macro does not underline when scoped under an
349.Sq \&It
350in the FILES section. This behaves correctly in
351.Nm .
352.
353.It
354A list or display following
355.Sq \&Ss
356.Xr mdoc 7
357macro in
358.Fl T Ns Ar ascii
359does not assert a prior vertical break, just as it doesn't with
360.Sq \&Sh .
361.
362.It
363The
364.Sq \&na
365.Xr man 7
366macro in
367.Fl T Ns Ar ascii
368has no effect.
369.
370.It
371Words aren't hyphenated.
372.
373.It
374In normal mode (not a literal block), blocks of spaces aren't preserved,
375so double spaces following sentence closure are reduced to a single space;
376.Xr groff 1
377retains spaces.
378.
379.It
380Sentences are unilaterally monospaced.
381.El
382.
383.Ss HTML output
384.Bl -bullet -compact
385.It
386The
387.Xr mdoc 7
388.Sq \&Bl \-hang
389and
390.Sq \&Bl \-tag
391list types render similarly (no break following overreached left-hand
392side) due to the expressive constraints of HTML.
393.
394.It
395The
396.Xr man 7
397.Sq IP
398and
399.Sq TP
400lists render similarly.
401.El
402.\" SECTION
403.Sh SEE ALSO
404.Xr mandoc_char 7 ,
405.Xr mdoc 7 ,
406.Xr man 7
407.
408.Sh AUTHORS
409The
410.Nm
411utility was written by
412.An Kristaps Dzonsons Aq kristaps@kth.se .
413.
414.Sh CAVEATS
415In
416.Fl T Ns Ar html ,
417the maximum size of an element attribute is determined by
418.Dv BUFSIZ ,
419which is usually 1024 bytes. Be aware of this when setting long link
420formats with
cbce6d97 421.Fl O Ns Ar man=fmt .