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