mandoc.1

   1 .\"     $Id: mandoc.1,v 1.53 2010/03/25 07:28:16 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 25 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 Don't halt when encountering parse errors.  Useful with
 224 .Fl T Ns Ar lint
 225 over a large set of manuals passed on the command line.
 226 .El
 227 .
 228 .
 229 .Ss Output Options
 230 For the time being, only
 231 .Fl T Ns Ar html
 232 and
 233 .Fl T Ns Ar xhtml
 234 accepts output options:
 235 .Bl -tag -width Ds
 236 .It Fl O Ns Ar style=style.css
 237 The file
 238 .Ar style.css
 239 is used for an external style-sheet.  This must be a valid absolute or
 240 relative URI.
 241 .It Fl O Ns Ar includes=fmt
 242 The string
 243 .Ar fmt ,
 244 for example,
 245 .Ar ../src/%I.html ,
 246 is used as a template for linked header files (usually via the
 247 .Sq \&In
 248 macro).  Instances of
 249 .Sq \&%I
 250 are replaced with the include filename.  The default is not to present a
 251 hyperlink.
 252 .It Fl O Ns Ar man=fmt
 253 The string
 254 .Ar fmt ,
 255 for example,
 256 .Ar ../html%S/%N.%S.html ,
 257 is used as a template for linked manuals (usually via the
 258 .Sq \&Xr
 259 macro).  Instances of
 260 .Sq \&%N
 261 and
 262 .Sq %S
 263 are replaced with the linked manual's name and section, respectively.
 264 If no section is included, section 1 is assumed.  The default is not to
 265 present a hyperlink.
 266 .El
 267 .
 268 .
 269 .Sh OUTPUT
 270 This section documents output details of
 271 .Nm .
 272 In general, output conforms to the traditional manual style of a header,
 273 a body composed of sections and sub-sections, and a footer.
 274 .Pp
 275 The text style of output characters (non-macro characters, punctuation,
 276 and white-space) is dictated by context.
 277 .Pp
 278 White-space is generally stripped from input.  This can be changed with
 279 character escapes (specified in
 280 .Xr mandoc_char 7 )
 281 or literal modes (specified in
 282 .Xr mdoc 7
 283 and
 284 .Xr man 7 ) .
 285 .Pp
 286 If non-macro punctuation is set apart from words, such as in the phrase
 287 .Dq to be \&, or not to be ,
 288 it's processed by
 289 .Nm ,
 290 regardless of output format, according to the following rules:  opening
 291 punctuation
 292 .Po
 293 .Sq \&( ,
 294 .Sq \&[ ,
 295 and
 296 .Sq \&{
 297 .Pc
 298 is not followed by a space; closing punctuation
 299 .Po
 300 .Sq \&. ,
 301 .Sq \&, ,
 302 .Sq \&; ,
 303 .Sq \&: ,
 304 .Sq \&? ,
 305 .Sq \&! ,
 306 .Sq \&) ,
 307 .Sq \&]
 308 and
 309 .Sq \&}
 310 .Pc
 311 is not preceded by white-space.
 312 .
 313 .Pp
 314 If the input is
 315 .Xr mdoc 7 ,
 316 however, these rules are also applied to macro arguments when appropriate.
 317 .
 318 .
 319 .Ss ASCII Output
 320 Output produced by
 321 .Fl T Ns Ar ascii ,
 322 which is the default, is rendered in standard 7-bit ASCII documented in
 323 .Xr ascii 7 .
 324 .Pp
 325 Font styles are applied by using back-spaced encoding such that an
 326 underlined character
 327 .Sq c
 328 is rendered as
 329 .Sq _ Ns \e[bs] Ns c ,
 330 where
 331 .Sq \e[bs]
 332 is the back-space character number 8.  Emboldened characters are rendered as
 333 .Sq c Ns \e[bs] Ns c .
 334 .Pp
 335 The special characters documented in
 336 .Xr mandoc_char 7
 337 are rendered best-effort in an ASCII equivalent.
 338 .Pp
 339 Output width is limited to 78 visible columns unless literal input lines
 340 exceed this limit.
 341 .
 342 .
 343 .Ss HTML Output
 344 Output produced by
 345 .Fl T Ns Ar html
 346 conforms to HTML-4.01 strict.
 347 .Pp
 348 Font styles and page structure are applied using CSS2.  By default, no
 349 font style is applied to any text, although CSS2 is hard-coded to format
 350 the basic structure of output.
 351 .Pp
 352 The
 353 .Pa example.style.css
 354 file documents the range of styles applied to output and, if used, will
 355 cause rendered documents to appear as they do in
 356 .Fl T Ns Ar ascii .
 357 .Pp
 358 Special characters are rendered in decimal-encoded UTF-8.
 359 .
 360 .
 361 .Ss XHTML Output
 362 Output produced by
 363 .Fl T Ns Ar xhtml
 364 conforms to XHTML-1.0 strict.
 365 .Pp
 366 See
 367 .Sx HTML Output
 368 for details; beyond generating XHTML tags instead of HTML tags, these
 369 output modes are identical.
 370 .
 371 .
 372 .Sh EXAMPLES
 373 To page manuals to the terminal:
 374 .
 375 .Pp
 376 .D1 % mandoc \-Wall,error \-fstrict mandoc.1 2>&1 | less
 377 .D1 % mandoc mandoc.1 mdoc.3 mdoc.7 | less
 378 .
 379 .Pp
 380 To produce HTML manuals with
 381 .Ar style.css
 382 as the style-sheet:
 383 .Pp
 384 .D1 % mandoc \-Thtml -Ostyle=style.css mdoc.7 > mdoc.7.html
 385 .Pp
 386 To check over a large set of manuals:
 387 .
 388 .Pp
 389 .Dl % mandoc \-Tlint \-fign-errors `find /usr/src -name \e*\e.[1-9]`
 390 .
 391 .
 392 .Sh COMPATIBILITY
 393 This section summarises
 394 .Nm
 395 compatibility with
 396 .Xr groff 1 .
 397 Each input and output format is separately noted.
 398 .
 399 .
 400 .Ss ASCII Compatibility
 401 .Bl -bullet -compact
 402 .It
 403 The
 404 .Sq \e~
 405 special character doesn't produce expected behaviour in
 406 .Fl T Ns Ar ascii .
 407 .
 408 .It
 409 The
 410 .Sq \&Bd \-literal
 411 and
 412 .Sq \&Bd \-unfilled
 413 macros of
 414 .Xr mdoc 7
 415 in
 416 .Fl T Ns Ar ascii
 417 are synonyms, as are \-filled and \-ragged.
 418 .
 419 .It
 420 In
 421 .Xr groff 1 ,
 422 the
 423 .Sq \&Pa
 424 .Xr mdoc 7
 425 macro does not underline when scoped under an
 426 .Sq \&It
 427 in the FILES section.  This behaves correctly in
 428 .Nm .
 429 .
 430 .It
 431 A list or display following
 432 .Sq \&Ss
 433 .Xr mdoc 7
 434 macro in
 435 .Fl T Ns Ar ascii
 436 does not assert a prior vertical break, just as it doesn't with
 437 .Sq \&Sh .
 438 .
 439 .It
 440 The
 441 .Sq \&na
 442 .Xr man 7
 443 macro in
 444 .Fl T Ns Ar ascii
 445 has no effect.
 446 .
 447 .It
 448 Words aren't hyphenated.
 449 .
 450 .It
 451 In normal mode (not a literal block), blocks of spaces aren't preserved,
 452 so double spaces following sentence closure are reduced to a single space;
 453 .Xr groff 1
 454 retains spaces.
 455 .
 456 .It
 457 Sentences are unilaterally monospaced.
 458 .El
 459 .
 460 .
 461 .Ss HTML/XHTML Compatibility
 462 .Bl -bullet -compact
 463 .It
 464 The
 465 .Sq \efP
 466 escape will revert the font to the previous
 467 .Sq \ef
 468 escape, not to the last rendered decoration, which is now dictated by
 469 CSS instead of hard-coded.  It also will not span past the current
 470 scope, for the same reason.  Note that in
 471 .Sx ASCII Output
 472 mode, this will work fine.
 473 .It
 474 The
 475 .Xr mdoc 7
 476 .Sq \&Bl \-hang
 477 and
 478 .Sq \&Bl \-tag
 479 list types render similarly (no break following overreached left-hand
 480 side) due to the expressive constraints of HTML.
 481 .
 482 .It
 483 The
 484 .Xr man 7
 485 .Sq IP
 486 and
 487 .Sq TP
 488 lists render similarly.
 489 .El
 490 .
 491 .
 492 .Sh SEE ALSO
 493 .Xr mandoc_char 7 ,
 494 .Xr mdoc 7 ,
 495 .Xr man 7
 496 .
 497 .Sh AUTHORS
 498 The
 499 .Nm
 500 utility was written by
 501 .An Kristaps Dzonsons Aq kristaps@kth.se .
 502 .
 503 .
 504 .Sh CAVEATS
 505 The
 506 .Fl T Ns Ar html
 507 and
 508 .Fl T Ns Ar xhtml
 509 CSS2 styling used for
 510 .Fl m Ns Ar doc
 511 input lists does not render properly in older browsers, such as Internet
 512 Explorer 6 and earlier.
 513 .Pp
 514 In
 515 .Fl T Ns Ar html
 516 and
 517 .Fl T Ns Ar xhtml ,
 518 the maximum size of an element attribute is determined by
 519 .Dv BUFSIZ ,
 520 which is usually 1024 bytes.  Be aware of this when setting long link
 521 formats, e.g.,
 522 .Fl O Ns Ar style=really/long/link .
 523 .Pp
 524 The
 525 .Fl T Ns Ar html
 526 and
 527 .Fl T Ns Ar xhtml
 528 output modes don't render the
 529 .Sq \es
 530 font size escape documented in
 531 .Xr mdoc 7
 532 and
 533 .Xr man 7 .
 534 .Pp
 535 Nesting elements within next-line element scopes of
 536 .Fl m Ns Ar an ,
 537 such as
 538 .Sq br
 539 within an empty
 540 .Sq B ,
 541 will confuse
 542 .Fl T Ns Ar html
 543 and
 544 .Fl T Ns Ar xhtml
 545 and cause them to forget the formatting of the prior next-line scope.
 546 .Pp
 547 The
 548 .Sq i
 549 macro in
 550 .Fl m Ns Ar an
 551 should italicise all subsequent text if a line argument is not provided.
 552 This behaviour is not implemented.