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