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