contrib/mdocml/mandoc.1

   1 .\"     $Id: mandoc.1,v 1.85 2011/02/09 10:03:02 kristaps 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: February 9 2011 $
  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 m Ns Ar format
  27 .Op Fl O Ns Ar option
  28 .Op Fl T Ns Ar output
  29 .Op Fl W Ns Ar level
  30 .Op Ar file...
  31 .Sh DESCRIPTION
  32 The
  33 .Nm
  34 utility formats
  35 .Ux
  36 manual pages for display.
  37 The arguments are as follows:
  38 .Bl -tag -width Ds
  39 .It Fl m Ns Ar format
  40 Input format.
  41 See
  42 .Sx Input Formats
  43 for available formats.
  44 Defaults to
  45 .Fl m Ns Cm andoc .
  46 .It Fl O Ns Ar option
  47 Comma-separated output options.
  48 .It Fl T Ns Ar output
  49 Output format.
  50 See
  51 .Sx Output Formats
  52 for available formats.
  53 Defaults to
  54 .Fl T Ns Cm ascii .
  55 .It Fl V
  56 Print version and exit.
  57 .It Fl W Ns Ar level
  58 Specify the minimum message
  59 .Ar level
  60 to be reported on the standard error output and to affect the exit status.
  61 The
  62 .Ar level
  63 can be
  64 .Cm warning ,
  65 .Cm error ,
  66 or
  67 .Cm fatal .
  68 The default is
  69 .Fl W Ns Cm fatal ;
  70 .Fl W Ns Cm all
  71 is an alias for
  72 .Fl W Ns Cm warning .
  73 See
  74 .Sx EXIT STATUS
  75 and
  76 .Sx DIAGNOSTICS
  77 for details.
  78 .Pp
  79 The special option
  80 .Fl W Ns Cm stop
  81 tells
  82 .Nm
  83 to exit after parsing a file that causes warnings or errors of at least
  84 the requested level.
  85 No formatted output will be produced from that file.
  86 If both a
  87 .Ar level
  88 and
  89 .Cm stop
  90 are requested, they can be joined with a comma, for example
  91 .Fl W Ns Cm error , Ns Cm stop .
  92 .It Ar file
  93 Read input from zero or more files.
  94 If unspecified, reads from stdin.
  95 If multiple files are specified,
  96 .Nm
  97 will halt with the first failed parse.
  98 .El
  99 .Pp
 100 By default,
 101 .Nm
 102 reads
 103 .Xr mdoc 7
 104 or
 105 .Xr man 7
 106 text from stdin, implying
 107 .Fl m Ns Cm andoc ,
 108 and produces
 109 .Fl T Ns Cm ascii
 110 output.
 111 .Ss Input Formats
 112 The
 113 .Nm
 114 utility accepts
 115 .Xr mdoc 7
 116 and
 117 .Xr man 7
 118 input with
 119 .Fl m Ns Cm doc
 120 and
 121 .Fl m Ns Cm an ,
 122 respectively.
 123 The
 124 .Xr mdoc 7
 125 format is
 126 .Em strongly
 127 recommended;
 128 .Xr man 7
 129 should only be used for legacy manuals.
 130 .Pp
 131 A third option,
 132 .Fl m Ns Cm andoc ,
 133 which is also the default, determines encoding on-the-fly: if the first
 134 non-comment macro is
 135 .Sq \&Dd
 136 or
 137 .Sq \&Dt ,
 138 the
 139 .Xr mdoc 7
 140 parser is used; otherwise, the
 141 .Xr man 7
 142 parser is used.
 143 .Pp
 144 If multiple
 145 files are specified with
 146 .Fl m Ns Cm andoc ,
 147 each has its file-type determined this way.
 148 If multiple files are
 149 specified and
 150 .Fl m Ns Cm doc
 151 or
 152 .Fl m Ns Cm an
 153 is specified, then this format is used exclusively.
 154 .Ss Output Formats
 155 The
 156 .Nm
 157 utility accepts the following
 158 .Fl T
 159 arguments, which correspond to output modes:
 160 .Bl -tag -width Ds
 161 .It Fl T Ns Cm ascii
 162 Produce 7-bit ASCII output.
 163 This is the default.
 164 See
 165 .Sx ASCII Output .
 166 .It Fl T Ns Cm html
 167 Produce strict CSS1/HTML-4.01 output.
 168 See
 169 .Sx HTML Output .
 170 .It Fl T Ns Cm lint
 171 Parse only: produce no output.
 172 Implies
 173 .Fl W Ns Cm warning .
 174 .It Fl T Ns Cm pdf
 175 Produce PDF output.
 176 See
 177 .Sx PDF Output .
 178 .It Fl T Ns Cm ps
 179 Produce PostScript output.
 180 See
 181 .Sx PostScript Output .
 182 .It Fl T Ns Cm tree
 183 Produce an indented parse tree.
 184 .It Fl T Ns Cm xhtml
 185 Produce strict CSS1/XHTML-1.0 output.
 186 See
 187 .Sx XHTML Output .
 188 .El
 189 .Pp
 190 If multiple input files are specified, these will be processed by the
 191 corresponding filter in-order.
 192 .Ss ASCII Output
 193 Output produced by
 194 .Fl T Ns Cm ascii ,
 195 which is the default, is rendered in standard 7-bit ASCII documented in
 196 .Xr ascii 7 .
 197 .Pp
 198 Font styles are applied by using back-spaced encoding such that an
 199 underlined character
 200 .Sq c
 201 is rendered as
 202 .Sq _ Ns \e[bs] Ns c ,
 203 where
 204 .Sq \e[bs]
 205 is the back-space character number 8.
 206 Emboldened characters are rendered as
 207 .Sq c Ns \e[bs] Ns c .
 208 .Pp
 209 The special characters documented in
 210 .Xr mandoc_char 7
 211 are rendered best-effort in an ASCII equivalent.
 212 .Pp
 213 Output width is limited to 78 visible columns unless literal input lines
 214 exceed this limit.
 215 .Pp
 216 The following
 217 .Fl O
 218 arguments are accepted:
 219 .Bl -tag -width Ds
 220 .It Cm width Ns = Ns Ar width
 221 The output width is set to
 222 .Ar width ,
 223 which will normalise to \(>=60.
 224 .El
 225 .Ss HTML Output
 226 Output produced by
 227 .Fl T Ns Cm html
 228 conforms to HTML-4.01 strict.
 229 .Pp
 230 The
 231 .Pa example.style.css
 232 file documents style-sheet classes available for customising output.
 233 If a style-sheet is not specified with
 234 .Fl O Ns Ar style ,
 235 .Fl T Ns Cm html
 236 defaults to simple output readable in any graphical or text-based web
 237 browser.
 238 .Pp
 239 Special characters are rendered in decimal-encoded UTF-8.
 240 .Pp
 241 The following
 242 .Fl O
 243 arguments are accepted:
 244 .Bl -tag -width Ds
 245 .It Cm includes Ns = Ns Ar fmt
 246 The string
 247 .Ar fmt ,
 248 for example,
 249 .Ar ../src/%I.html ,
 250 is used as a template for linked header files (usually via the
 251 .Sq \&In
 252 macro).
 253 Instances of
 254 .Sq \&%I
 255 are replaced with the include filename.
 256 The default is not to present a
 257 hyperlink.
 258 .It Cm man Ns = Ns Ar fmt
 259 The string
 260 .Ar fmt ,
 261 for example,
 262 .Ar ../html%S/%N.%S.html ,
 263 is used as a template for linked manuals (usually via the
 264 .Sq \&Xr
 265 macro).
 266 Instances of
 267 .Sq \&%N
 268 and
 269 .Sq %S
 270 are replaced with the linked manual's name and section, respectively.
 271 If no section is included, section 1 is assumed.
 272 The default is not to
 273 present a hyperlink.
 274 .It Cm style Ns = Ns Ar style.css
 275 The file
 276 .Ar style.css
 277 is used for an external style-sheet.
 278 This must be a valid absolute or
 279 relative URI.
 280 .El
 281 .Ss PostScript Output
 282 PostScript
 283 .Qq Adobe-3.0
 284 Level-2 pages may be generated by
 285 .Fl T Ns Cm ps .
 286 Output pages default to letter sized and are rendered in the Times font
 287 family, 11-point.
 288 Margins are calculated as 1/9 the page length and width.
 289 Line-height is 1.4m.
 290 .Pp
 291 Special characters are rendered as in
 292 .Sx ASCII Output .
 293 .Pp
 294 The following
 295 .Fl O
 296 arguments are accepted:
 297 .Bl -tag -width Ds
 298 .It Cm paper Ns = Ns Ar name
 299 The paper size
 300 .Ar name
 301 may be one of
 302 .Ar a3 ,
 303 .Ar a4 ,
 304 .Ar a5 ,
 305 .Ar legal ,
 306 or
 307 .Ar letter .
 308 You may also manually specify dimensions as
 309 .Ar NNxNN ,
 310 width by height in millimetres.
 311 If an unknown value is encountered,
 312 .Ar letter
 313 is used.
 314 .El
 315 .Ss PDF Output
 316 PDF-1.1 output may be generated by
 317 .Fl T Ns Cm pdf .
 318 See
 319 .Sx PostScript Output
 320 for
 321 .Fl O
 322 arguments and defaults.
 323 .Ss XHTML Output
 324 Output produced by
 325 .Fl T Ns Cm xhtml
 326 conforms to XHTML-1.0 strict.
 327 .Pp
 328 See
 329 .Sx HTML Output
 330 for details; beyond generating XHTML tags instead of HTML tags, these
 331 output modes are identical.
 332 .Sh EXIT STATUS
 333 The
 334 .Nm
 335 utility exits with one of the following values, controlled by the message
 336 .Ar level
 337 associated with the
 338 .Fl W
 339 option:
 340 .Pp
 341 .Bl -tag -width Ds -compact
 342 .It 0
 343 No warnings or errors occurred, or those that did were ignored because
 344 they were lower than the requested
 345 .Ar level .
 346 .It 2
 347 At least one warning occurred, but no error, and
 348 .Fl W Ns Cm warning
 349 was specified.
 350 .It 3
 351 At least one parsing error occurred, but no fatal error, and
 352 .Fl W Ns Cm error
 353 or
 354 .Fl W Ns Cm warning
 355 was specified.
 356 .It 4
 357 A fatal parsing error occurred.
 358 .It 5
 359 Invalid command line arguments were specified.
 360 No input files have been read.
 361 .It 6
 362 An operating system error occurred, for example memory exhaustion or an
 363 error accessing input files.
 364 Such errors cause
 365 .Nm
 366 to exit at once, possibly in the middle of parsing or formatting a file.
 367 .El
 368 .Pp
 369 Note that selecting
 370 .Fl T Ns Cm lint
 371 output mode implies
 372 .Fl W Ns Cm warning .
 373 .Sh EXAMPLES
 374 To page manuals to the terminal:
 375 .Pp
 376 .Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less
 377 .Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less
 378 .Pp
 379 To produce HTML manuals with
 380 .Ar style.css
 381 as the style-sheet:
 382 .Pp
 383 .Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html
 384 .Pp
 385 To check over a large set of manuals:
 386 .Pp
 387 .Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]`
 388 .Pp
 389 To produce a series of PostScript manuals for A4 paper:
 390 .Pp
 391 .Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps
 392 .Sh DIAGNOSTICS
 393 Standard error messages reporting parsing errors are prefixed by
 394 .Pp
 395 .Sm off
 396 .D1 Ar file : line : column : \ level :
 397 .Sm on
 398 .Pp
 399 where the fields have the following meanings:
 400 .Bl -tag -width "column"
 401 .It Ar file
 402 The name of the input file causing the message.
 403 .It Ar line
 404 The line number in that input file.
 405 Line numbering starts at 1.
 406 .It Ar column
 407 The column number in that input file.
 408 Column numbering starts at 1.
 409 If the issue is caused by a word, the column number usually
 410 points to the first character of the word.
 411 .It Ar level
 412 The message level, printed in capital letters.
 413 .El
 414 .Pp
 415 Message levels have the following meanings:
 416 .Bl -tag -width "warning"
 417 .It Cm fatal
 418 The parser is unable to parse a given input file at all.
 419 No formatted output is produced from that input file.
 420 .It Cm error
 421 An input file contains syntax that cannot be safely interpreted,
 422 either because it is invalid or because
 423 .Nm
 424 does not implement it yet.
 425 By discarding part of the input or inserting missing tokens,
 426 the parser is able to continue, and the error does not prevent
 427 generation of formatted output, but typically, preparing that
 428 output involves information loss, broken document structure
 429 or unintended formatting.
 430 .It Cm warning
 431 An input file uses obsolete, discouraged or non-portable syntax.
 432 All the same, the meaning of the input is unambiguous and a correct
 433 rendering can be produced.
 434 Documents causing warnings may render poorly when using other
 435 formatting tools instead of
 436 .Nm .
 437 .El
 438 .Pp
 439 Messages of the
 440 .Cm warning
 441 and
 442 .Cm error
 443 levels are hidden unless their level, or a lower level, is requested using a
 444 .Fl W
 445 option or
 446 .Fl T Ns Cm lint
 447 output mode.
 448 .Pp
 449 The
 450 .Nm
 451 utility may also print messages related to invalid command line arguments
 452 or operating system errors, for example when memory is exhausted or
 453 input files cannot be read.
 454 Such messages do not carry the prefix described above.
 455 .Sh COMPATIBILITY
 456 This section summarises
 457 .Nm
 458 compatibility with GNU troff.
 459 Each input and output format is separately noted.
 460 .Ss ASCII Compatibility
 461 .Bl -bullet -compact
 462 .It
 463 The
 464 .Sq \&Bd \-literal
 465 and
 466 .Sq \&Bd \-unfilled
 467 macros of
 468 .Xr mdoc 7
 469 in
 470 .Fl T Ns Cm ascii
 471 are synonyms, as are \-filled and \-ragged.
 472 .It
 473 In GNU troff, the
 474 .Sq \&Pa
 475 .Xr mdoc 7
 476 macro does not underline when scoped under an
 477 .Sq \&It
 478 in the FILES section.
 479 This behaves correctly in
 480 .Nm .
 481 .It
 482 A list or display following the
 483 .Sq \&Ss
 484 .Xr mdoc 7
 485 macro in
 486 .Fl T Ns Cm ascii
 487 does not assert a prior vertical break, just as it doesn't with
 488 .Sq \&Sh .
 489 .It
 490 The
 491 .Sq \&na
 492 .Xr man 7
 493 macro in
 494 .Fl T Ns Cm ascii
 495 has no effect.
 496 .It
 497 Words aren't hyphenated.
 498 .It
 499 Sentences are unilaterally monospaced.
 500 .El
 501 .Ss HTML/XHTML Compatibility
 502 .Bl -bullet -compact
 503 .It
 504 The
 505 .Sq \efP
 506 escape will revert the font to the previous
 507 .Sq \ef
 508 escape, not to the last rendered decoration, which is now dictated by
 509 CSS instead of hard-coded.
 510 It also will not span past the current scope,
 511 for the same reason.
 512 Note that in
 513 .Sx ASCII Output
 514 mode, this will work fine.
 515 .It
 516 The
 517 .Xr mdoc 7
 518 .Sq \&Bl \-hang
 519 and
 520 .Sq \&Bl \-tag
 521 list types render similarly (no break following overreached left-hand
 522 side) due to the expressive constraints of HTML.
 523 .It
 524 The
 525 .Xr man 7
 526 .Sq IP
 527 and
 528 .Sq TP
 529 lists render similarly.
 530 .El
 531 .Sh SEE ALSO
 532 .Xr eqn 7 ,
 533 .Xr man 7 ,
 534 .Xr mandoc_char 7 ,
 535 .Xr mdoc 7 ,
 536 .Xr roff 7 ,
 537 .Xr tbl 7
 538 .Sh AUTHORS
 539 The
 540 .Nm
 541 utility was written by
 542 .An Kristaps Dzonsons Aq kristaps@bsd.lv .
 543 .Sh CAVEATS
 544 In
 545 .Fl T Ns Cm html
 546 and
 547 .Fl T Ns Cm xhtml ,
 548 the maximum size of an element attribute is determined by
 549 .Dv BUFSIZ ,
 550 which is usually 1024 bytes.
 551 Be aware of this when setting long link
 552 formats such as
 553 .Fl O Ns Cm style Ns = Ns Ar really/long/link .
 554 .Pp
 555 Nesting elements within next-line element scopes of
 556 .Fl m Ns Cm an ,
 557 such as
 558 .Sq br
 559 within an empty
 560 .Sq B ,
 561 will confuse
 562 .Fl T Ns Cm html
 563 and
 564 .Fl T Ns Cm xhtml
 565 and cause them to forget the formatting of the prior next-line scope.
 566 .Pp
 567 The
 568 .Sq \(aq
 569 control character is an alias for the standard macro control character
 570 and does not emit a line-break as stipulated in GNU troff.