usr.bin/mandoc/mandoc.1

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