contrib/mdocml/mandoc.1

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