contrib/mdocml/mandoc.1

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