| blob | 7cb90793e2798ad3ed4b78d1a7a4b14e89cbe699 |
1 .\" $Vendor-Id: mandoc.1,v 1.48 2009/11/16 09:52:47 kristaps 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 $Mdocdate$
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 produces
100 .Fl T Ns Ar ascii
101 output.
102 .
103 .Pp
104 .Ex -std mandoc
105 .
106 .
107 .Ss Input Formats
108 The
109 .Nm
110 utility accepts
111 .Xr mdoc 7
112 and
113 .Xr man 7
114 input with
115 .Fl m Ns Ar doc
116 and
117 .Fl m Ns Ar an ,
118 respectively. The
119 .Xr mdoc 7
120 format is
121 .Em strongly
122 recommended;
123 .Xr man 7
124 should only be used for legacy manuals.
125 .
126 .Pp
127 A third option,
128 .Fl m Ns Ar andoc ,
129 which is also the default, determines encoding on-the-fly: if the first
130 non-comment macro is
131 .Sq \&Dd
132 or
133 .Sq \&Dt ,
134 the
135 .Xr mdoc 7
136 parser is used; otherwise, the
137 .Xr man 7
138 parser is used.
139 .
140 .Pp
141 If multiple
142 files are specified with
143 .Fl m Ns Ar andoc ,
144 each has its file-type determined this way. If multiple files are
145 specified and
146 .Fl m Ns Ar doc
147 or
148 .Fl m Ns Ar an
149 is specified, then this format is used exclusively.
150 .
151 .
152 .Ss Output Formats
153 The
154 .Nm
155 utility accepts the following
156 .Fl T
157 arguments (see
158 .Sx OUTPUT ) :
159 .
160 .Bl -tag -width Ds
161 .It Fl T Ns Ar ascii
162 Produce 7-bit ASCII output, backspace-encoded for bold and underline
163 styles. This is the default. See
164 .Sx ASCII Output .
165 .
166 .It Fl T Ns Ar html
167 Produce strict HTML-4.01 output, with a sane default style. See
168 .Sx HTML Output .
169 .
170 .It Fl T Ns Ar tree
171 Produce an indented parse tree.
172 .
173 .It Fl T Ns Ar lint
174 Parse only: produce no output.
175 .El
176 .
177 .Pp
178 If multiple input files are specified, these will be processed by the
179 corresponding filter in-order.
180 .
181 .
182 .Ss Compiler Options
183 Default compiler behaviour may be overridden with the
184 .Fl f
185 flag.
186 .
187 .Bl -tag -width Ds
188 .It Fl f Ns Ar ign-scope
189 When rewinding the scope of a block macro, forces the compiler to ignore
190 scope violations. This can seriously mangle the resulting tree.
191 .Pq mdoc only
192 .
193 .It Fl f Ns Ar ign-escape
194 Ignore invalid escape sequences.
195 This is the default, but the option can be used to override an earlier
196 .Fl f Ns Ar strict .
197 .
198 .It Fl f Ns Ar no-ign-escape
199 Don't ignore invalid escape sequences.
200 .
201 .It Fl f Ns Ar no-ign-macro
202 Do not ignore unknown macros at the start of input lines.
203 .
204 .It Fl f Ns Ar no-ign-chars
205 Do not ignore disallowed characters.
206 .
207 .It Fl f Ns Ar strict
208 Implies
209 .Fl f Ns Ar no-ign-escape ,
210 .Fl f Ns Ar no-ign-macro
211 and
212 .Fl f Ns Ar no-ign-chars .
213 .
214 .It Fl f Ns Ar ign-errors
215 Don't halt when encountering parse errors. Useful with
216 .Fl T Ns Ar lint
217 over a large set of manuals passed on the command line.
218 .El
219 .
220 .
221 .Ss Output Options
222 For the time being, only
223 .Fl T Ns Ar html
224 accepts output options:
225 .Bl -tag -width Ds
226 .It Fl O Ns Ar style=style.css
227 The file
228 .Ar style.css
229 is used for an external style-sheet. This must be a valid absolute or
230 relative URI.
231 .It Fl O Ns Ar includes=fmt
232 The string
233 .Ar fmt ,
234 for example,
235 .Ar ../src/%I.html ,
236 is used as a template for linked header files (usually via the
237 .Sq \&In
238 macro). Instances of
239 .Sq \&%I
240 are replaced with the include filename. The default is not to present a
241 hyperlink.
242 .It Fl O Ns Ar man=fmt
243 The string
244 .Ar fmt ,
245 for example,
246 .Ar ../html%S/%N.%S.html ,
247 is used as a template for linked manuals (usually via the
248 .Sq \&Xr
249 macro). Instances of
250 .Sq \&%N
251 and
252 .Sq %S
253 are replaced with the linked manual's name and section, respectively.
254 If no section is included, section 1 is assumed. The default is not to
255 present a hyperlink.
256 .El
257 .
258 .
259 .Sh OUTPUT
260 This section documents output details of
261 .Nm .
262 In general, output conforms to the traditional manual style of a header,
263 a body composed of sections and sub-sections, and a footer.
264 .Pp
265 The text style of output characters (non-macro characters, punctuation,
266 and white-space) is dictated by context.
267 .Pp
268 White-space is generally stripped from input. This can be changed with
269 character escapes (specified in
270 .Xr mandoc_char 7 )
271 or literal modes (specified in
272 .Xr mdoc 7
273 and
274 .Xr man 7 ) .
275 .Pp
276 If non-macro punctuation is set apart from words, such as in the phrase
277 .Dq to be \&, or not to be ,
278 it's processed by
279 .Nm ,
280 regardless of output format, according to the following rules: opening
281 punctuation
282 .Po
283 .Sq \&( ,
284 .Sq \&[ ,
285 and
286 .Sq \&{
287 .Pc
288 is not followed by a space; closing punctuation
289 .Po
290 .Sq \&. ,
291 .Sq \&, ,
292 .Sq \&; ,
293 .Sq \&: ,
294 .Sq \&? ,
295 .Sq \&! ,
296 .Sq \&) ,
297 .Sq \&]
298 and
299 .Sq \&}
300 .Pc
301 is not preceded by white-space.
302 .
303 .Pp
304 If the input is
305 .Xr mdoc 7 ,
306 however, these rules are also applied to macro arguments when appropriate.
307 .
308 .
309 .Ss ASCII Output
310 Output produced by
311 .Fl T Ns Ar ascii ,
312 which is the default, is rendered in standard 7-bit ASCII documented in
313 .Xr ascii 7 .
314 .Pp
315 Font styles are applied by using back-spaced encoding such that an
316 underlined character
317 .Sq c
318 is rendered as
319 .Sq _ Ns \e[bs] Ns c ,
320 where
321 .Sq \e[bs]
322 is the back-space character number 8. Emboldened characters are rendered as
323 .Sq c Ns \e[bs] Ns c .
324 .Pp
325 The special characters documented in
326 .Xr mandoc_char 7
327 are rendered best-effort in an ASCII equivalent.
328 .Pp
329 Output width is limited to 78 visible columns unless literal input lines
330 exceed this limit.
331 .
332 .
333 .Ss HTML Output
334 Output produced by
335 .Fl T Ns Ar html
336 comforms to HTML-4.01 strict.
337 .Pp
338 Font styles and page structure are applied using CSS2. By default, no
339 font style is applied to any text, although CSS2 is hard-coded to format
340 the basic structure of output.
341 .Pp
342 The
343 .Pa example.style.css
344 file documents the range of styles applied to output and, if used, will
345 cause rendered documents to appear as they do in
346 .Fl T Ns Ar ascii .
347 .Pp
348 Special characters are rendered in decimal-encoded UTF-8.
349 .
350 .
351 .Sh EXAMPLES
352 To page manuals to the terminal:
353 .
354 .Pp
355 .D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
356 .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
357 .
358 .Pp
359 To produce HTML manuals with
360 .Ar style.css
361 as the style-sheet:
362 .Pp
363 .D1 % mandoc \-Thtml -Ostyle=style.css mdoc.7 > mdoc.7.html
364 .Pp
365 To check over a large set of manuals:
366 .
367 .Pp
368 .Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
369 .
370 .
371 .Sh COMPATIBILITY
372 This section summarises
373 .Nm
374 compatibility with
375 .Xr groff 1 .
376 Each input and output format is separately noted.
377 .
378 .
379 .Ss ASCII Compatibility
380 .Bl -bullet -compact
381 .It
382 The
383 .Sq \e~
384 special character doesn't produce expected behaviour in
385 .Fl T Ns Ar ascii .
386 .
387 .It
388 The
389 .Sq \&Bd \-literal
390 and
391 .Sq \&Bd \-unfilled
392 macros of
393 .Xr mdoc 7
394 in
395 .Fl T Ns Ar ascii
396 are synonyms, as are \-filled and \-ragged.
397 .
398 .It
399 In
400 .Xr groff 1 ,
401 the
402 .Sq \&Pa
403 .Xr mdoc 7
404 macro does not underline when scoped under an
405 .Sq \&It
406 in the FILES section. This behaves correctly in
407 .Nm .
408 .
409 .It
410 A list or display following
411 .Sq \&Ss
412 .Xr mdoc 7
413 macro in
414 .Fl T Ns Ar ascii
415 does not assert a prior vertical break, just as it doesn't with
416 .Sq \&Sh .
417 .
418 .It
419 The
420 .Sq \&na
421 .Xr man 7
422 macro in
423 .Fl T Ns Ar ascii
424 has no effect.
425 .
426 .It
427 Words aren't hyphenated.
428 .
429 .It
430 In normal mode (not a literal block), blocks of spaces aren't preserved,
431 so double spaces following sentence closure are reduced to a single space;
432 .Xr groff 1
433 retains spaces.
434 .
435 .It
436 Sentences are unilaterally monospaced.
437 .El
438 .
439 .
440 .Ss HTML Compatibility
441 .Bl -bullet -compact
442 .It
443 The
444 .Sq \efP
445 escape will revert the font to the previous
446 .Sq \ef
447 escape, not to the last rendered decoration, which is now dictated by
448 CSS instead of hard-coded. It also will not span past the current
449 scope, for the same reason. Note that in
450 .Sx ASCII Output
451 mode, this will work fine.
452 .It
453 The
454 .Xr mdoc 7
455 .Sq \&Bl \-hang
456 and
457 .Sq \&Bl \-tag
458 list types render similarly (no break following overreached left-hand
459 side) due to the expressive constraints of HTML.
460 .
461 .It
462 The
463 .Xr man 7
464 .Sq IP
465 and
466 .Sq TP
467 lists render similarly.
468 .El
469 .
470 .
471 .Sh SEE ALSO
472 .Xr mandoc_char 7 ,
473 .Xr mdoc 7 ,
474 .Xr man 7
475 .
476 .Sh AUTHORS
477 The
478 .Nm
479 utility was written by
480 .An Kristaps Dzonsons Aq kristaps@kth.se .
481 .
482 .
483 .Sh CAVEATS
484 The
485 .Fl T Ns Ar html
486 CSS2 styling used for
487 .Fl m Ns Ar doc
488 input lists does not render properly in brain-dead browsers, such as
489 Internet Explorer 6 and earlier.
490 .Pp
491 In
492 .Fl T Ns Ar html ,
493 the maximum size of an element attribute is determined by
494 .Dv BUFSIZ ,
495 which is usually 1024 bytes. Be aware of this when setting long link
496 formats, e.g.,
497 .Fl O Ns Ar style=really/long/link .
498 .Pp
499 The
500 .Fl T Ns Ar html
501 output mode doesn't render the
502 .Sq \es
503 font size escape documented in
504 .Xr mdoc 7
505 and
506 .Xr man 7 .