mandoc.1

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