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