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