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