mandoc.1

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