mandoc.1

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