1.\" $OpenBSD: mdoc.7,v 1.162 2018/12/23 22:03:17 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: December 23 2018 $ 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) (no 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. 1329For 1330.Ox , 1331the following are valid architectures: 1332.Cm alpha , 1333.Cm amd64 , 1334.Cm armv7 , 1335.Cm arm64 , 1336.Cm hppa , 1337.Cm i386 , 1338.Cm landisk , 1339.Cm loongson , 1340.Cm luna88k , 1341.Cm macppc , 1342.Cm mips64 , 1343.Cm octeon , 1344.Cm sgi , 1345.Cm socppc , 1346and 1347.Cm sparc64 . 1348.El 1349.Pp 1350Examples: 1351.Dl \&.Dt FOO 1 1352.Dl \&.Dt FOO 9 i386 1353.Pp 1354See also 1355.Ic \&Dd 1356and 1357.Ic \&Os . 1358.It Ic \&Dv Ar identifier ... 1359Defined variables such as preprocessor constants, constant symbols, 1360enumeration values, and so on. 1361.Pp 1362Examples: 1363.Dl \&.Dv NULL 1364.Dl \&.Dv BUFSIZ 1365.Dl \&.Dv STDOUT_FILENO 1366.Pp 1367See also 1368.Ic \&Er 1369and 1370.Ic \&Ev 1371for special-purpose constants, 1372.Ic \&Va 1373for variable symbols, and 1374.Ic \&Fd 1375for listing preprocessor variable definitions in the 1376.Em SYNOPSIS . 1377.It Ic \&Dx Op Ar version 1378Format the 1379.Dx 1380version provided as an argument, or a default 1381value if no argument is provided. 1382.Pp 1383Examples: 1384.Dl \&.Dx 2.4.1 1385.Dl \&.Dx 1386.Pp 1387See also 1388.Ic \&At , 1389.Ic \&Bsx , 1390.Ic \&Bx , 1391.Ic \&Fx , 1392.Ic \&Nx , 1393and 1394.Ic \&Ox . 1395.It Ic \&Ec Op Ar closing_delimiter 1396Close a scope started by 1397.Ic \&Eo . 1398.Pp 1399The 1400.Ar closing_delimiter 1401argument is used as the enclosure tail, for example, specifying \e(rq 1402will emulate 1403.Ic \&Dc . 1404.It Ic \&Ed 1405End a display context started by 1406.Ic \&Bd . 1407.It Ic \&Ef 1408End a font mode context started by 1409.Ic \&Bf . 1410.It Ic \&Ek 1411End a keep context started by 1412.Ic \&Bk . 1413.It Ic \&El 1414End a list context started by 1415.Ic \&Bl . 1416See also 1417.Ic \&It . 1418.It Ic \&Em Ar word ... 1419Request an italic font. 1420If the output device does not provide that, underline. 1421.Pp 1422This is most often used for stress emphasis (not to be confused with 1423importance, see 1424.Ic \&Sy ) . 1425In the rare cases where none of the semantic markup macros fit, 1426it can also be used for technical terms and placeholders, except 1427that for syntax elements, 1428.Ic \&Sy 1429and 1430.Ic \&Ar 1431are preferred, respectively. 1432.Pp 1433Examples: 1434.Bd -literal -compact -offset indent 1435Selected lines are those 1436\&.Em not 1437matching any of the specified patterns. 1438Some of the functions use a 1439\&.Em hold space 1440to save the pattern space for subsequent retrieval. 1441.Ed 1442.Pp 1443See also 1444.Ic \&No , 1445.Ic \&Ql , 1446and 1447.Ic \&Sy . 1448.It Ic \&En Ar word ... 1449This macro is obsolete. 1450Use 1451.Ic \&Eo 1452or any of the other enclosure macros. 1453.Pp 1454It encloses its argument in the delimiters specified by the last 1455.Ic \&Es 1456macro. 1457.It Ic \&Eo Op Ar opening_delimiter 1458An arbitrary enclosure. 1459The 1460.Ar opening_delimiter 1461argument is used as the enclosure head, for example, specifying \e(lq 1462will emulate 1463.Ic \&Do . 1464.It Ic \&Er Ar identifier ... 1465Error constants for definitions of the 1466.Va errno 1467libc global variable. 1468This is most often used in section 2 and 3 manual pages. 1469.Pp 1470Examples: 1471.Dl \&.Er EPERM 1472.Dl \&.Er ENOENT 1473.Pp 1474See also 1475.Ic \&Dv 1476for general constants. 1477.It Ic \&Es Ar opening_delimiter closing_delimiter 1478This macro is obsolete. 1479Use 1480.Ic \&Eo 1481or any of the other enclosure macros. 1482.Pp 1483It takes two arguments, defining the delimiters to be used by subsequent 1484.Ic \&En 1485macros. 1486.It Ic \&Ev Ar identifier ... 1487Environmental variables such as those specified in 1488.Xr environ 7 . 1489.Pp 1490Examples: 1491.Dl \&.Ev DISPLAY 1492.Dl \&.Ev PATH 1493.Pp 1494See also 1495.Ic \&Dv 1496for general constants. 1497.It Ic \&Ex Fl std Op Ar utility ... 1498Insert a standard sentence regarding command exit values of 0 on success 1499and >0 on failure. 1500This is most often used in section 1, 6, and 8 manual pages. 1501.Pp 1502If 1503.Ar utility 1504is not specified, the document's name set by 1505.Ic \&Nm 1506is used. 1507Multiple 1508.Ar utility 1509arguments are treated as separate utilities. 1510.Pp 1511See also 1512.Ic \&Rv . 1513.It Ic \&Fa Ar argument ... 1514Function argument or parameter. 1515Each argument may be a name and a type (recommended for the 1516.Em SYNOPSIS 1517section), a name alone (for function invocations), 1518or a type alone (for function prototypes). 1519If both a type and a name are given or if the type consists of multiple 1520words, all words belonging to the same function argument have to be 1521given in a single argument to the 1522.Ic \&Fa 1523macro. 1524.Pp 1525This macro is also used to specify the field name of a structure. 1526.Pp 1527Most often, the 1528.Ic \&Fa 1529macro is used in the 1530.Em SYNOPSIS 1531within 1532.Ic \&Fo 1533blocks when documenting multi-line function prototypes. 1534If invoked with multiple arguments, the arguments are separated by a 1535comma. 1536Furthermore, if the following macro is another 1537.Ic \&Fa , 1538the last argument will also have a trailing comma. 1539.Pp 1540Examples: 1541.Dl \&.Fa \(dqconst char *p\(dq 1542.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq 1543.Dl \&.Fa \(dqchar *\(dq size_t 1544.Pp 1545See also 1546.Ic \&Fo . 1547.It Ic \&Fc 1548End a function context started by 1549.Ic \&Fo . 1550.It Ic \&Fd Pf # Ar directive Op Ar argument ... 1551Preprocessor directive, in particular for listing it in the 1552.Em SYNOPSIS . 1553Historically, it was also used to document include files. 1554The latter usage has been deprecated in favour of 1555.Ic \&In . 1556.Pp 1557Examples: 1558.Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler 1559.Dl \&.Fd #define SIO_MAXNFDS 1560.Dl \&.Fd #ifdef FS_DEBUG 1561.Dl \&.Ft void 1562.Dl \&.Fn dbg_open \(dqconst char *\(dq 1563.Dl \&.Fd #endif 1564.Pp 1565See also 1566.Sx MANUAL STRUCTURE , 1567.Ic \&In , 1568and 1569.Ic \&Dv . 1570.It Ic \&Fl Op Ar word ... 1571Command-line flag or option. 1572Used when listing arguments to command-line utilities. 1573Prints a fixed-width hyphen 1574.Sq \- 1575directly followed by each argument. 1576If no arguments are provided, a hyphen is printed followed by a space. 1577If the argument is a macro, a hyphen is prefixed to the subsequent macro 1578output. 1579.Pp 1580Examples: 1581.Dl ".Fl R Op Fl H | L | P" 1582.Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux" 1583.Dl ".Fl type Cm d Fl name Pa CVS" 1584.Dl ".Fl Ar signal_number" 1585.Dl ".Fl o Fl" 1586.Pp 1587See also 1588.Ic \&Cm . 1589.It Ic \&Fn Ar funcname Op Ar argument ... 1590A function name. 1591.Pp 1592Function arguments are surrounded in parenthesis and 1593are delimited by commas. 1594If no arguments are specified, blank parenthesis are output. 1595In the 1596.Em SYNOPSIS 1597section, this macro starts a new output line, 1598and a blank line is automatically inserted between function definitions. 1599.Pp 1600Examples: 1601.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq 1602.Dl \&.Fn funcname \(dqint arg0\(dq 1603.Dl \&.Fn funcname arg0 1604.Pp 1605.Bd -literal -offset indent -compact 1606\&.Ft functype 1607\&.Fn funcname 1608.Ed 1609.Pp 1610When referring to a function documented in another manual page, use 1611.Ic \&Xr 1612instead. 1613See also 1614.Sx MANUAL STRUCTURE , 1615.Ic \&Fo , 1616and 1617.Ic \&Ft . 1618.It Ic \&Fo Ar funcname 1619Begin a function block. 1620This is a multi-line version of 1621.Ic \&Fn . 1622.Pp 1623Invocations usually occur in the following context: 1624.Bd -ragged -offset indent 1625.Pf \. Ic \&Ft Ar functype 1626.br 1627.Pf \. Ic \&Fo Ar funcname 1628.br 1629.Pf \. Ic \&Fa Qq Ar argtype Ar argname 1630.br 1631\&.\.\. 1632.br 1633.Pf \. Ic \&Fc 1634.Ed 1635.Pp 1636A 1637.Ic \&Fo 1638scope is closed by 1639.Ic \&Fc . 1640.Pp 1641See also 1642.Sx MANUAL STRUCTURE , 1643.Ic \&Fa , 1644.Ic \&Fc , 1645and 1646.Ic \&Ft . 1647.It Ic \&Fr Ar number 1648This macro is obsolete. 1649No replacement markup is needed. 1650.Pp 1651It was used to show numerical function return values in an italic font. 1652.It Ic \&Ft Ar functype 1653A function type. 1654.Pp 1655In the 1656.Em SYNOPSIS 1657section, a new output line is started after this macro. 1658.Pp 1659Examples: 1660.Dl \&.Ft int 1661.Bd -literal -offset indent -compact 1662\&.Ft functype 1663\&.Fn funcname 1664.Ed 1665.Pp 1666See also 1667.Sx MANUAL STRUCTURE , 1668.Ic \&Fn , 1669and 1670.Ic \&Fo . 1671.It Ic \&Fx Op Ar version 1672Format the 1673.Fx 1674version provided as an argument, or a default value 1675if no argument is provided. 1676.Pp 1677Examples: 1678.Dl \&.Fx 7.1 1679.Dl \&.Fx 1680.Pp 1681See also 1682.Ic \&At , 1683.Ic \&Bsx , 1684.Ic \&Bx , 1685.Ic \&Dx , 1686.Ic \&Nx , 1687and 1688.Ic \&Ox . 1689.It Ic \&Hf Ar filename 1690This macro is not implemented in 1691.Xr mandoc 1 . 1692It was used to include the contents of a (header) file literally. 1693.It Ic \&Ic Ar keyword ... 1694Designate an internal or interactive command. 1695This is similar to 1696.Ic \&Cm 1697but used for instructions rather than values. 1698.Pp 1699Examples: 1700.Dl \&.Ic :wq 1701.Dl \&.Ic hash 1702.Dl \&.Ic alias 1703.Pp 1704Note that using 1705.Ic \&Ql , 1706.Ic \&Dl , 1707or 1708.Ic \&Bd Fl literal 1709is preferred for displaying code samples; the 1710.Ic \&Ic 1711macro is used when referring to an individual command name. 1712.It Ic \&In Ar filename 1713The name of an include file. 1714This macro is most often used in section 2, 3, and 9 manual pages. 1715.Pp 1716When invoked as the first macro on an input line in the 1717.Em SYNOPSIS 1718section, the argument is displayed in angle brackets 1719and preceded by 1720.Qq #include , 1721and a blank line is inserted in front if there is a preceding 1722function declaration. 1723In other sections, it only encloses its argument in angle brackets 1724and causes no line break. 1725.Pp 1726Examples: 1727.Dl \&.In sys/types.h 1728.Pp 1729See also 1730.Sx MANUAL STRUCTURE . 1731.It Ic \&It Op Ar head 1732A list item. 1733The syntax of this macro depends on the list type. 1734.Pp 1735Lists 1736of type 1737.Fl hang , 1738.Fl ohang , 1739.Fl inset , 1740and 1741.Fl diag 1742have the following syntax: 1743.Pp 1744.D1 Pf \. Ic \&It Ar args 1745.Pp 1746Lists of type 1747.Fl bullet , 1748.Fl dash , 1749.Fl enum , 1750.Fl hyphen 1751and 1752.Fl item 1753have the following syntax: 1754.Pp 1755.D1 Pf \. Ic \&It 1756.Pp 1757with subsequent lines interpreted within the scope of the 1758.Ic \&It 1759until either a closing 1760.Ic \&El 1761or another 1762.Ic \&It . 1763.Pp 1764The 1765.Fl tag 1766list has the following syntax: 1767.Pp 1768.D1 Pf \. Ic \&It Op Cm args 1769.Pp 1770Subsequent lines are interpreted as with 1771.Fl bullet 1772and family. 1773The line arguments correspond to the list's left-hand side; body 1774arguments correspond to the list's contents. 1775.Pp 1776The 1777.Fl column 1778list is the most complicated. 1779Its syntax is as follows: 1780.Pp 1781.D1 Pf \. Ic \&It Ar cell Op Ic \&Ta Ar cell ... 1782.D1 Pf \. Ic \&It Ar cell Op <TAB> Ar cell ... 1783.Pp 1784The arguments consist of one or more lines of text and macros 1785representing a complete table line. 1786Cells within the line are delimited by the special 1787.Ic \&Ta 1788block macro or by literal tab characters. 1789.Pp 1790Using literal tabs is strongly discouraged because they are very 1791hard to use correctly and 1792.Nm 1793code using them is very hard to read. 1794In particular, a blank character is syntactically significant 1795before and after the literal tab character. 1796If a word precedes or follows the tab without an intervening blank, 1797that word is never interpreted as a macro call, but always output 1798literally. 1799.Pp 1800The tab cell delimiter may only be used within the 1801.Ic \&It 1802line itself; on following lines, only the 1803.Ic \&Ta 1804macro can be used to delimit cells, and portability requires that 1805.Ic \&Ta 1806is called by other macros: some parsers do not recognize it when 1807it appears as the first macro on a line. 1808.Pp 1809Note that quoted strings may span tab-delimited cells on an 1810.Ic \&It 1811line. 1812For example, 1813.Pp 1814.Dl .It \(dqcol1 ,\& <TAB> col2 ,\(dq \&; 1815.Pp 1816will preserve the whitespace before both commas, 1817but not the whitespace before the semicolon. 1818.Pp 1819See also 1820.Ic \&Bl . 1821.It Ic \&Lb Cm lib Ns Ar name 1822Specify a library. 1823.Pp 1824The 1825.Ar name 1826parameter may be a system library, such as 1827.Cm z 1828or 1829.Cm pam , 1830in which case a small library description is printed next to the linker 1831invocation; or a custom library, in which case the library name is 1832printed in quotes. 1833This is most commonly used in the 1834.Em SYNOPSIS 1835section as described in 1836.Sx MANUAL STRUCTURE . 1837.Pp 1838Examples: 1839.Dl \&.Lb libz 1840.Dl \&.Lb libmandoc 1841.It Ic \&Li Ar word ... 1842Request a typewriter (literal) font. 1843Deprecated because on terminal output devices, this is usually 1844indistinguishable from normal text. 1845For literal displays, use 1846.Ic \&Ql Pq in-line , 1847.Ic \&Dl Pq single line , 1848or 1849.Ic \&Bd Fl literal Pq multi-line 1850instead. 1851.It Ic \&Lk Ar uri Op Ar display_name 1852Format a hyperlink. 1853.Pp 1854Examples: 1855.Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq 1856.Dl \&.Lk http://bsd.lv 1857.Pp 1858See also 1859.Ic \&Mt . 1860.It Ic \&Lp 1861Deprecated synonym for 1862.Ic \&Pp . 1863.It Ic \&Ms Ar name 1864Display a mathematical symbol. 1865.Pp 1866Examples: 1867.Dl \&.Ms sigma 1868.Dl \&.Ms aleph 1869.It Ic \&Mt Ar localpart Ns @ Ns Ar domain 1870Format a 1871.Dq mailto: 1872hyperlink. 1873.Pp 1874Examples: 1875.Dl \&.Mt discuss@manpages.bsd.lv 1876.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv 1877.It Ic \&Nd Ar line 1878A one line description of the manual's content. 1879This is the mandatory last macro of the 1880.Em NAME 1881section and not appropriate for other sections. 1882.Pp 1883Examples: 1884.Dl Pf . Ic \&Nd mdoc language reference 1885.Dl Pf . Ic \&Nd format and display UNIX manuals 1886.Pp 1887The 1888.Ic \&Nd 1889macro technically accepts child macros and terminates with a subsequent 1890.Ic \&Sh 1891invocation. 1892Do not assume this behaviour: some 1893.Xr whatis 1 1894database generators are not smart enough to parse more than the line 1895arguments and will display macros verbatim. 1896.Pp 1897See also 1898.Ic \&Nm . 1899.It Ic \&Nm Op Ar name 1900The name of the manual page, or \(em in particular in section 1, 6, 1901and 8 pages \(em of an additional command or feature documented in 1902the manual page. 1903When first invoked, the 1904.Ic \&Nm 1905macro expects a single argument, the name of the manual page. 1906Usually, the first invocation happens in the 1907.Em NAME 1908section of the page. 1909The specified name will be remembered and used whenever the macro is 1910called again without arguments later in the page. 1911The 1912.Ic \&Nm 1913macro uses 1914.Sx Block full-implicit 1915semantics when invoked as the first macro on an input line in the 1916.Em SYNOPSIS 1917section; otherwise, it uses ordinary 1918.Sx In-line 1919semantics. 1920.Pp 1921Examples: 1922.Bd -literal -offset indent 1923\&.Sh SYNOPSIS 1924\&.Nm cat 1925\&.Op Fl benstuv 1926\&.Op Ar 1927.Ed 1928.Pp 1929In the 1930.Em SYNOPSIS 1931of section 2, 3 and 9 manual pages, use the 1932.Ic \&Fn 1933macro rather than 1934.Ic \&Nm 1935to mark up the name of the manual page. 1936.It Ic \&No Ar word ... 1937Normal text. 1938Closes the scope of any preceding in-line macro. 1939When used after physical formatting macros like 1940.Ic \&Em 1941or 1942.Ic \&Sy , 1943switches back to the standard font face and weight. 1944Can also be used to embed plain text strings in macro lines 1945using semantic annotation macros. 1946.Pp 1947Examples: 1948.Dl ".Em italic , Sy bold , No and roman" 1949.Pp 1950.Bd -literal -offset indent -compact 1951\&.Sm off 1952\&.Cm :C No / Ar pattern No / Ar replacement No / 1953\&.Sm on 1954.Ed 1955.Pp 1956See also 1957.Ic \&Em , 1958.Ic \&Ql , 1959and 1960.Ic \&Sy . 1961.It Ic \&Ns 1962Suppress a space between the output of the preceding macro 1963and the following text or macro. 1964Following invocation, input is interpreted as normal text 1965just like after an 1966.Ic \&No 1967macro. 1968.Pp 1969This has no effect when invoked at the start of a macro line. 1970.Pp 1971Examples: 1972.Dl ".Ar name Ns = Ns Ar value" 1973.Dl ".Cm :M Ns Ar pattern" 1974.Dl ".Fl o Ns Ar output" 1975.Pp 1976See also 1977.Ic \&No 1978and 1979.Ic \&Sm . 1980.It Ic \&Nx Op Ar version 1981Format the 1982.Nx 1983version provided as an argument, or a default value if 1984no argument is provided. 1985.Pp 1986Examples: 1987.Dl \&.Nx 5.01 1988.Dl \&.Nx 1989.Pp 1990See also 1991.Ic \&At , 1992.Ic \&Bsx , 1993.Ic \&Bx , 1994.Ic \&Dx , 1995.Ic \&Fx , 1996and 1997.Ic \&Ox . 1998.It Ic \&Oc 1999Close multi-line 2000.Ic \&Oo 2001context. 2002.It Ic \&Oo Ar block 2003Multi-line version of 2004.Ic \&Op . 2005.Pp 2006Examples: 2007.Bd -literal -offset indent -compact 2008\&.Oo 2009\&.Op Fl flag Ns Ar value 2010\&.Oc 2011.Ed 2012.It Ic \&Op Ar line 2013Optional part of a command line. 2014Prints the argument(s) in brackets. 2015This is most often used in the 2016.Em SYNOPSIS 2017section of section 1 and 8 manual pages. 2018.Pp 2019Examples: 2020.Dl \&.Op \&Fl a \&Ar b 2021.Dl \&.Op \&Ar a | b 2022.Pp 2023See also 2024.Ic \&Oo . 2025.It Ic \&Os Op Ar system Op Ar version 2026Operating system version for display in the page footer. 2027This is the mandatory third macro of 2028any 2029.Nm 2030file. 2031.Pp 2032The optional 2033.Ar system 2034parameter specifies the relevant operating system or environment. 2035It is suggested to leave it unspecified, in which case 2036.Xr mandoc 1 2037uses its 2038.Fl Ios 2039argument or, if that isn't specified either, 2040.Fa sysname 2041and 2042.Fa release 2043as returned by 2044.Xr uname 3 . 2045.Pp 2046Examples: 2047.Dl \&.Os 2048.Dl \&.Os KTH/CSC/TCS 2049.Dl \&.Os BSD 4.3 2050.Pp 2051See also 2052.Ic \&Dd 2053and 2054.Ic \&Dt . 2055.It Ic \&Ot Ar functype 2056This macro is obsolete. 2057Use 2058.Ic \&Ft 2059instead; with 2060.Xr mandoc 1 , 2061both have the same effect. 2062.Pp 2063Historical 2064.Nm 2065packages described it as 2066.Dq "old function type (FORTRAN)" . 2067.It Ic \&Ox Op Ar version 2068Format the 2069.Ox 2070version provided as an argument, or a default value 2071if no argument is provided. 2072.Pp 2073Examples: 2074.Dl \&.Ox 4.5 2075.Dl \&.Ox 2076.Pp 2077See also 2078.Ic \&At , 2079.Ic \&Bsx , 2080.Ic \&Bx , 2081.Ic \&Dx , 2082.Ic \&Fx , 2083and 2084.Ic \&Nx . 2085.It Ic \&Pa Ar name ... 2086An absolute or relative file system path, or a file or directory name. 2087If an argument is not provided, the character 2088.Sq \(ti 2089is used as a default. 2090.Pp 2091Examples: 2092.Dl \&.Pa /usr/bin/mandoc 2093.Dl \&.Pa /usr/share/man/man7/mdoc.7 2094.Pp 2095See also 2096.Ic \&Lk . 2097.It Ic \&Pc 2098Close parenthesised context opened by 2099.Ic \&Po . 2100.It Ic \&Pf Ar prefix macro Op Ar argument ... 2101Removes the space between its argument and the following macro. 2102It is equivalent to: 2103.Pp 2104.D1 Ic \&No Pf \e& Ar prefix Ic \&Ns Ar macro Op Ar argument ... 2105.Pp 2106The 2107.Ar prefix 2108argument is not parsed for macro names or delimiters, 2109but used verbatim as if it were escaped. 2110.Pp 2111Examples: 2112.Dl ".Pf $ Ar variable_name" 2113.Dl ".Pf . Ar macro_name" 2114.Dl ".Pf 0x Ar hex_digits" 2115.Pp 2116See also 2117.Ic \&Ns 2118and 2119.Ic \&Sm . 2120.It Ic \&Po Ar block 2121Multi-line version of 2122.Ic \&Pq . 2123.It Ic \&Pp 2124Break a paragraph. 2125This will assert vertical space between prior and subsequent macros 2126and/or text. 2127.Pp 2128Paragraph breaks are not needed before or after 2129.Ic \&Sh 2130or 2131.Ic \&Ss 2132macros or before displays 2133.Pq Ic \&Bd Ar line 2134or lists 2135.Pq Ic \&Bl 2136unless the 2137.Fl compact 2138flag is given. 2139.It Ic \&Pq Ar line 2140Parenthesised enclosure. 2141.Pp 2142See also 2143.Ic \&Po . 2144.It Ic \&Qc 2145Close quoted context opened by 2146.Ic \&Qo . 2147.It Ic \&Ql Ar line 2148In-line literal display. 2149This can be used for complete command invocations and for multi-word 2150code examples when an indented display is not desired. 2151.Pp 2152See also 2153.Ic \&Dl 2154and 2155.Ic \&Bd 2156.Fl literal . 2157.It Ic \&Qo Ar block 2158Multi-line version of 2159.Ic \&Qq . 2160.It Ic \&Qq Ar line 2161Encloses its arguments in 2162.Qq typewriter 2163double-quotes. 2164Consider using 2165.Ic \&Dq . 2166.Pp 2167See also 2168.Ic \&Dq , 2169.Ic \&Sq , 2170and 2171.Ic \&Qo . 2172.It Ic \&Re 2173Close an 2174.Ic \&Rs 2175block. 2176Does not have any tail arguments. 2177.It Ic \&Rs 2178Begin a bibliographic 2179.Pq Dq reference 2180block. 2181Does not have any head arguments. 2182The block macro may only contain 2183.Ic \&%A , 2184.Ic \&%B , 2185.Ic \&%C , 2186.Ic \&%D , 2187.Ic \&%I , 2188.Ic \&%J , 2189.Ic \&%N , 2190.Ic \&%O , 2191.Ic \&%P , 2192.Ic \&%Q , 2193.Ic \&%R , 2194.Ic \&%T , 2195.Ic \&%U , 2196and 2197.Ic \&%V 2198child macros (at least one must be specified). 2199.Pp 2200Examples: 2201.Bd -literal -offset indent -compact 2202\&.Rs 2203\&.%A J. E. Hopcroft 2204\&.%A J. D. Ullman 2205\&.%B Introduction to Automata Theory, Languages, and Computation 2206\&.%I Addison-Wesley 2207\&.%C Reading, Massachusetts 2208\&.%D 1979 2209\&.Re 2210.Ed 2211.Pp 2212If an 2213.Ic \&Rs 2214block is used within a SEE ALSO section, a vertical space is asserted 2215before the rendered output, else the block continues on the current 2216line. 2217.It Ic \&Rv Fl std Op Ar function ... 2218Insert a standard sentence regarding a function call's return value of 0 2219on success and \-1 on error, with the 2220.Va errno 2221libc global variable set on error. 2222.Pp 2223If 2224.Ar function 2225is not specified, the document's name set by 2226.Ic \&Nm 2227is used. 2228Multiple 2229.Ar function 2230arguments are treated as separate functions. 2231.Pp 2232See also 2233.Ic \&Ex . 2234.It Ic \&Sc 2235Close single-quoted context opened by 2236.Ic \&So . 2237.It Ic \&Sh Ar TITLE LINE 2238Begin a new section. 2239For a list of conventional manual sections, see 2240.Sx MANUAL STRUCTURE . 2241These sections should be used unless it's absolutely necessary that 2242custom sections be used. 2243.Pp 2244Section names should be unique so that they may be keyed by 2245.Ic \&Sx . 2246Although this macro is parsed, it should not consist of child node or it 2247may not be linked with 2248.Ic \&Sx . 2249.Pp 2250See also 2251.Ic \&Pp , 2252.Ic \&Ss , 2253and 2254.Ic \&Sx . 2255.It Ic \&Sm Op Cm on | off 2256Switches the spacing mode for output generated from macros. 2257.Pp 2258By default, spacing is 2259.Cm on . 2260When switched 2261.Cm off , 2262no white space is inserted between macro arguments and between the 2263output generated from adjacent macros, but text lines 2264still get normal spacing between words and sentences. 2265.Pp 2266When called without an argument, the 2267.Ic \&Sm 2268macro toggles the spacing mode. 2269Using this is not recommended because it makes the code harder to read. 2270.It Ic \&So Ar block 2271Multi-line version of 2272.Ic \&Sq . 2273.It Ic \&Sq Ar line 2274Encloses its arguments in 2275.Sq typewriter 2276single-quotes. 2277.Pp 2278See also 2279.Ic \&Dq , 2280.Ic \&Qq , 2281and 2282.Ic \&So . 2283.It Ic \&Ss Ar Title line 2284Begin a new subsection. 2285Unlike with 2286.Ic \&Sh , 2287there is no convention for the naming of subsections. 2288Except 2289.Em DESCRIPTION , 2290the conventional sections described in 2291.Sx MANUAL STRUCTURE 2292rarely have subsections. 2293.Pp 2294Sub-section names should be unique so that they may be keyed by 2295.Ic \&Sx . 2296Although this macro is parsed, it should not consist of child node or it 2297may not be linked with 2298.Ic \&Sx . 2299.Pp 2300See also 2301.Ic \&Pp , 2302.Ic \&Sh , 2303and 2304.Ic \&Sx . 2305.It Ic \&St Fl Ns Ar abbreviation 2306Replace an abbreviation for a standard with the full form. 2307The following standards are recognised. 2308Where multiple lines are given without a blank line in between, 2309they all refer to the same standard, and using the first form 2310is recommended. 2311.Bl -tag -width 1n 2312.It C language standards 2313.Pp 2314.Bl -tag -width "-p1003.1g-2000" -compact 2315.It \-ansiC 2316.St -ansiC 2317.It \-ansiC-89 2318.St -ansiC-89 2319.It \-isoC 2320.St -isoC 2321.It \-isoC-90 2322.St -isoC-90 2323.br 2324The original C standard. 2325.Pp 2326.It \-isoC-amd1 2327.St -isoC-amd1 2328.Pp 2329.It \-isoC-tcor1 2330.St -isoC-tcor1 2331.Pp 2332.It \-isoC-tcor2 2333.St -isoC-tcor2 2334.Pp 2335.It \-isoC-99 2336.St -isoC-99 2337.br 2338The second major version of the C language standard. 2339.Pp 2340.It \-isoC-2011 2341.St -isoC-2011 2342.br 2343The third major version of the C language standard. 2344.El 2345.It POSIX.1 before the Single UNIX Specification 2346.Pp 2347.Bl -tag -width "-p1003.1g-2000" -compact 2348.It \-p1003.1-88 2349.St -p1003.1-88 2350.It \-p1003.1 2351.St -p1003.1 2352.br 2353The original POSIX standard, based on ANSI C. 2354.Pp 2355.It \-p1003.1-90 2356.St -p1003.1-90 2357.It \-iso9945-1-90 2358.St -iso9945-1-90 2359.br 2360The first update of POSIX.1. 2361.Pp 2362.It \-p1003.1b-93 2363.St -p1003.1b-93 2364.It \-p1003.1b 2365.St -p1003.1b 2366.br 2367Real-time extensions. 2368.Pp 2369.It \-p1003.1c-95 2370.St -p1003.1c-95 2371.br 2372POSIX thread interfaces. 2373.Pp 2374.It \-p1003.1i-95 2375.St -p1003.1i-95 2376.br 2377Technical Corrigendum. 2378.Pp 2379.It \-p1003.1-96 2380.St -p1003.1-96 2381.It \-iso9945-1-96 2382.St -iso9945-1-96 2383.br 2384Includes POSIX.1-1990, 1b, 1c, and 1i. 2385.El 2386.It X/Open Portability Guide version 4 and related standards 2387.Pp 2388.Bl -tag -width "-p1003.1g-2000" -compact 2389.It \-xpg3 2390.St -xpg3 2391.br 2392An XPG4 precursor, published in 1989. 2393.Pp 2394.It \-p1003.2 2395.St -p1003.2 2396.It \-p1003.2-92 2397.St -p1003.2-92 2398.It \-iso9945-2-93 2399.St -iso9945-2-93 2400.br 2401An XCU4 precursor. 2402.Pp 2403.It \-p1003.2a-92 2404.St -p1003.2a-92 2405.br 2406Updates to POSIX.2. 2407.Pp 2408.It \-xpg4 2409.St -xpg4 2410.br 2411Based on POSIX.1 and POSIX.2, published in 1992. 2412.El 2413.It Single UNIX Specification version 1 and related standards 2414.Pp 2415.Bl -tag -width "-p1003.1g-2000" -compact 2416.It \-susv1 2417.St -susv1 2418.It \-xpg4.2 2419.St -xpg4.2 2420.br 2421This standard was published in 1994. 2422It was used as the basis for UNIX 95 certification. 2423The following three refer to parts of it. 2424.Pp 2425.It \-xsh4.2 2426.St -xsh4.2 2427.Pp 2428.It \-xcurses4.2 2429.St -xcurses4.2 2430.Pp 2431.It \-p1003.1g-2000 2432.St -p1003.1g-2000 2433.br 2434Networking APIs, including sockets. 2435.Pp 2436.It \-svid4 2437.St -svid4 , 2438.br 2439Published in 1995. 2440.El 2441.It Single UNIX Specification version 2 and related standards 2442.Pp 2443.Bl -tag -width "-p1003.1g-2000" -compact 2444.It \-susv2 2445.St -susv2 2446This Standard was published in 1997 2447and is also called X/Open Portability Guide version 5. 2448It was used as the basis for UNIX 98 certification. 2449The following refer to parts of it. 2450.Pp 2451.It \-xbd5 2452.St -xbd5 2453.Pp 2454.It \-xsh5 2455.St -xsh5 2456.Pp 2457.It \-xcu5 2458.St -xcu5 2459.Pp 2460.It \-xns5 2461.St -xns5 2462.It \-xns5.2 2463.St -xns5.2 2464.El 2465.It Single UNIX Specification version 3 2466.Pp 2467.Bl -tag -width "-p1003.1-2001" -compact 2468.It \-p1003.1-2001 2469.St -p1003.1-2001 2470.It \-susv3 2471.St -susv3 2472.br 2473This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j. 2474It is also called X/Open Portability Guide version 6. 2475It is used as the basis for UNIX 03 certification. 2476.Pp 2477.It \-p1003.1-2004 2478.St -p1003.1-2004 2479.br 2480The second and last Technical Corrigendum. 2481.El 2482.It Single UNIX Specification version 4 2483.Pp 2484.Bl -tag -width "-p1003.1g-2000" -compact 2485.It \-p1003.1-2008 2486.St -p1003.1-2008 2487.It \-susv4 2488.St -susv4 2489.br 2490This standard is also called 2491X/Open Portability Guide version 7. 2492.El 2493.It Other standards 2494.Pp 2495.Bl -tag -width "-p1003.1g-2000" -compact 2496.It \-ieee754 2497.St -ieee754 2498.br 2499Floating-point arithmetic. 2500.Pp 2501.It \-iso8601 2502.St -iso8601 2503.br 2504Representation of dates and times, published in 1988. 2505.Pp 2506.It \-iso8802-3 2507.St -iso8802-3 2508.br 2509Ethernet local area networks. 2510.Pp 2511.It \-ieee1275-94 2512.St -ieee1275-94 2513.El 2514.El 2515.It Ic \&Sx Ar Title line 2516Reference a section or subsection in the same manual page. 2517The referenced section or subsection name must be identical to the 2518enclosed argument, including whitespace. 2519.Pp 2520Examples: 2521.Dl \&.Sx MANUAL STRUCTURE 2522.Pp 2523See also 2524.Ic \&Sh 2525and 2526.Ic \&Ss . 2527.It Ic \&Sy Ar word ... 2528Request a boldface font. 2529.Pp 2530This is most often used to indicate importance or seriousness (not to be 2531confused with stress emphasis, see 2532.Ic \&Em ) . 2533When none of the semantic macros fit, it is also adequate for syntax 2534elements that have to be given or that appear verbatim. 2535.Pp 2536Examples: 2537.Bd -literal -compact -offset indent 2538\&.Sy Warning : 2539If 2540\&.Sy s 2541appears in the owner permissions, set-user-ID mode is set. 2542This utility replaces the former 2543\&.Sy dumpdir 2544program. 2545.Ed 2546.Pp 2547See also 2548.Ic \&Em , 2549.Ic \&No , 2550and 2551.Ic \&Ql . 2552.It Ic \&Ta 2553Table cell separator in 2554.Ic \&Bl Fl column 2555lists; can only be used below 2556.Ic \&It . 2557.It Ic \&Tn Ar word ... 2558Supported only for compatibility, do not use this in new manuals. 2559Even though the macro name 2560.Pq Dq tradename 2561suggests a semantic function, historic usage is inconsistent, mostly 2562using it as a presentation-level macro to request a small caps font. 2563.It Ic \&Ud 2564Supported only for compatibility, do not use this in new manuals. 2565Prints out 2566.Dq currently under development. 2567.It Ic \&Ux 2568Supported only for compatibility, do not use this in new manuals. 2569Prints out 2570.Dq Ux . 2571.It Ic \&Va Oo Ar type Oc Ar identifier ... 2572A variable name. 2573.Pp 2574Examples: 2575.Dl \&.Va foo 2576.Dl \&.Va const char *bar ; 2577.Pp 2578For function arguments and parameters, use 2579.Ic \&Fa 2580instead. 2581For declarations of global variables in the 2582.Em SYNOPSIS 2583section, use 2584.Ic \&Vt . 2585.It Ic \&Vt Ar type Op Ar identifier 2586A variable type. 2587.Pp 2588This is also used for indicating global variables in the 2589.Em SYNOPSIS 2590section, in which case a variable name is also specified. 2591Note that it accepts 2592.Sx Block partial-implicit 2593syntax when invoked as the first macro on an input line in the 2594.Em SYNOPSIS 2595section, else it accepts ordinary 2596.Sx In-line 2597syntax. 2598In the former case, this macro starts a new output line, 2599and a blank line is inserted in front if there is a preceding 2600function definition or include directive. 2601.Pp 2602Examples: 2603.Dl \&.Vt unsigned char 2604.Dl \&.Vt extern const char * const sys_signame[] \&; 2605.Pp 2606For parameters in function prototypes, use 2607.Ic \&Fa 2608instead, for function return types 2609.Ic \&Ft , 2610and for variable names outside the 2611.Em SYNOPSIS 2612section 2613.Ic \&Va , 2614even when including a type with the name. 2615See also 2616.Sx MANUAL STRUCTURE . 2617.It Ic \&Xc 2618Close a scope opened by 2619.Ic \&Xo . 2620.It Ic \&Xo Ar block 2621Extend the header of an 2622.Ic \&It 2623macro or the body of a partial-implicit block macro 2624beyond the end of the input line. 2625This macro originally existed to work around the 9-argument limit 2626of historic 2627.Xr roff 7 . 2628.It Ic \&Xr Ar name section 2629Link to another manual 2630.Pq Qq cross-reference . 2631.Pp 2632Cross reference the 2633.Ar name 2634and 2635.Ar section 2636number of another man page. 2637.Pp 2638Examples: 2639.Dl \&.Xr mandoc 1 2640.Dl \&.Xr mandoc 1 \&; 2641.Dl \&.Xr mandoc 1 \&Ns s behaviour 2642.El 2643.Sh MACRO SYNTAX 2644The syntax of a macro depends on its classification. 2645In this section, 2646.Sq \-arg 2647refers to macro arguments, which may be followed by zero or more 2648.Sq parm 2649parameters; 2650.Sq \&Yo 2651opens the scope of a macro; and if specified, 2652.Sq \&Yc 2653closes it out. 2654.Pp 2655The 2656.Em Callable 2657column indicates that the macro may also be called by passing its name 2658as an argument to another macro. 2659For example, 2660.Sq \&.Op \&Fl O \&Ar file 2661produces 2662.Sq Op Fl O Ar file . 2663To prevent a macro call and render the macro name literally, 2664escape it by prepending a zero-width space, 2665.Sq \e& . 2666For example, 2667.Sq \&Op \e&Fl O 2668produces 2669.Sq Op \&Fl O . 2670If a macro is not callable but its name appears as an argument 2671to another macro, it is interpreted as opaque text. 2672For example, 2673.Sq \&.Fl \&Sh 2674produces 2675.Sq Fl \&Sh . 2676.Pp 2677The 2678.Em Parsed 2679column indicates whether the macro may call other macros by receiving 2680their names as arguments. 2681If a macro is not parsed but the name of another macro appears 2682as an argument, it is interpreted as opaque text. 2683.Pp 2684The 2685.Em Scope 2686column, if applicable, describes closure rules. 2687.Ss Block full-explicit 2688Multi-line scope closed by an explicit closing macro. 2689All macros contains bodies; only 2690.Ic \s&Bf 2691and 2692.Pq optionally 2693.Ic \&Bl 2694contain a head. 2695.Bd -literal -offset indent 2696\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB 2697\(lBbody...\(rB 2698\&.Yc 2699.Ed 2700.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent 2701.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2702.It Ic \&Bd Ta \&No Ta \&No Ta closed by Ic \&Ed 2703.It Ic \&Bf Ta \&No Ta \&No Ta closed by Ic \&Ef 2704.It Ic \&Bk Ta \&No Ta \&No Ta closed by Ic \&Ek 2705.It Ic \&Bl Ta \&No Ta \&No Ta closed by Ic \&El 2706.It Ic \&Ed Ta \&No Ta \&No Ta opened by Ic \&Bd 2707.It Ic \&Ef Ta \&No Ta \&No Ta opened by Ic \&Bf 2708.It Ic \&Ek Ta \&No Ta \&No Ta opened by Ic \&Bk 2709.It Ic \&El Ta \&No Ta \&No Ta opened by Ic \&Bl 2710.El 2711.Ss Block full-implicit 2712Multi-line scope closed by end-of-file or implicitly by another macro. 2713All macros have bodies; some 2714.Po 2715.Ic \&It Fl bullet , 2716.Fl hyphen , 2717.Fl dash , 2718.Fl enum , 2719.Fl item 2720.Pc 2721don't have heads; only one 2722.Po 2723.Ic \&It 2724in 2725.Ic \&Bl Fl column 2726.Pc 2727has multiple heads. 2728.Bd -literal -offset indent 2729\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB 2730\(lBbody...\(rB 2731.Ed 2732.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent 2733.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2734.It Ic \&It Ta \&No Ta Yes Ta closed by Ic \&It , Ic \&El 2735.It Ic \&Nd Ta \&No Ta \&No Ta closed by Ic \&Sh 2736.It Ic \&Nm Ta \&No Ta Yes Ta closed by Ic \&Nm , Ic \&Sh , Ic \&Ss 2737.It Ic \&Sh Ta \&No Ta Yes Ta closed by Ic \&Sh 2738.It Ic \&Ss Ta \&No Ta Yes Ta closed by Ic \&Sh , Ic \&Ss 2739.El 2740.Pp 2741Note that the 2742.Ic \&Nm 2743macro is a 2744.Sx Block full-implicit 2745macro only when invoked as the first macro 2746in a 2747.Em SYNOPSIS 2748section line, else it is 2749.Sx In-line . 2750.Ss Block partial-explicit 2751Like block full-explicit, but also with single-line scope. 2752Each has at least a body and, in limited circumstances, a head 2753.Po 2754.Ic \&Fo , 2755.Ic \&Eo 2756.Pc 2757and/or tail 2758.Pq Ic \&Ec . 2759.Bd -literal -offset indent 2760\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB 2761\(lBbody...\(rB 2762\&.Yc \(lBtail...\(rB 2763 2764\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ 2765\(lBbody...\(rB \&Yc \(lBtail...\(rB 2766.Ed 2767.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent 2768.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2769.It Ic \&Ac Ta Yes Ta Yes Ta opened by Ic \&Ao 2770.It Ic \&Ao Ta Yes Ta Yes Ta closed by Ic \&Ac 2771.It Ic \&Bc Ta Yes Ta Yes Ta closed by Ic \&Bo 2772.It Ic \&Bo Ta Yes Ta Yes Ta opened by Ic \&Bc 2773.It Ic \&Brc Ta Yes Ta Yes Ta opened by Ic \&Bro 2774.It Ic \&Bro Ta Yes Ta Yes Ta closed by Ic \&Brc 2775.It Ic \&Dc Ta Yes Ta Yes Ta opened by Ic \&Do 2776.It Ic \&Do Ta Yes Ta Yes Ta closed by Ic \&Dc 2777.It Ic \&Ec Ta Yes Ta Yes Ta opened by Ic \&Eo 2778.It Ic \&Eo Ta Yes Ta Yes Ta closed by Ic \&Ec 2779.It Ic \&Fc Ta Yes Ta Yes Ta opened by Ic \&Fo 2780.It Ic \&Fo Ta \&No Ta \&No Ta closed by Ic \&Fc 2781.It Ic \&Oc Ta Yes Ta Yes Ta closed by Ic \&Oo 2782.It Ic \&Oo Ta Yes Ta Yes Ta opened by Ic \&Oc 2783.It Ic \&Pc Ta Yes Ta Yes Ta closed by Ic \&Po 2784.It Ic \&Po Ta Yes Ta Yes Ta opened by Ic \&Pc 2785.It Ic \&Qc Ta Yes Ta Yes Ta opened by Ic \&Oo 2786.It Ic \&Qo Ta Yes Ta Yes Ta closed by Ic \&Oc 2787.It Ic \&Re Ta \&No Ta \&No Ta opened by Ic \&Rs 2788.It Ic \&Rs Ta \&No Ta \&No Ta closed by Ic \&Re 2789.It Ic \&Sc Ta Yes Ta Yes Ta opened by Ic \&So 2790.It Ic \&So Ta Yes Ta Yes Ta closed by Ic \&Sc 2791.It Ic \&Xc Ta Yes Ta Yes Ta opened by Ic \&Xo 2792.It Ic \&Xo Ta Yes Ta Yes Ta closed by Ic \&Xc 2793.El 2794.Ss Block partial-implicit 2795Like block full-implicit, but with single-line scope closed by the 2796end of the line. 2797.Bd -literal -offset indent 2798\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB 2799.Ed 2800.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent 2801.It Em Macro Ta Em Callable Ta Em Parsed 2802.It Ic \&Aq Ta Yes Ta Yes 2803.It Ic \&Bq Ta Yes Ta Yes 2804.It Ic \&Brq Ta Yes Ta Yes 2805.It Ic \&D1 Ta \&No Ta \&Yes 2806.It Ic \&Dl Ta \&No Ta Yes 2807.It Ic \&Dq Ta Yes Ta Yes 2808.It Ic \&En Ta Yes Ta Yes 2809.It Ic \&Op Ta Yes Ta Yes 2810.It Ic \&Pq Ta Yes Ta Yes 2811.It Ic \&Ql Ta Yes Ta Yes 2812.It Ic \&Qq Ta Yes Ta Yes 2813.It Ic \&Sq Ta Yes Ta Yes 2814.It Ic \&Vt Ta Yes Ta Yes 2815.El 2816.Pp 2817Note that the 2818.Ic \&Vt 2819macro is a 2820.Sx Block partial-implicit 2821only when invoked as the first macro 2822in a 2823.Em SYNOPSIS 2824section line, else it is 2825.Sx In-line . 2826.Ss Special block macro 2827The 2828.Ic \&Ta 2829macro can only be used below 2830.Ic \&It 2831in 2832.Ic \&Bl Fl column 2833lists. 2834It delimits blocks representing table cells; 2835these blocks have bodies, but no heads. 2836.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent 2837.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2838.It Ic \&Ta Ta Yes Ta Yes Ta closed by Ic \&Ta , Ic \&It 2839.El 2840.Ss In-line 2841Closed by the end of the line, fixed argument lengths, 2842and/or subsequent macros. 2843In-line macros have only text children. 2844If a number (or inequality) of arguments is 2845.Pq n , 2846then the macro accepts an arbitrary number of arguments. 2847.Bd -literal -offset indent 2848\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB 2849 2850\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc... 2851 2852\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN 2853.Ed 2854.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent 2855.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments 2856.It Ic \&%A Ta \&No Ta \&No Ta >0 2857.It Ic \&%B Ta \&No Ta \&No Ta >0 2858.It Ic \&%C Ta \&No Ta \&No Ta >0 2859.It Ic \&%D Ta \&No Ta \&No Ta >0 2860.It Ic \&%I Ta \&No Ta \&No Ta >0 2861.It Ic \&%J Ta \&No Ta \&No Ta >0 2862.It Ic \&%N Ta \&No Ta \&No Ta >0 2863.It Ic \&%O Ta \&No Ta \&No Ta >0 2864.It Ic \&%P Ta \&No Ta \&No Ta >0 2865.It Ic \&%Q Ta \&No Ta \&No Ta >0 2866.It Ic \&%R Ta \&No Ta \&No Ta >0 2867.It Ic \&%T Ta \&No Ta \&No Ta >0 2868.It Ic \&%U Ta \&No Ta \&No Ta >0 2869.It Ic \&%V Ta \&No Ta \&No Ta >0 2870.It Ic \&Ad Ta Yes Ta Yes Ta >0 2871.It Ic \&An Ta Yes Ta Yes Ta >0 2872.It Ic \&Ap Ta Yes Ta Yes Ta 0 2873.It Ic \&Ar Ta Yes Ta Yes Ta n 2874.It Ic \&At Ta Yes Ta Yes Ta 1 2875.It Ic \&Bsx Ta Yes Ta Yes Ta n 2876.It Ic \&Bt Ta \&No Ta \&No Ta 0 2877.It Ic \&Bx Ta Yes Ta Yes Ta n 2878.It Ic \&Cd Ta Yes Ta Yes Ta >0 2879.It Ic \&Cm Ta Yes Ta Yes Ta >0 2880.It Ic \&Db Ta \&No Ta \&No Ta 1 2881.It Ic \&Dd Ta \&No Ta \&No Ta n 2882.It Ic \&Dt Ta \&No Ta \&No Ta n 2883.It Ic \&Dv Ta Yes Ta Yes Ta >0 2884.It Ic \&Dx Ta Yes Ta Yes Ta n 2885.It Ic \&Em Ta Yes Ta Yes Ta >0 2886.It Ic \&Er Ta Yes Ta Yes Ta >0 2887.It Ic \&Es Ta Yes Ta Yes Ta 2 2888.It Ic \&Ev Ta Yes Ta Yes Ta >0 2889.It Ic \&Ex Ta \&No Ta \&No Ta n 2890.It Ic \&Fa Ta Yes Ta Yes Ta >0 2891.It Ic \&Fd Ta \&No Ta \&No Ta >0 2892.It Ic \&Fl Ta Yes Ta Yes Ta n 2893.It Ic \&Fn Ta Yes Ta Yes Ta >0 2894.It Ic \&Fr Ta Yes Ta Yes Ta >0 2895.It Ic \&Ft Ta Yes Ta Yes Ta >0 2896.It Ic \&Fx Ta Yes Ta Yes Ta n 2897.It Ic \&Hf Ta \&No Ta \&No Ta n 2898.It Ic \&Ic Ta Yes Ta Yes Ta >0 2899.It Ic \&In Ta \&No Ta \&No Ta 1 2900.It Ic \&Lb Ta \&No Ta \&No Ta 1 2901.It Ic \&Li Ta Yes Ta Yes Ta >0 2902.It Ic \&Lk Ta Yes Ta Yes Ta >0 2903.It Ic \&Lp Ta \&No Ta \&No Ta 0 2904.It Ic \&Ms Ta Yes Ta Yes Ta >0 2905.It Ic \&Mt Ta Yes Ta Yes Ta >0 2906.It Ic \&Nm Ta Yes Ta Yes Ta n 2907.It Ic \&No Ta Yes Ta Yes Ta 0 2908.It Ic \&Ns Ta Yes Ta Yes Ta 0 2909.It Ic \&Nx Ta Yes Ta Yes Ta n 2910.It Ic \&Os Ta \&No Ta \&No Ta n 2911.It Ic \&Ot Ta Yes Ta Yes Ta >0 2912.It Ic \&Ox Ta Yes Ta Yes Ta n 2913.It Ic \&Pa Ta Yes Ta Yes Ta n 2914.It Ic \&Pf Ta Yes Ta Yes Ta 1 2915.It Ic \&Pp Ta \&No Ta \&No Ta 0 2916.It Ic \&Rv Ta \&No Ta \&No Ta n 2917.It Ic \&Sm Ta \&No Ta \&No Ta <2 2918.It Ic \&St Ta \&No Ta Yes Ta 1 2919.It Ic \&Sx Ta Yes Ta Yes Ta >0 2920.It Ic \&Sy Ta Yes Ta Yes Ta >0 2921.It Ic \&Tn Ta Yes Ta Yes Ta >0 2922.It Ic \&Ud Ta \&No Ta \&No Ta 0 2923.It Ic \&Ux Ta Yes Ta Yes Ta n 2924.It Ic \&Va Ta Yes Ta Yes Ta n 2925.It Ic \&Vt Ta Yes Ta Yes Ta >0 2926.It Ic \&Xr Ta Yes Ta Yes Ta 2 2927.El 2928.Ss Delimiters 2929When a macro argument consists of one single input character 2930considered as a delimiter, the argument gets special handling. 2931This does not apply when delimiters appear in arguments containing 2932more than one character. 2933Consequently, to prevent special handling and just handle it 2934like any other argument, a delimiter can be escaped by prepending 2935a zero-width space 2936.Pq Sq \e& . 2937In text lines, delimiters never need escaping, but may be used 2938as normal punctuation. 2939.Pp 2940For many macros, when the leading arguments are opening delimiters, 2941these delimiters are put before the macro scope, 2942and when the trailing arguments are closing delimiters, 2943these delimiters are put after the macro scope. 2944Spacing is suppressed after opening delimiters 2945and before closing delimiters. 2946For example, 2947.Pp 2948.D1 Pf \. \&Aq "( [ word ] ) ." 2949.Pp 2950renders as: 2951.Pp 2952.D1 Aq ( [ word ] ) . 2953.Pp 2954Opening delimiters are: 2955.Pp 2956.Bl -tag -width Ds -offset indent -compact 2957.It \&( 2958left parenthesis 2959.It \&[ 2960left bracket 2961.El 2962.Pp 2963Closing delimiters are: 2964.Pp 2965.Bl -tag -width Ds -offset indent -compact 2966.It \&. 2967period 2968.It \&, 2969comma 2970.It \&: 2971colon 2972.It \&; 2973semicolon 2974.It \&) 2975right parenthesis 2976.It \&] 2977right bracket 2978.It \&? 2979question mark 2980.It \&! 2981exclamation mark 2982.El 2983.Pp 2984Note that even a period preceded by a backslash 2985.Pq Sq \e.\& 2986gets this special handling; use 2987.Sq \e&. 2988to prevent that. 2989.Pp 2990Many in-line macros interrupt their scope when they encounter 2991delimiters, and resume their scope when more arguments follow that 2992are not delimiters. 2993For example, 2994.Pp 2995.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e" 2996.Pp 2997renders as: 2998.Pp 2999.D1 Fl a ( b | c \*(Ba d ) e 3000.Pp 3001This applies to both opening and closing delimiters, 3002and also to the middle delimiter, which does not suppress spacing: 3003.Pp 3004.Bl -tag -width Ds -offset indent -compact 3005.It \&| 3006vertical bar 3007.El 3008.Pp 3009As a special case, the predefined string \e*(Ba is handled and rendered 3010in the same way as a plain 3011.Sq \&| 3012character. 3013Using this predefined string is not recommended in new manuals. 3014.Ss Font handling 3015In 3016.Nm 3017documents, usage of semantic markup is recommended in order to have 3018proper fonts automatically selected; only when no fitting semantic markup 3019is available, consider falling back to 3020.Sx Physical markup 3021macros. 3022Whenever any 3023.Nm 3024macro switches the 3025.Xr roff 7 3026font mode, it will automatically restore the previous font when exiting 3027its scope. 3028Manually switching the font using the 3029.Xr roff 7 3030.Ql \ef 3031font escape sequences is never required. 3032.Sh COMPATIBILITY 3033This section provides an incomplete list of compatibility issues 3034between mandoc and GNU troff 3035.Pq Qq groff . 3036.Pp 3037The following problematic behaviour is found in groff: 3038.Pp 3039.Bl -dash -compact 3040.It 3041.Ic \&Dd 3042with non-standard arguments behaves very strangely. 3043When there are three arguments, they are printed verbatim. 3044Any other number of arguments is replaced by the current date, 3045but without any arguments the string 3046.Dq Epoch 3047is printed. 3048.It 3049.Ic \&Lk 3050only accepts a single link-name argument; the remainder is misformatted. 3051.It 3052.Ic \&Pa 3053does not format its arguments when used in the FILES section under 3054certain list types. 3055.It 3056.Ic \&Ta 3057can only be called by other macros, but not at the beginning of a line. 3058.It 3059.Ic \&%C 3060is not implemented (up to and including groff-1.22.2). 3061.It 3062.Sq \ef 3063.Pq font face 3064and 3065.Sq \eF 3066.Pq font family face 3067.Sx Text Decoration 3068escapes behave irregularly when specified within line-macro scopes. 3069.It 3070Negative scaling units return to prior lines. 3071Instead, mandoc truncates them to zero. 3072.El 3073.Pp 3074The following features are unimplemented in mandoc: 3075.Pp 3076.Bl -dash -compact 3077.It 3078.Ic \&Bd Fl file Ar file 3079is unsupported for security reasons. 3080.It 3081.Ic \&Bd 3082.Fl filled 3083does not adjust the right margin, but is an alias for 3084.Ic \&Bd 3085.Fl ragged . 3086.It 3087.Ic \&Bd 3088.Fl literal 3089does not use a literal font, but is an alias for 3090.Ic \&Bd 3091.Fl unfilled . 3092.It 3093.Ic \&Bd 3094.Fl offset Cm center 3095and 3096.Fl offset Cm right 3097don't work. 3098Groff does not implement centered and flush-right rendering either, 3099but produces large indentations. 3100.El 3101.Sh SEE ALSO 3102.Xr man 1 , 3103.Xr mandoc 1 , 3104.Xr eqn 7 , 3105.Xr man 7 , 3106.Xr mandoc_char 7 , 3107.Xr roff 7 , 3108.Xr tbl 7 3109.Pp 3110The web page 3111.Lk http://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language" 3112provides a few tutorial-style pages for beginners, an extensive style 3113guide for advanced authors, and an alphabetic index helping to choose 3114the best macros for various kinds of content. 3115.Sh HISTORY 3116The 3117.Nm 3118language first appeared as a troff macro package in 3119.Bx 4.4 . 3120It was later significantly updated by Werner Lemberg and Ruslan Ermilov 3121in groff-1.17. 3122The standalone implementation that is part of the 3123.Xr mandoc 1 3124utility written by Kristaps Dzonsons appeared in 3125.Ox 4.6 . 3126.Sh AUTHORS 3127The 3128.Nm 3129reference was written by 3130.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 3131