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