843f3d738c56537eb5bbea6c51870200bc636ef0
[dragonfly.git] / contrib / mdocml / mandoc.1
1 .\"     $Id: mandoc.1,v 1.84 2011/01/04 23:32:21 kristaps Exp $
2 .\"
3 .\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
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: January 4 2011 $
18 .Dt MANDOC 1
19 .Os
20 .Sh NAME
21 .Nm mandoc
22 .Nd format and display UNIX manuals
23 .Sh SYNOPSIS
24 .Nm mandoc
25 .Op Fl V
26 .Op Fl m Ns Ar format
27 .Op Fl O Ns Ar option
28 .Op Fl T Ns Ar output
29 .Op Fl W Ns Ar level
30 .Op Ar file...
31 .Sh DESCRIPTION
32 The
33 .Nm
34 utility formats
35 .Ux
36 manual pages for display.
37 The arguments are as follows:
38 .Bl -tag -width Ds
39 .It Fl m Ns Ar format
40 Input format.
41 See
42 .Sx Input Formats
43 for available formats.
44 Defaults to
45 .Fl m Ns Cm andoc .
46 .It Fl O Ns Ar option
47 Comma-separated output options.
48 .It Fl T Ns Ar output
49 Output format.
50 See
51 .Sx Output Formats
52 for available formats.
53 Defaults to
54 .Fl T Ns Cm ascii .
55 .It Fl V
56 Print version and exit.
57 .It Fl W Ns Ar level
58 Specify the minimum message
59 .Ar level
60 to be reported on the standard error output and to affect the exit status.
61 The
62 .Ar level
63 can be
64 .Cm warning ,
65 .Cm error ,
66 or
67 .Cm fatal .
68 The default is
69 .Fl W Ns Cm fatal ;
70 .Fl W Ns Cm all
71 is an alias for
72 .Fl W Ns Cm warning .
73 See
74 .Sx EXIT STATUS
75 and
76 .Sx DIAGNOSTICS
77 for details.
78 .Pp
79 The special option
80 .Fl W Ns Cm stop
81 tells
82 .Nm
83 to exit after parsing a file that causes warnings or errors of at least
84 the requested level.
85 No formatted output will be produced from that file.
86 If both a
87 .Ar level
88 and
89 .Cm stop
90 are requested, they can be joined with a comma, for example
91 .Fl W Ns Cm error , Ns Cm stop .
92 .It Ar file
93 Read input from zero or more files.
94 If unspecified, reads from stdin.
95 If multiple files are specified,
96 .Nm
97 will halt with the first failed parse.
98 .El
99 .Pp
100 By default,
101 .Nm
102 reads
103 .Xr mdoc 7
104 or
105 .Xr man 7
106 text from stdin, implying
107 .Fl m Ns Cm andoc ,
108 and produces
109 .Fl T Ns Cm ascii
110 output.
111 .Ss Input Formats
112 The
113 .Nm
114 utility accepts
115 .Xr mdoc 7
116 and
117 .Xr man 7
118 input with
119 .Fl m Ns Cm doc
120 and
121 .Fl m Ns Cm an ,
122 respectively.
123 The
124 .Xr mdoc 7
125 format is
126 .Em strongly
127 recommended;
128 .Xr man 7
129 should only be used for legacy manuals.
130 .Pp
131 A third option,
132 .Fl m Ns Cm andoc ,
133 which is also the default, determines encoding on-the-fly: if the first
134 non-comment macro is
135 .Sq \&Dd
136 or
137 .Sq \&Dt ,
138 the
139 .Xr mdoc 7
140 parser is used; otherwise, the
141 .Xr man 7
142 parser is used.
143 .Pp
144 If multiple
145 files are specified with
146 .Fl m Ns Cm andoc ,
147 each has its file-type determined this way.
148 If multiple files are
149 specified and
150 .Fl m Ns Cm doc
151 or
152 .Fl m Ns Cm an
153 is specified, then this format is used exclusively.
154 .Ss Output Formats
155 The
156 .Nm
157 utility accepts the following
158 .Fl T
159 arguments, which correspond to output modes:
160 .Bl -tag -width Ds
161 .It Fl T Ns Cm ascii
162 Produce 7-bit ASCII output.
163 This is the default.
164 See
165 .Sx ASCII Output .
166 .It Fl T Ns Cm html
167 Produce strict CSS1/HTML-4.01 output.
168 See
169 .Sx HTML Output .
170 .It Fl T Ns Cm lint
171 Parse only: produce no output.
172 Implies
173 .Fl W Ns Cm warning .
174 .It Fl T Ns Cm pdf
175 Produce PDF output.
176 See
177 .Sx PDF Output .
178 .It Fl T Ns Cm ps
179 Produce PostScript output.
180 See
181 .Sx PostScript Output .
182 .It Fl T Ns Cm tree
183 Produce an indented parse tree.
184 .It Fl T Ns Cm xhtml
185 Produce strict CSS1/XHTML-1.0 output.
186 See
187 .Sx XHTML Output .
188 .El
189 .Pp
190 If multiple input files are specified, these will be processed by the
191 corresponding filter in-order.
192 .Ss ASCII Output
193 Output produced by
194 .Fl T Ns Cm ascii ,
195 which is the default, is rendered in standard 7-bit ASCII documented in
196 .Xr ascii 7 .
197 .Pp
198 Font styles are applied by using back-spaced encoding such that an
199 underlined character
200 .Sq c
201 is rendered as
202 .Sq _ Ns \e[bs] Ns c ,
203 where
204 .Sq \e[bs]
205 is the back-space character number 8.
206 Emboldened characters are rendered as
207 .Sq c Ns \e[bs] Ns c .
208 .Pp
209 The special characters documented in
210 .Xr mandoc_char 7
211 are rendered best-effort in an ASCII equivalent.
212 .Pp
213 Output width is limited to 78 visible columns unless literal input lines
214 exceed this limit.
215 .Pp
216 The following
217 .Fl O
218 arguments are accepted:
219 .Bl -tag -width Ds
220 .It Cm width Ns = Ns Ar width
221 The output width is set to
222 .Ar width ,
223 which will normalise to \(>=60.
224 .El
225 .Ss HTML Output
226 Output produced by
227 .Fl T Ns Cm html
228 conforms to HTML-4.01 strict.
229 .Pp
230 The
231 .Pa example.style.css
232 file documents style-sheet classes available for customising output.
233 If a style-sheet is not specified with
234 .Fl O Ns Ar style ,
235 .Fl T Ns Cm html
236 defaults to simple output readable in any graphical or text-based web
237 browser.
238 .Pp
239 Special characters are rendered in decimal-encoded UTF-8.
240 .Pp
241 The following
242 .Fl O
243 arguments are accepted:
244 .Bl -tag -width Ds
245 .It Cm includes Ns = Ns Ar fmt
246 The string
247 .Ar fmt ,
248 for example,
249 .Ar ../src/%I.html ,
250 is used as a template for linked header files (usually via the
251 .Sq \&In
252 macro).
253 Instances of
254 .Sq \&%I
255 are replaced with the include filename.
256 The default is not to present a
257 hyperlink.
258 .It Cm man Ns = Ns Ar fmt
259 The string
260 .Ar fmt ,
261 for example,
262 .Ar ../html%S/%N.%S.html ,
263 is used as a template for linked manuals (usually via the
264 .Sq \&Xr
265 macro).
266 Instances of
267 .Sq \&%N
268 and
269 .Sq %S
270 are replaced with the linked manual's name and section, respectively.
271 If no section is included, section 1 is assumed.
272 The default is not to
273 present a hyperlink.
274 .It Cm style Ns = Ns Ar style.css
275 The file
276 .Ar style.css
277 is used for an external style-sheet.
278 This must be a valid absolute or
279 relative URI.
280 .El
281 .Ss PostScript Output
282 PostScript
283 .Qq Adobe-3.0
284 Level-2 pages may be generated by
285 .Fl T Ns Cm ps .
286 Output pages default to letter sized and are rendered in the Times font
287 family, 11-point.
288 Margins are calculated as 1/9 the page length and width.
289 Line-height is 1.4m.
290 .Pp
291 Special characters are rendered as in
292 .Sx ASCII Output .
293 .Pp
294 The following
295 .Fl O
296 arguments are accepted:
297 .Bl -tag -width Ds
298 .It Cm paper Ns = Ns Ar name
299 The paper size
300 .Ar name
301 may be one of
302 .Ar a3 ,
303 .Ar a4 ,
304 .Ar a5 ,
305 .Ar legal ,
306 or
307 .Ar letter .
308 You may also manually specify dimensions as
309 .Ar NNxNN ,
310 width by height in millimetres.
311 If an unknown value is encountered,
312 .Ar letter
313 is used.
314 .El
315 .Ss PDF Output
316 PDF-1.1 output may be generated by
317 .Fl T Ns Cm pdf .
318 See
319 .Sx PostScript Output
320 for
321 .Fl O
322 arguments and defaults.
323 .Ss XHTML Output
324 Output produced by
325 .Fl T Ns Cm xhtml
326 conforms to XHTML-1.0 strict.
327 .Pp
328 See
329 .Sx HTML Output
330 for details; beyond generating XHTML tags instead of HTML tags, these
331 output modes are identical.
332 .Sh EXIT STATUS
333 The
334 .Nm
335 utility exits with one of the following values, controlled by the message
336 .Ar level
337 associated with the
338 .Fl W
339 option:
340 .Pp
341 .Bl -tag -width Ds -compact
342 .It 0
343 No warnings or errors occurred, or those that did were ignored because
344 they were lower than the requested
345 .Ar level .
346 .It 2
347 At least one warning occurred, but no error, and
348 .Fl W Ns Cm warning
349 was specified.
350 .It 3
351 At least one parsing error occurred, but no fatal error, and
352 .Fl W Ns Cm error
353 or
354 .Fl W Ns Cm warning
355 was specified.
356 .It 4
357 A fatal parsing error occurred.
358 .It 5
359 Invalid command line arguments were specified.
360 No input files have been read.
361 .It 6
362 An operating system error occurred, for example memory exhaustion or an
363 error accessing input files.
364 Such errors cause
365 .Nm
366 to exit at once, possibly in the middle of parsing or formatting a file.
367 .El
368 .Pp
369 Note that selecting
370 .Fl T Ns Cm lint
371 output mode implies
372 .Fl W Ns Cm warning .
373 .Sh EXAMPLES
374 To page manuals to the terminal:
375 .Pp
376 .Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less
377 .Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
378 .Pp
379 To produce HTML manuals with
380 .Ar style.css
381 as the style-sheet:
382 .Pp
383 .Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
384 .Pp
385 To check over a large set of manuals:
386 .Pp
387 .Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]`
388 .Pp
389 To produce a series of PostScript manuals for A4 paper:
390 .Pp
391 .Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
392 .Sh DIAGNOSTICS
393 Standard error messages reporting parsing errors are prefixed by
394 .Pp
395 .Sm off
396 .D1 Ar file : line : column : \ level :
397 .Sm on
398 .Pp
399 where the fields have the following meanings:
400 .Bl -tag -width "column"
401 .It Ar file
402 The name of the input file causing the message.
403 .It Ar line
404 The line number in that input file.
405 Line numbering starts at 1.
406 .It Ar column
407 The column number in that input file.
408 Column numbering starts at 1.
409 If the issue is caused by a word, the column number usually
410 points to the first character of the word.
411 .It Ar level
412 The message level, printed in capital letters.
413 .El
414 .Pp
415 Message levels have the following meanings:
416 .Bl -tag -width "warning"
417 .It Cm fatal
418 The parser is unable to parse a given input file at all.
419 No formatted output is produced from that input file.
420 .It Cm error
421 An input file contains syntax that cannot be safely interpreted,
422 either because it is invalid or because
423 .Nm
424 does not implement it yet.
425 By discarding part of the input or inserting missing tokens,
426 the parser is able to continue, and the error does not prevent
427 generation of formatted output, but typically, preparing that
428 output involves information loss, broken document structure
429 or unintended formatting.
430 .It Cm warning
431 An input file uses obsolete, discouraged or non-portable syntax.
432 All the same, the meaning of the input is unambiguous and a correct
433 rendering can be produced.
434 Documents causing warnings may render poorly when using other
435 formatting tools instead of
436 .Nm .
437 .El
438 .Pp
439 Messages of the
440 .Cm warning
441 and
442 .Cm error
443 levels are hidden unless their level, or a lower level, is requested using a
444 .Fl W
445 option or
446 .Fl T Ns Cm lint
447 output mode.
448 .Pp
449 The
450 .Nm
451 utility may also print messages related to invalid command line arguments
452 or operating system errors, for example when memory is exhausted or
453 input files cannot be read.
454 Such messages do not carry the prefix described above.
455 .Sh COMPATIBILITY
456 This section summarises
457 .Nm
458 compatibility with GNU troff.
459 Each input and output format is separately noted.
460 .Ss ASCII Compatibility
461 .Bl -bullet -compact
462 .It
463 The
464 .Sq \&Bd \-literal
465 and
466 .Sq \&Bd \-unfilled
467 macros of
468 .Xr mdoc 7
469 in
470 .Fl T Ns Cm ascii
471 are synonyms, as are \-filled and \-ragged.
472 .It
473 In GNU troff, the
474 .Sq \&Pa
475 .Xr mdoc 7
476 macro does not underline when scoped under an
477 .Sq \&It
478 in the FILES section.
479 This behaves correctly in
480 .Nm .
481 .It
482 A list or display following the
483 .Sq \&Ss
484 .Xr mdoc 7
485 macro in
486 .Fl T Ns Cm ascii
487 does not assert a prior vertical break, just as it doesn't with
488 .Sq \&Sh .
489 .It
490 The
491 .Sq \&na
492 .Xr man 7
493 macro in
494 .Fl T Ns Cm ascii
495 has no effect.
496 .It
497 Words aren't hyphenated.
498 .It
499 Sentences are unilaterally monospaced.
500 .El
501 .Ss HTML/XHTML Compatibility
502 .Bl -bullet -compact
503 .It
504 The
505 .Sq \efP
506 escape will revert the font to the previous
507 .Sq \ef
508 escape, not to the last rendered decoration, which is now dictated by
509 CSS instead of hard-coded.
510 It also will not span past the current scope,
511 for the same reason.
512 Note that in
513 .Sx ASCII Output
514 mode, this will work fine.
515 .It
516 The
517 .Xr mdoc 7
518 .Sq \&Bl \-hang
519 and
520 .Sq \&Bl \-tag
521 list types render similarly (no break following overreached left-hand
522 side) due to the expressive constraints of HTML.
523 .It
524 The
525 .Xr man 7
526 .Sq IP
527 and
528 .Sq TP
529 lists render similarly.
530 .El
531 .Sh SEE ALSO
532 .Xr man 7 ,
533 .Xr mandoc_char 7 ,
534 .Xr mdoc 7 ,
535 .Xr roff 7 ,
536 .Xr tbl 7
537 .Sh AUTHORS
538 The
539 .Nm
540 utility was written by
541 .An Kristaps Dzonsons Aq kristaps@bsd.lv .
542 .Sh CAVEATS
543 In
544 .Fl T Ns Cm html
545 and
546 .Fl T Ns Cm xhtml ,
547 the maximum size of an element attribute is determined by
548 .Dv BUFSIZ ,
549 which is usually 1024 bytes.
550 Be aware of this when setting long link
551 formats such as
552 .Fl O Ns Cm style Ns = Ns Ar really/long/link .
553 .Pp
554 Nesting elements within next-line element scopes of
555 .Fl m Ns Cm an ,
556 such as
557 .Sq br
558 within an empty
559 .Sq B ,
560 will confuse
561 .Fl T Ns Cm html
562 and
563 .Fl T Ns Cm xhtml
564 and cause them to forget the formatting of the prior next-line scope.
565 .Pp
566 The
567 .Sq \(aq
568 control character is an alias for the standard macro control character
569 and does not emit a line-break as stipulated in GNU troff.