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