mandoc.1

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