mandoc.1

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