1.\" $Id: mandoc.1,v 1.106 2014/08/08 01:50:59 schwarze Exp $ 2.\" 3.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2012, 2014 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: August 8 2014 $ 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 26.Op Fl V 27.Sm off 28.Op Fl I Cm os Li = Ar name 29.Sm on 30.Op Fl m Ns Ar format 31.Op Fl O Ns Ar option 32.Op Fl T Ns Ar output 33.Op Fl W Ns Ar level 34.Op Ar 35.Sh DESCRIPTION 36The 37.Nm 38utility formats 39.Ux 40manual pages for display. 41.Pp 42By default, 43.Nm 44reads 45.Xr mdoc 7 46or 47.Xr man 7 48text from stdin, implying 49.Fl m Ns Cm andoc , 50and produces 51.Fl T Ns Cm ascii 52output. 53.Pp 54The arguments are as follows: 55.Bl -tag -width Ds 56.Sm off 57.It Fl I Cm os Li = Ar name 58.Sm on 59Override the default operating system 60.Ar name 61for the 62.Xr mdoc 7 63.Sq \&Os 64macro. 65.It Fl m Ns Ar format 66Input format. 67See 68.Sx Input Formats 69for available formats. 70Defaults to 71.Fl m Ns Cm andoc . 72.It Fl O Ns Ar option 73Comma-separated output options. 74.It Fl T Ns Ar output 75Output format. 76See 77.Sx Output Formats 78for available formats. 79Defaults to 80.Fl T Ns Cm ascii . 81.It Fl V 82Print version and exit. 83.It Fl W Ns Ar level 84Specify the minimum message 85.Ar level 86to be reported on the standard error output and to affect the exit status. 87The 88.Ar level 89can be 90.Cm warning , 91.Cm error , 92or 93.Cm fatal . 94The default is 95.Fl W Ns Cm fatal ; 96.Fl W Ns Cm all 97is an alias for 98.Fl W Ns Cm warning . 99See 100.Sx EXIT STATUS 101and 102.Sx DIAGNOSTICS 103for details. 104.Pp 105The special option 106.Fl W Ns Cm stop 107tells 108.Nm 109to exit after parsing a file that causes warnings or errors of at least 110the requested level. 111No formatted output will be produced from that file. 112If both a 113.Ar level 114and 115.Cm stop 116are requested, they can be joined with a comma, for example 117.Fl W Ns Cm error , Ns Cm stop . 118.It Ar file 119Read input from zero or more files. 120If unspecified, reads from stdin. 121If multiple files are specified, 122.Nm 123will halt with the first failed parse. 124.El 125.Ss Input Formats 126The 127.Nm 128utility accepts 129.Xr mdoc 7 130and 131.Xr man 7 132input with 133.Fl m Ns Cm doc 134and 135.Fl m Ns Cm an , 136respectively. 137The 138.Xr mdoc 7 139format is 140.Em strongly 141recommended; 142.Xr man 7 143should only be used for legacy manuals. 144.Pp 145A third option, 146.Fl m Ns Cm andoc , 147which is also the default, determines encoding on-the-fly: if the first 148non-comment macro is 149.Sq \&Dd 150or 151.Sq \&Dt , 152the 153.Xr mdoc 7 154parser is used; otherwise, the 155.Xr man 7 156parser is used. 157.Pp 158If multiple 159files are specified with 160.Fl m Ns Cm andoc , 161each has its file-type determined this way. 162If multiple files are 163specified and 164.Fl m Ns Cm doc 165or 166.Fl m Ns Cm an 167is specified, then this format is used exclusively. 168.Ss Output Formats 169The 170.Nm 171utility accepts the following 172.Fl T 173arguments, which correspond to output modes: 174.Bl -tag -width "-Tlocale" 175.It Fl T Ns Cm ascii 176Produce 7-bit ASCII output. 177This is the default. 178See 179.Sx ASCII Output . 180.It Fl T Ns Cm html 181Produce strict CSS1/HTML-4.01 output. 182See 183.Sx HTML Output . 184.It Fl T Ns Cm lint 185Parse only: produce no output. 186Implies 187.Fl W Ns Cm warning . 188.It Fl T Ns Cm locale 189Encode output using the current locale. 190See 191.Sx Locale Output . 192.It Fl T Ns Cm man 193Produce 194.Xr man 7 195format output. 196See 197.Sx Man Output . 198.It Fl T Ns Cm pdf 199Produce PDF output. 200See 201.Sx PDF Output . 202.It Fl T Ns Cm ps 203Produce PostScript output. 204See 205.Sx PostScript Output . 206.It Fl T Ns Cm tree 207Produce an indented parse tree. 208.It Fl T Ns Cm utf8 209Encode output in the UTF\-8 multi-byte format. 210See 211.Sx UTF\-8 Output . 212.It Fl T Ns Cm xhtml 213Produce strict CSS1/XHTML-1.0 output. 214See 215.Sx XHTML Output . 216.El 217.Pp 218If multiple input files are specified, these will be processed by the 219corresponding filter in-order. 220.Ss ASCII Output 221Output produced by 222.Fl T Ns Cm ascii , 223which is the default, is rendered in standard 7-bit ASCII documented in 224.Xr ascii 7 . 225.Pp 226Font styles are applied by using back-spaced encoding such that an 227underlined character 228.Sq c 229is rendered as 230.Sq _ Ns \e[bs] Ns c , 231where 232.Sq \e[bs] 233is the back-space character number 8. 234Emboldened characters are rendered as 235.Sq c Ns \e[bs] Ns c . 236.Pp 237The special characters documented in 238.Xr mandoc_char 7 239are rendered best-effort in an ASCII equivalent. 240If no equivalent is found, 241.Sq \&? 242is used instead. 243.Pp 244Output width is limited to 78 visible columns unless literal input lines 245exceed this limit. 246.Pp 247The following 248.Fl O 249arguments are accepted: 250.Bl -tag -width Ds 251.It Cm indent Ns = Ns Ar indent 252The left margin for normal text is set to 253.Ar indent 254blank characters instead of the default of five for 255.Xr mdoc 7 256and seven for 257.Xr man 7 . 258Increasing this is not recommended; it may result in degraded formatting, 259for example overfull lines or ugly line breaks. 260.It Cm width Ns = Ns Ar width 261The output width is set to 262.Ar width , 263which will normalise to \(>=60. 264.El 265.Ss HTML Output 266Output produced by 267.Fl T Ns Cm html 268conforms to HTML-4.01 strict. 269.Pp 270The 271.Pa example.style.css 272file documents style-sheet classes available for customising output. 273If a style-sheet is not specified with 274.Fl O Ns Ar style , 275.Fl T Ns Cm html 276defaults to simple output readable in any graphical or text-based web 277browser. 278.Pp 279Special characters are rendered in decimal-encoded UTF\-8. 280.Pp 281The following 282.Fl O 283arguments are accepted: 284.Bl -tag -width Ds 285.It Cm fragment 286Omit the 287.Aq !DOCTYPE 288declaration and the 289.Aq html , 290.Aq head , 291and 292.Aq body 293elements and only emit the subtree below the 294.Aq body 295element. 296The 297.Cm style 298argument will be ignored. 299This is useful when embedding manual content within existing documents. 300.It Cm includes Ns = Ns Ar fmt 301The string 302.Ar fmt , 303for example, 304.Ar ../src/%I.html , 305is used as a template for linked header files (usually via the 306.Sq \&In 307macro). 308Instances of 309.Sq \&%I 310are replaced with the include filename. 311The default is not to present a 312hyperlink. 313.It Cm man Ns = Ns Ar fmt 314The string 315.Ar fmt , 316for example, 317.Ar ../html%S/%N.%S.html , 318is used as a template for linked manuals (usually via the 319.Sq \&Xr 320macro). 321Instances of 322.Sq \&%N 323and 324.Sq %S 325are replaced with the linked manual's name and section, respectively. 326If no section is included, section 1 is assumed. 327The default is not to 328present a hyperlink. 329.It Cm style Ns = Ns Ar style.css 330The file 331.Ar style.css 332is used for an external style-sheet. 333This must be a valid absolute or 334relative URI. 335.El 336.Ss Locale Output 337Locale-depending output encoding is triggered with 338.Fl T Ns Cm locale . 339This option is not available on all systems: systems without locale 340support, or those whose internal representation is not natively UCS-4, 341will fall back to 342.Fl T Ns Cm ascii . 343See 344.Sx ASCII Output 345for font style specification and available command-line arguments. 346.Ss Man Output 347Translate input format into 348.Xr man 7 349output format. 350This is useful for distributing manual sources to legacy systems 351lacking 352.Xr mdoc 7 353formatters. 354.Pp 355If 356.Xr mdoc 7 357is passed as input, it is translated into 358.Xr man 7 . 359If the input format is 360.Xr man 7 , 361the input is copied to the output, expanding any 362.Xr roff 7 363.Sq so 364requests. 365The parser is also run, and as usual, the 366.Fl W 367level controls which 368.Sx DIAGNOSTICS 369are displayed before copying the input to the output. 370.Ss PDF Output 371PDF-1.1 output may be generated by 372.Fl T Ns Cm pdf . 373See 374.Sx PostScript Output 375for 376.Fl O 377arguments and defaults. 378.Ss PostScript Output 379PostScript 380.Qq Adobe-3.0 381Level-2 pages may be generated by 382.Fl T Ns Cm ps . 383Output pages default to letter sized and are rendered in the Times font 384family, 11-point. 385Margins are calculated as 1/9 the page length and width. 386Line-height is 1.4m. 387.Pp 388Special characters are rendered as in 389.Sx ASCII Output . 390.Pp 391The following 392.Fl O 393arguments are accepted: 394.Bl -tag -width Ds 395.It Cm paper Ns = Ns Ar name 396The paper size 397.Ar name 398may be one of 399.Ar a3 , 400.Ar a4 , 401.Ar a5 , 402.Ar legal , 403or 404.Ar letter . 405You may also manually specify dimensions as 406.Ar NNxNN , 407width by height in millimetres. 408If an unknown value is encountered, 409.Ar letter 410is used. 411.El 412.Ss UTF\-8 Output 413Use 414.Fl T Ns Cm utf8 415to force a UTF\-8 locale. 416See 417.Sx Locale Output 418for details and options. 419.Ss XHTML Output 420Output produced by 421.Fl T Ns Cm xhtml 422conforms to XHTML-1.0 strict. 423.Pp 424See 425.Sx HTML Output 426for details; beyond generating XHTML tags instead of HTML tags, these 427output modes are identical. 428.Sh EXIT STATUS 429The 430.Nm 431utility exits with one of the following values, controlled by the message 432.Ar level 433associated with the 434.Fl W 435option: 436.Pp 437.Bl -tag -width Ds -compact 438.It 0 439No warnings or errors occurred, or those that did were ignored because 440they were lower than the requested 441.Ar level . 442.It 2 443At least one warning occurred, but no error, and 444.Fl W Ns Cm warning 445was specified. 446.It 3 447At least one parsing error occurred, but no fatal error, and 448.Fl W Ns Cm error 449or 450.Fl W Ns Cm warning 451was specified. 452.It 4 453A fatal parsing error occurred. 454.It 5 455Invalid command line arguments were specified. 456No input files have been read. 457.It 6 458An operating system error occurred, for example memory exhaustion or an 459error accessing input files. 460Such errors cause 461.Nm 462to exit at once, possibly in the middle of parsing or formatting a file. 463.El 464.Pp 465Note that selecting 466.Fl T Ns Cm lint 467output mode implies 468.Fl W Ns Cm warning . 469.Sh EXAMPLES 470To page manuals to the terminal: 471.Pp 472.Dl $ mandoc \-Wall,stop mandoc.1 2\*(Gt&1 | less 473.Dl $ mandoc mandoc.1 mdoc.3 mdoc.7 | less 474.Pp 475To produce HTML manuals with 476.Ar style.css 477as the style-sheet: 478.Pp 479.Dl $ mandoc \-Thtml -Ostyle=style.css mdoc.7 \*(Gt mdoc.7.html 480.Pp 481To check over a large set of manuals: 482.Pp 483.Dl $ mandoc \-Tlint `find /usr/src -name \e*\e.[1-9]` 484.Pp 485To produce a series of PostScript manuals for A4 paper: 486.Pp 487.Dl $ mandoc \-Tps \-Opaper=a4 mdoc.7 man.7 \*(Gt manuals.ps 488.Pp 489Convert a modern 490.Xr mdoc 7 491manual to the older 492.Xr man 7 493format, for use on systems lacking an 494.Xr mdoc 7 495parser: 496.Pp 497.Dl $ mandoc \-Tman foo.mdoc \*(Gt foo.man 498.Sh DIAGNOSTICS 499Messages displayed by 500.Nm 501follow this format: 502.Pp 503.D1 Nm Ns : Ar file : Ns Ar line : Ns Ar column : level : message : macro args 504.Pp 505Line and column numbers start at 1. 506Both are omitted for messages referring to an input file as a whole. 507Macro names and arguments are omitted where meaningless. 508Fatal messages about invalid command line arguments 509or operating system errors, for example when memory is exhausted, 510may also omit the 511.Ar file 512and 513.Ar level 514fields. 515.Pp 516Message levels have the following meanings: 517.Bl -tag -width "warning" 518.It Cm syserr 519Opening or reading an input file failed, so the parser cannot 520even be started and no output is produced from that input file. 521.It Cm fatal 522The parser is unable to parse a given input file at all. 523No formatted output is produced from that input file. 524.It Cm error 525An input file contains syntax that cannot be safely interpreted, 526either because it is invalid or because 527.Nm 528does not implement it yet. 529By discarding part of the input or inserting missing tokens, 530the parser is able to continue, and the error does not prevent 531generation of formatted output, but typically, preparing that 532output involves information loss, broken document structure 533or unintended formatting. 534.It Cm warning 535An input file uses obsolete, discouraged or non-portable syntax. 536All the same, the meaning of the input is unambiguous and a correct 537rendering can be produced. 538Documents causing warnings may render poorly when using other 539formatting tools instead of 540.Nm . 541.El 542.Pp 543Messages of the 544.Cm warning 545and 546.Cm error 547levels are hidden unless their level, or a lower level, is requested using a 548.Fl W 549option or 550.Fl T Ns Cm lint 551output mode. 552.Ss Warnings related to the document prologue 553.Bl -ohang 554.It Sy "missing manual title, using UNTITLED" 555.Pq mdoc 556A 557.Ic \&Dt 558macro has no arguments, or there is no 559.Ic \&Dt 560macro before the first non-prologue macro. 561.It Sy "missing manual title, using \(dq\(dq" 562.Pq man 563There is no 564.Ic \&TH 565macro, or it has no arguments. 566.It Sy "lower case character in document title" 567.Pq mdoc , man 568The title is still used as given in the 569.Ic \&Dt 570or 571.Ic \&TH 572macro. 573.It Sy "missing manual section, using \(dq\(dq" 574.Pq mdoc , man 575A 576.Ic \&Dt 577or 578.Ic \&TH 579macro lacks the mandatory section argument. 580.It Sy "unknown manual section" 581.Pq mdoc 582The section number in a 583.Ic \&Dt 584line is invalid, but still used. 585.It Sy "unknown manual volume or arch" 586.Pq mdoc 587The volume name in a 588.Ic \&Dt 589line is invalid, but still used. 590The manual is assumed to be architecture-independent. 591.It Sy "missing date, using today's date" 592.Pq mdoc, man 593The document was parsed as 594.Xr mdoc 7 595and it has no 596.Ic \&Dd 597macro, or the 598.Ic \&Dd 599macro has no arguments or only empty arguments; 600or the document was parsed as 601.Xr man 7 602and it has no 603.Ic \&TH 604macro, or the 605.Ic \&TH 606macro has less than three arguments or its third argument is empty. 607.It Sy "cannot parse date, using it verbatim" 608.Pq mdoc , man 609The date given in a 610.Ic \&Dd 611or 612.Ic \&TH 613macro does not follow the conventional format. 614.It Sy "missing Os macro, using \(dq\(dq" 615.Pq mdoc 616The default or current system is not shown in this case. 617.It Sy "duplicate prologue macro" 618.Pq mdoc 619One of the prologue macros occurs more than once. 620The last instance overrides all previous ones. 621.It Sy "late prologue macro" 622.Pq mdoc 623A 624.Ic \&Dd 625or 626.Ic \&Os 627macro occurs after some non-prologue macro, but still takes effect. 628.It Sy "skipping late title macro" 629.Pq mdoc 630The 631.Ic \&Dt 632macro can only occur before the first non-prologue macro 633because traditional formatters write the page header 634before parsing the document body. 635Even though this technical restriction does not apply to 636.Nm , 637traditional semantics is preserved. 638The late macro is discarded including its arguments. 639.It Sy "prologue macros out of order" 640.Pq mdoc 641The prologue macros are not given in the conventional order 642.Ic \&Dd , 643.Ic \&Dt , 644.Ic \&Os . 645All three macros are used even when given in another order. 646.El 647.Ss Warnings regarding document structure 648.Bl -ohang 649.It Sy ".so is fragile, better use ln(1)" 650.Pq roff 651Including files only works when the parser program runs with the correct 652current working directory. 653.It Sy "no document body" 654.Pq mdoc , man 655The document body contains neither text nor macros. 656An empty document is shown, consisting only of a header and a footer line. 657.It Sy "content before first section header" 658.Pq mdoc , man 659Some macros or text precede the first 660.Ic \&Sh 661or 662.Ic \&SH 663section header. 664The offending macros and text are parsed and added to the top level 665of the syntax tree, outside any section block. 666.It Sy "first section is not NAME" 667.Pq mdoc 668The argument of the first 669.Ic \&Sh 670macro is not 671.Sq NAME . 672This may confuse 673.Xr makewhatis 8 674and 675.Xr apropos 1 . 676.It Sy "bad NAME section contents" 677.Pq mdoc 678The last node in the NAME section is not an 679.Ic \&Nd 680macro, or any preceding macro is not 681.Ic \&Nm , 682or the NAME section is completely empty. 683This may confuse 684.Xr makewhatis 8 685and 686.Xr apropos 1 . 687.It Sy "sections out of conventional order" 688.Pq mdoc 689A standard section occurs after another section it usually precedes. 690All section titles are used as given, 691and the order of sections is not changed. 692.It Sy "duplicate section title" 693.Pq mdoc 694The same standard section title occurs more than once. 695.It Sy "unexpected section" 696.Pq mdoc 697A standard section header occurs in a section of the manual 698where it normally isn't useful. 699.El 700.Ss "Warnings related to macros and nesting" 701.Bl -ohang 702.It Sy "obsolete macro" 703.Pq mdoc 704See the 705.Xr mdoc 7 706manual for replacements. 707.It Sy "skipping paragraph macro" 708In 709.Xr mdoc 7 710documents, this happens 711.Bl -dash -compact 712.It 713at the beginning and end of sections and subsections 714.It 715right before non-compact lists and displays 716.It 717at the end of items in non-column, non-compact lists 718.It 719and for multiple consecutive paragraph macros. 720.El 721In 722.Xr man 7 723documents, it happens 724.Bl -dash -compact 725.It 726for empty 727.Ic \&P , 728.Ic \&PP , 729and 730.Ic \&LP 731macros 732.It 733for 734.Ic \&IP 735macros having neither head nor body arguments 736.It 737for 738.Ic \&br 739or 740.Ic \&sp 741right after 742.Ic \&SH 743or 744.Ic \&SS 745.El 746.It Sy "moving paragraph macro out of list" 747.Pq mdoc 748A list item in a 749.Ic \&Bl 750list contains a trailing paragraph macro. 751The paragraph macro is moved after the end of the list. 752.It Sy "skipping no-space macro" 753.Pq mdoc 754An input line begins with an 755.Ic \&Ns 756macro. 757The macro is ignored. 758.It Sy "blocks badly nested" 759.Pq mdoc 760If two blocks intersect, one should completely contain the other. 761Otherwise, rendered output is likely to look strange in any output 762format, and rendering in SGML-based output formats is likely to be 763outright wrong because such languages do not support badly nested 764blocks at all. 765Typical examples of badly nested blocks are 766.Qq Ic \&Ao \&Bo \&Ac \&Bc 767and 768.Qq Ic \&Ao \&Bq \&Ac . 769In these examples, 770.Ic \&Ac 771breaks 772.Ic \&Bo 773and 774.Ic \&Bq , 775respectively. 776.It Sy "nested displays are not portable" 777.Pq mdoc 778A 779.Ic \&Bd , 780.Ic \&D1 , 781or 782.Ic \&Dl 783display occurs nested inside another 784.Ic \&Bd 785display. 786This works with 787.Nm , 788but fails with most other implementations. 789.It Sy "moving content out of list" 790.Pq mdoc 791A 792.Ic \&Bl 793list block contains text or macros before the first 794.Ic \&It 795macro. 796The offending children are moved before the beginning of the list. 797.It Sy ".Vt block has child macro" 798.Pq mdoc 799The 800.Ic \&Vt 801macro supports plain text arguments only. 802Formatting may be ugly and semantic searching 803for the affected content might not work. 804.It Sy "fill mode already enabled, skipping" 805.Pq man 806A 807.Ic \&fi 808request occurs even though the document is still in fill mode, 809or already switched back to fill mode. 810It has no effect. 811.It Sy "fill mode already disabled, skipping" 812.Pq man 813An 814.Ic \&nf 815request occurs even though the document already switched to no-fill mode 816and did not switch back to fill mode yet. 817It has no effect. 818.It Sy "line scope broken" 819.Pq man 820While parsing the next-line scope of the previous macro, 821another macro is found that prematurely terminates the previous one. 822The previous, interrupted macro is deleted from the parse tree. 823.El 824.Ss "Warnings related to missing arguments" 825.Bl -ohang 826.It Sy "skipping empty request" 827.Pq roff 828The macro name is missing from a macro definition request. 829.It Sy "conditional request controls empty scope" 830.Pq roff 831A conditional request is only useful if any of the following 832follows it on the same logical input line: 833.Bl -dash -compact 834.It 835The 836.Sq \e{ 837keyword to open a multi-line scope. 838.It 839A request or macro or some text, resulting in a single-line scope. 840.It 841The immediate end of the logical line without any intervening whitespace, 842resulting in next-line scope. 843.El 844Here, a conditional request is followed by trailing whitespace only, 845and there is no other content on its logical input line. 846Note that it doesn't matter whether the logical input line is split 847across multiple physical input lines using 848.Sq \e 849line continuation characters. 850This is one of the rare cases 851where trailing whitespace is syntactically significant. 852The conditional request controls a scope containing whitespace only, 853so it is unlikely to have a significant effect, 854except that it may control a following 855.Ic \&el 856clause. 857.It Sy "skipping empty macro" 858.Pq mdoc 859The indicated macro has no arguments and hence no effect. 860.It Sy "empty argument, using 0n" 861.Pq mdoc 862The required width is missing after 863.Ic \&Bd 864or 865.Ic \&Bl 866.Fl offset 867or 868.Fl width. 869.It Sy "argument count wrong" 870.Pq mdoc , man 871The indicated macro has too few or too many arguments. 872The syntax tree will contain the wrong number of arguments as given. 873Formatting behaviour depends on the specific macro in question. 874Note that the same message may also occur as an ERROR, see below. 875.It Sy "missing display type, using -ragged" 876.Pq mdoc 877The 878.Ic \&Bd 879macro is invoked without the required display type. 880.It Sy "list type is not the first argument" 881.Pq mdoc 882In a 883.Ic \&Bl 884macro, at least one other argument precedes the type argument. 885The 886.Nm 887utility copes with any argument order, but some other 888.Xr mdoc 7 889implementations do not. 890.It Sy "missing -width in -tag list, using 8n" 891.Pq mdoc 892Every 893.Ic \&Bl 894macro having the 895.Fl tag 896argument requires 897.Fl width , 898too. 899.It Sy "missing utility name, using \(dq\(dq" 900.Pq mdoc 901The 902.Ic \&Ex Fl std 903macro is called without an argument before 904.Ic \&Nm 905has first been called with an argument. 906.It Sy "empty head in list item" 907.Pq mdoc 908In a 909.Ic \&Bl 910.Fl diag , 911.Fl hang , 912.Fl inset , 913.Fl ohang , 914or 915.Fl tag 916list, an 917.Ic \&It 918macro lacks the required argument. 919The item head is left empty. 920.It Sy "empty list item" 921.Pq mdoc 922In a 923.Ic \&Bl 924.Fl bullet , 925.Fl dash , 926.Fl enum , 927or 928.Fl hyphen 929list, an 930.Ic \&It 931block is empty. 932An empty list item is shown. 933.It Sy "missing font type" 934.Pq mdoc 935A 936.Ic \&Bf 937macro has no argument. 938It switches to the default font, 939.Cm \efR . 940.It Sy "unknown font type" 941.Pq mdoc 942The 943.Ic \&Bf 944argument is invalid. 945The default font 946.Cm \efR 947is used instead. 948.It Sy "missing -std argument, adding it" 949.Pq mdoc 950An 951.Ic \&Ex 952or 953.Ic \&Rv 954macro lacks the required 955.Fl std 956argument. 957The 958.Nm 959utility assumes 960.Fl std 961even when it is not specified, but other implementations may not. 962.El 963.Ss "Warnings related to bad macro arguments" 964.Bl -ohang 965.It Sy "unterminated quoted argument" 966.Pq roff 967Macro arguments can be enclosed in double quote characters 968such that space characters and macro names contained in the quoted 969argument need not be escaped. 970The closing quote of the last argument of a macro can be omitted. 971However, omitting it is not recommended because it makes the code 972harder to read. 973.It Sy "duplicate argument" 974.Pq mdoc 975A 976.Ic \&Bd 977or 978.Ic \&Bl 979macro has more than one 980.Fl compact , 981more than one 982.Fl offset , 983or more than one 984.Fl width 985argument. 986All but the last instances of these arguments are ignored. 987.It Sy "skipping duplicate argument" 988.Pq mdoc 989An 990.Ic \&An 991macro has more than one 992.Fl split 993or 994.Fl nosplit 995argument. 996All but the first of these arguments are ignored. 997.It Sy "skipping duplicate display type" 998.Pq mdoc 999A 1000.Ic \&Bd 1001macro has more than one type argument; the first one is used. 1002.It Sy "skipping duplicate list type" 1003.Pq mdoc 1004A 1005.Ic \&Bl 1006macro has more than one type argument; the first one is used. 1007.It Sy "skipping -width argument" 1008.Pq mdoc 1009A 1010.Ic \&Bl 1011.Fl column , 1012.Fl diag , 1013.Fl ohang , 1014.Fl inset , 1015or 1016.Fl item 1017list has a 1018.Fl width 1019argument. 1020That has no effect. 1021.It Sy "unknown AT&T UNIX version" 1022.Pq mdoc 1023An 1024.Ic \&At 1025macro has an invalid argument. 1026It is used verbatim, with 1027.Qq "AT&T UNIX " 1028prefixed to it. 1029.It Sy "invalid content in Rs block" 1030.Pq mdoc 1031An 1032.Ic \&Rs 1033block contains plain text or non-% macros. 1034The bogus content is left in the syntax tree. 1035Formatting may be poor. 1036.It Sy "invalid Boolean argument" 1037.Pq mdoc 1038An 1039.Ic \&Sm 1040macro has an argument other than 1041.Cm on 1042or 1043.Cm off . 1044The invalid argument is moved out of the macro, which leaves the macro 1045empty, causing it to toggle the spacing mode. 1046.It Sy "unknown font, skipping request" 1047.Pq man 1048A 1049.Xr roff 7 1050.Ic \&ft 1051request has an invalid argument. 1052.El 1053.Ss "Warnings related to plain text" 1054.Bl -ohang 1055.It Sy "blank line in fill mode, using .sp" 1056.Pq mdoc 1057The meaning of blank input lines is only well-defined in non-fill mode: 1058In fill mode, line breaks of text input lines are not supposed to be 1059significant. 1060However, for compatibility with groff, blank lines in fill mode 1061are replaced with 1062.Ic \&sp 1063requests. 1064.It Sy "tab in filled text" 1065.Pq mdoc , man 1066The meaning of tab characters is only well-defined in non-fill mode: 1067In fill mode, whitespace is not supposed to be significant 1068on text input lines. 1069As an implementation dependent choice, tab characters on text lines 1070are passed through to the formatters in any case. 1071Given that the text before the tab character will be filled, 1072it is hard to predict which tab stop position the tab will advance to. 1073.It Sy "whitespace at end of input line" 1074.Pq mdoc , man , roff 1075Whitespace at the end of input lines is almost never semantically 1076significant \(em but in the odd case where it might be, it is 1077extremely confusing when reviewing and maintaining documents. 1078.It Sy "bad comment style" 1079.Pq roff 1080Comment lines start with a dot, a backslash, and a double-quote character. 1081The 1082.Nm 1083utility treats the line as a comment line even without the backslash, 1084but leaving out the backslash might not be portable. 1085.It Sy "invalid escape sequence" 1086.Pq roff 1087An escape sequence has an invalid opening argument delimiter, lacks the 1088closing argument delimiter, or the argument has too few characters. 1089If the argument is incomplete, 1090.Ic \e* 1091and 1092.Ic \en 1093expand to an empty string, 1094.Ic \eB 1095to the digit 1096.Sq 0 , 1097and 1098.Ic \ew 1099to the length of the incomplete argument. 1100All other invalid escape sequences are ignored. 1101.It Sy "undefined string, using \(dq\(dq" 1102.Pq roff 1103If a string is used without being defined before, 1104its value is implicitly set to the empty string. 1105However, defining strings explicitly before use 1106keeps the code more readable. 1107.El 1108.Ss "Errors related to equations" 1109.Bl -inset -compact 1110.It "unexpected equation scope closure" 1111.It "equation scope open on exit" 1112.It "overlapping equation scopes" 1113.It "unexpected end of equation" 1114.It "equation syntax error" 1115.El 1116.Ss "Errors related to tables" 1117.Bl -inset -compact 1118.It "bad table syntax" 1119.It "bad table option" 1120.It "bad table layout" 1121.It "no table layout cells specified" 1122.It "no table data cells specified" 1123.It "ignore data in cell" 1124.It "data block still open" 1125.It "ignoring extra data cells" 1126.El 1127.Ss "Errors related to roff, mdoc, and man code" 1128.Bl -ohang 1129.It Sy "input stack limit exceeded, infinite loop?" 1130.Pq roff 1131Explicit recursion limits are implemented for the following features, 1132in order to prevent infinite loops: 1133.Bl -dash -compact 1134.It 1135expansion of nested escape sequences 1136including expansion of strings and number registers, 1137.It 1138expansion of nested user-defined macros, 1139.It 1140and 1141.Ic \&so 1142file inclusion. 1143.El 1144When a limit is hit, the output is incorrect, typically losing 1145some content, but the parser can continue. 1146.It Sy "skipping bad character" 1147.Pq mdoc , man , roff 1148The input file contains a byte that is not a printable 1149.Xr ascii 7 1150character. 1151The message mentions the character number. 1152The offending byte is replaced with a question mark 1153.Pq Sq \&? . 1154Consider editing the input file to replace the byte with an ASCII 1155transliteration of the intended character. 1156.It Sy "skipping unknown macro" 1157.Pq mdoc , man , roff 1158The first identifier on a request or macro line is neither recognized as a 1159.Xr roff 7 1160request, nor as a user-defined macro, nor, respectively, as an 1161.Xr mdoc 7 1162or 1163.Xr man 7 1164macro. 1165It may be mistyped or unsupported. 1166The request or macro is discarded including its arguments. 1167.It Sy "skipping item outside list" 1168.Pq mdoc 1169An 1170.Ic \&It 1171macro occurs outside any 1172.Ic \&Bl 1173list. 1174It is discarded including its arguments. 1175.It Sy "skipping column outside column list" 1176.Pq mdoc 1177A 1178.Ic \&Ta 1179macro occurs outside any 1180.Ic \&Bl Fl column 1181block. 1182It is discarded including its arguments. 1183.It Sy "skipping end of block that is not open" 1184.Pq mdoc , man , eqn , tbl , roff 1185Various syntax elements can only be used to explicitly close blocks 1186that have previously been opened. 1187An 1188.Xr mdoc 7 1189block closing macro, a 1190.Xr man 7 1191.Ic \&RE 1192or 1193.Ic \&UE 1194macro, or the end of an equation, table, or 1195.Xr roff 7 1196conditional request is encountered but no matching block is open. 1197The offending request or macro is discarded. 1198.It Sy "inserting missing end of block" 1199.Pq mdoc , tbl 1200Various 1201.Xr mdoc 7 1202macros as well as tables require explicit closing by dedicated macros. 1203A block that doesn't support bad nesting 1204ends before all of its children are properly closed. 1205The open child nodes are closed implicitly. 1206.It Sy "scope open on exit" 1207.Pq mdoc , man , eqn , tbl , roff 1208At the end of the document, an explicit 1209.Xr mdoc 7 1210block, a 1211.Xr man 7 1212next-line scope or 1213.Ic \&RS 1214or 1215.Ic \&UR 1216block, an equation, table, or 1217.Xr roff 7 1218conditional or ignore block is still open. 1219The open block is closed implicitly. 1220.It Sy "escaped character not allowed in a name" 1221.Pq roff 1222Macro, string and register identifiers consist of printable, 1223non-whitespace ASCII characters. 1224Escape sequences and characters and strings expressed in terms of them 1225cannot form part of a name. 1226The first argument of an 1227.Ic \&am , 1228.Ic \&as , 1229.Ic \&de , 1230.Ic \&ds , 1231.Ic \&nr , 1232or 1233.Ic \&rr 1234request, or any argument of an 1235.Ic \&rm 1236request, or the name of a request or user defined macro being called, 1237is terminated by an escape sequence. 1238In the cases of 1239.Ic \&as , 1240.Ic \&ds , 1241and 1242.Ic \&nr , 1243the request has no effect at all. 1244In the cases of 1245.Ic \&am , 1246.Ic \&de , 1247.Ic \&rr , 1248and 1249.Ic \&rm , 1250what was parsed up to this point is used as the arguments to the request, 1251and the rest of the input line is discarded including the escape sequence. 1252When parsing for a request or a user-defined macro name to be called, 1253only the escape sequence is discarded. 1254The characters preceding it are used as the request or macro name, 1255the characters following it are used as the arguments to the request or macro. 1256.It Sy "argument count wrong" 1257.Pq mdoc , man , roff 1258The indicated request or macro has too few or too many arguments. 1259The syntax tree will contain the wrong number of arguments as given. 1260Formatting behaviour depends on the specific request or macro in question. 1261Note that the same message may also occur as a WARNING, see above. 1262.It Sy "missing list type, using -item" 1263.Pq mdoc 1264A 1265.Ic \&Bl 1266macro fails to specify the list type. 1267.It Sy "missing manual name, using \(dq\(dq" 1268.Pq mdoc 1269The first call to 1270.Ic \&Nm 1271lacks the required argument. 1272.It Sy "uname(3) system call failed, using UNKNOWN" 1273.Pq mdoc 1274The 1275.Ic \&Os 1276macro is called without arguments, and the 1277.Xr uname 3 1278system call failed. 1279As a workaround, 1280.Nm 1281can be compiled with 1282.Sm off 1283.Fl D Cm OSNAME=\(dq\e\(dq Ar string Cm \e\(dq\(dq . 1284.Sm on 1285.It Sy "unknown standard specifier" 1286.Pq mdoc 1287An 1288.Ic \&St 1289macro has an unknown argument and is discarded. 1290.It Sy "skipping request without numeric argument" 1291.Pq roff 1292An 1293.Ic \&it 1294request has a non-numeric or negative argument or no argument at all. 1295The invalid request is ignored. 1296.It Sy "skipping all arguments" 1297.Pq mdoc , man , eqn , roff 1298An 1299.Xr mdoc 7 1300.Ic \&Bt , 1301.Ic \&Ed , 1302.Ic \&Ef , 1303.Ic \&Ek , 1304.Ic \&El , 1305.Ic \&Re , 1306or 1307.Ic \&Ud 1308macro, an 1309.Ic \&It 1310macro in a list that don't support item heads, a 1311.Xr man 7 1312.Ic \&LP , 1313.Ic \&P , 1314or 1315.Ic \&PP 1316macro, an 1317.Xr eqn 7 1318.Ic \&EN 1319macro, or a 1320.Xr roff 7 1321.Sq \&.. 1322block closing request is invoked with at least one argument. 1323All arguments are ignored. 1324.It Sy "skipping excess arguments" 1325.Pq mdoc , roff 1326The 1327.Ic \&Bf 1328macro is invoked with more than one argument, or a request of the 1329.Ic \&de 1330family is invoked with more than two arguments. 1331The excess arguments are ignored. 1332.El 1333.Ss FATAL errors 1334.Bl -ohang 1335.It Sy "input too large" 1336.Pq mdoc , man 1337Currently, 1338.Nm 1339cannot handle input files larger than its arbitrary size limit 1340of 2^31 bytes (2 Gigabytes). 1341Since useful manuals are always small, this is not a problem in practice. 1342Parsing is aborted as soon as the condition is detected. 1343.It Sy "NOT IMPLEMENTED: Bd -file" 1344.Pq mdoc 1345For security reasons, the 1346.Ic \&Bd 1347macro does not support the 1348.Fl file 1349argument. 1350By requesting the inclusion of a sensitive file, a malicious document 1351might otherwise trick a privileged user into inadvertently displaying 1352the file on the screen, revealing the file content to bystanders. 1353The parser exits immediately. 1354.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" 1355.Pq roff 1356For security reasons, 1357.Nm 1358allows 1359.Ic \&so 1360file inclusion requests only with relative paths 1361and only without ascending to any parent directory. 1362By requesting the inclusion of a sensitive file, a malicious document 1363might otherwise trick a privileged user into inadvertently displaying 1364the file on the screen, revealing the file content to bystanders. 1365The parser exits immediately. 1366.It Sy ".so request failed" 1367.Pq roff 1368Servicing a 1369.Ic \&so 1370request requires reading an external file. 1371While trying to do so, an 1372.Xr open 2 , 1373.Xr stat 2 , 1374or 1375.Xr read 2 1376system call failed. 1377The parser exits immediately. 1378Before showing this message, 1379.Nm 1380always shows another message explaining why the system call failed. 1381.El 1382.Sh COMPATIBILITY 1383This section summarises 1384.Nm 1385compatibility with GNU troff. 1386Each input and output format is separately noted. 1387.Ss ASCII Compatibility 1388.Bl -bullet -compact 1389.It 1390Unrenderable unicode codepoints specified with 1391.Sq \e[uNNNN] 1392escapes are printed as 1393.Sq \&? 1394in mandoc. 1395In GNU troff, these raise an error. 1396.It 1397The 1398.Sq \&Bd \-literal 1399and 1400.Sq \&Bd \-unfilled 1401macros of 1402.Xr mdoc 7 1403in 1404.Fl T Ns Cm ascii 1405are synonyms, as are \-filled and \-ragged. 1406.It 1407In historic GNU troff, the 1408.Sq \&Pa 1409.Xr mdoc 7 1410macro does not underline when scoped under an 1411.Sq \&It 1412in the FILES section. 1413This behaves correctly in 1414.Nm . 1415.It 1416A list or display following the 1417.Sq \&Ss 1418.Xr mdoc 7 1419macro in 1420.Fl T Ns Cm ascii 1421does not assert a prior vertical break, just as it doesn't with 1422.Sq \&Sh . 1423.It 1424The 1425.Sq \&na 1426.Xr man 7 1427macro in 1428.Fl T Ns Cm ascii 1429has no effect. 1430.It 1431Words aren't hyphenated. 1432.El 1433.Ss HTML/XHTML Compatibility 1434.Bl -bullet -compact 1435.It 1436The 1437.Sq \efP 1438escape will revert the font to the previous 1439.Sq \ef 1440escape, not to the last rendered decoration, which is now dictated by 1441CSS instead of hard-coded. 1442It also will not span past the current scope, 1443for the same reason. 1444Note that in 1445.Sx ASCII Output 1446mode, this will work fine. 1447.It 1448The 1449.Xr mdoc 7 1450.Sq \&Bl \-hang 1451and 1452.Sq \&Bl \-tag 1453list types render similarly (no break following overreached left-hand 1454side) due to the expressive constraints of HTML. 1455.It 1456The 1457.Xr man 7 1458.Sq IP 1459and 1460.Sq TP 1461lists render similarly. 1462.El 1463.Sh SEE ALSO 1464.Xr eqn 7 , 1465.Xr man 7 , 1466.Xr mandoc_char 7 , 1467.Xr mdoc 7 , 1468.Xr roff 7 , 1469.Xr tbl 7 1470.Sh AUTHORS 1471The 1472.Nm 1473utility was written by 1474.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 1475.Sh CAVEATS 1476In 1477.Fl T Ns Cm html 1478and 1479.Fl T Ns Cm xhtml , 1480the maximum size of an element attribute is determined by 1481.Dv BUFSIZ , 1482which is usually 1024 bytes. 1483Be aware of this when setting long link 1484formats such as 1485.Fl O Ns Cm style Ns = Ns Ar really/long/link . 1486.Pp 1487Nesting elements within next-line element scopes of 1488.Fl m Ns Cm an , 1489such as 1490.Sq br 1491within an empty 1492.Sq B , 1493will confuse 1494.Fl T Ns Cm html 1495and 1496.Fl T Ns Cm xhtml 1497and cause them to forget the formatting of the prior next-line scope. 1498.Pp 1499The 1500.Sq \(aq 1501control character is an alias for the standard macro control character 1502and does not emit a line-break as stipulated in GNU troff. 1503