1.\" $Id: mdoc.7,v 1.279 2019/07/15 19:20:30 schwarze Exp $ 2.\" 3.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2010, 2011, 2013-2018 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 15 2019 $ 19.Dt MDOC 7 20.Os 21.Sh NAME 22.Nm mdoc 23.Nd semantic markup language for formatting manual pages 24.Sh DESCRIPTION 25The 26.Nm mdoc 27language supports authoring of manual pages for the 28.Xr man 1 29utility by allowing semantic annotations of words, phrases, 30page sections and complete manual pages. 31Such annotations are used by formatting tools to achieve a uniform 32presentation across all manuals written in 33.Nm , 34and to support hyperlinking if supported by the output medium. 35.Pp 36This reference document describes the structure of manual pages 37and the syntax and usage of the 38.Nm 39language. 40The reference implementation of a parsing and formatting tool is 41.Xr mandoc 1 ; 42the 43.Sx COMPATIBILITY 44section describes compatibility with other implementations. 45.Pp 46In an 47.Nm 48document, lines beginning with the control character 49.Sq \&. 50are called 51.Dq macro lines . 52The first word is the macro name. 53It consists of two or three letters. 54Most macro names begin with a capital letter. 55For a list of available macros, see 56.Sx MACRO OVERVIEW . 57The words following the macro name are arguments to the macro, optionally 58including the names of other, callable macros; see 59.Sx MACRO SYNTAX 60for details. 61.Pp 62Lines not beginning with the control character are called 63.Dq text lines . 64They provide free-form text to be printed; the formatting of the text 65depends on the respective processing context: 66.Bd -literal -offset indent 67\&.Sh Macro lines change control state. 68Text lines are interpreted within the current state. 69.Ed 70.Pp 71Many aspects of the basic syntax of the 72.Nm 73language are based on the 74.Xr roff 7 75language; see the 76.Em LANGUAGE SYNTAX 77and 78.Em MACRO SYNTAX 79sections in the 80.Xr roff 7 81manual for details, in particular regarding 82comments, escape sequences, whitespace, and quoting. 83However, using 84.Xr roff 7 85requests in 86.Nm 87documents is discouraged; 88.Xr mandoc 1 89supports some of them merely for backward compatibility. 90.Sh MANUAL STRUCTURE 91A well-formed 92.Nm 93document consists of a document prologue followed by one or more 94sections. 95.Pp 96The prologue, which consists of the 97.Ic \&Dd , 98.Ic \&Dt , 99and 100.Ic \&Os 101macros in that order, is required for every document. 102.Pp 103The first section (sections are denoted by 104.Ic \&Sh ) 105must be the NAME section, consisting of at least one 106.Ic \&Nm 107followed by 108.Ic \&Nd . 109.Pp 110Following that, convention dictates specifying at least the 111.Em SYNOPSIS 112and 113.Em DESCRIPTION 114sections, although this varies between manual sections. 115.Pp 116The following is a well-formed skeleton 117.Nm 118file for a utility 119.Qq progname : 120.Bd -literal -offset indent 121\&.Dd $\&Mdocdate$ 122\&.Dt PROGNAME section 123\&.Os 124\&.Sh NAME 125\&.Nm progname 126\&.Nd one line about what it does 127\&.\e\(dq .Sh LIBRARY 128\&.\e\(dq For sections 2, 3, and 9 only. 129\&.\e\(dq Not used in OpenBSD. 130\&.Sh SYNOPSIS 131\&.Nm progname 132\&.Op Fl options 133\&.Ar 134\&.Sh DESCRIPTION 135The 136\&.Nm 137utility processes files ... 138\&.\e\(dq .Sh CONTEXT 139\&.\e\(dq For section 9 functions only. 140\&.\e\(dq .Sh IMPLEMENTATION NOTES 141\&.\e\(dq Not used in OpenBSD. 142\&.\e\(dq .Sh RETURN VALUES 143\&.\e\(dq For sections 2, 3, and 9 function return values only. 144\&.\e\(dq .Sh ENVIRONMENT 145\&.\e\(dq For sections 1, 6, 7, and 8 only. 146\&.\e\(dq .Sh FILES 147\&.\e\(dq .Sh EXIT STATUS 148\&.\e\(dq For sections 1, 6, and 8 only. 149\&.\e\(dq .Sh EXAMPLES 150\&.\e\(dq .Sh DIAGNOSTICS 151\&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only. 152\&.\e\(dq .Sh ERRORS 153\&.\e\(dq For sections 2, 3, 4, and 9 errno settings only. 154\&.\e\(dq .Sh SEE ALSO 155\&.\e\(dq .Xr foobar 1 156\&.\e\(dq .Sh STANDARDS 157\&.\e\(dq .Sh HISTORY 158\&.\e\(dq .Sh AUTHORS 159\&.\e\(dq .Sh CAVEATS 160\&.\e\(dq .Sh BUGS 161\&.\e\(dq .Sh SECURITY CONSIDERATIONS 162\&.\e\(dq Not used in OpenBSD. 163.Ed 164.Pp 165The sections in an 166.Nm 167document are conventionally ordered as they appear above. 168Sections should be composed as follows: 169.Bl -ohang -offset Ds 170.It Em NAME 171The name(s) and a one line description of the documented material. 172The syntax for this as follows: 173.Bd -literal -offset indent 174\&.Nm name0 , 175\&.Nm name1 , 176\&.Nm name2 177\&.Nd a one line description 178.Ed 179.Pp 180Multiple 181.Sq \&Nm 182names should be separated by commas. 183.Pp 184The 185.Ic \&Nm 186macro(s) must precede the 187.Ic \&Nd 188macro. 189.Pp 190See 191.Ic \&Nm 192and 193.Ic \&Nd . 194.It Em LIBRARY 195The name of the library containing the documented material, which is 196assumed to be a function in a section 2, 3, or 9 manual. 197The syntax for this is as follows: 198.Bd -literal -offset indent 199\&.Lb libarm 200.Ed 201.Pp 202See 203.Ic \&Lb . 204.It Em SYNOPSIS 205Documents the utility invocation syntax, function call syntax, or device 206configuration. 207.Pp 208For the first, utilities (sections 1, 6, and 8), this is 209generally structured as follows: 210.Bd -literal -offset indent 211\&.Nm bar 212\&.Op Fl v 213\&.Op Fl o Ar file 214\&.Op Ar 215\&.Nm foo 216\&.Op Fl v 217\&.Op Fl o Ar file 218\&.Op Ar 219.Ed 220.Pp 221Commands should be ordered alphabetically. 222.Pp 223For the second, function calls (sections 2, 3, 9): 224.Bd -literal -offset indent 225\&.In header.h 226\&.Vt extern const char *global; 227\&.Ft "char *" 228\&.Fn foo "const char *src" 229\&.Ft "char *" 230\&.Fn bar "const char *src" 231.Ed 232.Pp 233Ordering of 234.Ic \&In , 235.Ic \&Vt , 236.Ic \&Fn , 237and 238.Ic \&Fo 239macros should follow C header-file conventions. 240.Pp 241And for the third, configurations (section 4): 242.Bd -literal -offset indent 243\&.Cd \(dqit* at isa? port 0x2e\(dq 244\&.Cd \(dqit* at isa? port 0x4e\(dq 245.Ed 246.Pp 247Manuals not in these sections generally don't need a 248.Em SYNOPSIS . 249.Pp 250Some macros are displayed differently in the 251.Em SYNOPSIS 252section, particularly 253.Ic \&Nm , 254.Ic \&Cd , 255.Ic \&Fd , 256.Ic \&Fn , 257.Ic \&Fo , 258.Ic \&In , 259.Ic \&Vt , 260and 261.Ic \&Ft . 262All of these macros are output on their own line. 263If two such dissimilar macros are pairwise invoked (except for 264.Ic \&Ft 265before 266.Ic \&Fo 267or 268.Ic \&Fn ) , 269they are separated by a vertical space, unless in the case of 270.Ic \&Fo , 271.Ic \&Fn , 272and 273.Ic \&Ft , 274which are always separated by vertical space. 275.Pp 276When text and macros following an 277.Ic \&Nm 278macro starting an input line span multiple output lines, 279all output lines but the first will be indented to align 280with the text immediately following the 281.Ic \&Nm 282macro, up to the next 283.Ic \&Nm , 284.Ic \&Sh , 285or 286.Ic \&Ss 287macro or the end of an enclosing block, whichever comes first. 288.It Em DESCRIPTION 289This begins with an expansion of the brief, one line description in 290.Em NAME : 291.Bd -literal -offset indent 292The 293\&.Nm 294utility does this, that, and the other. 295.Ed 296.Pp 297It usually follows with a breakdown of the options (if documenting a 298command), such as: 299.Bd -literal -offset indent 300The arguments are as follows: 301\&.Bl \-tag \-width Ds 302\&.It Fl v 303Print verbose information. 304\&.El 305.Ed 306.Pp 307List the options in alphabetical order, 308uppercase before lowercase for each letter and 309with no regard to whether an option takes an argument. 310Put digits in ascending order before all letter options. 311.Pp 312Manuals not documenting a command won't include the above fragment. 313.Pp 314Since the 315.Em DESCRIPTION 316section usually contains most of the text of a manual, longer manuals 317often use the 318.Ic \&Ss 319macro to form subsections. 320In very long manuals, the 321.Em DESCRIPTION 322may be split into multiple sections, each started by an 323.Ic \&Sh 324macro followed by a non-standard section name, and each having 325several subsections, like in the present 326.Nm 327manual. 328.It Em CONTEXT 329This section lists the contexts in which functions can be called in section 9. 330The contexts are autoconf, process, or interrupt. 331.It Em IMPLEMENTATION NOTES 332Implementation-specific notes should be kept here. 333This is useful when implementing standard functions that may have side 334effects or notable algorithmic implications. 335.It Em RETURN VALUES 336This section documents the 337return values of functions in sections 2, 3, and 9. 338.Pp 339See 340.Ic \&Rv . 341.It Em ENVIRONMENT 342Lists the environment variables used by the utility, 343and explains the syntax and semantics of their values. 344The 345.Xr environ 7 346manual provides examples of typical content and formatting. 347.Pp 348See 349.Ic \&Ev . 350.It Em FILES 351Documents files used. 352It's helpful to document both the file name and a short description of how 353the file is used (created, modified, etc.). 354.Pp 355See 356.Ic \&Pa . 357.It Em EXIT STATUS 358This section documents the 359command exit status for section 1, 6, and 8 utilities. 360Historically, this information was described in 361.Em DIAGNOSTICS , 362a practise that is now discouraged. 363.Pp 364See 365.Ic \&Ex . 366.It Em EXAMPLES 367Example usages. 368This often contains snippets of well-formed, well-tested invocations. 369Make sure that examples work properly! 370.It Em DIAGNOSTICS 371Documents error messages. 372In section 4 and 9 manuals, these are usually messages printed by the 373kernel to the console and to the kernel log. 374In section 1, 6, 7, and 8, these are usually messages printed by 375userland programs to the standard error output. 376.Pp 377Historically, this section was used in place of 378.Em EXIT STATUS 379for manuals in sections 1, 6, and 8; however, this practise is 380discouraged. 381.Pp 382See 383.Ic \&Bl 384.Fl diag . 385.It Em ERRORS 386Documents 387.Xr errno 2 388settings in sections 2, 3, 4, and 9. 389.Pp 390See 391.Ic \&Er . 392.It Em SEE ALSO 393References other manuals with related topics. 394This section should exist for most manuals. 395Cross-references should conventionally be ordered first by section, then 396alphabetically (ignoring case). 397.Pp 398References to other documentation concerning the topic of the manual page, 399for example authoritative books or journal articles, may also be 400provided in this section. 401.Pp 402See 403.Ic \&Rs 404and 405.Ic \&Xr . 406.It Em STANDARDS 407References any standards implemented or used. 408If not adhering to any standards, the 409.Em HISTORY 410section should be used instead. 411.Pp 412See 413.Ic \&St . 414.It Em HISTORY 415A brief history of the subject, including where it was first implemented, 416and when it was ported to or reimplemented for the operating system at hand. 417.It Em AUTHORS 418Credits to the person or persons who wrote the code and/or documentation. 419Authors should generally be noted by both name and email address. 420.Pp 421See 422.Ic \&An . 423.It Em CAVEATS 424Common misuses and misunderstandings should be explained 425in this section. 426.It Em BUGS 427Known bugs, limitations, and work-arounds should be described 428in this section. 429.It Em SECURITY CONSIDERATIONS 430Documents any security precautions that operators should consider. 431.El 432.Sh MACRO OVERVIEW 433This overview is sorted such that macros of similar purpose are listed 434together, to help find the best macro for any given purpose. 435Deprecated macros are not included in the overview, but can be found below 436in the alphabetical 437.Sx MACRO REFERENCE . 438.Ss Document preamble and NAME section macros 439.Bl -column "Brq, Bro, Brc" description 440.It Ic \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year 441.It Ic \&Dt Ta document title: Ar TITLE section Op Ar arch 442.It Ic \&Os Ta operating system version: Op Ar system Op Ar version 443.It Ic \&Nm Ta document name (one argument) 444.It Ic \&Nd Ta document description (one line) 445.El 446.Ss Sections and cross references 447.Bl -column "Brq, Bro, Brc" description 448.It Ic \&Sh Ta section header (one line) 449.It Ic \&Ss Ta subsection header (one line) 450.It Ic \&Sx Ta internal cross reference to a section or subsection 451.It Ic \&Xr Ta cross reference to another manual page: Ar name section 452.It Ic \&Pp Ta start a text paragraph (no arguments) 453.El 454.Ss Displays and lists 455.Bl -column "Brq, Bro, Brc" description 456.It Ic \&Bd , \&Ed Ta display block: 457.Fl Ar type 458.Op Fl offset Ar width 459.Op Fl compact 460.It Ic \&D1 Ta indented display (one line) 461.It Ic \&Dl Ta indented literal display (one line) 462.It Ic \&Ql Ta in-line literal display: Ql text 463.It Ic \&Bl , \&El Ta list block: 464.Fl Ar type 465.Op Fl width Ar val 466.Op Fl offset Ar val 467.Op Fl compact 468.It Ic \&It Ta list item (syntax depends on Fl Ar type ) 469.It Ic \&Ta Ta table cell separator in Ic \&Bl Fl column No lists 470.It Ic \&Rs , \&%* , \&Re Ta bibliographic block (references) 471.El 472.Ss Spacing control 473.Bl -column "Brq, Bro, Brc" description 474.It Ic \&Pf Ta prefix, no following horizontal space (one argument) 475.It Ic \&Ns Ta roman font, no preceding horizontal space (no arguments) 476.It Ic \&Ap Ta apostrophe without surrounding whitespace (no arguments) 477.It Ic \&Sm Ta switch horizontal spacing mode: Op Cm on | off 478.It Ic \&Bk , \&Ek Ta keep block: Fl words 479.El 480.Ss Semantic markup for command line utilities 481.Bl -column "Brq, Bro, Brc" description 482.It Ic \&Nm Ta start a SYNOPSIS block with the name of a utility 483.It Ic \&Fl Ta command line options (flags) (>=0 arguments) 484.It Ic \&Cm Ta command modifier (>0 arguments) 485.It Ic \&Ar Ta command arguments (>=0 arguments) 486.It Ic \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure) 487.It Ic \&Ic Ta internal or interactive command (>0 arguments) 488.It Ic \&Ev Ta environmental variable (>0 arguments) 489.It Ic \&Pa Ta file system path (>=0 arguments) 490.El 491.Ss Semantic markup for function libraries 492.Bl -column "Brq, Bro, Brc" description 493.It Ic \&Lb Ta function library (one argument) 494.It Ic \&In Ta include file (one argument) 495.It Ic \&Fd Ta other preprocessor directive (>0 arguments) 496.It Ic \&Ft Ta function type (>0 arguments) 497.It Ic \&Fo , \&Fc Ta function block: Ar funcname 498.It Ic \&Fn Ta function name: Ar funcname Op Ar argument ... 499.It Ic \&Fa Ta function argument (>0 arguments) 500.It Ic \&Vt Ta variable type (>0 arguments) 501.It Ic \&Va Ta variable name (>0 arguments) 502.It Ic \&Dv Ta defined variable or preprocessor constant (>0 arguments) 503.It Ic \&Er Ta error constant (>0 arguments) 504.It Ic \&Ev Ta environmental variable (>0 arguments) 505.El 506.Ss Various semantic markup 507.Bl -column "Brq, Bro, Brc" description 508.It Ic \&An Ta author name (>0 arguments) 509.It Ic \&Lk Ta hyperlink: Ar uri Op Ar display_name 510.It Ic \&Mt Ta Do mailto Dc hyperlink: Ar localpart Ns @ Ns Ar domain 511.It Ic \&Cd Ta kernel configuration declaration (>0 arguments) 512.It Ic \&Ad Ta memory address (>0 arguments) 513.It Ic \&Ms Ta mathematical symbol (>0 arguments) 514.El 515.Ss Physical markup 516.Bl -column "Brq, Bro, Brc" description 517.It Ic \&Em Ta italic font or underline (emphasis) (>0 arguments) 518.It Ic \&Sy Ta boldface font (symbolic) (>0 arguments) 519.It Ic \&No Ta return to roman font (normal) (>0 arguments) 520.It Ic \&Bf , \&Ef Ta font block: Fl Ar type | Cm \&Em | \&Li | \&Sy 521.El 522.Ss Physical enclosures 523.Bl -column "Brq, Bro, Brc" description 524.It Ic \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text 525.It Ic \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text 526.It Ic \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text 527.It Ic \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text 528.It Ic \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text 529.It Ic \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text 530.It Ic \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text 531.It Ic \&Eo , \&Ec Ta generic enclosure 532.El 533.Ss Text production 534.Bl -column "Brq, Bro, Brc" description 535.It Ic \&Ex Fl std Ta standard command exit values: Op Ar utility ... 536.It Ic \&Rv Fl std Ta standard function return values: Op Ar function ... 537.It Ic \&St Ta reference to a standards document (one argument) 538.It Ic \&At Ta At 539.It Ic \&Bx Ta Bx 540.It Ic \&Bsx Ta Bsx 541.It Ic \&Nx Ta Nx 542.It Ic \&Fx Ta Fx 543.It Ic \&Ox Ta Ox 544.It Ic \&Dx Ta Dx 545.El 546.Sh MACRO REFERENCE 547This section is a canonical reference of all macros, arranged 548alphabetically. 549For the scoping of individual macros, see 550.Sx MACRO SYNTAX . 551.Bl -tag -width 3n 552.It Ic \&%A Ar first_name ... last_name 553Author name of an 554.Ic \&Rs 555block. 556Multiple authors should each be accorded their own 557.Ic \%%A 558line. 559Author names should be ordered with full or abbreviated forename(s) 560first, then full surname. 561.It Ic \&%B Ar title 562Book title of an 563.Ic \&Rs 564block. 565This macro may also be used in a non-bibliographic context when 566referring to book titles. 567.It Ic \&%C Ar location 568Publication city or location of an 569.Ic \&Rs 570block. 571.It Ic \&%D Oo Ar month day , Oc Ar year 572Publication date of an 573.Ic \&Rs 574block. 575Provide the full English name of the 576.Ar month 577and all four digits of the 578.Ar year . 579.It Ic \&%I Ar name 580Publisher or issuer name of an 581.Ic \&Rs 582block. 583.It Ic \&%J Ar name 584Journal name of an 585.Ic \&Rs 586block. 587.It Ic \&%N Ar number 588Issue number (usually for journals) of an 589.Ic \&Rs 590block. 591.It Ic \&%O Ar line 592Optional information of an 593.Ic \&Rs 594block. 595.It Ic \&%P Ar number 596Book or journal page number of an 597.Ic \&Rs 598block. 599Conventionally, the argument starts with 600.Ql p.\& 601for a single page or 602.Ql pp.\& 603for a range of pages, for example: 604.Pp 605.Dl .%P pp. 42\e(en47 606.It Ic \&%Q Ar name 607Institutional author (school, government, etc.) of an 608.Ic \&Rs 609block. 610Multiple institutional authors should each be accorded their own 611.Ic \&%Q 612line. 613.It Ic \&%R Ar name 614Technical report name of an 615.Ic \&Rs 616block. 617.It Ic \&%T Ar title 618Article title of an 619.Ic \&Rs 620block. 621This macro may also be used in a non-bibliographical context when 622referring to article titles. 623.It Ic \&%U Ar protocol Ns :// Ns Ar path 624URI of reference document. 625.It Ic \&%V Ar number 626Volume number of an 627.Ic \&Rs 628block. 629.It Ic \&Ac 630Close an 631.Ic \&Ao 632block. 633Does not have any tail arguments. 634.It Ic \&Ad Ar address 635Memory address. 636Do not use this for postal addresses. 637.Pp 638Examples: 639.Dl \&.Ad [0,$] 640.Dl \&.Ad 0x00000000 641.It Ic \&An Fl split | nosplit | Ar first_name ... last_name 642Author name. 643Can be used both for the authors of the program, function, or driver 644documented in the manual, or for the authors of the manual itself. 645Requires either the name of an author or one of the following arguments: 646.Pp 647.Bl -tag -width "-nosplitX" -offset indent -compact 648.It Fl split 649Start a new output line before each subsequent invocation of 650.Ic \&An . 651.It Fl nosplit 652The opposite of 653.Fl split . 654.El 655.Pp 656The default is 657.Fl nosplit . 658The effect of selecting either of the 659.Fl split 660modes ends at the beginning of the 661.Em AUTHORS 662section. 663In the 664.Em AUTHORS 665section, the default is 666.Fl nosplit 667for the first author listing and 668.Fl split 669for all other author listings. 670.Pp 671Examples: 672.Dl \&.An -nosplit 673.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv 674.It Ic \&Ao Ar block 675Begin a block enclosed by angle brackets. 676Does not have any head arguments. 677This macro is almost never useful. 678See 679.Ic \&Aq 680for more details. 681.It Ic \&Ap 682Inserts an apostrophe without any surrounding whitespace. 683This is generally used as a grammatical device when referring to the verb 684form of a function. 685.Pp 686Examples: 687.Dl \&.Fn execve \&Ap d 688.It Ic \&Aq Ar line 689Enclose the rest of the input line in angle brackets. 690The only important use case is for email addresses. 691See 692.Ic \&Mt 693for an example. 694.Pp 695Occasionally, it is used for names of characters and keys, for example: 696.Bd -literal -offset indent 697Press the 698\&.Aq escape 699key to ... 700.Ed 701.Pp 702For URIs, use 703.Ic \&Lk 704instead, and 705.Ic \&In 706for 707.Dq #include 708directives. 709Never wrap 710.Ic \&Ar 711in 712.Ic \&Aq . 713.Pp 714Since 715.Ic \&Aq 716usually renders with non-ASCII characters in non-ASCII output modes, 717do not use it where the ASCII characters 718.Sq < 719and 720.Sq > 721are required as syntax elements. 722Instead, use these characters directly in such cases, combining them 723with the macros 724.Ic \&Pf , 725.Ic \&Ns , 726or 727.Ic \&Eo 728as needed. 729.Pp 730See also 731.Ic \&Ao . 732.It Ic \&Ar Op Ar placeholder ... 733Command arguments. 734If an argument is not provided, the string 735.Dq file ...\& 736is used as a default. 737.Pp 738Examples: 739.Dl ".Fl o Ar file" 740.Dl ".Ar" 741.Dl ".Ar arg1 , arg2 ." 742.Pp 743The arguments to the 744.Ic \&Ar 745macro are names and placeholders for command arguments; 746for fixed strings to be passed verbatim as arguments, use 747.Ic \&Fl 748or 749.Ic \&Cm . 750.It Ic \&At Op Ar version 751Formats an 752.At 753version. 754Accepts one optional argument: 755.Pp 756.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact 757.It Cm v[1-7] | 32v 758A version of 759.At . 760.It Cm III 761.At III . 762.It Cm V | V.[1-4] 763A version of 764.At V . 765.El 766.Pp 767Note that these arguments do not begin with a hyphen. 768.Pp 769Examples: 770.Dl \&.At 771.Dl \&.At III 772.Dl \&.At V.1 773.Pp 774See also 775.Ic \&Bsx , 776.Ic \&Bx , 777.Ic \&Dx , 778.Ic \&Fx , 779.Ic \&Nx , 780and 781.Ic \&Ox . 782.It Ic \&Bc 783Close a 784.Ic \&Bo 785block. 786Does not have any tail arguments. 787.It Ic \&Bd Fl Ns Ar type Oo Fl offset Ar width Oc Op Fl compact 788Begin a display block. 789Display blocks are used to select a different indentation and 790justification than the one used by the surrounding text. 791They may contain both macro lines and text lines. 792By default, a display block is preceded by a vertical space. 793.Pp 794The 795.Ar type 796must be one of the following: 797.Bl -tag -width 13n -offset indent 798.It Fl centered 799Produce one output line from each input line, and center-justify each line. 800Using this display type is not recommended; many 801.Nm 802implementations render it poorly. 803.It Fl filled 804Change the positions of line breaks to fill each line, and left- and 805right-justify the resulting block. 806.It Fl literal 807Produce one output line from each input line, 808and do not justify the block at all. 809Preserve white space as it appears in the input. 810Always use a constant-width font. 811Use this for displaying source code. 812.It Fl ragged 813Change the positions of line breaks to fill each line, and left-justify 814the resulting block. 815.It Fl unfilled 816The same as 817.Fl literal , 818but using the same font as for normal text, which is a variable width font 819if supported by the output device. 820.El 821.Pp 822The 823.Ar type 824must be provided first. 825Additional arguments may follow: 826.Bl -tag -width 13n -offset indent 827.It Fl offset Ar width 828Indent the display by the 829.Ar width , 830which may be one of the following: 831.Bl -item 832.It 833One of the pre-defined strings 834.Cm indent , 835the width of a standard indentation (six constant width characters); 836.Cm indent-two , 837twice 838.Cm indent ; 839.Cm left , 840which has no effect; 841.Cm right , 842which justifies to the right margin; or 843.Cm center , 844which aligns around an imagined center axis. 845.It 846A macro invocation, which selects a predefined width 847associated with that macro. 848The most popular is the imaginary macro 849.Ar \&Ds , 850which resolves to 851.Sy 6n . 852.It 853A scaling width as described in 854.Xr roff 7 . 855.It 856An arbitrary string, which indents by the length of this string. 857.El 858.Pp 859When the argument is missing, 860.Fl offset 861is ignored. 862.It Fl compact 863Do not assert vertical space before the display. 864.El 865.Pp 866Examples: 867.Bd -literal -offset indent 868\&.Bd \-literal \-offset indent \-compact 869 Hello world. 870\&.Ed 871.Ed 872.Pp 873See also 874.Ic \&D1 875and 876.Ic \&Dl . 877.It Ic \&Bf Fl emphasis | literal | symbolic | Cm \&Em | \&Li | \&Sy 878Change the font mode for a scoped block of text. 879The 880.Fl emphasis 881and 882.Cm \&Em 883argument are equivalent, as are 884.Fl symbolic 885and 886.Cm \&Sy , 887and 888.Fl literal 889and 890.Cm \&Li . 891Without an argument, this macro does nothing. 892The font mode continues until broken by a new font mode in a nested 893scope or 894.Ic \&Ef 895is encountered. 896.Pp 897See also 898.Ic \&Li , 899.Ic \&Ef , 900.Ic \&Em , 901and 902.Ic \&Sy . 903.It Ic \&Bk Fl words 904For each macro, keep its output together on the same output line, 905until the end of the macro or the end of the input line is reached, 906whichever comes first. 907Line breaks in text lines are unaffected. 908.Pp 909The 910.Fl words 911argument is required; additional arguments are ignored. 912.Pp 913The following example will not break within each 914.Ic \&Op 915macro line: 916.Bd -literal -offset indent 917\&.Bk \-words 918\&.Op Fl f Ar flags 919\&.Op Fl o Ar output 920\&.Ek 921.Ed 922.Pp 923Be careful in using over-long lines within a keep block! 924Doing so will clobber the right margin. 925.It Xo 926.Ic \&Bl 927.Fl Ns Ar type 928.Op Fl width Ar val 929.Op Fl offset Ar val 930.Op Fl compact 931.Op Ar col ... 932.Xc 933Begin a list. 934Lists consist of items specified using the 935.Ic \&It 936macro, containing a head or a body or both. 937.Pp 938The list 939.Ar type 940is mandatory and must be specified first. 941The 942.Fl width 943and 944.Fl offset 945arguments accept macro names as described for 946.Ic \&Bd 947.Fl offset , 948scaling widths as described in 949.Xr roff 7 , 950or use the length of the given string. 951The 952.Fl offset 953is a global indentation for the whole list, affecting both item heads 954and bodies. 955For those list types supporting it, the 956.Fl width 957argument requests an additional indentation of item bodies, 958to be added to the 959.Fl offset . 960Unless the 961.Fl compact 962argument is specified, list entries are separated by vertical space. 963.Pp 964A list must specify one of the following list types: 965.Bl -tag -width 12n -offset indent 966.It Fl bullet 967No item heads can be specified, but a bullet will be printed at the head 968of each item. 969Item bodies start on the same output line as the bullet 970and are indented according to the 971.Fl width 972argument. 973.It Fl column 974A columnated list. 975The 976.Fl width 977argument has no effect; instead, the string length of each argument 978specifies the width of one column. 979If the first line of the body of a 980.Fl column 981list is not an 982.Ic \&It 983macro line, 984.Ic \&It 985contexts spanning one input line each are implied until an 986.Ic \&It 987macro line is encountered, at which point items start being interpreted as 988described in the 989.Ic \&It 990documentation. 991.It Fl dash 992Like 993.Fl bullet , 994except that dashes are used in place of bullets. 995.It Fl diag 996Like 997.Fl inset , 998except that item heads are not parsed for macro invocations. 999Most often used in the 1000.Em DIAGNOSTICS 1001section with error constants in the item heads. 1002.It Fl enum 1003A numbered list. 1004No item heads can be specified. 1005Formatted like 1006.Fl bullet , 1007except that cardinal numbers are used in place of bullets, 1008starting at 1. 1009.It Fl hang 1010Like 1011.Fl tag , 1012except that the first lines of item bodies are not indented, but follow 1013the item heads like in 1014.Fl inset 1015lists. 1016.It Fl hyphen 1017Synonym for 1018.Fl dash . 1019.It Fl inset 1020Item bodies follow items heads on the same line, using normal inter-word 1021spacing. 1022Bodies are not indented, and the 1023.Fl width 1024argument is ignored. 1025.It Fl item 1026No item heads can be specified, and none are printed. 1027Bodies are not indented, and the 1028.Fl width 1029argument is ignored. 1030.It Fl ohang 1031Item bodies start on the line following item heads and are not indented. 1032The 1033.Fl width 1034argument is ignored. 1035.It Fl tag 1036Item bodies are indented according to the 1037.Fl width 1038argument. 1039When an item head fits inside the indentation, the item body follows 1040this head on the same output line. 1041Otherwise, the body starts on the output line following the head. 1042.El 1043.Pp 1044Lists may be nested within lists and displays. 1045Nesting of 1046.Fl column 1047and 1048.Fl enum 1049lists may not be portable. 1050.Pp 1051See also 1052.Ic \&El 1053and 1054.Ic \&It . 1055.It Ic \&Bo Ar block 1056Begin a block enclosed by square brackets. 1057Does not have any head arguments. 1058.Pp 1059Examples: 1060.Bd -literal -offset indent -compact 1061\&.Bo 1 , 1062\&.Dv BUFSIZ \&Bc 1063.Ed 1064.Pp 1065See also 1066.Ic \&Bq . 1067.It Ic \&Bq Ar line 1068Encloses its arguments in square brackets. 1069.Pp 1070Examples: 1071.Dl \&.Bq 1 , \&Dv BUFSIZ 1072.Pp 1073.Em Remarks : 1074this macro is sometimes abused to emulate optional arguments for 1075commands; the correct macros to use for this purpose are 1076.Ic \&Op , 1077.Ic \&Oo , 1078and 1079.Ic \&Oc . 1080.Pp 1081See also 1082.Ic \&Bo . 1083.It Ic \&Brc 1084Close a 1085.Ic \&Bro 1086block. 1087Does not have any tail arguments. 1088.It Ic \&Bro Ar block 1089Begin a block enclosed by curly braces. 1090Does not have any head arguments. 1091.Pp 1092Examples: 1093.Bd -literal -offset indent -compact 1094\&.Bro 1 , ... , 1095\&.Va n \&Brc 1096.Ed 1097.Pp 1098See also 1099.Ic \&Brq . 1100.It Ic \&Brq Ar line 1101Encloses its arguments in curly braces. 1102.Pp 1103Examples: 1104.Dl \&.Brq 1 , ... , \&Va n 1105.Pp 1106See also 1107.Ic \&Bro . 1108.It Ic \&Bsx Op Ar version 1109Format the 1110.Bsx 1111version provided as an argument, or a default value if 1112no argument is provided. 1113.Pp 1114Examples: 1115.Dl \&.Bsx 1.0 1116.Dl \&.Bsx 1117.Pp 1118See also 1119.Ic \&At , 1120.Ic \&Bx , 1121.Ic \&Dx , 1122.Ic \&Fx , 1123.Ic \&Nx , 1124and 1125.Ic \&Ox . 1126.It Ic \&Bt 1127Supported only for compatibility, do not use this in new manuals. 1128Prints 1129.Dq is currently in beta test. 1130.It Ic \&Bx Op Ar version Op Ar variant 1131Format the 1132.Bx 1133version provided as an argument, or a default value if no 1134argument is provided. 1135.Pp 1136Examples: 1137.Dl \&.Bx 4.3 Tahoe 1138.Dl \&.Bx 4.4 1139.Dl \&.Bx 1140.Pp 1141See also 1142.Ic \&At , 1143.Ic \&Bsx , 1144.Ic \&Dx , 1145.Ic \&Fx , 1146.Ic \&Nx , 1147and 1148.Ic \&Ox . 1149.It Ic \&Cd Ar line 1150Kernel configuration declaration. 1151This denotes strings accepted by 1152.Xr config 8 . 1153It is most often used in section 4 manual pages. 1154.Pp 1155Examples: 1156.Dl \&.Cd device le0 at scode? 1157.Pp 1158.Em Remarks : 1159this macro is commonly abused by using quoted literals to retain 1160whitespace and align consecutive 1161.Ic \&Cd 1162declarations. 1163This practise is discouraged. 1164.It Ic \&Cm Ar keyword ... 1165Command modifiers. 1166Typically used for fixed strings passed as arguments to interactive 1167commands, to commands in interpreted scripts, or to configuration 1168file directives, unless 1169.Ic \&Fl 1170is more appropriate. 1171.Pp 1172Examples: 1173.Dl ".Nm mt Fl f Ar device Cm rewind" 1174.Dl ".Nm ps Fl o Cm pid , Ns Cm command" 1175.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2" 1176.Dl ".Ic set Fl o Cm vi" 1177.Dl ".Ic lookup Cm file bind" 1178.Dl ".Ic permit Ar identity Op Cm as Ar target" 1179.It Ic \&D1 Ar line 1180One-line indented display. 1181This is formatted by the default rules and is useful for simple indented 1182statements. 1183It is followed by a newline. 1184.Pp 1185Examples: 1186.Dl \&.D1 \&Fl abcdefgh 1187.Pp 1188See also 1189.Ic \&Bd 1190and 1191.Ic \&Dl . 1192.It Ic \&Db 1193This macro is obsolete. 1194No replacement is needed. 1195It is ignored by 1196.Xr mandoc 1 1197and groff including its arguments. 1198It was formerly used to toggle a debugging mode. 1199.It Ic \&Dc 1200Close a 1201.Ic \&Do 1202block. 1203Does not have any tail arguments. 1204.It Ic \&Dd Cm $\&Mdocdate$ | Ar month day , year 1205Document date for display in the page footer. 1206This is the mandatory first macro of any 1207.Nm 1208manual. 1209.Pp 1210The 1211.Ar month 1212is the full English month name, the 1213.Ar day 1214is an integer number, and the 1215.Ar year 1216is the full four-digit year. 1217.Pp 1218Other arguments are not portable; the 1219.Xr mandoc 1 1220utility handles them as follows: 1221.Bl -dash -offset 3n -compact 1222.It 1223To have the date automatically filled in by the 1224.Ox 1225version of 1226.Xr cvs 1 , 1227the special string 1228.Dq $\&Mdocdate$ 1229can be given as an argument. 1230.It 1231The traditional, purely numeric 1232.Xr man 7 1233format 1234.Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day 1235is accepted, too. 1236.It 1237If a date string cannot be parsed, it is used verbatim. 1238.It 1239If no date string is given, the current date is used. 1240.El 1241.Pp 1242Examples: 1243.Dl \&.Dd $\&Mdocdate$ 1244.Dl \&.Dd $\&Mdocdate: July 2 2018$ 1245.Dl \&.Dd July 2, 2018 1246.Pp 1247See also 1248.Ic \&Dt 1249and 1250.Ic \&Os . 1251.It Ic \&Dl Ar line 1252One-line indented display. 1253This is formatted as literal text and is useful for commands and 1254invocations. 1255It is followed by a newline. 1256.Pp 1257Examples: 1258.Dl \&.Dl % mandoc mdoc.7 \e(ba less 1259.Pp 1260See also 1261.Ic \&Ql , 1262.Ic \&Bd Fl literal , 1263and 1264.Ic \&D1 . 1265.It Ic \&Do Ar block 1266Begin a block enclosed by double quotes. 1267Does not have any head arguments. 1268.Pp 1269Examples: 1270.Bd -literal -offset indent -compact 1271\&.Do 1272April is the cruellest month 1273\&.Dc 1274\e(em T.S. Eliot 1275.Ed 1276.Pp 1277See also 1278.Ic \&Dq . 1279.It Ic \&Dq Ar line 1280Encloses its arguments in 1281.Dq typographic 1282double-quotes. 1283.Pp 1284Examples: 1285.Bd -literal -offset indent -compact 1286\&.Dq April is the cruellest month 1287\e(em T.S. Eliot 1288.Ed 1289.Pp 1290See also 1291.Ic \&Qq , 1292.Ic \&Sq , 1293and 1294.Ic \&Do . 1295.It Ic \&Dt Ar TITLE section Op Ar arch 1296Document title for display in the page header. 1297This is the mandatory second macro of any 1298.Nm 1299file. 1300.Pp 1301Its arguments are as follows: 1302.Bl -tag -width section -offset 2n 1303.It Ar TITLE 1304The document's title (name), defaulting to 1305.Dq UNTITLED 1306if unspecified. 1307To achieve a uniform appearance of page header lines, 1308it should by convention be all caps. 1309.It Ar section 1310The manual section. 1311This may be one of 1312.Cm 1 1313.Pq General Commands , 1314.Cm 2 1315.Pq System Calls , 1316.Cm 3 1317.Pq Library Functions , 1318.Cm 3p 1319.Pq Perl Library , 1320.Cm 4 1321.Pq Device Drivers , 1322.Cm 5 1323.Pq File Formats , 1324.Cm 6 1325.Pq Games , 1326.Cm 7 1327.Pq Miscellaneous Information , 1328.Cm 8 1329.Pq System Manager's Manual , 1330or 1331.Cm 9 1332.Pq Kernel Developer's Manual . 1333It should correspond to the manual's filename suffix and defaults to 1334the empty string if unspecified. 1335.It Ar arch 1336This specifies the machine architecture a manual page applies to, 1337where relevant, for example 1338.Cm alpha , 1339.Cm amd64 , 1340.Cm i386 , 1341or 1342.Cm sparc64 . 1343The list of valid architectures varies by operating system. 1344.El 1345.Pp 1346Examples: 1347.Dl \&.Dt FOO 1 1348.Dl \&.Dt FOO 9 i386 1349.Pp 1350See also 1351.Ic \&Dd 1352and 1353.Ic \&Os . 1354.It Ic \&Dv Ar identifier ... 1355Defined variables such as preprocessor constants, constant symbols, 1356enumeration values, and so on. 1357.Pp 1358Examples: 1359.Dl \&.Dv NULL 1360.Dl \&.Dv BUFSIZ 1361.Dl \&.Dv STDOUT_FILENO 1362.Pp 1363See also 1364.Ic \&Er 1365and 1366.Ic \&Ev 1367for special-purpose constants, 1368.Ic \&Va 1369for variable symbols, and 1370.Ic \&Fd 1371for listing preprocessor variable definitions in the 1372.Em SYNOPSIS . 1373.It Ic \&Dx Op Ar version 1374Format the 1375.Dx 1376version provided as an argument, or a default 1377value if no argument is provided. 1378.Pp 1379Examples: 1380.Dl \&.Dx 2.4.1 1381.Dl \&.Dx 1382.Pp 1383See also 1384.Ic \&At , 1385.Ic \&Bsx , 1386.Ic \&Bx , 1387.Ic \&Fx , 1388.Ic \&Nx , 1389and 1390.Ic \&Ox . 1391.It Ic \&Ec Op Ar closing_delimiter 1392Close a scope started by 1393.Ic \&Eo . 1394.Pp 1395The 1396.Ar closing_delimiter 1397argument is used as the enclosure tail, for example, specifying \e(rq 1398will emulate 1399.Ic \&Dc . 1400.It Ic \&Ed 1401End a display context started by 1402.Ic \&Bd . 1403.It Ic \&Ef 1404End a font mode context started by 1405.Ic \&Bf . 1406.It Ic \&Ek 1407End a keep context started by 1408.Ic \&Bk . 1409.It Ic \&El 1410End a list context started by 1411.Ic \&Bl . 1412See also 1413.Ic \&It . 1414.It Ic \&Em Ar word ... 1415Request an italic font. 1416If the output device does not provide that, underline. 1417.Pp 1418This is most often used for stress emphasis (not to be confused with 1419importance, see 1420.Ic \&Sy ) . 1421In the rare cases where none of the semantic markup macros fit, 1422it can also be used for technical terms and placeholders, except 1423that for syntax elements, 1424.Ic \&Sy 1425and 1426.Ic \&Ar 1427are preferred, respectively. 1428.Pp 1429Examples: 1430.Bd -literal -compact -offset indent 1431Selected lines are those 1432\&.Em not 1433matching any of the specified patterns. 1434Some of the functions use a 1435\&.Em hold space 1436to save the pattern space for subsequent retrieval. 1437.Ed 1438.Pp 1439See also 1440.Ic \&No , 1441.Ic \&Ql , 1442and 1443.Ic \&Sy . 1444.It Ic \&En Ar word ... 1445This macro is obsolete. 1446Use 1447.Ic \&Eo 1448or any of the other enclosure macros. 1449.Pp 1450It encloses its argument in the delimiters specified by the last 1451.Ic \&Es 1452macro. 1453.It Ic \&Eo Op Ar opening_delimiter 1454An arbitrary enclosure. 1455The 1456.Ar opening_delimiter 1457argument is used as the enclosure head, for example, specifying \e(lq 1458will emulate 1459.Ic \&Do . 1460.It Ic \&Er Ar identifier ... 1461Error constants for definitions of the 1462.Va errno 1463libc global variable. 1464This is most often used in section 2 and 3 manual pages. 1465.Pp 1466Examples: 1467.Dl \&.Er EPERM 1468.Dl \&.Er ENOENT 1469.Pp 1470See also 1471.Ic \&Dv 1472for general constants. 1473.It Ic \&Es Ar opening_delimiter closing_delimiter 1474This macro is obsolete. 1475Use 1476.Ic \&Eo 1477or any of the other enclosure macros. 1478.Pp 1479It takes two arguments, defining the delimiters to be used by subsequent 1480.Ic \&En 1481macros. 1482.It Ic \&Ev Ar identifier ... 1483Environmental variables such as those specified in 1484.Xr environ 7 . 1485.Pp 1486Examples: 1487.Dl \&.Ev DISPLAY 1488.Dl \&.Ev PATH 1489.Pp 1490See also 1491.Ic \&Dv 1492for general constants. 1493.It Ic \&Ex Fl std Op Ar utility ... 1494Insert a standard sentence regarding command exit values of 0 on success 1495and >0 on failure. 1496This is most often used in section 1, 6, and 8 manual pages. 1497.Pp 1498If 1499.Ar utility 1500is not specified, the document's name set by 1501.Ic \&Nm 1502is used. 1503Multiple 1504.Ar utility 1505arguments are treated as separate utilities. 1506.Pp 1507See also 1508.Ic \&Rv . 1509.It Ic \&Fa Ar argument ... 1510Function argument or parameter. 1511Each argument may be a name and a type (recommended for the 1512.Em SYNOPSIS 1513section), a name alone (for function invocations), 1514or a type alone (for function prototypes). 1515If both a type and a name are given or if the type consists of multiple 1516words, all words belonging to the same function argument have to be 1517given in a single argument to the 1518.Ic \&Fa 1519macro. 1520.Pp 1521This macro is also used to specify the field name of a structure. 1522.Pp 1523Most often, the 1524.Ic \&Fa 1525macro is used in the 1526.Em SYNOPSIS 1527within 1528.Ic \&Fo 1529blocks when documenting multi-line function prototypes. 1530If invoked with multiple arguments, the arguments are separated by a 1531comma. 1532Furthermore, if the following macro is another 1533.Ic \&Fa , 1534the last argument will also have a trailing comma. 1535.Pp 1536Examples: 1537.Dl \&.Fa \(dqconst char *p\(dq 1538.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq 1539.Dl \&.Fa \(dqchar *\(dq size_t 1540.Pp 1541See also 1542.Ic \&Fo . 1543.It Ic \&Fc 1544End a function context started by 1545.Ic \&Fo . 1546.It Ic \&Fd Pf # Ar directive Op Ar argument ... 1547Preprocessor directive, in particular for listing it in the 1548.Em SYNOPSIS . 1549Historically, it was also used to document include files. 1550The latter usage has been deprecated in favour of 1551.Ic \&In . 1552.Pp 1553Examples: 1554.Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler 1555.Dl \&.Fd #define SIO_MAXNFDS 1556.Dl \&.Fd #ifdef FS_DEBUG 1557.Dl \&.Ft void 1558.Dl \&.Fn dbg_open \(dqconst char *\(dq 1559.Dl \&.Fd #endif 1560.Pp 1561See also 1562.Sx MANUAL STRUCTURE , 1563.Ic \&In , 1564and 1565.Ic \&Dv . 1566.It Ic \&Fl Op Ar word ... 1567Command-line flag or option. 1568Used when listing arguments to command-line utilities. 1569Prints a fixed-width hyphen 1570.Sq \- 1571directly followed by each argument. 1572If no arguments are provided, a hyphen is printed followed by a space. 1573If the argument is a macro, a hyphen is prefixed to the subsequent macro 1574output. 1575.Pp 1576Examples: 1577.Dl ".Fl R Op Fl H | L | P" 1578.Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux" 1579.Dl ".Fl type Cm d Fl name Pa CVS" 1580.Dl ".Fl Ar signal_number" 1581.Dl ".Fl o Fl" 1582.Pp 1583See also 1584.Ic \&Cm . 1585.It Ic \&Fn Ar funcname Op Ar argument ... 1586A function name. 1587.Pp 1588Function arguments are surrounded in parenthesis and 1589are delimited by commas. 1590If no arguments are specified, blank parenthesis are output. 1591In the 1592.Em SYNOPSIS 1593section, this macro starts a new output line, 1594and a blank line is automatically inserted between function definitions. 1595.Pp 1596Examples: 1597.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq 1598.Dl \&.Fn funcname \(dqint arg0\(dq 1599.Dl \&.Fn funcname arg0 1600.Bd -literal -offset indent 1601\&.Ft functype 1602\&.Fn funcname 1603.Ed 1604.Pp 1605When referring to a function documented in another manual page, use 1606.Ic \&Xr 1607instead. 1608See also 1609.Sx MANUAL STRUCTURE , 1610.Ic \&Fo , 1611and 1612.Ic \&Ft . 1613.It Ic \&Fo Ar funcname 1614Begin a function block. 1615This is a multi-line version of 1616.Ic \&Fn . 1617.Pp 1618Invocations usually occur in the following context: 1619.Bd -ragged -offset indent 1620.Pf \. Ic \&Ft Ar functype 1621.br 1622.Pf \. Ic \&Fo Ar funcname 1623.br 1624.Pf \. Ic \&Fa Qq Ar argtype Ar argname 1625.br 1626\&.\.\. 1627.br 1628.Pf \. Ic \&Fc 1629.Ed 1630.Pp 1631A 1632.Ic \&Fo 1633scope is closed by 1634.Ic \&Fc . 1635.Pp 1636See also 1637.Sx MANUAL STRUCTURE , 1638.Ic \&Fa , 1639.Ic \&Fc , 1640and 1641.Ic \&Ft . 1642.It Ic \&Fr Ar number 1643This macro is obsolete. 1644No replacement markup is needed. 1645.Pp 1646It was used to show numerical function return values in an italic font. 1647.It Ic \&Ft Ar functype 1648A function type. 1649.Pp 1650In the 1651.Em SYNOPSIS 1652section, a new output line is started after this macro. 1653.Pp 1654Examples: 1655.Dl \&.Ft int 1656.Bd -literal -offset indent -compact 1657\&.Ft functype 1658\&.Fn funcname 1659.Ed 1660.Pp 1661See also 1662.Sx MANUAL STRUCTURE , 1663.Ic \&Fn , 1664and 1665.Ic \&Fo . 1666.It Ic \&Fx Op Ar version 1667Format the 1668.Fx 1669version provided as an argument, or a default value 1670if no argument is provided. 1671.Pp 1672Examples: 1673.Dl \&.Fx 7.1 1674.Dl \&.Fx 1675.Pp 1676See also 1677.Ic \&At , 1678.Ic \&Bsx , 1679.Ic \&Bx , 1680.Ic \&Dx , 1681.Ic \&Nx , 1682and 1683.Ic \&Ox . 1684.It Ic \&Hf Ar filename 1685This macro is not implemented in 1686.Xr mandoc 1 . 1687It was used to include the contents of a (header) file literally. 1688.It Ic \&Ic Ar keyword ... 1689Internal or interactive command, or configuration instruction 1690in a configuration file. 1691See also 1692.Ic \&Cm . 1693.Pp 1694Examples: 1695.Dl \&.Ic :wq 1696.Dl \&.Ic hash 1697.Dl \&.Ic alias 1698.Pp 1699Note that using 1700.Ic \&Ql , 1701.Ic \&Dl , 1702or 1703.Ic \&Bd Fl literal 1704is preferred for displaying code samples; the 1705.Ic \&Ic 1706macro is used when referring to an individual command name. 1707.It Ic \&In Ar filename 1708The name of an include file. 1709This macro is most often used in section 2, 3, and 9 manual pages. 1710.Pp 1711When invoked as the first macro on an input line in the 1712.Em SYNOPSIS 1713section, the argument is displayed in angle brackets 1714and preceded by 1715.Qq #include , 1716and a blank line is inserted in front if there is a preceding 1717function declaration. 1718In other sections, it only encloses its argument in angle brackets 1719and causes no line break. 1720.Pp 1721Examples: 1722.Dl \&.In sys/types.h 1723.Pp 1724See also 1725.Sx MANUAL STRUCTURE . 1726.It Ic \&It Op Ar head 1727A list item. 1728The syntax of this macro depends on the list type. 1729.Pp 1730Lists 1731of type 1732.Fl hang , 1733.Fl ohang , 1734.Fl inset , 1735and 1736.Fl diag 1737have the following syntax: 1738.Pp 1739.D1 Pf \. Ic \&It Ar args 1740.Pp 1741Lists of type 1742.Fl bullet , 1743.Fl dash , 1744.Fl enum , 1745.Fl hyphen 1746and 1747.Fl item 1748have the following syntax: 1749.Pp 1750.D1 Pf \. Ic \&It 1751.Pp 1752with subsequent lines interpreted within the scope of the 1753.Ic \&It 1754until either a closing 1755.Ic \&El 1756or another 1757.Ic \&It . 1758.Pp 1759The 1760.Fl tag 1761list has the following syntax: 1762.Pp 1763.D1 Pf \. Ic \&It Op Cm args 1764.Pp 1765Subsequent lines are interpreted as with 1766.Fl bullet 1767and family. 1768The line arguments correspond to the list's left-hand side; body 1769arguments correspond to the list's contents. 1770.Pp 1771The 1772.Fl column 1773list is the most complicated. 1774Its syntax is as follows: 1775.Pp 1776.D1 Pf \. Ic \&It Ar cell Op Ic \&Ta Ar cell ... 1777.D1 Pf \. Ic \&It Ar cell Op <TAB> Ar cell ... 1778.Pp 1779The arguments consist of one or more lines of text and macros 1780representing a complete table line. 1781Cells within the line are delimited by the special 1782.Ic \&Ta 1783block macro or by literal tab characters. 1784.Pp 1785Using literal tabs is strongly discouraged because they are very 1786hard to use correctly and 1787.Nm 1788code using them is very hard to read. 1789In particular, a blank character is syntactically significant 1790before and after the literal tab character. 1791If a word precedes or follows the tab without an intervening blank, 1792that word is never interpreted as a macro call, but always output 1793literally. 1794.Pp 1795The tab cell delimiter may only be used within the 1796.Ic \&It 1797line itself; on following lines, only the 1798.Ic \&Ta 1799macro can be used to delimit cells, and portability requires that 1800.Ic \&Ta 1801is called by other macros: some parsers do not recognize it when 1802it appears as the first macro on a line. 1803.Pp 1804Note that quoted strings may span tab-delimited cells on an 1805.Ic \&It 1806line. 1807For example, 1808.Pp 1809.Dl .It \(dqcol1 ,\& <TAB> col2 ,\(dq \&; 1810.Pp 1811will preserve the whitespace before both commas, 1812but not the whitespace before the semicolon. 1813.Pp 1814See also 1815.Ic \&Bl . 1816.It Ic \&Lb Cm lib Ns Ar name 1817Specify a library. 1818.Pp 1819The 1820.Ar name 1821parameter may be a system library, such as 1822.Cm z 1823or 1824.Cm pam , 1825in which case a small library description is printed next to the linker 1826invocation; or a custom library, in which case the library name is 1827printed in quotes. 1828This is most commonly used in the 1829.Em SYNOPSIS 1830section as described in 1831.Sx MANUAL STRUCTURE . 1832.Pp 1833Examples: 1834.Dl \&.Lb libz 1835.Dl \&.Lb libmandoc 1836.It Ic \&Li Ar word ... 1837Request a typewriter (literal) font. 1838Deprecated because on terminal output devices, this is usually 1839indistinguishable from normal text. 1840For literal displays, use 1841.Ic \&Ql Pq in-line , 1842.Ic \&Dl Pq single line , 1843or 1844.Ic \&Bd Fl literal Pq multi-line 1845instead. 1846.It Ic \&Lk Ar uri Op Ar display_name 1847Format a hyperlink. 1848.Pp 1849Examples: 1850.Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq 1851.Dl \&.Lk http://bsd.lv 1852.Pp 1853See also 1854.Ic \&Mt . 1855.It Ic \&Lp 1856Deprecated synonym for 1857.Ic \&Pp . 1858.It Ic \&Ms Ar name 1859Display a mathematical symbol. 1860.Pp 1861Examples: 1862.Dl \&.Ms sigma 1863.Dl \&.Ms aleph 1864.It Ic \&Mt Ar localpart Ns @ Ns Ar domain 1865Format a 1866.Dq mailto: 1867hyperlink. 1868.Pp 1869Examples: 1870.Dl \&.Mt discuss@manpages.bsd.lv 1871.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv 1872.It Ic \&Nd Ar line 1873A one line description of the manual's content. 1874This is the mandatory last macro of the 1875.Em NAME 1876section and not appropriate for other sections. 1877.Pp 1878Examples: 1879.Dl Pf . Ic \&Nd mdoc language reference 1880.Dl Pf . Ic \&Nd format and display UNIX manuals 1881.Pp 1882The 1883.Ic \&Nd 1884macro technically accepts child macros and terminates with a subsequent 1885.Ic \&Sh 1886invocation. 1887Do not assume this behaviour: some 1888.Xr whatis 1 1889database generators are not smart enough to parse more than the line 1890arguments and will display macros verbatim. 1891.Pp 1892See also 1893.Ic \&Nm . 1894.It Ic \&Nm Op Ar name 1895The name of the manual page, or \(em in particular in section 1, 6, 1896and 8 pages \(em of an additional command or feature documented in 1897the manual page. 1898When first invoked, the 1899.Ic \&Nm 1900macro expects a single argument, the name of the manual page. 1901Usually, the first invocation happens in the 1902.Em NAME 1903section of the page. 1904The specified name will be remembered and used whenever the macro is 1905called again without arguments later in the page. 1906The 1907.Ic \&Nm 1908macro uses 1909.Sx Block full-implicit 1910semantics when invoked as the first macro on an input line in the 1911.Em SYNOPSIS 1912section; otherwise, it uses ordinary 1913.Sx In-line 1914semantics. 1915.Pp 1916Examples: 1917.Bd -literal -offset indent 1918\&.Sh SYNOPSIS 1919\&.Nm cat 1920\&.Op Fl benstuv 1921\&.Op Ar 1922.Ed 1923.Pp 1924In the 1925.Em SYNOPSIS 1926of section 2, 3 and 9 manual pages, use the 1927.Ic \&Fn 1928macro rather than 1929.Ic \&Nm 1930to mark up the name of the manual page. 1931.It Ic \&No Ar word ... 1932Normal text. 1933Closes the scope of any preceding in-line macro. 1934When used after physical formatting macros like 1935.Ic \&Em 1936or 1937.Ic \&Sy , 1938switches back to the standard font face and weight. 1939Can also be used to embed plain text strings in macro lines 1940using semantic annotation macros. 1941.Pp 1942Examples: 1943.Dl ".Em italic , Sy bold , No and roman" 1944.Bd -literal -offset indent 1945\&.Sm off 1946\&.Cm :C No / Ar pattern No / Ar replacement No / 1947\&.Sm on 1948.Ed 1949.Pp 1950See also 1951.Ic \&Em , 1952.Ic \&Ql , 1953and 1954.Ic \&Sy . 1955.It Ic \&Ns 1956Suppress a space between the output of the preceding macro 1957and the following text or macro. 1958Following invocation, input is interpreted as normal text 1959just like after an 1960.Ic \&No 1961macro. 1962.Pp 1963This has no effect when invoked at the start of a macro line. 1964.Pp 1965Examples: 1966.Dl ".Ar name Ns = Ns Ar value" 1967.Dl ".Cm :M Ns Ar pattern" 1968.Dl ".Fl o Ns Ar output" 1969.Pp 1970See also 1971.Ic \&No 1972and 1973.Ic \&Sm . 1974.It Ic \&Nx Op Ar version 1975Format the 1976.Nx 1977version provided as an argument, or a default value if 1978no argument is provided. 1979.Pp 1980Examples: 1981.Dl \&.Nx 5.01 1982.Dl \&.Nx 1983.Pp 1984See also 1985.Ic \&At , 1986.Ic \&Bsx , 1987.Ic \&Bx , 1988.Ic \&Dx , 1989.Ic \&Fx , 1990and 1991.Ic \&Ox . 1992.It Ic \&Oc 1993Close multi-line 1994.Ic \&Oo 1995context. 1996.It Ic \&Oo Ar block 1997Multi-line version of 1998.Ic \&Op . 1999.Pp 2000Examples: 2001.Bd -literal -offset indent -compact 2002\&.Oo 2003\&.Op Fl flag Ns Ar value 2004\&.Oc 2005.Ed 2006.It Ic \&Op Ar line 2007Optional part of a command line. 2008Prints the argument(s) in brackets. 2009This is most often used in the 2010.Em SYNOPSIS 2011section of section 1 and 8 manual pages. 2012.Pp 2013Examples: 2014.Dl \&.Op \&Fl a \&Ar b 2015.Dl \&.Op \&Ar a | b 2016.Pp 2017See also 2018.Ic \&Oo . 2019.It Ic \&Os Op Ar system Op Ar version 2020Operating system version for display in the page footer. 2021This is the mandatory third macro of 2022any 2023.Nm 2024file. 2025.Pp 2026The optional 2027.Ar system 2028parameter specifies the relevant operating system or environment. 2029It is suggested to leave it unspecified, in which case 2030.Xr mandoc 1 2031uses its 2032.Fl Ios 2033argument or, if that isn't specified either, 2034.Fa sysname 2035and 2036.Fa release 2037as returned by 2038.Xr uname 3 . 2039.Pp 2040Examples: 2041.Dl \&.Os 2042.Dl \&.Os KTH/CSC/TCS 2043.Dl \&.Os BSD 4.3 2044.Pp 2045See also 2046.Ic \&Dd 2047and 2048.Ic \&Dt . 2049.It Ic \&Ot Ar functype 2050This macro is obsolete. 2051Use 2052.Ic \&Ft 2053instead; with 2054.Xr mandoc 1 , 2055both have the same effect. 2056.Pp 2057Historical 2058.Nm 2059packages described it as 2060.Dq "old function type (FORTRAN)" . 2061.It Ic \&Ox Op Ar version 2062Format the 2063.Ox 2064version provided as an argument, or a default value 2065if no argument is provided. 2066.Pp 2067Examples: 2068.Dl \&.Ox 4.5 2069.Dl \&.Ox 2070.Pp 2071See also 2072.Ic \&At , 2073.Ic \&Bsx , 2074.Ic \&Bx , 2075.Ic \&Dx , 2076.Ic \&Fx , 2077and 2078.Ic \&Nx . 2079.It Ic \&Pa Ar name ... 2080An absolute or relative file system path, or a file or directory name. 2081If an argument is not provided, the character 2082.Sq \(ti 2083is used as a default. 2084.Pp 2085Examples: 2086.Dl \&.Pa /usr/bin/mandoc 2087.Dl \&.Pa /usr/share/man/man7/mdoc.7 2088.Pp 2089See also 2090.Ic \&Lk . 2091.It Ic \&Pc 2092Close parenthesised context opened by 2093.Ic \&Po . 2094.It Ic \&Pf Ar prefix macro Op Ar argument ... 2095Removes the space between its argument and the following macro. 2096It is equivalent to: 2097.Pp 2098.D1 Ic \&No Pf \e& Ar prefix Ic \&Ns Ar macro Op Ar argument ... 2099.Pp 2100The 2101.Ar prefix 2102argument is not parsed for macro names or delimiters, 2103but used verbatim as if it were escaped. 2104.Pp 2105Examples: 2106.Dl ".Pf $ Ar variable_name" 2107.Dl ".Pf . Ar macro_name" 2108.Dl ".Pf 0x Ar hex_digits" 2109.Pp 2110See also 2111.Ic \&Ns 2112and 2113.Ic \&Sm . 2114.It Ic \&Po Ar block 2115Multi-line version of 2116.Ic \&Pq . 2117.It Ic \&Pp 2118Break a paragraph. 2119This will assert vertical space between prior and subsequent macros 2120and/or text. 2121.Pp 2122Paragraph breaks are not needed before or after 2123.Ic \&Sh 2124or 2125.Ic \&Ss 2126macros or before displays 2127.Pq Ic \&Bd Ar line 2128or lists 2129.Pq Ic \&Bl 2130unless the 2131.Fl compact 2132flag is given. 2133.It Ic \&Pq Ar line 2134Parenthesised enclosure. 2135.Pp 2136See also 2137.Ic \&Po . 2138.It Ic \&Qc 2139Close quoted context opened by 2140.Ic \&Qo . 2141.It Ic \&Ql Ar line 2142In-line literal display. 2143This can be used for complete command invocations and for multi-word 2144code examples when an indented display is not desired. 2145.Pp 2146See also 2147.Ic \&Dl 2148and 2149.Ic \&Bd 2150.Fl literal . 2151.It Ic \&Qo Ar block 2152Multi-line version of 2153.Ic \&Qq . 2154.It Ic \&Qq Ar line 2155Encloses its arguments in 2156.Qq typewriter 2157double-quotes. 2158Consider using 2159.Ic \&Dq . 2160.Pp 2161See also 2162.Ic \&Dq , 2163.Ic \&Sq , 2164and 2165.Ic \&Qo . 2166.It Ic \&Re 2167Close an 2168.Ic \&Rs 2169block. 2170Does not have any tail arguments. 2171.It Ic \&Rs 2172Begin a bibliographic 2173.Pq Dq reference 2174block. 2175Does not have any head arguments. 2176The block macro may only contain 2177.Ic \&%A , 2178.Ic \&%B , 2179.Ic \&%C , 2180.Ic \&%D , 2181.Ic \&%I , 2182.Ic \&%J , 2183.Ic \&%N , 2184.Ic \&%O , 2185.Ic \&%P , 2186.Ic \&%Q , 2187.Ic \&%R , 2188.Ic \&%T , 2189.Ic \&%U , 2190and 2191.Ic \&%V 2192child macros (at least one must be specified). 2193.Pp 2194Examples: 2195.Bd -literal -offset indent -compact 2196\&.Rs 2197\&.%A J. E. Hopcroft 2198\&.%A J. D. Ullman 2199\&.%B Introduction to Automata Theory, Languages, and Computation 2200\&.%I Addison-Wesley 2201\&.%C Reading, Massachusetts 2202\&.%D 1979 2203\&.Re 2204.Ed 2205.Pp 2206If an 2207.Ic \&Rs 2208block is used within a SEE ALSO section, a vertical space is asserted 2209before the rendered output, else the block continues on the current 2210line. 2211.It Ic \&Rv Fl std Op Ar function ... 2212Insert a standard sentence regarding a function call's return value of 0 2213on success and \-1 on error, with the 2214.Va errno 2215libc global variable set on error. 2216.Pp 2217If 2218.Ar function 2219is not specified, the document's name set by 2220.Ic \&Nm 2221is used. 2222Multiple 2223.Ar function 2224arguments are treated as separate functions. 2225.Pp 2226See also 2227.Ic \&Ex . 2228.It Ic \&Sc 2229Close single-quoted context opened by 2230.Ic \&So . 2231.It Ic \&Sh Ar TITLE LINE 2232Begin a new section. 2233For a list of conventional manual sections, see 2234.Sx MANUAL STRUCTURE . 2235These sections should be used unless it's absolutely necessary that 2236custom sections be used. 2237.Pp 2238Section names should be unique so that they may be keyed by 2239.Ic \&Sx . 2240Although this macro is parsed, it should not consist of child node or it 2241may not be linked with 2242.Ic \&Sx . 2243.Pp 2244See also 2245.Ic \&Pp , 2246.Ic \&Ss , 2247and 2248.Ic \&Sx . 2249.It Ic \&Sm Op Cm on | off 2250Switches the spacing mode for output generated from macros. 2251.Pp 2252By default, spacing is 2253.Cm on . 2254When switched 2255.Cm off , 2256no white space is inserted between macro arguments and between the 2257output generated from adjacent macros, but text lines 2258still get normal spacing between words and sentences. 2259.Pp 2260When called without an argument, the 2261.Ic \&Sm 2262macro toggles the spacing mode. 2263Using this is not recommended because it makes the code harder to read. 2264.It Ic \&So Ar block 2265Multi-line version of 2266.Ic \&Sq . 2267.It Ic \&Sq Ar line 2268Encloses its arguments in 2269.Sq typewriter 2270single-quotes. 2271.Pp 2272See also 2273.Ic \&Dq , 2274.Ic \&Qq , 2275and 2276.Ic \&So . 2277.It Ic \&Ss Ar Title line 2278Begin a new subsection. 2279Unlike with 2280.Ic \&Sh , 2281there is no convention for the naming of subsections. 2282Except 2283.Em DESCRIPTION , 2284the conventional sections described in 2285.Sx MANUAL STRUCTURE 2286rarely have subsections. 2287.Pp 2288Sub-section names should be unique so that they may be keyed by 2289.Ic \&Sx . 2290Although this macro is parsed, it should not consist of child node or it 2291may not be linked with 2292.Ic \&Sx . 2293.Pp 2294See also 2295.Ic \&Pp , 2296.Ic \&Sh , 2297and 2298.Ic \&Sx . 2299.It Ic \&St Fl Ns Ar abbreviation 2300Replace an abbreviation for a standard with the full form. 2301The following standards are recognised. 2302Where multiple lines are given without a blank line in between, 2303they all refer to the same standard, and using the first form 2304is recommended. 2305.Bl -tag -width 1n 2306.It C language standards 2307.Pp 2308.Bl -tag -width "-p1003.1g-2000" -compact 2309.It \-ansiC 2310.St -ansiC 2311.It \-ansiC-89 2312.St -ansiC-89 2313.It \-isoC 2314.St -isoC 2315.It \-isoC-90 2316.St -isoC-90 2317.br 2318The original C standard. 2319.Pp 2320.It \-isoC-amd1 2321.St -isoC-amd1 2322.Pp 2323.It \-isoC-tcor1 2324.St -isoC-tcor1 2325.Pp 2326.It \-isoC-tcor2 2327.St -isoC-tcor2 2328.Pp 2329.It \-isoC-99 2330.St -isoC-99 2331.br 2332The second major version of the C language standard. 2333.Pp 2334.It \-isoC-2011 2335.St -isoC-2011 2336.br 2337The third major version of the C language standard. 2338.El 2339.It POSIX.1 before the Single UNIX Specification 2340.Pp 2341.Bl -tag -width "-p1003.1g-2000" -compact 2342.It \-p1003.1-88 2343.St -p1003.1-88 2344.It \-p1003.1 2345.St -p1003.1 2346.br 2347The original POSIX standard, based on ANSI C. 2348.Pp 2349.It \-p1003.1-90 2350.St -p1003.1-90 2351.It \-iso9945-1-90 2352.St -iso9945-1-90 2353.br 2354The first update of POSIX.1. 2355.Pp 2356.It \-p1003.1b-93 2357.St -p1003.1b-93 2358.It \-p1003.1b 2359.St -p1003.1b 2360.br 2361Real-time extensions. 2362.Pp 2363.It \-p1003.1c-95 2364.St -p1003.1c-95 2365.br 2366POSIX thread interfaces. 2367.Pp 2368.It \-p1003.1i-95 2369.St -p1003.1i-95 2370.br 2371Technical Corrigendum. 2372.Pp 2373.It \-p1003.1-96 2374.St -p1003.1-96 2375.It \-iso9945-1-96 2376.St -iso9945-1-96 2377.br 2378Includes POSIX.1-1990, 1b, 1c, and 1i. 2379.El 2380.It X/Open Portability Guide version 4 and related standards 2381.Pp 2382.Bl -tag -width "-p1003.1g-2000" -compact 2383.It \-xpg3 2384.St -xpg3 2385.br 2386An XPG4 precursor, published in 1989. 2387.Pp 2388.It \-p1003.2 2389.St -p1003.2 2390.It \-p1003.2-92 2391.St -p1003.2-92 2392.It \-iso9945-2-93 2393.St -iso9945-2-93 2394.br 2395An XCU4 precursor. 2396.Pp 2397.It \-p1003.2a-92 2398.St -p1003.2a-92 2399.br 2400Updates to POSIX.2. 2401.Pp 2402.It \-xpg4 2403.St -xpg4 2404.br 2405Based on POSIX.1 and POSIX.2, published in 1992. 2406.El 2407.It Single UNIX Specification version 1 and related standards 2408.Pp 2409.Bl -tag -width "-p1003.1g-2000" -compact 2410.It \-susv1 2411.St -susv1 2412.It \-xpg4.2 2413.St -xpg4.2 2414.br 2415This standard was published in 1994. 2416It was used as the basis for UNIX 95 certification. 2417The following three refer to parts of it. 2418.Pp 2419.It \-xsh4.2 2420.St -xsh4.2 2421.Pp 2422.It \-xcurses4.2 2423.St -xcurses4.2 2424.Pp 2425.It \-p1003.1g-2000 2426.St -p1003.1g-2000 2427.br 2428Networking APIs, including sockets. 2429.Pp 2430.It \-svid4 2431.St -svid4 , 2432.br 2433Published in 1995. 2434.El 2435.It Single UNIX Specification version 2 and related standards 2436.Pp 2437.Bl -tag -width "-p1003.1g-2000" -compact 2438.It \-susv2 2439.St -susv2 2440This Standard was published in 1997 2441and is also called X/Open Portability Guide version 5. 2442It was used as the basis for UNIX 98 certification. 2443The following refer to parts of it. 2444.Pp 2445.It \-xbd5 2446.St -xbd5 2447.Pp 2448.It \-xsh5 2449.St -xsh5 2450.Pp 2451.It \-xcu5 2452.St -xcu5 2453.Pp 2454.It \-xns5 2455.St -xns5 2456.It \-xns5.2 2457.St -xns5.2 2458.El 2459.It Single UNIX Specification version 3 2460.Pp 2461.Bl -tag -width "-p1003.1-2001" -compact 2462.It \-p1003.1-2001 2463.St -p1003.1-2001 2464.It \-susv3 2465.St -susv3 2466.br 2467This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j. 2468It is also called X/Open Portability Guide version 6. 2469It is used as the basis for UNIX 03 certification. 2470.Pp 2471.It \-p1003.1-2004 2472.St -p1003.1-2004 2473.br 2474The second and last Technical Corrigendum. 2475.El 2476.It Single UNIX Specification version 4 2477.Pp 2478.Bl -tag -width "-p1003.1g-2000" -compact 2479.It \-p1003.1-2008 2480.St -p1003.1-2008 2481.It \-susv4 2482.St -susv4 2483.br 2484This standard is also called 2485X/Open Portability Guide version 7. 2486.El 2487.It Other standards 2488.Pp 2489.Bl -tag -width "-p1003.1g-2000" -compact 2490.It \-ieee754 2491.St -ieee754 2492.br 2493Floating-point arithmetic. 2494.Pp 2495.It \-iso8601 2496.St -iso8601 2497.br 2498Representation of dates and times, published in 1988. 2499.Pp 2500.It \-iso8802-3 2501.St -iso8802-3 2502.br 2503Ethernet local area networks. 2504.Pp 2505.It \-ieee1275-94 2506.St -ieee1275-94 2507.El 2508.El 2509.It Ic \&Sx Ar Title line 2510Reference a section or subsection in the same manual page. 2511The referenced section or subsection name must be identical to the 2512enclosed argument, including whitespace. 2513.Pp 2514Examples: 2515.Dl \&.Sx MANUAL STRUCTURE 2516.Pp 2517See also 2518.Ic \&Sh 2519and 2520.Ic \&Ss . 2521.It Ic \&Sy Ar word ... 2522Request a boldface font. 2523.Pp 2524This is most often used to indicate importance or seriousness (not to be 2525confused with stress emphasis, see 2526.Ic \&Em ) . 2527When none of the semantic macros fit, it is also adequate for syntax 2528elements that have to be given or that appear verbatim. 2529.Pp 2530Examples: 2531.Bd -literal -compact -offset indent 2532\&.Sy Warning : 2533If 2534\&.Sy s 2535appears in the owner permissions, set-user-ID mode is set. 2536This utility replaces the former 2537\&.Sy dumpdir 2538program. 2539.Ed 2540.Pp 2541See also 2542.Ic \&Em , 2543.Ic \&No , 2544and 2545.Ic \&Ql . 2546.It Ic \&Ta 2547Table cell separator in 2548.Ic \&Bl Fl column 2549lists; can only be used below 2550.Ic \&It . 2551.It Ic \&Tn Ar word ... 2552Supported only for compatibility, do not use this in new manuals. 2553Even though the macro name 2554.Pq Dq tradename 2555suggests a semantic function, historic usage is inconsistent, mostly 2556using it as a presentation-level macro to request a small caps font. 2557.It Ic \&Ud 2558Supported only for compatibility, do not use this in new manuals. 2559Prints out 2560.Dq currently under development. 2561.It Ic \&Ux 2562Supported only for compatibility, do not use this in new manuals. 2563Prints out 2564.Dq Ux . 2565.It Ic \&Va Oo Ar type Oc Ar identifier ... 2566A variable name. 2567.Pp 2568Examples: 2569.Dl \&.Va foo 2570.Dl \&.Va const char *bar ; 2571.Pp 2572For function arguments and parameters, use 2573.Ic \&Fa 2574instead. 2575For declarations of global variables in the 2576.Em SYNOPSIS 2577section, use 2578.Ic \&Vt . 2579.It Ic \&Vt Ar type Op Ar identifier 2580A variable type. 2581.Pp 2582This is also used for indicating global variables in the 2583.Em SYNOPSIS 2584section, in which case a variable name is also specified. 2585Note that it accepts 2586.Sx Block partial-implicit 2587syntax when invoked as the first macro on an input line in the 2588.Em SYNOPSIS 2589section, else it accepts ordinary 2590.Sx In-line 2591syntax. 2592In the former case, this macro starts a new output line, 2593and a blank line is inserted in front if there is a preceding 2594function definition or include directive. 2595.Pp 2596Examples: 2597.Dl \&.Vt unsigned char 2598.Dl \&.Vt extern const char * const sys_signame[] \&; 2599.Pp 2600For parameters in function prototypes, use 2601.Ic \&Fa 2602instead, for function return types 2603.Ic \&Ft , 2604and for variable names outside the 2605.Em SYNOPSIS 2606section 2607.Ic \&Va , 2608even when including a type with the name. 2609See also 2610.Sx MANUAL STRUCTURE . 2611.It Ic \&Xc 2612Close a scope opened by 2613.Ic \&Xo . 2614.It Ic \&Xo Ar block 2615Extend the header of an 2616.Ic \&It 2617macro or the body of a partial-implicit block macro 2618beyond the end of the input line. 2619This macro originally existed to work around the 9-argument limit 2620of historic 2621.Xr roff 7 . 2622.It Ic \&Xr Ar name section 2623Link to another manual 2624.Pq Qq cross-reference . 2625.Pp 2626Cross reference the 2627.Ar name 2628and 2629.Ar section 2630number of another man page. 2631.Pp 2632Examples: 2633.Dl \&.Xr mandoc 1 2634.Dl \&.Xr mandoc 1 \&; 2635.Dl \&.Xr mandoc 1 \&Ns s behaviour 2636.El 2637.Sh MACRO SYNTAX 2638The syntax of a macro depends on its classification. 2639In this section, 2640.Sq \-arg 2641refers to macro arguments, which may be followed by zero or more 2642.Sq parm 2643parameters; 2644.Sq \&Yo 2645opens the scope of a macro; and if specified, 2646.Sq \&Yc 2647closes it out. 2648.Pp 2649The 2650.Em Callable 2651column indicates that the macro may also be called by passing its name 2652as an argument to another macro. 2653For example, 2654.Sq \&.Op \&Fl O \&Ar file 2655produces 2656.Sq Op Fl O Ar file . 2657To prevent a macro call and render the macro name literally, 2658escape it by prepending a zero-width space, 2659.Sq \e& . 2660For example, 2661.Sq \&Op \e&Fl O 2662produces 2663.Sq Op \&Fl O . 2664If a macro is not callable but its name appears as an argument 2665to another macro, it is interpreted as opaque text. 2666For example, 2667.Sq \&.Fl \&Sh 2668produces 2669.Sq Fl \&Sh . 2670.Pp 2671The 2672.Em Parsed 2673column indicates whether the macro may call other macros by receiving 2674their names as arguments. 2675If a macro is not parsed but the name of another macro appears 2676as an argument, it is interpreted as opaque text. 2677.Pp 2678The 2679.Em Scope 2680column, if applicable, describes closure rules. 2681.Ss Block full-explicit 2682Multi-line scope closed by an explicit closing macro. 2683All macros contains bodies; only 2684.Ic \s&Bf 2685and 2686.Pq optionally 2687.Ic \&Bl 2688contain a head. 2689.Bd -literal -offset indent 2690\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB 2691\(lBbody...\(rB 2692\&.Yc 2693.Ed 2694.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent 2695.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2696.It Ic \&Bd Ta \&No Ta \&No Ta closed by Ic \&Ed 2697.It Ic \&Bf Ta \&No Ta \&No Ta closed by Ic \&Ef 2698.It Ic \&Bk Ta \&No Ta \&No Ta closed by Ic \&Ek 2699.It Ic \&Bl Ta \&No Ta \&No Ta closed by Ic \&El 2700.It Ic \&Ed Ta \&No Ta \&No Ta opened by Ic \&Bd 2701.It Ic \&Ef Ta \&No Ta \&No Ta opened by Ic \&Bf 2702.It Ic \&Ek Ta \&No Ta \&No Ta opened by Ic \&Bk 2703.It Ic \&El Ta \&No Ta \&No Ta opened by Ic \&Bl 2704.El 2705.Ss Block full-implicit 2706Multi-line scope closed by end-of-file or implicitly by another macro. 2707All macros have bodies; some 2708.Po 2709.Ic \&It Fl bullet , 2710.Fl hyphen , 2711.Fl dash , 2712.Fl enum , 2713.Fl item 2714.Pc 2715don't have heads; only one 2716.Po 2717.Ic \&It 2718in 2719.Ic \&Bl Fl column 2720.Pc 2721has multiple heads. 2722.Bd -literal -offset indent 2723\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB 2724\(lBbody...\(rB 2725.Ed 2726.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent 2727.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2728.It Ic \&It Ta \&No Ta Yes Ta closed by Ic \&It , Ic \&El 2729.It Ic \&Nd Ta \&No Ta \&No Ta closed by Ic \&Sh 2730.It Ic \&Nm Ta \&No Ta Yes Ta closed by Ic \&Nm , Ic \&Sh , Ic \&Ss 2731.It Ic \&Sh Ta \&No Ta Yes Ta closed by Ic \&Sh 2732.It Ic \&Ss Ta \&No Ta Yes Ta closed by Ic \&Sh , Ic \&Ss 2733.El 2734.Pp 2735Note that the 2736.Ic \&Nm 2737macro is a 2738.Sx Block full-implicit 2739macro only when invoked as the first macro 2740in a 2741.Em SYNOPSIS 2742section line, else it is 2743.Sx In-line . 2744.Ss Block partial-explicit 2745Like block full-explicit, but also with single-line scope. 2746Each has at least a body and, in limited circumstances, a head 2747.Po 2748.Ic \&Fo , 2749.Ic \&Eo 2750.Pc 2751and/or tail 2752.Pq Ic \&Ec . 2753.Bd -literal -offset indent 2754\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB 2755\(lBbody...\(rB 2756\&.Yc \(lBtail...\(rB 2757 2758\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ 2759\(lBbody...\(rB \&Yc \(lBtail...\(rB 2760.Ed 2761.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent 2762.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2763.It Ic \&Ac Ta Yes Ta Yes Ta opened by Ic \&Ao 2764.It Ic \&Ao Ta Yes Ta Yes Ta closed by Ic \&Ac 2765.It Ic \&Bc Ta Yes Ta Yes Ta closed by Ic \&Bo 2766.It Ic \&Bo Ta Yes Ta Yes Ta opened by Ic \&Bc 2767.It Ic \&Brc Ta Yes Ta Yes Ta opened by Ic \&Bro 2768.It Ic \&Bro Ta Yes Ta Yes Ta closed by Ic \&Brc 2769.It Ic \&Dc Ta Yes Ta Yes Ta opened by Ic \&Do 2770.It Ic \&Do Ta Yes Ta Yes Ta closed by Ic \&Dc 2771.It Ic \&Ec Ta Yes Ta Yes Ta opened by Ic \&Eo 2772.It Ic \&Eo Ta Yes Ta Yes Ta closed by Ic \&Ec 2773.It Ic \&Fc Ta Yes Ta Yes Ta opened by Ic \&Fo 2774.It Ic \&Fo Ta \&No Ta \&No Ta closed by Ic \&Fc 2775.It Ic \&Oc Ta Yes Ta Yes Ta closed by Ic \&Oo 2776.It Ic \&Oo Ta Yes Ta Yes Ta opened by Ic \&Oc 2777.It Ic \&Pc Ta Yes Ta Yes Ta closed by Ic \&Po 2778.It Ic \&Po Ta Yes Ta Yes Ta opened by Ic \&Pc 2779.It Ic \&Qc Ta Yes Ta Yes Ta opened by Ic \&Oo 2780.It Ic \&Qo Ta Yes Ta Yes Ta closed by Ic \&Oc 2781.It Ic \&Re Ta \&No Ta \&No Ta opened by Ic \&Rs 2782.It Ic \&Rs Ta \&No Ta \&No Ta closed by Ic \&Re 2783.It Ic \&Sc Ta Yes Ta Yes Ta opened by Ic \&So 2784.It Ic \&So Ta Yes Ta Yes Ta closed by Ic \&Sc 2785.It Ic \&Xc Ta Yes Ta Yes Ta opened by Ic \&Xo 2786.It Ic \&Xo Ta Yes Ta Yes Ta closed by Ic \&Xc 2787.El 2788.Ss Block partial-implicit 2789Like block full-implicit, but with single-line scope closed by the 2790end of the line. 2791.Bd -literal -offset indent 2792\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB 2793.Ed 2794.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent 2795.It Em Macro Ta Em Callable Ta Em Parsed 2796.It Ic \&Aq Ta Yes Ta Yes 2797.It Ic \&Bq Ta Yes Ta Yes 2798.It Ic \&Brq Ta Yes Ta Yes 2799.It Ic \&D1 Ta \&No Ta \&Yes 2800.It Ic \&Dl Ta \&No Ta Yes 2801.It Ic \&Dq Ta Yes Ta Yes 2802.It Ic \&En Ta Yes Ta Yes 2803.It Ic \&Op Ta Yes Ta Yes 2804.It Ic \&Pq Ta Yes Ta Yes 2805.It Ic \&Ql Ta Yes Ta Yes 2806.It Ic \&Qq Ta Yes Ta Yes 2807.It Ic \&Sq Ta Yes Ta Yes 2808.It Ic \&Vt Ta Yes Ta Yes 2809.El 2810.Pp 2811Note that the 2812.Ic \&Vt 2813macro is a 2814.Sx Block partial-implicit 2815only when invoked as the first macro 2816in a 2817.Em SYNOPSIS 2818section line, else it is 2819.Sx In-line . 2820.Ss Special block macro 2821The 2822.Ic \&Ta 2823macro can only be used below 2824.Ic \&It 2825in 2826.Ic \&Bl Fl column 2827lists. 2828It delimits blocks representing table cells; 2829these blocks have bodies, but no heads. 2830.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent 2831.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2832.It Ic \&Ta Ta Yes Ta Yes Ta closed by Ic \&Ta , Ic \&It 2833.El 2834.Ss In-line 2835Closed by the end of the line, fixed argument lengths, 2836and/or subsequent macros. 2837In-line macros have only text children. 2838If a number (or inequality) of arguments is 2839.Pq n , 2840then the macro accepts an arbitrary number of arguments. 2841.Bd -literal -offset indent 2842\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB 2843 2844\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc... 2845 2846\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN 2847.Ed 2848.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent 2849.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments 2850.It Ic \&%A Ta \&No Ta \&No Ta >0 2851.It Ic \&%B Ta \&No Ta \&No Ta >0 2852.It Ic \&%C Ta \&No Ta \&No Ta >0 2853.It Ic \&%D Ta \&No Ta \&No Ta >0 2854.It Ic \&%I Ta \&No Ta \&No Ta >0 2855.It Ic \&%J Ta \&No Ta \&No Ta >0 2856.It Ic \&%N Ta \&No Ta \&No Ta >0 2857.It Ic \&%O Ta \&No Ta \&No Ta >0 2858.It Ic \&%P Ta \&No Ta \&No Ta >0 2859.It Ic \&%Q Ta \&No Ta \&No Ta >0 2860.It Ic \&%R Ta \&No Ta \&No Ta >0 2861.It Ic \&%T Ta \&No Ta \&No Ta >0 2862.It Ic \&%U Ta \&No Ta \&No Ta >0 2863.It Ic \&%V Ta \&No Ta \&No Ta >0 2864.It Ic \&Ad Ta Yes Ta Yes Ta >0 2865.It Ic \&An Ta Yes Ta Yes Ta >0 2866.It Ic \&Ap Ta Yes Ta Yes Ta 0 2867.It Ic \&Ar Ta Yes Ta Yes Ta n 2868.It Ic \&At Ta Yes Ta Yes Ta 1 2869.It Ic \&Bsx Ta Yes Ta Yes Ta n 2870.It Ic \&Bt Ta \&No Ta \&No Ta 0 2871.It Ic \&Bx Ta Yes Ta Yes Ta n 2872.It Ic \&Cd Ta Yes Ta Yes Ta >0 2873.It Ic \&Cm Ta Yes Ta Yes Ta >0 2874.It Ic \&Db Ta \&No Ta \&No Ta 1 2875.It Ic \&Dd Ta \&No Ta \&No Ta n 2876.It Ic \&Dt Ta \&No Ta \&No Ta n 2877.It Ic \&Dv Ta Yes Ta Yes Ta >0 2878.It Ic \&Dx Ta Yes Ta Yes Ta n 2879.It Ic \&Em Ta Yes Ta Yes Ta >0 2880.It Ic \&Er Ta Yes Ta Yes Ta >0 2881.It Ic \&Es Ta Yes Ta Yes Ta 2 2882.It Ic \&Ev Ta Yes Ta Yes Ta >0 2883.It Ic \&Ex Ta \&No Ta \&No Ta n 2884.It Ic \&Fa Ta Yes Ta Yes Ta >0 2885.It Ic \&Fd Ta \&No Ta \&No Ta >0 2886.It Ic \&Fl Ta Yes Ta Yes Ta n 2887.It Ic \&Fn Ta Yes Ta Yes Ta >0 2888.It Ic \&Fr Ta Yes Ta Yes Ta >0 2889.It Ic \&Ft Ta Yes Ta Yes Ta >0 2890.It Ic \&Fx Ta Yes Ta Yes Ta n 2891.It Ic \&Hf Ta \&No Ta \&No Ta n 2892.It Ic \&Ic Ta Yes Ta Yes Ta >0 2893.It Ic \&In Ta \&No Ta \&No Ta 1 2894.It Ic \&Lb Ta \&No Ta \&No Ta 1 2895.It Ic \&Li Ta Yes Ta Yes Ta >0 2896.It Ic \&Lk Ta Yes Ta Yes Ta >0 2897.It Ic \&Lp Ta \&No Ta \&No Ta 0 2898.It Ic \&Ms Ta Yes Ta Yes Ta >0 2899.It Ic \&Mt Ta Yes Ta Yes Ta >0 2900.It Ic \&Nm Ta Yes Ta Yes Ta n 2901.It Ic \&No Ta Yes Ta Yes Ta >0 2902.It Ic \&Ns Ta Yes Ta Yes Ta 0 2903.It Ic \&Nx Ta Yes Ta Yes Ta n 2904.It Ic \&Os Ta \&No Ta \&No Ta n 2905.It Ic \&Ot Ta Yes Ta Yes Ta >0 2906.It Ic \&Ox Ta Yes Ta Yes Ta n 2907.It Ic \&Pa Ta Yes Ta Yes Ta n 2908.It Ic \&Pf Ta Yes Ta Yes Ta 1 2909.It Ic \&Pp Ta \&No Ta \&No Ta 0 2910.It Ic \&Rv Ta \&No Ta \&No Ta n 2911.It Ic \&Sm Ta \&No Ta \&No Ta <2 2912.It Ic \&St Ta \&No Ta Yes Ta 1 2913.It Ic \&Sx Ta Yes Ta Yes Ta >0 2914.It Ic \&Sy Ta Yes Ta Yes Ta >0 2915.It Ic \&Tn Ta Yes Ta Yes Ta >0 2916.It Ic \&Ud Ta \&No Ta \&No Ta 0 2917.It Ic \&Ux Ta Yes Ta Yes Ta n 2918.It Ic \&Va Ta Yes Ta Yes Ta n 2919.It Ic \&Vt Ta Yes Ta Yes Ta >0 2920.It Ic \&Xr Ta Yes Ta Yes Ta 2 2921.El 2922.Ss Delimiters 2923When a macro argument consists of one single input character 2924considered as a delimiter, the argument gets special handling. 2925This does not apply when delimiters appear in arguments containing 2926more than one character. 2927Consequently, to prevent special handling and just handle it 2928like any other argument, a delimiter can be escaped by prepending 2929a zero-width space 2930.Pq Sq \e& . 2931In text lines, delimiters never need escaping, but may be used 2932as normal punctuation. 2933.Pp 2934For many macros, when the leading arguments are opening delimiters, 2935these delimiters are put before the macro scope, 2936and when the trailing arguments are closing delimiters, 2937these delimiters are put after the macro scope. 2938Spacing is suppressed after opening delimiters 2939and before closing delimiters. 2940For example, 2941.Pp 2942.D1 Pf \. \&Aq "( [ word ] ) ." 2943.Pp 2944renders as: 2945.Pp 2946.D1 Aq ( [ word ] ) . 2947.Pp 2948Opening delimiters are: 2949.Pp 2950.Bl -tag -width Ds -offset indent -compact 2951.It \&( 2952left parenthesis 2953.It \&[ 2954left bracket 2955.El 2956.Pp 2957Closing delimiters are: 2958.Pp 2959.Bl -tag -width Ds -offset indent -compact 2960.It \&. 2961period 2962.It \&, 2963comma 2964.It \&: 2965colon 2966.It \&; 2967semicolon 2968.It \&) 2969right parenthesis 2970.It \&] 2971right bracket 2972.It \&? 2973question mark 2974.It \&! 2975exclamation mark 2976.El 2977.Pp 2978Note that even a period preceded by a backslash 2979.Pq Sq \e.\& 2980gets this special handling; use 2981.Sq \e&.\& 2982to prevent that. 2983.Pp 2984Many in-line macros interrupt their scope when they encounter 2985delimiters, and resume their scope when more arguments follow that 2986are not delimiters. 2987For example, 2988.Pp 2989.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e" 2990.Pp 2991renders as: 2992.Pp 2993.D1 Fl a ( b | c \*(Ba d ) e 2994.Pp 2995This applies to both opening and closing delimiters, 2996and also to the middle delimiter, which does not suppress spacing: 2997.Pp 2998.Bl -tag -width Ds -offset indent -compact 2999.It \&| 3000vertical bar 3001.El 3002.Pp 3003As a special case, the predefined string \e*(Ba is handled and rendered 3004in the same way as a plain 3005.Sq \&| 3006character. 3007Using this predefined string is not recommended in new manuals. 3008.Pp 3009Appending a zero-width space 3010.Pq Sq \e& 3011to the end of an input line is also useful to prevent the interpretation 3012of a trailing period, exclamation or question mark as the end of a 3013sentence, for example when an abbreviation happens to occur 3014at the end of a text or macro input line. 3015.Ss Font handling 3016In 3017.Nm 3018documents, usage of semantic markup is recommended in order to have 3019proper fonts automatically selected; only when no fitting semantic markup 3020is available, consider falling back to 3021.Sx Physical markup 3022macros. 3023Whenever any 3024.Nm 3025macro switches the 3026.Xr roff 7 3027font mode, it will automatically restore the previous font when exiting 3028its scope. 3029Manually switching the font using the 3030.Xr roff 7 3031.Ql \ef 3032font escape sequences is never required. 3033.Sh COMPATIBILITY 3034This section provides an incomplete list of compatibility issues 3035between mandoc and GNU troff 3036.Pq Qq groff . 3037.Pp 3038The following problematic behaviour is found in groff: 3039.Pp 3040.Bl -dash -compact 3041.It 3042.Ic \&Dd 3043with non-standard arguments behaves very strangely. 3044When there are three arguments, they are printed verbatim. 3045Any other number of arguments is replaced by the current date, 3046but without any arguments the string 3047.Dq Epoch 3048is printed. 3049.It 3050.Ic \&Lk 3051only accepts a single link-name argument; the remainder is misformatted. 3052.It 3053.Ic \&Pa 3054does not format its arguments when used in the FILES section under 3055certain list types. 3056.It 3057.Ic \&Ta 3058can only be called by other macros, but not at the beginning of a line. 3059.It 3060.Ic \&%C 3061is not implemented (up to and including groff-1.22.2). 3062.It 3063.Sq \ef 3064.Pq font face 3065and 3066.Sq \eF 3067.Pq font family face 3068.Sx Text Decoration 3069escapes behave irregularly when specified within line-macro scopes. 3070.It 3071Negative scaling units return to prior lines. 3072Instead, mandoc truncates them to zero. 3073.El 3074.Pp 3075The following features are unimplemented in mandoc: 3076.Pp 3077.Bl -dash -compact 3078.It 3079.Ic \&Bd Fl file Ar file 3080is unsupported for security reasons. 3081.It 3082.Ic \&Bd 3083.Fl filled 3084does not adjust the right margin, but is an alias for 3085.Ic \&Bd 3086.Fl ragged . 3087.It 3088.Ic \&Bd 3089.Fl literal 3090does not use a literal font, but is an alias for 3091.Ic \&Bd 3092.Fl unfilled . 3093.It 3094.Ic \&Bd 3095.Fl offset Cm center 3096and 3097.Fl offset Cm right 3098don't work. 3099Groff does not implement centered and flush-right rendering either, 3100but produces large indentations. 3101.El 3102.Sh SEE ALSO 3103.Xr man 1 , 3104.Xr mandoc 1 , 3105.Xr eqn 7 , 3106.Xr man 7 , 3107.Xr mandoc_char 7 , 3108.Xr roff 7 , 3109.Xr tbl 7 3110.Pp 3111The web page 3112.Lk http://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language" 3113provides a few tutorial-style pages for beginners, an extensive style 3114guide for advanced authors, and an alphabetic index helping to choose 3115the best macros for various kinds of content. 3116.Sh HISTORY 3117The 3118.Nm 3119language first appeared as a troff macro package in 3120.Bx 4.4 . 3121It was later significantly updated by Werner Lemberg and Ruslan Ermilov 3122in groff-1.17. 3123The standalone implementation that is part of the 3124.Xr mandoc 1 3125utility written by Kristaps Dzonsons appeared in 3126.Ox 4.6 . 3127.Sh AUTHORS 3128The 3129.Nm 3130reference was written by 3131.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 3132