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