mandoc.1

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