contrib/mdocml/mandoc.1

   1 .\"     $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 $Mdocdate: 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.