mandoc.1

   1 .\"     $Id: mandoc.1,v 1.58 2010/04/12 19:27:22 kristaps Exp $
   2 .\"
   3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
   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: April 12 2010 $
  18 .Dt MANDOC 1
  19 .Os
  20 .
  21 .
  22 .Sh NAME
  23 .Nm mandoc
  24 .Nd format and display UNIX manuals
  25 .
  26 .
  27 .Sh SYNOPSIS
  28 .Nm mandoc
  29 .Op Fl V
  30 .Op Fl f Ns Ar option
  31 .Op Fl m Ns Ar format
  32 .Op Fl O Ns Ar option
  33 .Op Fl T Ns Ar output
  34 .Op Fl W Ns Ar err
  35 .Op Ar file...
  36 .
  37 .
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 utility formats
  42 .Ux
  43 manual pages for display.
  44 The arguments are as follows:
  45 .
  46 .Bl -tag -width Ds
  47 .It Fl f Ns Ar option
  48 Comma-separated compiler options.
  49 See
  50 .Sx Compiler Options
  51 for details.
  52 .
  53 .It Fl m Ns Ar format
  54 Input format.
  55 See
  56 .Sx Input Formats
  57 for available formats.
  58 Defaults to
  59 .Fl m Ns Cm andoc .
  60 .
  61 .It Fl O Ns Ar option
  62 Comma-separated output options.
  63 See
  64 .Sx Output Options
  65 for details.
  66 .
  67 .It Fl T Ns Ar output
  68 Output format.
  69 See
  70 .Sx Output Formats
  71 for available formats.
  72 Defaults to
  73 .Fl T Ns Cm ascii .
  74 .
  75 .It Fl V
  76 Print version and exit.
  77 .
  78 .It Fl W Ns Ar err
  79 Comma-separated warning options.
  80 Use
  81 .Fl W Ns Cm all
  82 to print warnings,
  83 .Fl W Ns Cm error
  84 for warnings to be considered errors and cause utility
  85 termination.
  86 Multiple
  87 .Fl W
  88 arguments may be comma-separated, such as
  89 .Fl W Ns Cm error , Ns Cm all .
  90 .
  91 .It Ar file
  92 Read input from zero or more files.
  93 If unspecified, reads from stdin.
  94 If multiple files are specified,
  95 .Nm
  96 will halt with the first failed parse.
  97 .El
  98 .
  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 .
 112 .Pp
 113 .Ex -std mandoc
 114 .
 115 .
 116 .Ss Input Formats
 117 The
 118 .Nm
 119 utility accepts
 120 .Xr mdoc 7
 121 and
 122 .Xr man 7
 123 input with
 124 .Fl m Ns Cm doc
 125 and
 126 .Fl m Ns Cm an ,
 127 respectively.
 128 The
 129 .Xr mdoc 7
 130 format is
 131 .Em strongly
 132 recommended;
 133 .Xr man 7
 134 should only be used for legacy manuals.
 135 .
 136 .Pp
 137 A third option,
 138 .Fl m Ns Cm andoc ,
 139 which is also the default, determines encoding on-the-fly: if the first
 140 non-comment macro is
 141 .Sq \&Dd
 142 or
 143 .Sq \&Dt ,
 144 the
 145 .Xr mdoc 7
 146 parser is used; otherwise, the
 147 .Xr man 7
 148 parser is used.
 149 .
 150 .Pp
 151 If multiple
 152 files are specified with
 153 .Fl m Ns Cm andoc ,
 154 each has its file-type determined this way.
 155 If multiple files are
 156 specified and
 157 .Fl m Ns Cm doc
 158 or
 159 .Fl m Ns Cm an
 160 is specified, then this format is used exclusively.
 161 .
 162 .
 163 .Ss Output Formats
 164 The
 165 .Nm
 166 utility accepts the following
 167 .Fl T
 168 arguments (see
 169 .Sx OUTPUT ) :
 170 .
 171 .Bl -tag -width Ds
 172 .It Fl T Ns Cm ascii
 173 Produce 7-bit ASCII output, backspace-encoded for bold and underline
 174 styles.
 175 This is the default.
 176 See
 177 .Sx ASCII Output .
 178 .
 179 .It Fl T Ns Cm html
 180 Produce strict HTML-4.01 output, with a sane default style.
 181 See
 182 .Sx HTML Output .
 183 .
 184 .It Fl T Ns Cm lint
 185 Parse only: produce no output.
 186 Implies
 187 .Fl W Ns Cm all
 188 and
 189 .Fl f Ns Cm strict .
 190 .
 191 .It Fl T Ns Cm tree
 192 Produce an indented parse tree.
 193 .
 194 .It Fl T Ns Cm xhtml
 195 Produce strict XHTML-1.0 output, with a sane default style.
 196 See
 197 .Sx XHTML Output .
 198 .El
 199 .
 200 .Pp
 201 If multiple input files are specified, these will be processed by the
 202 corresponding filter in-order.
 203 .
 204 .
 205 .Ss Compiler Options
 206 Default compiler behaviour may be overridden with the
 207 .Fl f
 208 flag.
 209 .
 210 .Bl -tag -width Ds
 211 .It Fl f Ns Cm ign-errors
 212 When parsing multiple files, don't halt when one errors out.
 213 Useful with
 214 .Fl T Ns Cm lint
 215 over a large set of manuals passed on the command line.
 216 .
 217 .It Fl f Ns Cm ign-escape
 218 Ignore invalid escape sequences.
 219 This is the default, but the option can be used to override an earlier
 220 .Fl f Ns Cm strict .
 221 .
 222 .It Fl f Ns Cm ign-scope
 223 When rewinding the scope of a block macro, forces the compiler to ignore
 224 scope violations.
 225 This can seriously mangle the resulting tree.
 226 .Pq mdoc only
 227 .
 228 .It Fl f Ns Cm no-ign-chars
 229 Do not ignore disallowed characters.
 230 .
 231 .It Fl f Ns Cm no-ign-escape
 232 Do not ignore invalid escape sequences.
 233 .
 234 .It Fl f Ns Cm no-ign-macro
 235 Do not ignore unknown macros at the start of input lines.
 236 .
 237 .It Fl f Ns Cm strict
 238 Implies
 239 .Fl f Ns Cm no-ign-escape ,
 240 .Fl f Ns Cm no-ign-macro ,
 241 and
 242 .Fl f Ns Cm no-ign-chars .
 243 .El
 244 .
 245 .
 246 .Ss Output Options
 247 For the time being, only
 248 .Fl T Ns Ar html
 249 and
 250 .Fl T Ns Ar xhtml
 251 accept output options:
 252 .Bl -tag -width Ds
 253 .It Fl O Ns Cm includes Ns = Ns Ar fmt
 254 The string
 255 .Ar fmt ,
 256 for example,
 257 .Ar ../src/%I.html ,
 258 is used as a template for linked header files (usually via the
 259 .Sq \&In
 260 macro).
 261 Instances of
 262 .Sq \&%I
 263 are replaced with the include filename.
 264 The default is not to present a
 265 hyperlink.
 266 .It Fl O Ns Cm man Ns = Ns Ar fmt
 267 The string
 268 .Ar fmt ,
 269 for example,
 270 .Ar ../html%S/%N.%S.html ,
 271 is used as a template for linked manuals (usually via the
 272 .Sq \&Xr
 273 macro).
 274 Instances of
 275 .Sq \&%N
 276 and
 277 .Sq %S
 278 are replaced with the linked manual's name and section, respectively.
 279 If no section is included, section 1 is assumed.
 280 The default is not to
 281 present a hyperlink.
 282 .It Fl O Ns Cm style Ns = Ns Ar style.css
 283 The file
 284 .Ar style.css
 285 is used for an external style-sheet.
 286 This must be a valid absolute or
 287 relative URI.
 288 .El
 289 .
 290 .
 291 .Sh OUTPUT
 292 This section documents output details of
 293 .Nm .
 294 In general, output conforms to the traditional manual style of a header,
 295 a body composed of sections and sub-sections, and a footer.
 296 .Pp
 297 The text style of output characters (non-macro characters, punctuation,
 298 and white-space) is dictated by context.
 299 .Pp
 300 White-space is generally stripped from input.
 301 This can be changed with
 302 character escapes (specified in
 303 .Xr mandoc_char 7 )
 304 or literal modes (specified in
 305 .Xr mdoc 7
 306 and
 307 .Xr man 7 ) .
 308 .Pp
 309 If non-macro punctuation is set apart from words, such as in the phrase
 310 .Dq to be \&, or not to be ,
 311 it's processed by
 312 .Nm ,
 313 regardless of output format, according to the following rules:  opening
 314 punctuation
 315 .Po
 316 .Sq \&( ,
 317 .Sq \&[ ,
 318 and
 319 .Sq \&{
 320 .Pc
 321 is not followed by a space; closing punctuation
 322 .Po
 323 .Sq \&. ,
 324 .Sq \&, ,
 325 .Sq \&; ,
 326 .Sq \&: ,
 327 .Sq \&? ,
 328 .Sq \&! ,
 329 .Sq \&) ,
 330 .Sq \&]
 331 and
 332 .Sq \&}
 333 .Pc
 334 is not preceded by white-space.
 335 .
 336 .Pp
 337 If the input is
 338 .Xr mdoc 7 ,
 339 however, these rules are also applied to macro arguments when appropriate.
 340 .
 341 .
 342 .Ss ASCII Output
 343 Output produced by
 344 .Fl T Ns Cm ascii ,
 345 which is the default, is rendered in standard 7-bit ASCII documented in
 346 .Xr ascii 7 .
 347 .Pp
 348 Font styles are applied by using back-spaced encoding such that an
 349 underlined character
 350 .Sq c
 351 is rendered as
 352 .Sq _ Ns \e[bs] Ns c ,
 353 where
 354 .Sq \e[bs]
 355 is the back-space character number 8.
 356 Emboldened characters are rendered as
 357 .Sq c Ns \e[bs] Ns c .
 358 .Pp
 359 The special characters documented in
 360 .Xr mandoc_char 7
 361 are rendered best-effort in an ASCII equivalent.
 362 .Pp
 363 Output width is limited to 78 visible columns unless literal input lines
 364 exceed this limit.
 365 .
 366 .
 367 .Ss HTML Output
 368 Output produced by
 369 .Fl T Ns Cm html
 370 conforms to HTML-4.01 strict.
 371 .Pp
 372 Font styles and page structure are applied using CSS2.
 373 By default, no font style is applied to any text,
 374 although CSS2 is hard-coded to format
 375 the basic structure of output.
 376 .Pp
 377 The
 378 .Pa example.style.css
 379 file documents the range of styles applied to output and, if used, will
 380 cause rendered documents to appear as they do in
 381 .Fl T Ns Cm ascii .
 382 .Pp
 383 Special characters are rendered in decimal-encoded UTF-8.
 384 .
 385 .
 386 .Ss XHTML Output
 387 Output produced by
 388 .Fl T Ns Cm xhtml
 389 conforms to XHTML-1.0 strict.
 390 .Pp
 391 See
 392 .Sx HTML Output
 393 for details; beyond generating XHTML tags instead of HTML tags, these
 394 output modes are identical.
 395 .
 396 .
 397 .Sh EXAMPLES
 398 To page manuals to the terminal:
 399 .
 400 .Pp
 401 .D1 $ mandoc \-Wall,error \-fstrict mandoc.1 2\*(Gt&1 | less
 402 .D1 $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
 403 .
 404 .Pp
 405 To produce HTML manuals with
 406 .Ar style.css
 407 as the style-sheet:
 408 .Pp
 409 .D1 $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
 410 .Pp
 411 To check over a large set of manuals:
 412 .
 413 .Pp
 414 .Dl $ mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
 415 .
 416 .
 417 .Sh COMPATIBILITY
 418 This section summarises
 419 .Nm
 420 compatibility with
 421 .Xr groff 1 .
 422 Each input and output format is separately noted.
 423 .
 424 .
 425 .Ss ASCII Compatibility
 426 .Bl -bullet -compact
 427 .It
 428 The
 429 .Sq \e~
 430 special character doesn't produce expected behaviour in
 431 .Fl T Ns Cm ascii .
 432 .
 433 .It
 434 The
 435 .Sq \&Bd \-literal
 436 and
 437 .Sq \&Bd \-unfilled
 438 macros of
 439 .Xr mdoc 7
 440 in
 441 .Fl T Ns Cm ascii
 442 are synonyms, as are \-filled and \-ragged.
 443 .
 444 .It
 445 In
 446 .Xr groff 1 ,
 447 the
 448 .Sq \&Pa
 449 .Xr mdoc 7
 450 macro does not underline when scoped under an
 451 .Sq \&It
 452 in the FILES section.
 453 This behaves correctly in
 454 .Nm .
 455 .
 456 .It
 457 A list or display following the
 458 .Sq \&Ss
 459 .Xr mdoc 7
 460 macro in
 461 .Fl T Ns Cm ascii
 462 does not assert a prior vertical break, just as it doesn't with
 463 .Sq \&Sh .
 464 .
 465 .It
 466 The
 467 .Sq \&na
 468 .Xr man 7
 469 macro in
 470 .Fl T Ns Cm ascii
 471 has no effect.
 472 .
 473 .It
 474 Words aren't hyphenated.
 475 .
 476 .It
 477 In normal mode (not a literal block), blocks of spaces aren't preserved,
 478 so double spaces following sentence closure are reduced to a single space;
 479 .Xr groff 1
 480 retains spaces.
 481 .
 482 .It
 483 Sentences are unilaterally monospaced.
 484 .El
 485 .
 486 .
 487 .Ss HTML/XHTML Compatibility
 488 .Bl -bullet -compact
 489 .It
 490 The
 491 .Sq \efP
 492 escape will revert the font to the previous
 493 .Sq \ef
 494 escape, not to the last rendered decoration, which is now dictated by
 495 CSS instead of hard-coded.
 496 It also will not span past the current scope,
 497 for the same reason.
 498 Note that in
 499 .Sx ASCII Output
 500 mode, this will work fine.
 501 .It
 502 The
 503 .Xr mdoc 7
 504 .Sq \&Bl \-hang
 505 and
 506 .Sq \&Bl \-tag
 507 list types render similarly (no break following overreached left-hand
 508 side) due to the expressive constraints of HTML.
 509 .
 510 .It
 511 The
 512 .Xr man 7
 513 .Sq IP
 514 and
 515 .Sq TP
 516 lists render similarly.
 517 .El
 518 .
 519 .
 520 .Sh SEE ALSO
 521 .Xr man 7 ,
 522 .Xr mandoc_char 7 ,
 523 .Xr mdoc 7
 524 .
 525 .Sh AUTHORS
 526 The
 527 .Nm
 528 utility was written by
 529 .An Kristaps Dzonsons Aq kristaps@kth.se .
 530 .
 531 .
 532 .Sh CAVEATS
 533 The
 534 .Fl T Ns Cm html
 535 and
 536 .Fl T Ns Cm xhtml
 537 CSS2 styling used for
 538 .Fl m Ns Cm doc
 539 input lists does not render properly in older browsers, such as Internet
 540 Explorer 6 and earlier.
 541 .
 542 .Pp
 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 .
 554 .Pp
 555 The
 556 .Fl T Ns Cm html
 557 and
 558 .Fl T Ns Cm xhtml
 559 output modes don't render the
 560 .Sq \es
 561 font size escape documented in
 562 .Xr mdoc 7
 563 and
 564 .Xr man 7 .
 565 .
 566 .Pp
 567 Nesting elements within next-line element scopes of
 568 .Fl m Ns Cm an ,
 569 such as
 570 .Sq br
 571 within an empty
 572 .Sq B ,
 573 will confuse
 574 .Fl T Ns Cm html
 575 and
 576 .Fl T Ns Cm xhtml
 577 and cause them to forget the formatting of the prior next-line scope.
 578 .
 579 .Pp
 580 The
 581 .Sq i
 582 macro in
 583 .Fl m Ns Cm an
 584 should italicise all subsequent text if a line argument is not provided.
 585 This behaviour is not implemented.
 586 .
 587 The
 588 .Sq \(aq
 589 control character is an alias for the standard macro control character
 590 and does not emit a line-break as stipulated in GNU troff.