mandoc.1

   1 .\"     $Id: mandoc.1,v 1.94 2011/10/05 21:35:17 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: October 5 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 output in
 180 .Xr man 7
 181 format; only useful when applied to
 182 .Fl m Ns Cm doc
 183 input.
 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 width Ns = Ns Ar width
 238 The output width is set to
 239 .Ar width ,
 240 which will normalise to \(>=60.
 241 .El
 242 .Ss HTML Output
 243 Output produced by
 244 .Fl T Ns Cm html
 245 conforms to HTML-4.01 strict.
 246 .Pp
 247 The
 248 .Pa example.style.css
 249 file documents style-sheet classes available for customising output.
 250 If a style-sheet is not specified with
 251 .Fl O Ns Ar style ,
 252 .Fl T Ns Cm html
 253 defaults to simple output readable in any graphical or text-based web
 254 browser.
 255 .Pp
 256 Special characters are rendered in decimal-encoded UTF\-8.
 257 .Pp
 258 The following
 259 .Fl O
 260 arguments are accepted:
 261 .Bl -tag -width Ds
 262 .It Cm fragment
 263 Do not emit doctype, html, and body elements.
 264 The
 265 .Cm style
 266 argument shall be unused.
 267 This is useful when embedding manual content within existing documents.
 268 .It Cm includes Ns = Ns Ar fmt
 269 The string
 270 .Ar fmt ,
 271 for example,
 272 .Ar ../src/%I.html ,
 273 is used as a template for linked header files (usually via the
 274 .Sq \&In
 275 macro).
 276 Instances of
 277 .Sq \&%I
 278 are replaced with the include filename.
 279 The default is not to present a
 280 hyperlink.
 281 .It Cm man Ns = Ns Ar fmt
 282 The string
 283 .Ar fmt ,
 284 for example,
 285 .Ar ../html%S/%N.%S.html ,
 286 is used as a template for linked manuals (usually via the
 287 .Sq \&Xr
 288 macro).
 289 Instances of
 290 .Sq \&%N
 291 and
 292 .Sq %S
 293 are replaced with the linked manual's name and section, respectively.
 294 If no section is included, section 1 is assumed.
 295 The default is not to
 296 present a hyperlink.
 297 .It Cm style Ns = Ns Ar style.css
 298 The file
 299 .Ar style.css
 300 is used for an external style-sheet.
 301 This must be a valid absolute or
 302 relative URI.
 303 .El
 304 .Ss Locale Output
 305 Locale-depending output encoding is triggered with
 306 .Fl T Ns Cm locale .
 307 This option is not available on all systems: systems without locale
 308 support, or those whose internal representation is not natively UCS-4,
 309 will fall back to
 310 .Fl T Ns Cm ascii .
 311 See
 312 .Sx ASCII Output
 313 for font style specification and available command-line arguments.
 314 .Ss PDF Output
 315 PDF-1.1 output may be generated by
 316 .Fl T Ns Cm pdf .
 317 See
 318 .Sx PostScript Output
 319 for
 320 .Fl O
 321 arguments and defaults.
 322 .Ss PostScript Output
 323 PostScript
 324 .Qq Adobe-3.0
 325 Level-2 pages may be generated by
 326 .Fl T Ns Cm ps .
 327 Output pages default to letter sized and are rendered in the Times font
 328 family, 11-point.
 329 Margins are calculated as 1/9 the page length and width.
 330 Line-height is 1.4m.
 331 .Pp
 332 Special characters are rendered as in
 333 .Sx ASCII Output .
 334 .Pp
 335 The following
 336 .Fl O
 337 arguments are accepted:
 338 .Bl -tag -width Ds
 339 .It Cm paper Ns = Ns Ar name
 340 The paper size
 341 .Ar name
 342 may be one of
 343 .Ar a3 ,
 344 .Ar a4 ,
 345 .Ar a5 ,
 346 .Ar legal ,
 347 or
 348 .Ar letter .
 349 You may also manually specify dimensions as
 350 .Ar NNxNN ,
 351 width by height in millimetres.
 352 If an unknown value is encountered,
 353 .Ar letter
 354 is used.
 355 .El
 356 .Ss UTF\-8 Output
 357 Use
 358 .Fl T Ns Cm utf8
 359 to force a UTF\-8 locale.
 360 See
 361 .Sx Locale Output
 362 for details and options.
 363 .Ss XHTML Output
 364 Output produced by
 365 .Fl T Ns Cm xhtml
 366 conforms to XHTML-1.0 strict.
 367 .Pp
 368 See
 369 .Sx HTML Output
 370 for details; beyond generating XHTML tags instead of HTML tags, these
 371 output modes are identical.
 372 .Sh EXIT STATUS
 373 The
 374 .Nm
 375 utility exits with one of the following values, controlled by the message
 376 .Ar level
 377 associated with the
 378 .Fl W
 379 option:
 380 .Pp
 381 .Bl -tag -width Ds -compact
 382 .It 0
 383 No warnings or errors occurred, or those that did were ignored because
 384 they were lower than the requested
 385 .Ar level .
 386 .It 2
 387 At least one warning occurred, but no error, and
 388 .Fl W Ns Cm warning
 389 was specified.
 390 .It 3
 391 At least one parsing error occurred, but no fatal error, and
 392 .Fl W Ns Cm error
 393 or
 394 .Fl W Ns Cm warning
 395 was specified.
 396 .It 4
 397 A fatal parsing error occurred.
 398 .It 5
 399 Invalid command line arguments were specified.
 400 No input files have been read.
 401 .It 6
 402 An operating system error occurred, for example memory exhaustion or an
 403 error accessing input files.
 404 Such errors cause
 405 .Nm
 406 to exit at once, possibly in the middle of parsing or formatting a file.
 407 .El
 408 .Pp
 409 Note that selecting
 410 .Fl T Ns Cm lint
 411 output mode implies
 412 .Fl W Ns Cm warning .
 413 .Sh EXAMPLES
 414 To page manuals to the terminal:
 415 .Pp
 416 .Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less
 417 .Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
 418 .Pp
 419 To produce HTML manuals with
 420 .Ar style.css
 421 as the style-sheet:
 422 .Pp
 423 .Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
 424 .Pp
 425 To check over a large set of manuals:
 426 .Pp
 427 .Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]`
 428 .Pp
 429 To produce a series of PostScript manuals for A4 paper:
 430 .Pp
 431 .Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
 432 .Pp
 433 Convert a modern
 434 .Xr mdoc 7
 435 manual to the older
 436 .Xr man 7
 437 format, for use on systems lacking an
 438 .Xr mdoc 7
 439 parser:
 440 .Pp
 441 .Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man
 442 .Sh DIAGNOSTICS
 443 Standard error messages reporting parsing errors are prefixed by
 444 .Pp
 445 .Sm off
 446 .D1 Ar file : line : column : \ level :
 447 .Sm on
 448 .Pp
 449 where the fields have the following meanings:
 450 .Bl -tag -width "column"
 451 .It Ar file
 452 The name of the input file causing the message.
 453 .It Ar line
 454 The line number in that input file.
 455 Line numbering starts at 1.
 456 .It Ar column
 457 The column number in that input file.
 458 Column numbering starts at 1.
 459 If the issue is caused by a word, the column number usually
 460 points to the first character of the word.
 461 .It Ar level
 462 The message level, printed in capital letters.
 463 .El
 464 .Pp
 465 Message levels have the following meanings:
 466 .Bl -tag -width "warning"
 467 .It Cm fatal
 468 The parser is unable to parse a given input file at all.
 469 No formatted output is produced from that input file.
 470 .It Cm error
 471 An input file contains syntax that cannot be safely interpreted,
 472 either because it is invalid or because
 473 .Nm
 474 does not implement it yet.
 475 By discarding part of the input or inserting missing tokens,
 476 the parser is able to continue, and the error does not prevent
 477 generation of formatted output, but typically, preparing that
 478 output involves information loss, broken document structure
 479 or unintended formatting.
 480 .It Cm warning
 481 An input file uses obsolete, discouraged or non-portable syntax.
 482 All the same, the meaning of the input is unambiguous and a correct
 483 rendering can be produced.
 484 Documents causing warnings may render poorly when using other
 485 formatting tools instead of
 486 .Nm .
 487 .El
 488 .Pp
 489 Messages of the
 490 .Cm warning
 491 and
 492 .Cm error
 493 levels are hidden unless their level, or a lower level, is requested using a
 494 .Fl W
 495 option or
 496 .Fl T Ns Cm lint
 497 output mode.
 498 .Pp
 499 The
 500 .Nm
 501 utility may also print messages related to invalid command line arguments
 502 or operating system errors, for example when memory is exhausted or
 503 input files cannot be read.
 504 Such messages do not carry the prefix described above.
 505 .Sh COMPATIBILITY
 506 This section summarises
 507 .Nm
 508 compatibility with GNU troff.
 509 Each input and output format is separately noted.
 510 .Ss ASCII Compatibility
 511 .Bl -bullet -compact
 512 .It
 513 Unrenderable unicode codepoints specified with
 514 .Sq \e[uNNNN]
 515 escapes are printed as
 516 .Sq \&?
 517 in mandoc.
 518 In GNU troff, these raise an error.
 519 .It
 520 The
 521 .Sq \&Bd \-literal
 522 and
 523 .Sq \&Bd \-unfilled
 524 macros of
 525 .Xr mdoc 7
 526 in
 527 .Fl T Ns Cm ascii
 528 are synonyms, as are \-filled and \-ragged.
 529 .It
 530 In historic GNU troff, the
 531 .Sq \&Pa
 532 .Xr mdoc 7
 533 macro does not underline when scoped under an
 534 .Sq \&It
 535 in the FILES section.
 536 This behaves correctly in
 537 .Nm .
 538 .It
 539 A list or display following the
 540 .Sq \&Ss
 541 .Xr mdoc 7
 542 macro in
 543 .Fl T Ns Cm ascii
 544 does not assert a prior vertical break, just as it doesn't with
 545 .Sq \&Sh .
 546 .It
 547 The
 548 .Sq \&na
 549 .Xr man 7
 550 macro in
 551 .Fl T Ns Cm ascii
 552 has no effect.
 553 .It
 554 Words aren't hyphenated.
 555 .El
 556 .Ss HTML/XHTML Compatibility
 557 .Bl -bullet -compact
 558 .It
 559 The
 560 .Sq \efP
 561 escape will revert the font to the previous
 562 .Sq \ef
 563 escape, not to the last rendered decoration, which is now dictated by
 564 CSS instead of hard-coded.
 565 It also will not span past the current scope,
 566 for the same reason.
 567 Note that in
 568 .Sx ASCII Output
 569 mode, this will work fine.
 570 .It
 571 The
 572 .Xr mdoc 7
 573 .Sq \&Bl \-hang
 574 and
 575 .Sq \&Bl \-tag
 576 list types render similarly (no break following overreached left-hand
 577 side) due to the expressive constraints of HTML.
 578 .It
 579 The
 580 .Xr man 7
 581 .Sq IP
 582 and
 583 .Sq TP
 584 lists render similarly.
 585 .El
 586 .Sh SEE ALSO
 587 .Xr eqn 7 ,
 588 .Xr man 7 ,
 589 .Xr mandoc_char 7 ,
 590 .Xr mdoc 7 ,
 591 .Xr roff 7 ,
 592 .Xr tbl 7
 593 .Sh AUTHORS
 594 The
 595 .Nm
 596 utility was written by
 597 .An Kristaps Dzonsons ,
 598 .Mt kristaps@bsd.lv .
 599 .Sh CAVEATS
 600 In
 601 .Fl T Ns Cm html
 602 and
 603 .Fl T Ns Cm xhtml ,
 604 the maximum size of an element attribute is determined by
 605 .Dv BUFSIZ ,
 606 which is usually 1024 bytes.
 607 Be aware of this when setting long link
 608 formats such as
 609 .Fl O Ns Cm style Ns = Ns Ar really/long/link .
 610 .Pp
 611 Nesting elements within next-line element scopes of
 612 .Fl m Ns Cm an ,
 613 such as
 614 .Sq br
 615 within an empty
 616 .Sq B ,
 617 will confuse
 618 .Fl T Ns Cm html
 619 and
 620 .Fl T Ns Cm xhtml
 621 and cause them to forget the formatting of the prior next-line scope.
 622 .Pp
 623 The
 624 .Sq \(aq
 625 control character is an alias for the standard macro control character
 626 and does not emit a line-break as stipulated in GNU troff.