mandoc.1

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