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