mandoc.1

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