mandoc.1

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