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