| mandoc.1 (302408) | mandoc.1 (241675) |
|---|---|
| 1.\" $Id: mandoc.1,v 1.164 2015/11/05 17:47:51 schwarze Exp $ | 1.\" $Id: mandoc.1,v 1.100 2011/12/25 19:35:44 kristaps Exp $ |
| 2.\" 3.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> | 2.\" 3.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
| 4.\" Copyright (c) 2012, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> | |
| 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" | 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.\" |
| 18.Dd $Mdocdate: November 5 2015 $ | 17.Dd $Mdocdate: December 25 2011 $ |
| 19.Dt MANDOC 1 20.Os 21.Sh NAME 22.Nm mandoc 23.Nd format and display UNIX manuals 24.Sh SYNOPSIS 25.Nm mandoc | 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 |
| 26.Op Fl acfhkl 27.Op Fl I Cm os Ns = Ns Ar name 28.Op Fl K Ar encoding | 25.Op Fl V |
| 29.Op Fl m Ns Ar format | 26.Op Fl m Ns Ar format |
| 30.Op Fl O Ar option 31.Op Fl T Ar output 32.Op Fl W Ar level | 27.Op Fl O Ns Ar option 28.Op Fl T Ns Ar output 29.Op Fl W Ns Ar level |
| 33.Op Ar 34.Sh DESCRIPTION 35The 36.Nm 37utility formats 38.Ux 39manual pages for display. 40.Pp 41By default, 42.Nm 43reads 44.Xr mdoc 7 45or 46.Xr man 7 47text from stdin, implying 48.Fl m Ns Cm andoc , 49and produces | 30.Op Ar 31.Sh DESCRIPTION 32The 33.Nm 34utility formats 35.Ux 36manual pages for display. 37.Pp 38By default, 39.Nm 40reads 41.Xr mdoc 7 42or 43.Xr man 7 44text from stdin, implying 45.Fl m Ns Cm andoc , 46and produces |
| 50.Fl T Cm locale | 47.Fl T Ns Cm ascii |
| 51output. 52.Pp | 48output. 49.Pp |
| 53The options are as follows: | 50The arguments are as follows: |
| 54.Bl -tag -width Ds | 51.Bl -tag -width Ds |
| 55.It Fl a 56If the standard output is a terminal device and 57.Fl c 58is not specified, use 59.Xr more 1 60to paginate the output, just like 61.Xr man 1 62would. 63.It Fl c 64Copy the formatted manual pages to the standard output without using 65.Xr more 1 66to paginate them. 67This is the default. 68It can be specified to override 69.Fl a . 70.It Fl f 71A synonym for 72.Xr whatis 1 . 73This overrides any earlier 74.Fl k 75and 76.Fl l 77options. 78.It Fl I Cm os Ns = Ns Ar name 79Override the default operating system 80.Ar name 81for the 82.Xr mdoc 7 83.Sq \&Os 84and for the 85.Xr man 7 86.Sq \&TH 87macro. 88.It Fl h 89Display only the SYNOPSIS lines. 90Implies 91.Fl c . 92.It Fl K Ar encoding 93Specify the input encoding. 94The supported 95.Ar encoding 96arguments are 97.Cm us-ascii , 98.Cm iso-8859-1 , 99and 100.Cm utf-8 . 101If not specified, autodetection uses the first match: 102.Bl -tag -width iso-8859-1 103.It Cm utf-8 104if the first three bytes of the input file 105are the UTF-8 byte order mark (BOM, 0xefbbbf) 106.It Ar encoding 107if the first or second line of the input file matches the 108.Sy emacs 109mode line format 110.Pp 111.D1 .\e" -*- Oo ...; Oc coding: Ar encoding ; No -*- 112.It Cm utf-8 113if the first non-ASCII byte in the file introduces a valid UTF-8 sequence 114.It Cm iso-8859-1 115otherwise 116.El 117.It Fl k 118A synonym for 119.Xr apropos 1 . 120This overrides any earlier 121.Fl f 122and 123.Fl l 124options. 125.It Fl l 126A synonym for 127.Fl a . 128Also reverts any earlier 129.Fl f 130and 131.Fl k 132options. | |
| 133.It Fl m Ns Ar format 134Input format. 135See 136.Sx Input Formats 137for available formats. 138Defaults to 139.Fl m Ns Cm andoc . | 52.It Fl m Ns Ar format 53Input format. 54See 55.Sx Input Formats 56for available formats. 57Defaults to 58.Fl m Ns Cm andoc . |
| 140.It Fl O Ar option | 59.It Fl O Ns Ar option |
| 141Comma-separated output options. | 60Comma-separated output options. |
| 142.It Fl T Ar output | 61.It Fl T Ns Ar output |
| 143Output format. 144See 145.Sx Output Formats 146for available formats. 147Defaults to | 62Output format. 63See 64.Sx Output Formats 65for available formats. 66Defaults to |
| 148.Fl T Cm locale . 149.It Fl W Ar level | 67.Fl T Ns Cm ascii . 68.It Fl V 69Print version and exit. 70.It Fl W Ns Ar level |
| 150Specify the minimum message 151.Ar level 152to be reported on the standard error output and to affect the exit status. 153The 154.Ar level 155can be 156.Cm warning , 157.Cm error , 158or | 71Specify the minimum message 72.Ar level 73to be reported on the standard error output and to affect the exit status. 74The 75.Ar level 76can be 77.Cm warning , 78.Cm error , 79or |
| 159.Cm unsupp ; 160.Cm all | 80.Cm fatal . 81The default is 82.Fl W Ns Cm fatal ; 83.Fl W Ns Cm all |
| 161is an alias for | 84is an alias for |
| 162.Cm warning . 163By default, 164.Nm 165is silent. | 85.Fl W Ns Cm warning . |
| 166See 167.Sx EXIT STATUS 168and 169.Sx DIAGNOSTICS 170for details. 171.Pp 172The special option | 86See 87.Sx EXIT STATUS 88and 89.Sx DIAGNOSTICS 90for details. 91.Pp 92The special option |
| 173.Fl W Cm stop | 93.Fl W Ns Cm stop |
| 174tells 175.Nm 176to exit after parsing a file that causes warnings or errors of at least 177the requested level. 178No formatted output will be produced from that file. 179If both a 180.Ar level 181and 182.Cm stop 183are requested, they can be joined with a comma, for example | 94tells 95.Nm 96to exit after parsing a file that causes warnings or errors of at least 97the requested level. 98No formatted output will be produced from that file. 99If both a 100.Ar level 101and 102.Cm stop 103are requested, they can be joined with a comma, for example |
| 184.Fl W Cm error , Ns Cm stop . | 104.Fl W Ns Cm error , Ns Cm stop . |
| 185.It Ar file 186Read input from zero or more files. 187If unspecified, reads from stdin. 188If multiple files are specified, 189.Nm 190will halt with the first failed parse. 191.El | 105.It Ar file 106Read input from zero or more files. 107If unspecified, reads from stdin. 108If multiple files are specified, 109.Nm 110will halt with the first failed parse. 111.El |
| 192.Pp 193In 194.Fl f 195and 196.Fl k 197mode, 198.Nm 199also supports the options 200.Fl CMmOSsw 201described in the 202.Xr apropos 1 203manual. | |
| 204.Ss Input Formats 205The 206.Nm 207utility accepts 208.Xr mdoc 7 209and 210.Xr man 7 211input with --- 33 unchanged lines hidden (view full) --- 245.Fl m Ns Cm an 246is specified, then this format is used exclusively. 247.Ss Output Formats 248The 249.Nm 250utility accepts the following 251.Fl T 252arguments, which correspond to output modes: | 112.Ss Input Formats 113The 114.Nm 115utility accepts 116.Xr mdoc 7 117and 118.Xr man 7 119input with --- 33 unchanged lines hidden (view full) --- 153.Fl m Ns Cm an 154is specified, then this format is used exclusively. 155.Ss Output Formats 156The 157.Nm 158utility accepts the following 159.Fl T 160arguments, which correspond to output modes: |
| 253.Bl -tag -width "-T locale" 254.It Fl T Cm ascii | 161.Bl -tag -width "-Tlocale" 162.It Fl T Ns Cm ascii |
| 255Produce 7-bit ASCII output. | 163Produce 7-bit ASCII output. |
| 164This is the default. |
|
| 256See 257.Sx ASCII Output . | 165See 166.Sx ASCII Output . |
| 258.It Fl T Cm html 259Produce HTML5, CSS1, and MathML output. | 167.It Fl T Ns Cm html 168Produce strict CSS1/HTML-4.01 output. |
| 260See 261.Sx HTML Output . | 169See 170.Sx HTML Output . |
| 262.It Fl T Cm lint | 171.It Fl T Ns Cm lint |
| 263Parse only: produce no output. 264Implies | 172Parse only: produce no output. 173Implies |
| 265.Fl W Cm warning . 266.It Fl T Cm locale | 174.Fl W Ns Cm warning . 175.It Fl T Ns Cm locale |
| 267Encode output using the current locale. | 176Encode output using the current locale. |
| 268This is the default. | |
| 269See 270.Sx Locale Output . | 177See 178.Sx Locale Output . |
| 271.It Fl T Cm man | 179.It Fl T Ns Cm man |
| 272Produce 273.Xr man 7 274format output. 275See 276.Sx Man Output . | 180Produce 181.Xr man 7 182format output. 183See 184.Sx Man Output . |
| 277.It Fl T Cm pdf | 185.It Fl T Ns Cm pdf |
| 278Produce PDF output. 279See 280.Sx PDF Output . | 186Produce PDF output. 187See 188.Sx PDF Output . |
| 281.It Fl T Cm ps | 189.It Fl T Ns Cm ps |
| 282Produce PostScript output. 283See 284.Sx PostScript Output . | 190Produce PostScript output. 191See 192.Sx PostScript Output . |
| 285.It Fl T Cm tree | 193.It Fl T Ns Cm tree |
| 286Produce an indented parse tree. | 194Produce an indented parse tree. |
| 287See 288.Sx Syntax tree output . 289.It Fl T Cm utf8 | 195.It Fl T Ns Cm utf8 |
| 290Encode output in the UTF\-8 multi-byte format. 291See 292.Sx UTF\-8 Output . | 196Encode output in the UTF\-8 multi-byte format. 197See 198.Sx UTF\-8 Output . |
| 293.It Fl T Cm xhtml 294This is a synonym for 295.Fl T Cm html . | 199.It Fl T Ns Cm xhtml 200Produce strict CSS1/XHTML-1.0 output. 201See 202.Sx XHTML Output . |
| 296.El 297.Pp 298If multiple input files are specified, these will be processed by the 299corresponding filter in-order. 300.Ss ASCII Output 301Output produced by | 203.El 204.Pp 205If multiple input files are specified, these will be processed by the 206corresponding filter in-order. 207.Ss ASCII Output 208Output produced by |
| 302.Fl T Cm ascii 303is rendered in standard 7-bit ASCII documented in | 209.Fl T Ns Cm ascii , 210which is the default, is rendered in standard 7-bit ASCII documented in |
| 304.Xr ascii 7 . 305.Pp 306Font styles are applied by using back-spaced encoding such that an 307underlined character 308.Sq c 309is rendered as 310.Sq _ Ns \e[bs] Ns c , 311where 312.Sq \e[bs] 313is the back-space character number 8. 314Emboldened characters are rendered as 315.Sq c Ns \e[bs] Ns c . 316.Pp 317The special characters documented in 318.Xr mandoc_char 7 319are rendered best-effort in an ASCII equivalent. | 211.Xr ascii 7 . 212.Pp 213Font styles are applied by using back-spaced encoding such that an 214underlined character 215.Sq c 216is rendered as 217.Sq _ Ns \e[bs] Ns c , 218where 219.Sq \e[bs] 220is the back-space character number 8. 221Emboldened characters are rendered as 222.Sq c Ns \e[bs] Ns c . 223.Pp 224The special characters documented in 225.Xr mandoc_char 7 226are rendered best-effort in an ASCII equivalent. |
| 227If no equivalent is found, 228.Sq \&? 229is used instead. |
|
| 320.Pp 321Output width is limited to 78 visible columns unless literal input lines 322exceed this limit. 323.Pp 324The following 325.Fl O 326arguments are accepted: 327.Bl -tag -width Ds --- 4 unchanged lines hidden (view full) --- 332.Xr mdoc 7 333and seven for 334.Xr man 7 . 335Increasing this is not recommended; it may result in degraded formatting, 336for example overfull lines or ugly line breaks. 337.It Cm width Ns = Ns Ar width 338The output width is set to 339.Ar width , | 230.Pp 231Output width is limited to 78 visible columns unless literal input lines 232exceed this limit. 233.Pp 234The following 235.Fl O 236arguments are accepted: 237.Bl -tag -width Ds --- 4 unchanged lines hidden (view full) --- 242.Xr mdoc 7 243and seven for 244.Xr man 7 . 245Increasing this is not recommended; it may result in degraded formatting, 246for example overfull lines or ugly line breaks. 247.It Cm width Ns = Ns Ar width 248The output width is set to 249.Ar width , |
| 340which will normalise to \(>=58. | 250which will normalise to \(>=60. |
| 341.El 342.Ss HTML Output 343Output produced by | 251.El 252.Ss HTML Output 253Output produced by |
| 344.Fl T Cm html 345conforms to HTML5 using optional self-closing tags. 346Default styles use only CSS1. 347Equations rendered from 348.Xr eqn 7 349blocks use MathML. | 254.Fl T Ns Cm html 255conforms to HTML-4.01 strict. |
| 350.Pp 351The | 256.Pp 257The |
| 352.Pa mandoc.css | 258.Pa example.style.css |
| 353file documents style-sheet classes available for customising output. 354If a style-sheet is not specified with | 259file documents style-sheet classes available for customising output. 260If a style-sheet is not specified with |
| 355.Fl O Cm style , 356.Fl T Cm html 357defaults to simple output (via an embedded style-sheet) 358readable in any graphical or text-based web | 261.Fl O Ns Ar style , 262.Fl T Ns Cm html 263defaults to simple output readable in any graphical or text-based web |
| 359browser. 360.Pp 361Special characters are rendered in decimal-encoded UTF\-8. 362.Pp 363The following 364.Fl O 365arguments are accepted: 366.Bl -tag -width Ds 367.It Cm fragment | 264browser. 265.Pp 266Special characters are rendered in decimal-encoded UTF\-8. 267.Pp 268The following 269.Fl O 270arguments are accepted: 271.Bl -tag -width Ds 272.It Cm fragment |
| 368Omit the <!DOCTYPE> declaration and the <html>, <head>, and <body> 369elements and only emit the subtree below the <body> element. | 273Omit the 274.Aq !DOCTYPE 275declaration and the 276.Aq html , 277.Aq head , 278and 279.Aq body 280elements and only emit the subtree below the 281.Aq body 282element. |
| 370The 371.Cm style 372argument will be ignored. 373This is useful when embedding manual content within existing documents. 374.It Cm includes Ns = Ns Ar fmt 375The string 376.Ar fmt , 377for example, --- 26 unchanged lines hidden (view full) --- 404The file 405.Ar style.css 406is used for an external style-sheet. 407This must be a valid absolute or 408relative URI. 409.El 410.Ss Locale Output 411Locale-depending output encoding is triggered with | 283The 284.Cm style 285argument will be ignored. 286This is useful when embedding manual content within existing documents. 287.It Cm includes Ns = Ns Ar fmt 288The string 289.Ar fmt , 290for example, --- 26 unchanged lines hidden (view full) --- 317The file 318.Ar style.css 319is used for an external style-sheet. 320This must be a valid absolute or 321relative URI. 322.El 323.Ss Locale Output 324Locale-depending output encoding is triggered with |
| 412.Fl T Cm locale . 413This is the default. 414.Pp | 325.Fl T Ns Cm locale . |
| 415This option is not available on all systems: systems without locale 416support, or those whose internal representation is not natively UCS-4, 417will fall back to | 326This option is not available on all systems: systems without locale 327support, or those whose internal representation is not natively UCS-4, 328will fall back to |
| 418.Fl T Cm ascii . | 329.Fl T Ns Cm ascii . |
| 419See 420.Sx ASCII Output 421for font style specification and available command-line arguments. 422.Ss Man Output 423Translate input format into 424.Xr man 7 425output format. | 330See 331.Sx ASCII Output 332for font style specification and available command-line arguments. 333.Ss Man Output 334Translate input format into 335.Xr man 7 336output format. |
| 426This is useful for distributing manual sources to legacy systems | 337This is useful for distributing manual sources to legancy systems |
| 427lacking 428.Xr mdoc 7 429formatters. 430.Pp 431If 432.Xr mdoc 7 433is passed as input, it is translated into 434.Xr man 7 . --- 5 unchanged lines hidden (view full) --- 440requests. 441The parser is also run, and as usual, the 442.Fl W 443level controls which 444.Sx DIAGNOSTICS 445are displayed before copying the input to the output. 446.Ss PDF Output 447PDF-1.1 output may be generated by | 338lacking 339.Xr mdoc 7 340formatters. 341.Pp 342If 343.Xr mdoc 7 344is passed as input, it is translated into 345.Xr man 7 . --- 5 unchanged lines hidden (view full) --- 351requests. 352The parser is also run, and as usual, the 353.Fl W 354level controls which 355.Sx DIAGNOSTICS 356are displayed before copying the input to the output. 357.Ss PDF Output 358PDF-1.1 output may be generated by |
| 448.Fl T Cm pdf . | 359.Fl T Ns Cm pdf . |
| 449See 450.Sx PostScript Output 451for 452.Fl O 453arguments and defaults. 454.Ss PostScript Output 455PostScript 456.Qq Adobe-3.0 457Level-2 pages may be generated by | 360See 361.Sx PostScript Output 362for 363.Fl O 364arguments and defaults. 365.Ss PostScript Output 366PostScript 367.Qq Adobe-3.0 368Level-2 pages may be generated by |
| 458.Fl T Cm ps . | 369.Fl T Ns Cm ps . |
| 459Output pages default to letter sized and are rendered in the Times font 460family, 11-point. 461Margins are calculated as 1/9 the page length and width. 462Line-height is 1.4m. 463.Pp 464Special characters are rendered as in 465.Sx ASCII Output . 466.Pp --- 15 unchanged lines hidden (view full) --- 482.Ar NNxNN , 483width by height in millimetres. 484If an unknown value is encountered, 485.Ar letter 486is used. 487.El 488.Ss UTF\-8 Output 489Use | 370Output pages default to letter sized and are rendered in the Times font 371family, 11-point. 372Margins are calculated as 1/9 the page length and width. 373Line-height is 1.4m. 374.Pp 375Special characters are rendered as in 376.Sx ASCII Output . 377.Pp --- 15 unchanged lines hidden (view full) --- 393.Ar NNxNN , 394width by height in millimetres. 395If an unknown value is encountered, 396.Ar letter 397is used. 398.El 399.Ss UTF\-8 Output 400Use |
| 490.Fl T Cm utf8 | 401.Fl T Ns Cm utf8 |
| 491to force a UTF\-8 locale. 492See 493.Sx Locale Output 494for details and options. | 402to force a UTF\-8 locale. 403See 404.Sx Locale Output 405for details and options. |
| 495.Ss Syntax tree output 496Use 497.Fl T Cm tree 498to show a human readable representation of the syntax tree. 499It is useful for debugging the source code of manual pages. 500The exact format is subject to change, so don't write parsers for it. 501Each output line shows one syntax tree node. 502Child nodes are indented with respect to their parent node. 503The columns are: | 406.Ss XHTML Output 407Output produced by 408.Fl T Ns Cm xhtml 409conforms to XHTML-1.0 strict. |
| 504.Pp | 410.Pp |
| 505.Bl -enum -compact 506.It 507For macro nodes, the macro name; for text and 508.Xr tbl 7 509nodes, the content. 510There is a special format for 511.Xr eqn 7 512nodes. 513.It 514Node type (text, elem, block, head, body, body-end, tail, tbl, eqn). 515.It 516Flags: 517.Bl -dash -compact 518.It 519An opening parenthesis if the node is an opening delimiter. 520.It 521An asterisk if the node starts a new input line. 522.It 523The input line number (starting at one). 524.It 525A colon. 526.It 527The input column number (starting at one). 528.It 529A closing parenthesis if the node is a closing delimiter. 530.It 531A full stop if the node ends a sentence. 532.El 533.El 534.Sh ENVIRONMENT 535.Bl -tag -width MANPAGER 536.It Ev MANPAGER 537Any non-empty value of the environment variable 538.Ev MANPAGER 539will be used instead of the standard pagination program, 540.Xr more 1 . 541.It Ev PAGER 542Specifies the pagination program to use when 543.Ev MANPAGER 544is not defined. 545If neither PAGER nor MANPAGER is defined, 546.Xr more 1 547.Fl s 548will be used. 549.El | 411See 412.Sx HTML Output 413for details; beyond generating XHTML tags instead of HTML tags, these 414output modes are identical. |
| 550.Sh EXIT STATUS 551The 552.Nm 553utility exits with one of the following values, controlled by the message 554.Ar level 555associated with the 556.Fl W 557option: 558.Pp 559.Bl -tag -width Ds -compact 560.It 0 561No warnings or errors occurred, or those that did were ignored because 562they were lower than the requested 563.Ar level . 564.It 2 565At least one warning occurred, but no error, and | 415.Sh EXIT STATUS 416The 417.Nm 418utility exits with one of the following values, controlled by the message 419.Ar level 420associated with the 421.Fl W 422option: 423.Pp 424.Bl -tag -width Ds -compact 425.It 0 426No warnings or errors occurred, or those that did were ignored because 427they were lower than the requested 428.Ar level . 429.It 2 430At least one warning occurred, but no error, and |
| 566.Fl W Cm warning | 431.Fl W Ns Cm warning |
| 567was specified. 568.It 3 | 432was specified. 433.It 3 |
| 569At least one parsing error occurred, 570but no unsupported feature was encountered, and 571.Fl W Cm error | 434At least one parsing error occurred, but no fatal error, and 435.Fl W Ns Cm error |
| 572or | 436or |
| 573.Fl W Cm warning | 437.Fl W Ns Cm warning |
| 574was specified. 575.It 4 | 438was specified. 439.It 4 |
| 576At least one unsupported feature was encountered, and 577.Fl W Cm unsupp , 578.Fl W Cm error 579or 580.Fl W Cm warning 581was specified. | 440A fatal parsing error occurred. |
| 582.It 5 583Invalid command line arguments were specified. 584No input files have been read. 585.It 6 | 441.It 5 442Invalid command line arguments were specified. 443No input files have been read. 444.It 6 |
| 586An operating system error occurred, for example exhaustion 587of memory, file descriptors, or process table entries. | 445An operating system error occurred, for example memory exhaustion or an 446error accessing input files. |
| 588Such errors cause 589.Nm 590to exit at once, possibly in the middle of parsing or formatting a file. 591.El 592.Pp 593Note that selecting | 447Such errors cause 448.Nm 449to exit at once, possibly in the middle of parsing or formatting a file. 450.El 451.Pp 452Note that selecting |
| 594.Fl T Cm lint | 453.Fl T Ns Cm lint |
| 595output mode implies | 454output mode implies |
| 596.Fl W Cm warning . | 455.Fl W Ns Cm warning . |
| 597.Sh EXAMPLES 598To page manuals to the terminal: 599.Pp | 456.Sh EXAMPLES 457To page manuals to the terminal: 458.Pp |
| 600.Dl $ mandoc \-W all,stop mandoc.1 2\*(Gt&1 | less | 459.Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less |
| 601.Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less 602.Pp 603To produce HTML manuals with | 460.Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less 461.Pp 462To produce HTML manuals with |
| 604.Pa mandoc.css | 463.Ar style.css |
| 605as the style-sheet: 606.Pp | 464as the style-sheet: 465.Pp |
| 607.Dl $ mandoc \-T html -O style=mandoc.css mdoc.7 \*(Gt mdoc.7.html | 466.Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html |
| 608.Pp 609To check over a large set of manuals: 610.Pp | 467.Pp 468To check over a large set of manuals: 469.Pp |
| 611.Dl $ mandoc \-T lint \(gafind /usr/src -name \e*\e.[1-9]\(ga | 470.Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]` |
| 612.Pp 613To produce a series of PostScript manuals for A4 paper: 614.Pp | 471.Pp 472To produce a series of PostScript manuals for A4 paper: 473.Pp |
| 615.Dl $ mandoc \-T ps \-O paper=a4 mdoc.7 man.7 \*(Gt manuals.ps | 474.Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps |
| 616.Pp 617Convert a modern 618.Xr mdoc 7 619manual to the older 620.Xr man 7 621format, for use on systems lacking an 622.Xr mdoc 7 623parser: 624.Pp | 475.Pp 476Convert a modern 477.Xr mdoc 7 478manual to the older 479.Xr man 7 480format, for use on systems lacking an 481.Xr mdoc 7 482parser: 483.Pp |
| 625.Dl $ mandoc \-T man foo.mdoc \*(Gt foo.man | 484.Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man |
| 626.Sh DIAGNOSTICS | 485.Sh DIAGNOSTICS |
| 627Messages displayed by 628.Nm 629follow this format: | 486Standard error messages reporting parsing errors are prefixed by |
| 630.Pp | 487.Pp |
| 631.D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args | 488.Sm off 489.D1 Ar file : line : column : \ level : 490.Sm on |
| 632.Pp | 491.Pp |
| 633Line and column numbers start at 1. 634Both are omitted for messages referring to an input file as a whole. 635Macro names and arguments are omitted where meaningless. 636Fatal messages about invalid command line arguments 637or operating system errors, for example when memory is exhausted, 638may also omit the 639.Ar file 640and 641.Ar level 642fields. | 492where the fields have the following meanings: 493.Bl -tag -width "column" 494.It Ar file 495The name of the input file causing the message. 496.It Ar line 497The line number in that input file. 498Line numbering starts at 1. 499.It Ar column 500The column number in that input file. 501Column numbering starts at 1. 502If the issue is caused by a word, the column number usually 503points to the first character of the word. 504.It Ar level 505The message level, printed in capital letters. 506.El |
| 643.Pp 644Message levels have the following meanings: 645.Bl -tag -width "warning" | 507.Pp 508Message levels have the following meanings: 509.Bl -tag -width "warning" |
| 646.It Cm unsupp 647An input file uses unsupported low-level 648.Xr roff 7 649features. 650The output may be incomplete and/or misformatted, 651so using GNU troff instead of 652.Nm 653to process the file may be preferable. | 510.It Cm fatal 511The parser is unable to parse a given input file at all. 512No formatted output is produced from that input file. |
| 654.It Cm error | 513.It Cm error |
| 655An input file contains invalid syntax that cannot be safely interpreted. | 514An input file contains syntax that cannot be safely interpreted, 515either because it is invalid or because 516.Nm 517does not implement it yet. |
| 656By discarding part of the input or inserting missing tokens, 657the parser is able to continue, and the error does not prevent 658generation of formatted output, but typically, preparing that 659output involves information loss, broken document structure | 518By discarding part of the input or inserting missing tokens, 519the parser is able to continue, and the error does not prevent 520generation of formatted output, but typically, preparing that 521output involves information loss, broken document structure |
| 660or unintended formatting, no matter whether 661.Nm 662or GNU troff is used. 663In many cases, the output of 664.Nm 665and GNU troff is identical, but in some, 666.Nm 667is more resilient than GNU troff with respect to malformed input. 668.Pp 669Non-existent or unreadable input files are also reported on the 670.Cm error 671level. 672In that case, the parser cannot even be started and no output 673is produced from those input files. | 522or unintended formatting. |
| 674.It Cm warning 675An input file uses obsolete, discouraged or non-portable syntax. 676All the same, the meaning of the input is unambiguous and a correct 677rendering can be produced. 678Documents causing warnings may render poorly when using other 679formatting tools instead of 680.Nm . 681.El 682.Pp 683Messages of the | 523.It Cm warning 524An input file uses obsolete, discouraged or non-portable syntax. 525All the same, the meaning of the input is unambiguous and a correct 526rendering can be produced. 527Documents causing warnings may render poorly when using other 528formatting tools instead of 529.Nm . 530.El 531.Pp 532Messages of the |
| 684.Cm warning , 685.Cm error , | 533.Cm warning |
| 686and | 534and |
| 687.Cm unsupp 688levels except those about non-existent or unreadable input files 689are hidden unless their level, or a lower level, is requested using a | 535.Cm error 536levels are hidden unless their level, or a lower level, is requested using a |
| 690.Fl W 691option or | 537.Fl W 538option or |
| 692.Fl T Cm lint | 539.Fl T Ns Cm lint |
| 693output mode. | 540output mode. |
| 694.Ss Warnings related to the document prologue 695.Bl -ohang 696.It Sy "missing manual title, using UNTITLED" 697.Pq mdoc 698A 699.Ic \&Dt 700macro has no arguments, or there is no 701.Ic \&Dt 702macro before the first non-prologue macro. 703.It Sy "missing manual title, using \(dq\(dq" 704.Pq man 705There is no 706.Ic \&TH 707macro, or it has no arguments. 708.It Sy "lower case character in document title" 709.Pq mdoc , man 710The title is still used as given in the 711.Ic \&Dt 712or 713.Ic \&TH 714macro. 715.It Sy "missing manual section, using \(dq\(dq" 716.Pq mdoc , man 717A 718.Ic \&Dt 719or 720.Ic \&TH 721macro lacks the mandatory section argument. 722.It Sy "unknown manual section" 723.Pq mdoc 724The section number in a 725.Ic \&Dt 726line is invalid, but still used. 727.It Sy "missing date, using today's date" 728.Pq mdoc, man 729The document was parsed as 730.Xr mdoc 7 731and it has no 732.Ic \&Dd 733macro, or the 734.Ic \&Dd 735macro has no arguments or only empty arguments; 736or the document was parsed as 737.Xr man 7 738and it has no 739.Ic \&TH 740macro, or the 741.Ic \&TH 742macro has less than three arguments or its third argument is empty. 743.It Sy "cannot parse date, using it verbatim" 744.Pq mdoc , man 745The date given in a 746.Ic \&Dd 747or 748.Ic \&TH 749macro does not follow the conventional format. 750.It Sy "missing Os macro, using \(dq\(dq" 751.Pq mdoc 752The default or current system is not shown in this case. 753.It Sy "duplicate prologue macro" 754.Pq mdoc 755One of the prologue macros occurs more than once. 756The last instance overrides all previous ones. 757.It Sy "late prologue macro" 758.Pq mdoc 759A 760.Ic \&Dd 761or 762.Ic \&Os 763macro occurs after some non-prologue macro, but still takes effect. 764.It Sy "skipping late title macro" 765.Pq mdoc | 541.Pp |
| 766The | 542The |
| 767.Ic \&Dt 768macro appears after the first non-prologue macro. 769Traditional formatters cannot handle this because 770they write the page header before parsing the document body. 771Even though this technical restriction does not apply to 772.Nm , 773traditional semantics is preserved. 774The late macro is discarded including its arguments. 775.It Sy "prologue macros out of order" 776.Pq mdoc 777The prologue macros are not given in the conventional order 778.Ic \&Dd , 779.Ic \&Dt , 780.Ic \&Os . 781All three macros are used even when given in another order. 782.El 783.Ss Warnings regarding document structure 784.Bl -ohang 785.It Sy ".so is fragile, better use ln(1)" 786.Pq roff 787Including files only works when the parser program runs with the correct 788current working directory. 789.It Sy "no document body" 790.Pq mdoc , man 791The document body contains neither text nor macros. 792An empty document is shown, consisting only of a header and a footer line. 793.It Sy "content before first section header" 794.Pq mdoc , man 795Some macros or text precede the first 796.Ic \&Sh 797or 798.Ic \&SH 799section header. 800The offending macros and text are parsed and added to the top level 801of the syntax tree, outside any section block. 802.It Sy "first section is not NAME" 803.Pq mdoc 804The argument of the first 805.Ic \&Sh 806macro is not 807.Sq NAME . 808This may confuse 809.Xr makewhatis 8 810and 811.Xr apropos 1 . 812.It Sy "NAME section without name" 813.Pq mdoc 814The NAME section does not contain any 815.Ic \&Nm 816child macro. 817.It Sy "NAME section without description" 818.Pq mdoc 819The NAME section lacks the mandatory 820.Ic \&Nd 821child macro. 822.It Sy "description not at the end of NAME" 823.Pq mdoc 824The NAME section does contain an 825.Ic \&Nd 826child macro, but other content follows it. 827.It Sy "bad NAME section content" 828.Pq mdoc 829The NAME section contains plain text or macros other than 830.Ic \&Nm 831and 832.Ic \&Nd . 833.It Sy "missing description line, using \(dq\(dq" 834.Pq mdoc | 543.Nm 544utility may also print messages related to invalid command line arguments 545or operating system errors, for example when memory is exhausted or 546input files cannot be read. 547Such messages do not carry the prefix described above. 548.Sh COMPATIBILITY 549This section summarises 550.Nm 551compatibility with GNU troff. 552Each input and output format is separately noted. 553.Ss ASCII Compatibility 554.Bl -bullet -compact 555.It 556Unrenderable unicode codepoints specified with 557.Sq \e[uNNNN] 558escapes are printed as 559.Sq \&? 560in mandoc. 561In GNU troff, these raise an error. 562.It |
| 835The | 563The |
| 836.Ic \&Nd 837macro lacks the required argument. 838The title line of the manual will end after the dash. 839.It Sy "sections out of conventional order" 840.Pq mdoc 841A standard section occurs after another section it usually precedes. 842All section titles are used as given, 843and the order of sections is not changed. 844.It Sy "duplicate section title" 845.Pq mdoc 846The same standard section title occurs more than once. 847.It Sy "unexpected section" 848.Pq mdoc 849A standard section header occurs in a section of the manual 850where it normally isn't useful. 851.It Sy "unusual Xr order" 852.Pq mdoc 853In the SEE ALSO section, an 854.Ic \&Xr 855macro with a lower section number follows one with a higher number, 856or two 857.Ic \&Xr 858macros referring to the same section are out of alphabetical order. 859.It Sy "unusual Xr punctuation" 860.Pq mdoc 861In the SEE ALSO section, punctuation between two 862.Ic \&Xr 863macros differs from a single comma, or there is trailing punctuation 864after the last 865.Ic \&Xr 866macro. 867.It Sy "AUTHORS section without An macro" 868.Pq mdoc 869An AUTHORS sections contains no 870.Ic \&An 871macros, or only empty ones. 872Probably, there are author names lacking markup. 873.El 874.Ss "Warnings related to macros and nesting" 875.Bl -ohang 876.It Sy "obsolete macro" 877.Pq mdoc 878See the | 564.Sq \&Bd \-literal 565and 566.Sq \&Bd \-unfilled 567macros of |
| 879.Xr mdoc 7 | 568.Xr mdoc 7 |
| 880manual for replacements. 881.It Sy "macro neither callable nor escaped" 882.Pq mdoc 883The name of a macro that is not callable appears on a macro line. 884It is printed verbatim. 885If the intention is to call it, move it to its own input line; 886otherwise, escape it by prepending 887.Sq \e& . 888.It Sy "skipping paragraph macro" 889In | 569in 570.Fl T Ns Cm ascii 571are synonyms, as are \-filled and \-ragged. 572.It 573In historic GNU troff, the 574.Sq \&Pa |
| 890.Xr mdoc 7 | 575.Xr mdoc 7 |
| 891documents, this happens 892.Bl -dash -compact | 576macro does not underline when scoped under an 577.Sq \&It 578in the FILES section. 579This behaves correctly in 580.Nm . |
| 893.It | 581.It |
| 894at the beginning and end of sections and subsections | 582A list or display following the 583.Sq \&Ss 584.Xr mdoc 7 585macro in 586.Fl T Ns Cm ascii 587does not assert a prior vertical break, just as it doesn't with 588.Sq \&Sh . |
| 895.It | 589.It |
| 896right before non-compact lists and displays 897.It 898at the end of items in non-column, non-compact lists 899.It 900and for multiple consecutive paragraph macros. 901.El 902In | 590The 591.Sq \&na |
| 903.Xr man 7 | 592.Xr man 7 |
| 904documents, it happens 905.Bl -dash -compact | 593macro in 594.Fl T Ns Cm ascii 595has no effect. |
| 906.It | 596.It |
| 907for empty 908.Ic \&P , 909.Ic \&PP , 910and 911.Ic \&LP 912macros 913.It 914for 915.Ic \&IP 916macros having neither head nor body arguments 917.It 918for 919.Ic \&br 920or 921.Ic \&sp 922right after 923.Ic \&SH 924or 925.Ic \&SS | 597Words aren't hyphenated. |
| 926.El | 598.El |
| 927.It Sy "moving paragraph macro out of list" 928.Pq mdoc 929A list item in a 930.Ic \&Bl 931list contains a trailing paragraph macro. 932The paragraph macro is moved after the end of the list. 933.It Sy "skipping no-space macro" 934.Pq mdoc 935An input line begins with an 936.Ic \&Ns 937macro. 938The macro is ignored. 939.It Sy "blocks badly nested" 940.Pq mdoc 941If two blocks intersect, one should completely contain the other. 942Otherwise, rendered output is likely to look strange in any output 943format, and rendering in SGML-based output formats is likely to be 944outright wrong because such languages do not support badly nested 945blocks at all. 946Typical examples of badly nested blocks are 947.Qq Ic \&Ao \&Bo \&Ac \&Bc 948and 949.Qq Ic \&Ao \&Bq \&Ac . 950In these examples, 951.Ic \&Ac 952breaks 953.Ic \&Bo 954and 955.Ic \&Bq , 956respectively. 957.It Sy "nested displays are not portable" 958.Pq mdoc 959A 960.Ic \&Bd , 961.Ic \&D1 , 962or 963.Ic \&Dl 964display occurs nested inside another 965.Ic \&Bd 966display. 967This works with 968.Nm , 969but fails with most other implementations. 970.It Sy "moving content out of list" 971.Pq mdoc 972A 973.Ic \&Bl 974list block contains text or macros before the first 975.Ic \&It 976macro. 977The offending children are moved before the beginning of the list. 978.It Sy "fill mode already enabled, skipping" 979.Pq man 980A 981.Ic \&fi 982request occurs even though the document is still in fill mode, 983or already switched back to fill mode. 984It has no effect. 985.It Sy "fill mode already disabled, skipping" 986.Pq man 987An 988.Ic \&nf 989request occurs even though the document already switched to no-fill mode 990and did not switch back to fill mode yet. 991It has no effect. 992.It Sy "line scope broken" 993.Pq man 994While parsing the next-line scope of the previous macro, 995another macro is found that prematurely terminates the previous one. 996The previous, interrupted macro is deleted from the parse tree. 997.El 998.Ss "Warnings related to missing arguments" 999.Bl -ohang 1000.It Sy "skipping empty request" 1001.Pq roff , eqn 1002The macro name is missing from a macro definition request, 1003or an 1004.Xr eqn 7 1005control statement or operation keyword lacks its required argument. 1006.It Sy "conditional request controls empty scope" 1007.Pq roff 1008A conditional request is only useful if any of the following 1009follows it on the same logical input line: 1010.Bl -dash -compact | 599.Ss HTML/XHTML Compatibility 600.Bl -bullet -compact |
| 1011.It 1012The | 601.It 602The |
| 1013.Sq \e{ 1014keyword to open a multi-line scope. | 603.Sq \efP 604escape will revert the font to the previous 605.Sq \ef 606escape, not to the last rendered decoration, which is now dictated by 607CSS instead of hard-coded. 608It also will not span past the current scope, 609for the same reason. 610Note that in 611.Sx ASCII Output 612mode, this will work fine. |
| 1015.It | 613.It |
| 1016A request or macro or some text, resulting in a single-line scope. 1017.It 1018The immediate end of the logical line without any intervening whitespace, 1019resulting in next-line scope. 1020.El 1021Here, a conditional request is followed by trailing whitespace only, 1022and there is no other content on its logical input line. 1023Note that it doesn't matter whether the logical input line is split 1024across multiple physical input lines using 1025.Sq \e 1026line continuation characters. 1027This is one of the rare cases 1028where trailing whitespace is syntactically significant. 1029The conditional request controls a scope containing whitespace only, 1030so it is unlikely to have a significant effect, 1031except that it may control a following 1032.Ic \&el 1033clause. 1034.It Sy "skipping empty macro" 1035.Pq mdoc 1036The indicated macro has no arguments and hence no effect. 1037.It Sy "empty block" 1038.Pq mdoc , man 1039A 1040.Ic \&Bd , 1041.Ic \&Bk , 1042.Ic \&Bl , 1043.Ic \&D1 , 1044.Ic \&Dl , 1045.Ic \&RS , 1046or 1047.Ic \&UR 1048block contains nothing in its body and will produce no output. 1049.It Sy "empty argument, using 0n" 1050.Pq mdoc 1051The required width is missing after 1052.Ic \&Bd 1053or 1054.Ic \&Bl 1055.Fl offset 1056or 1057.Fl width. 1058.It Sy "missing display type, using -ragged" 1059.Pq mdoc | |
| 1060The | 614The |
| 1061.Ic \&Bd 1062macro is invoked without the required display type. 1063.It Sy "list type is not the first argument" 1064.Pq mdoc 1065In a 1066.Ic \&Bl 1067macro, at least one other argument precedes the type argument. 1068The 1069.Nm 1070utility copes with any argument order, but some other | |
| 1071.Xr mdoc 7 | 615.Xr mdoc 7 |
| 1072implementations do not. 1073.It Sy "missing -width in -tag list, using 8n" 1074.Pq mdoc 1075Every 1076.Ic \&Bl 1077macro having the 1078.Fl tag 1079argument requires 1080.Fl width , 1081too. 1082.It Sy "missing utility name, using \(dq\(dq" 1083.Pq mdoc 1084The 1085.Ic \&Ex Fl std 1086macro is called without an argument before 1087.Ic \&Nm 1088has first been called with an argument. 1089.It Sy "missing function name, using \(dq\(dq" 1090.Pq mdoc 1091The 1092.Ic \&Fo 1093macro is called without an argument. 1094No function name is printed. 1095.It Sy "empty head in list item" 1096.Pq mdoc 1097In a 1098.Ic \&Bl 1099.Fl diag , 1100.Fl hang , 1101.Fl inset , 1102.Fl ohang , 1103or 1104.Fl tag 1105list, an 1106.Ic \&It 1107macro lacks the required argument. 1108The item head is left empty. 1109.It Sy "empty list item" 1110.Pq mdoc 1111In a 1112.Ic \&Bl 1113.Fl bullet , 1114.Fl dash , 1115.Fl enum , 1116or 1117.Fl hyphen 1118list, an 1119.Ic \&It 1120block is empty. 1121An empty list item is shown. 1122.It Sy "missing font type, using \efR" 1123.Pq mdoc 1124A 1125.Ic \&Bf 1126macro has no argument. 1127It switches to the default font. 1128.It Sy "unknown font type, using \efR" 1129.Pq mdoc 1130The 1131.Ic \&Bf 1132argument is invalid. 1133The default font is used instead. 1134.It Sy "nothing follows prefix" 1135.Pq mdoc 1136A 1137.Ic \&Pf 1138macro has no argument, or only one argument and no macro follows 1139on the same input line. 1140This defeats its purpose; in particular, spacing is not suppressed 1141before the text or macros following on the next input line. 1142.It Sy "empty reference block" 1143.Pq mdoc 1144An 1145.Ic \&Rs 1146macro is immediately followed by an 1147.Ic \&Re 1148macro on the next input line. 1149Such an empty block does not produce any output. 1150.It Sy "missing -std argument, adding it" 1151.Pq mdoc 1152An 1153.Ic \&Ex 1154or 1155.Ic \&Rv 1156macro lacks the required 1157.Fl std 1158argument. 1159The 1160.Nm 1161utility assumes 1162.Fl std 1163even when it is not specified, but other implementations may not. 1164.It Sy "missing option string, using \(dq\(dq" 1165.Pq man 1166The 1167.Ic \&OP 1168macro is invoked without any argument. 1169An empty pair of square brackets is shown. 1170.It Sy "missing resource identifier, using \(dq\(dq" 1171.Pq man 1172The 1173.Ic \&UR 1174macro is invoked without any argument. 1175An empty pair of angle brackets is shown. 1176.It Sy "missing eqn box, using \(dq\(dq" 1177.Pq eqn 1178A diacritic mark or a binary operator is found, 1179but there is nothing to the left of it. 1180An empty box is inserted. 1181.El 1182.Ss "Warnings related to bad macro arguments" 1183.Bl -ohang 1184.It Sy "unterminated quoted argument" 1185.Pq roff 1186Macro arguments can be enclosed in double quote characters 1187such that space characters and macro names contained in the quoted 1188argument need not be escaped. 1189The closing quote of the last argument of a macro can be omitted. 1190However, omitting it is not recommended because it makes the code 1191harder to read. 1192.It Sy "duplicate argument" 1193.Pq mdoc 1194A 1195.Ic \&Bd 1196or 1197.Ic \&Bl 1198macro has more than one 1199.Fl compact , 1200more than one 1201.Fl offset , 1202or more than one 1203.Fl width 1204argument. 1205All but the last instances of these arguments are ignored. 1206.It Sy "skipping duplicate argument" 1207.Pq mdoc 1208An 1209.Ic \&An 1210macro has more than one 1211.Fl split 1212or 1213.Fl nosplit 1214argument. 1215All but the first of these arguments are ignored. 1216.It Sy "skipping duplicate display type" 1217.Pq mdoc 1218A 1219.Ic \&Bd 1220macro has more than one type argument; the first one is used. 1221.It Sy "skipping duplicate list type" 1222.Pq mdoc 1223A 1224.Ic \&Bl 1225macro has more than one type argument; the first one is used. 1226.It Sy "skipping -width argument" 1227.Pq mdoc 1228A 1229.Ic \&Bl 1230.Fl column , 1231.Fl diag , 1232.Fl ohang , 1233.Fl inset , 1234or 1235.Fl item 1236list has a 1237.Fl width 1238argument. 1239That has no effect. 1240.It Sy "wrong number of cells" 1241In a line of a 1242.Ic \&Bl Fl column 1243list, the number of tabs or 1244.Ic \&Ta 1245macros is less than the number expected from the list header line 1246or exceeds the expected number by more than one. 1247Missing cells remain empty, and all cells exceeding the number of 1248columns are joined into one single cell. 1249.It Sy "unknown AT&T UNIX version" 1250.Pq mdoc 1251An 1252.Ic \&At 1253macro has an invalid argument. 1254It is used verbatim, with 1255.Qq "AT&T UNIX " 1256prefixed to it. 1257.It Sy "comma in function argument" 1258.Pq mdoc 1259An argument of an 1260.Ic \&Fa 1261or 1262.Ic \&Fn 1263macro contains a comma; it should probably be split into two arguments. 1264.It Sy "parenthesis in function name" 1265.Pq mdoc 1266The first argument of an 1267.Ic \&Fc 1268or 1269.Ic \&Fn 1270macro contains an opening or closing parenthesis; that's probably wrong, 1271parentheses are added automatically. 1272.It Sy "invalid content in Rs block" 1273.Pq mdoc 1274An 1275.Ic \&Rs 1276block contains plain text or non-% macros. 1277The bogus content is left in the syntax tree. 1278Formatting may be poor. 1279.It Sy "invalid Boolean argument" 1280.Pq mdoc 1281An 1282.Ic \&Sm 1283macro has an argument other than 1284.Cm on 1285or 1286.Cm off . 1287The invalid argument is moved out of the macro, which leaves the macro 1288empty, causing it to toggle the spacing mode. 1289.It Sy "unknown font, skipping request" 1290.Pq man , tbl 1291A 1292.Xr roff 7 1293.Ic \&ft 1294request or a 1295.Xr tbl 7 1296.Ic \&f 1297layout modifier has an unknown 1298.Ar font 1299argument. 1300.It Sy "odd number of characters in request" 1301.Pq roff 1302A 1303.Ic \&tr 1304request contains an odd number of characters. 1305The last character is mapped to the blank character. 1306.El 1307.Ss "Warnings related to plain text" 1308.Bl -ohang 1309.It Sy "blank line in fill mode, using .sp" 1310.Pq mdoc 1311The meaning of blank input lines is only well-defined in non-fill mode: 1312In fill mode, line breaks of text input lines are not supposed to be 1313significant. 1314However, for compatibility with groff, blank lines in fill mode 1315are replaced with 1316.Ic \&sp 1317requests. 1318.It Sy "tab in filled text" 1319.Pq mdoc , man 1320The meaning of tab characters is only well-defined in non-fill mode: 1321In fill mode, whitespace is not supposed to be significant 1322on text input lines. 1323As an implementation dependent choice, tab characters on text lines 1324are passed through to the formatters in any case. 1325Given that the text before the tab character will be filled, 1326it is hard to predict which tab stop position the tab will advance to. 1327.It Sy "whitespace at end of input line" 1328.Pq mdoc , man , roff 1329Whitespace at the end of input lines is almost never semantically 1330significant \(em but in the odd case where it might be, it is 1331extremely confusing when reviewing and maintaining documents. 1332.It Sy "bad comment style" 1333.Pq roff 1334Comment lines start with a dot, a backslash, and a double-quote character. 1335The 1336.Nm 1337utility treats the line as a comment line even without the backslash, 1338but leaving out the backslash might not be portable. 1339.It Sy "invalid escape sequence" 1340.Pq roff 1341An escape sequence has an invalid opening argument delimiter, lacks the 1342closing argument delimiter, or the argument has too few characters. 1343If the argument is incomplete, 1344.Ic \e* | 616.Sq \&Bl \-hang |
| 1345and | 617and |
| 1346.Ic \en 1347expand to an empty string, 1348.Ic \eB 1349to the digit 1350.Sq 0 , 1351and 1352.Ic \ew 1353to the length of the incomplete argument. 1354All other invalid escape sequences are ignored. 1355.It Sy "undefined string, using \(dq\(dq" 1356.Pq roff 1357If a string is used without being defined before, 1358its value is implicitly set to the empty string. 1359However, defining strings explicitly before use 1360keeps the code more readable. 1361.El 1362.Ss "Warnings related to tables" 1363.Bl -ohang 1364.It Sy "tbl line starts with span" 1365.Pq tbl 1366The first cell in a table layout line is a horizontal span 1367.Pq Sq Cm s . 1368Data provided for this cell is ignored, and nothing is printed in the cell. 1369.It Sy "tbl column starts with span" 1370.Pq tbl 1371The first line of a table layout specification 1372requests a vertical span 1373.Pq Sq Cm ^ . 1374Data provided for this cell is ignored, and nothing is printed in the cell. 1375.It Sy "skipping vertical bar in tbl layout" 1376.Pq tbl 1377A table layout specification contains more than two consecutive vertical bars. 1378A double bar is printed, all additional bars are discarded. 1379.El 1380.Ss "Errors related to tables" 1381.Bl -ohang 1382.It Sy "non-alphabetic character in tbl options" 1383.Pq tbl 1384The table options line contains a character other than a letter, 1385blank, or comma where the beginning of an option name is expected. 1386The character is ignored. 1387.It Sy "skipping unknown tbl option" 1388.Pq tbl 1389The table options line contains a string of letters that does not 1390match any known option name. 1391The word is ignored. 1392.It Sy "missing tbl option argument" 1393.Pq tbl 1394A table option that requires an argument is not followed by an 1395opening parenthesis, or the opening parenthesis is immediately 1396followed by a closing parenthesis. 1397The option is ignored. 1398.It Sy "wrong tbl option argument size" 1399.Pq tbl 1400A table option argument contains an invalid number of characters. 1401Both the option and the argument are ignored. 1402.It Sy "empty tbl layout" 1403.Pq tbl 1404A table layout specification is completely empty, 1405specifying zero lines and zero columns. 1406As a fallback, a single left-justified column is used. 1407.It Sy "invalid character in tbl layout" 1408.Pq tbl 1409A table layout specification contains a character that can neither 1410be interpreted as a layout key character nor as a layout modifier, 1411or a modifier precedes the first key. 1412The invalid character is discarded. 1413.It Sy "unmatched parenthesis in tbl layout" 1414.Pq tbl 1415A table layout specification contains an opening parenthesis, 1416but no matching closing parenthesis. 1417The rest of the input line, starting from the parenthesis, has no effect. 1418.It Sy "tbl without any data cells" 1419.Pq tbl 1420A table does not contain any data cells. 1421It will probably produce no output. 1422.It Sy "ignoring data in spanned tbl cell" 1423.Pq tbl 1424A table cell is marked as a horizontal span 1425.Pq Sq Cm s 1426or vertical span 1427.Pq Sq Cm ^ 1428in the table layout, but it contains data. 1429The data is ignored. 1430.It Sy "ignoring extra tbl data cells" 1431.Pq tbl 1432A data line contains more cells than the corresponding layout line. 1433The data in the extra cells is ignored. 1434.It Sy "data block open at end of tbl" 1435.Pq tbl 1436A data block is opened with 1437.Cm T{ , 1438but never closed with a matching 1439.Cm T} . 1440The remaining data lines of the table are all put into one cell, 1441and any remaining cells stay empty. 1442.El 1443.Ss "Errors related to roff, mdoc, and man code" 1444.Bl -ohang 1445.It Sy "input stack limit exceeded, infinite loop?" 1446.Pq roff 1447Explicit recursion limits are implemented for the following features, 1448in order to prevent infinite loops: 1449.Bl -dash -compact | 618.Sq \&Bl \-tag 619list types render similarly (no break following overreached left-hand 620side) due to the expressive constraints of HTML. |
| 1450.It | 621.It |
| 1451expansion of nested escape sequences 1452including expansion of strings and number registers, 1453.It 1454expansion of nested user-defined macros, 1455.It 1456and 1457.Ic \&so 1458file inclusion. 1459.El 1460When a limit is hit, the output is incorrect, typically losing 1461some content, but the parser can continue. 1462.It Sy "skipping bad character" 1463.Pq mdoc , man , roff 1464The input file contains a byte that is not a printable 1465.Xr ascii 7 1466character. 1467The message mentions the character number. 1468The offending byte is replaced with a question mark 1469.Pq Sq \&? . 1470Consider editing the input file to replace the byte with an ASCII 1471transliteration of the intended character. 1472.It Sy "skipping unknown macro" 1473.Pq mdoc , man , roff 1474The first identifier on a request or macro line is neither recognized as a 1475.Xr roff 7 1476request, nor as a user-defined macro, nor, respectively, as an 1477.Xr mdoc 7 1478or 1479.Xr man 7 1480macro. 1481It may be mistyped or unsupported. 1482The request or macro is discarded including its arguments. 1483.It Sy "skipping insecure request" 1484.Pq roff 1485An input file attempted to run a shell command 1486or to read or write an external file. 1487Such attempts are denied for security reasons. 1488.It Sy "skipping item outside list" 1489.Pq mdoc , eqn 1490An 1491.Ic \&It 1492macro occurs outside any 1493.Ic \&Bl 1494list, or an 1495.Xr eqn 7 1496.Ic above 1497delimiter occurs outside any pile. 1498It is discarded including its arguments. 1499.It Sy "skipping column outside column list" 1500.Pq mdoc 1501A 1502.Ic \&Ta 1503macro occurs outside any 1504.Ic \&Bl Fl column 1505block. 1506It is discarded including its arguments. 1507.It Sy "skipping end of block that is not open" 1508.Pq mdoc , man , eqn , tbl , roff 1509Various syntax elements can only be used to explicitly close blocks 1510that have previously been opened. 1511An 1512.Xr mdoc 7 1513block closing macro, a 1514.Xr man 7 1515.Ic \&RE 1516or 1517.Ic \&UE 1518macro, an 1519.Xr eqn 7 1520right delimiter or closing brace, or the end of an equation, table, or 1521.Xr roff 7 1522conditional request is encountered but no matching block is open. 1523The offending request or macro is discarded. 1524.It Sy "fewer RS blocks open, skipping" 1525.Pq man | |
| 1526The | 622The |
| 1527.Ic \&RE 1528macro is invoked with an argument, but less than the specified number of 1529.Ic \&RS 1530blocks is open. 1531The 1532.Ic \&RE 1533macro is discarded. 1534.It Sy "inserting missing end of block" 1535.Pq mdoc , tbl 1536Various 1537.Xr mdoc 7 1538macros as well as tables require explicit closing by dedicated macros. 1539A block that doesn't support bad nesting 1540ends before all of its children are properly closed. 1541The open child nodes are closed implicitly. 1542.It Sy "appending missing end of block" 1543.Pq mdoc , man , eqn , tbl , roff 1544At the end of the document, an explicit 1545.Xr mdoc 7 1546block, a | |
| 1547.Xr man 7 | 623.Xr man 7 |
| 1548next-line scope or 1549.Ic \&RS 1550or 1551.Ic \&UR 1552block, an equation, table, or 1553.Xr roff 7 1554conditional or ignore block is still open. 1555The open block is closed implicitly. 1556.It Sy "escaped character not allowed in a name" 1557.Pq roff 1558Macro, string and register identifiers consist of printable, 1559non-whitespace ASCII characters. 1560Escape sequences and characters and strings expressed in terms of them 1561cannot form part of a name. 1562The first argument of an 1563.Ic \&am , 1564.Ic \&as , 1565.Ic \&de , 1566.Ic \&ds , 1567.Ic \&nr , 1568or 1569.Ic \&rr 1570request, or any argument of an 1571.Ic \&rm 1572request, or the name of a request or user defined macro being called, 1573is terminated by an escape sequence. 1574In the cases of 1575.Ic \&as , 1576.Ic \&ds , | 624.Sq IP |
| 1577and | 625and |
| 1578.Ic \&nr , 1579the request has no effect at all. 1580In the cases of 1581.Ic \&am , 1582.Ic \&de , 1583.Ic \&rr , 1584and 1585.Ic \&rm , 1586what was parsed up to this point is used as the arguments to the request, 1587and the rest of the input line is discarded including the escape sequence. 1588When parsing for a request or a user-defined macro name to be called, 1589only the escape sequence is discarded. 1590The characters preceding it are used as the request or macro name, 1591the characters following it are used as the arguments to the request or macro. 1592.It Sy "NOT IMPLEMENTED: Bd -file" 1593.Pq mdoc 1594For security reasons, the 1595.Ic \&Bd 1596macro does not support the 1597.Fl file 1598argument. 1599By requesting the inclusion of a sensitive file, a malicious document 1600might otherwise trick a privileged user into inadvertently displaying 1601the file on the screen, revealing the file content to bystanders. 1602The argument is ignored including the file name following it. 1603.It Sy "skipping display without arguments" 1604.Pq mdoc 1605A 1606.Ic \&Bd 1607block macro does not have any arguments. 1608The block is discarded, and the block content is displayed in 1609whatever mode was active before the block. 1610.It Sy "missing list type, using -item" 1611.Pq mdoc 1612A 1613.Ic \&Bl 1614macro fails to specify the list type. 1615.It Sy "missing manual name, using \(dq\(dq" 1616.Pq mdoc 1617The first call to 1618.Ic \&Nm 1619lacks the required argument. 1620.It Sy "uname(3) system call failed, using UNKNOWN" 1621.Pq mdoc 1622The 1623.Ic \&Os 1624macro is called without arguments, and the 1625.Xr uname 3 1626system call failed. 1627As a workaround, 1628.Nm 1629can be compiled with 1630.Sm off 1631.Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq . 1632.Sm on 1633.It Sy "unknown standard specifier" 1634.Pq mdoc 1635An 1636.Ic \&St 1637macro has an unknown argument and is discarded. 1638.It Sy "skipping request without numeric argument" 1639.Pq roff , eqn 1640An 1641.Ic \&it 1642request or an 1643.Xr eqn 7 1644.Ic \&size 1645or 1646.Ic \&gsize 1647statement has a non-numeric or negative argument or no argument at all. 1648The invalid request or statement is ignored. 1649.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" 1650.Pq roff 1651For security reasons, 1652.Nm 1653allows 1654.Ic \&so 1655file inclusion requests only with relative paths 1656and only without ascending to any parent directory. 1657By requesting the inclusion of a sensitive file, a malicious document 1658might otherwise trick a privileged user into inadvertently displaying 1659the file on the screen, revealing the file content to bystanders. 1660.Nm 1661only shows the path as it appears behind 1662.Ic \&so . 1663.It Sy ".so request failed" 1664.Pq roff 1665Servicing a 1666.Ic \&so 1667request requires reading an external file, but the file could not be 1668opened. 1669.Nm 1670only shows the path as it appears behind 1671.Ic \&so . 1672.It Sy "skipping all arguments" 1673.Pq mdoc , man , eqn , roff 1674An 1675.Xr mdoc 7 1676.Ic \&Bt , 1677.Ic \&Ed , 1678.Ic \&Ef , 1679.Ic \&Ek , 1680.Ic \&El , 1681.Ic \&Lp , 1682.Ic \&Pp , 1683.Ic \&Re , 1684.Ic \&Rs , 1685or 1686.Ic \&Ud 1687macro, an 1688.Ic \&It 1689macro in a list that don't support item heads, a 1690.Xr man 7 1691.Ic \&LP , 1692.Ic \&P , 1693or 1694.Ic \&PP 1695macro, an 1696.Xr eqn 7 1697.Ic \&EQ 1698or 1699.Ic \&EN 1700macro, or a 1701.Xr roff 7 1702.Ic \&br , 1703.Ic \&fi , 1704or 1705.Ic \&nf 1706request or 1707.Sq \&.. 1708block closing request is invoked with at least one argument. 1709All arguments are ignored. 1710.It Sy "skipping excess arguments" 1711.Pq mdoc , man , roff 1712A macro or request is invoked with too many arguments: 1713.Bl -dash -offset 2n -width 2n -compact 1714.It 1715.Ic \&Fo , 1716.Ic \&PD , 1717.Ic \&RS , 1718.Ic \&UR , 1719.Ic \&ft , 1720or 1721.Ic \&sp 1722with more than one argument 1723.It 1724.Ic \&An 1725with another argument after 1726.Fl split 1727or 1728.Fl nosplit 1729.It 1730.Ic \&RE 1731with more than one argument or with a non-integer argument 1732.It 1733.Ic \&OP 1734or a request of the 1735.Ic \&de 1736family with more than two arguments 1737.It 1738.Ic \&Dt 1739with more than three arguments 1740.It 1741.Ic \&TH 1742with more than five arguments 1743.It 1744.Ic \&Bd , 1745.Ic \&Bk , 1746or 1747.Ic \&Bl 1748with invalid arguments | 626.Sq TP 627lists render similarly. |
| 1749.El | 628.El |
| 1750The excess arguments are ignored. 1751.El 1752.Ss Unsupported features 1753.Bl -ohang 1754.It Sy "input too large" 1755.Pq mdoc , man 1756Currently, 1757.Nm 1758cannot handle input files larger than its arbitrary size limit 1759of 2^31 bytes (2 Gigabytes). 1760Since useful manuals are always small, this is not a problem in practice. 1761Parsing is aborted as soon as the condition is detected. 1762.It Sy "unsupported control character" 1763.Pq roff 1764An ASCII control character supported by other 1765.Xr roff 7 1766implementations but not by 1767.Nm 1768was found in an input file. 1769It is replaced by a question mark. 1770.It Sy "unsupported roff request" 1771.Pq roff 1772An input file contains a 1773.Xr roff 7 1774request supported by GNU troff or Heirloom troff but not by 1775.Nm , 1776and it is likely that this will cause information loss 1777or considerable misformatting. 1778.It Sy "eqn delim option in tbl" 1779.Pq eqn , tbl 1780The options line of a table defines equation delimiters. 1781Any equation source code contained in the table will be printed unformatted. 1782.It Sy "unsupported table layout modifier" 1783.Pq tbl 1784A table layout specification contains an 1785.Sq Cm m 1786modifier. 1787The modifier is discarded. 1788.It Sy "ignoring macro in table" 1789.Pq tbl , mdoc , man 1790A table contains an invocation of an 1791.Xr mdoc 7 1792or 1793.Xr man 7 1794macro or of an undefined macro. 1795The macro is ignored, and its arguments are handled 1796as if they were a text line. 1797.El | |
| 1798.Sh SEE ALSO | 629.Sh SEE ALSO |
| 1799.Xr apropos 1 , 1800.Xr man 1 , | |
| 1801.Xr eqn 7 , 1802.Xr man 7 , 1803.Xr mandoc_char 7 , 1804.Xr mdoc 7 , 1805.Xr roff 7 , 1806.Xr tbl 7 1807.Sh AUTHORS | 630.Xr eqn 7 , 631.Xr man 7 , 632.Xr mandoc_char 7 , 633.Xr mdoc 7 , 634.Xr roff 7 , 635.Xr tbl 7 636.Sh AUTHORS |
| 1808.An -nosplit | |
| 1809The 1810.Nm 1811utility was written by | 637The 638.Nm 639utility was written by |
| 1812.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv 1813and is maintained by 1814.An Ingo Schwarze Aq Mt schwarze@openbsd.org . 1815.Sh BUGS | 640.An Kristaps Dzonsons , 641.Mt kristaps@bsd.lv . 642.Sh CAVEATS |
| 1816In | 643In |
| 1817.Fl T Cm html , | 644.Fl T Ns Cm html 645and 646.Fl T Ns Cm xhtml , |
| 1818the maximum size of an element attribute is determined by 1819.Dv BUFSIZ , 1820which is usually 1024 bytes. 1821Be aware of this when setting long link 1822formats such as | 647the maximum size of an element attribute is determined by 648.Dv BUFSIZ , 649which is usually 1024 bytes. 650Be aware of this when setting long link 651formats such as |
| 1823.Fl O Cm style Ns = Ns Ar really/long/link . | 652.Fl O Ns Cm style Ns = Ns Ar really/long/link . 653.Pp 654Nesting elements within next-line element scopes of 655.Fl m Ns Cm an , 656such as 657.Sq br 658within an empty 659.Sq B , 660will confuse 661.Fl T Ns Cm html 662and 663.Fl T Ns Cm xhtml 664and cause them to forget the formatting of the prior next-line scope. 665.Pp 666The 667.Sq \(aq 668control character is an alias for the standard macro control character 669and does not emit a line-break as stipulated in GNU troff. |