mandoc.1

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