mandoc.1

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