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