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