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) 2011 Ingo Schwarze <schwarze@openbsd.org> 17 .\" Copyright 2012 Nexenta Systems, Inc. All rights reserved. 18 .\" 19 .Dd Jan 3, 2012 20 .Dt MAN 5 21 .Os 22 .Sh NAME 23 .Nm man 24 .Nd legacy formatting language for manual pages 25 .Sh DESCRIPTION 26 Traditionally, the 27 .Nm man 28 language has been used to write 29 .Ux 30 manuals for the 31 .Xr man 1 32 utility. 33 It supports limited control of presentational details like fonts, 34 indentation and spacing. 35 This reference document describes the structure of manual pages 36 and the syntax and usage of the man language. 37 .Pp 38 .Bf -emphasis 39 Do not use 40 .Nm 41 to write your manuals: 42 .Ef 43 It lacks support for semantic markup. 44 Use the 45 .Xr mdoc 5 46 language, instead. 47 .Pp 48 In a 49 .Nm 50 document, lines beginning with the control character 51 .Sq \&. 52 are called 53 .Dq macro lines . 54 The first word is the macro name. 55 It usually consists of two capital letters. 56 For a list of available macros, see 57 .Sx MACRO OVERVIEW . 58 The words following the macro name are arguments to the macro. 59 .Pp 60 Lines not beginning with the control character are called 61 .Dq text lines . 62 They provide free-form text to be printed; the formatting of the text 63 depends on the respective processing context: 64 .Bd -literal -offset indent 65 \&.SH Macro lines change control state. 66 Text lines are interpreted within the current state. 67 .Ed 68 .Pp 69 Many aspects of the basic syntax of the 70 .Nm 71 language are based on the 72 .Xr roff 5 73 language; see the 74 .Em LANGUAGE SYNTAX 75 and 76 .Em MACRO SYNTAX 77 sections in the 78 .Xr roff 5 79 manual for details, in particular regarding 80 comments, escape sequences, whitespace, and quoting. 81 .Sh MANUAL STRUCTURE 82 Each 83 .Nm 84 document must contain the 85 .Sx \&TH 86 macro describing the document's section and title. 87 It may occur anywhere in the document, although conventionally it 88 appears as the first macro. 89 .Pp 90 Beyond 91 .Sx \&TH , 92 at least one macro or text line must appear in the document. 93 .Pp 94 The following is a well-formed skeleton 95 .Nm 96 file for a utility 97 .Qq progname : 98 .Bd -literal -offset indent 99 \&.TH PROGNAME 1 "Oct 10, 2009" 100 \&.SH NAME 101 \efBprogname\efR \e(en a description goes here 102 \&.\e\(dq .SH LIBRARY 103 \&.\e\(dq For sections 2 & 3 only. 104 \&.SH SYNOPSIS 105 \efBprogname\efR [\efB\e-options\efR] arguments... 106 \&.SH DESCRIPTION 107 The \efBfoo\efR utility processes files... 108 \&.\e\(dq .SH IMPLEMENTATION NOTES 109 \&.\e\(dq .SH RETURN VALUES 110 \&.\e\(dq For sections 2, 3, & 9 only. 111 \&.\e\(dq .SH ENVIRONMENT 112 \&.\e\(dq For sections 1, 1M, 5, & 6 only. 113 \&.\e\(dq .SH FILES 114 \&.\e\(dq .SH EXIT STATUS 115 \&.\e\(dq For sections 1, 1M, & 6 only. 116 \&.\e\(dq .SH EXAMPLES 117 \&.\e\(dq .SH DIAGNOSTICS 118 \&.\e\(dq For sections 1, 1M, 5, 6, & 7 only. 119 \&.\e\(dq .SH ERRORS 120 \&.\e\(dq For sections 2, 3, & 9 only. 121 \&.\e\(dq .SH SEE ALSO 122 \&.\e\(dq .BR foo ( 1 ) 123 \&.\e\(dq .SH STANDARDS 124 \&.\e\(dq .SH HISTORY 125 \&.\e\(dq .SH AUTHORS 126 \&.\e\(dq .SH CAVEATS 127 \&.\e\(dq .SH BUGS 128 \&.\e\(dq .SH SECURITY CONSIDERATIONS 129 .Ed 130 .Pp 131 The sections in a 132 .Nm 133 document are conventionally ordered as they appear above. 134 Sections should be composed as follows: 135 .Bl -ohang -offset indent 136 .It Em NAME 137 The name(s) and a short description of the documented material. 138 The syntax for this is generally as follows: 139 .Pp 140 .D1 \efBname\efR \e(en description 141 .It Em LIBRARY 142 The name of the library containing the documented material, which is 143 assumed to be a function in a section 2 or 3 manual. 144 For functions in the C library, this may be as follows: 145 .Pp 146 .D1 Standard C Library (libc, -lc) 147 .It Em SYNOPSIS 148 Documents the utility invocation syntax, function call syntax, or device 149 configuration. 150 .Pp 151 For the first, utilities (sections 1, 1M, and 6), this is 152 generally structured as follows: 153 .Pp 154 .D1 \efBname\efR [-\efBab\efR] [-\efBc\efR\efIarg\efR] \efBpath\efR... 155 .Pp 156 For the second, function calls (sections 2, 3, 9): 157 .Pp 158 .D1 \&.B char *name(char *\efIarg\efR); 159 .Pp 160 And for the third, configurations (section 7): 161 .Pp 162 .D1 \&.B name* at cardbus ? function ? 163 .Pp 164 Manuals not in these sections generally don't need a 165 .Em SYNOPSIS . 166 .It Em DESCRIPTION 167 This expands upon the brief, one-line description in 168 .Em NAME . 169 It usually contains a break-down of the options (if documenting a 170 command). 171 .It Em IMPLEMENTATION NOTES 172 Implementation-specific notes should be kept here. 173 This is useful when implementing standard functions that may have side 174 effects or notable algorithmic implications. 175 .It Em RETURN VALUES 176 This section documents the return values of functions in sections 2, 3, and 9. 177 .It Em ENVIRONMENT 178 Documents any usages of environment variables, e.g., 179 .Xr environ 5 . 180 .It Em FILES 181 Documents files used. 182 It's helpful to document both the file name and a short description of how 183 the file is used (created, modified, etc.). 184 .It Em EXIT STATUS 185 This section documents the command exit status for 186 section 1, 6, and 8 utilities. 187 Historically, this information was described in 188 .Em DIAGNOSTICS , 189 a practise that is now discouraged. 190 .It Em EXAMPLES 191 Example usages. 192 This often contains snippets of well-formed, 193 well-tested invocations. 194 Make sure that examples work properly! 195 .It Em DIAGNOSTICS 196 Documents error conditions. 197 This is most useful in section 4 manuals. 198 Historically, this section was used in place of 199 .Em EXIT STATUS 200 for manuals in sections 1, 6, and 8; however, this practise is 201 discouraged. 202 .It Em ERRORS 203 Documents error handling in sections 2, 3, and 9. 204 .It Em SEE ALSO 205 References other manuals with related topics. 206 This section should exist for most manuals. 207 .Pp 208 .D1 \&.BR bar \&( 1 \&), 209 .Pp 210 Cross-references should conventionally be ordered 211 first by section, then alphabetically. 212 .It Em STANDARDS 213 References any standards implemented or used, such as 214 .Pp 215 .D1 IEEE Std 1003.2 (\e(lqPOSIX.2\e(rq) 216 .Pp 217 If not adhering to any standards, the 218 .Em HISTORY 219 section should be used. 220 .It Em HISTORY 221 A brief history of the subject, including where support first appeared. 222 .It Em AUTHORS 223 Credits to the person or persons who wrote the code and/or documentation. 224 Authors should generally be noted by both name and email address. 225 .It Em CAVEATS 226 Common misuses and misunderstandings should be explained 227 in this section. 228 .It Em BUGS 229 Known bugs, limitations, and work-arounds should be described 230 in this section. 231 .It Em SECURITY CONSIDERATIONS 232 Documents any security precautions that operators should consider. 233 .El 234 .Sh MACRO OVERVIEW 235 This overview is sorted such that macros of similar purpose are listed 236 together, to help find the best macro for any given purpose. 237 Deprecated macros are not included in the overview, but can be found 238 in the alphabetical reference below. 239 .Ss Page header and footer meta-data 240 .Bl -column "PP, LP, P" description 241 .It Sx TH Ta set the title: Ar title section date Op Ar source Op Ar volume 242 .It Sx AT Ta display AT&T UNIX version in the page footer (<= 1 argument) 243 .It Sx UC Ta display BSD version in the page footer (<= 1 argument) 244 .El 245 .Ss Sections and paragraphs 246 .Bl -column "PP, LP, P" description 247 .It Sx SH Ta section header (one line) 248 .It Sx SS Ta subsection header (one line) 249 .It Sx PP , LP , P Ta start an undecorated paragraph (no arguments) 250 .It Sx RS , RE Ta reset the left margin: Op Ar width 251 .It Sx IP Ta indented paragraph: Op Ar head Op Ar width 252 .It Sx TP Ta tagged paragraph: Op Ar width 253 .It Sx HP Ta hanged paragraph: Op Ar width 254 .It Sx \&br Ta force output line break in text mode (no arguments) 255 .It Sx \&sp Ta force vertical space: Op Ar height 256 .It Sx fi , nf Ta fill mode and no-fill mode (no arguments) 257 .It Sx in Ta additional indent: Op Ar width 258 .El 259 .Ss Physical markup 260 .Bl -column "PP, LP, P" description 261 .It Sx B Ta boldface font 262 .It Sx I Ta italic font 263 .It Sx R Ta roman (default) font 264 .It Sx SB Ta small boldface font 265 .It Sx SM Ta small roman font 266 .It Sx BI Ta alternate between boldface and italic fonts 267 .It Sx BR Ta alternate between boldface and roman fonts 268 .It Sx IB Ta alternate between italic and boldface fonts 269 .It Sx IR Ta alternate between italic and roman fonts 270 .It Sx RB Ta alternate between roman and boldface fonts 271 .It Sx RI Ta alternate between roman and italic fonts 272 .El 273 .Ss Semantic markup 274 .Bl -column "PP, LP, P" description 275 .It Sx OP Ta optional arguments 276 .El 277 .Sh MACRO REFERENCE 278 This section is a canonical reference to all macros, arranged 279 alphabetically. 280 For the scoping of individual macros, see 281 .Sx MACRO SYNTAX . 282 .Ss \&AT 283 Sets the volume for the footer for compatibility with man pages from 284 .Tn AT&T UNIX 285 releases. 286 The optional arguments specify which release it is from. 287 .Ss \&B 288 Text is rendered in bold face. 289 .Pp 290 See also 291 .Sx \&I 292 and 293 .Sx \&R . 294 .Ss \&BI 295 Text is rendered alternately in bold face and italic. 296 Thus, 297 .Sq .BI this word and that 298 causes 299 .Sq this 300 and 301 .Sq and 302 to render in bold face, while 303 .Sq word 304 and 305 .Sq that 306 render in italics. 307 Whitespace between arguments is omitted in output. 308 .Pp 309 Examples: 310 .Pp 311 .Dl \&.BI bold italic bold italic 312 .Pp 313 The output of this example will be emboldened 314 .Dq bold 315 and italicised 316 .Dq italic , 317 with spaces stripped between arguments. 318 .Pp 319 See also 320 .Sx \&IB , 321 .Sx \&BR , 322 .Sx \&RB , 323 .Sx \&RI , 324 and 325 .Sx \&IR . 326 .Ss \&BR 327 Text is rendered alternately in bold face and roman (the default font). 328 Whitespace between arguments is omitted in output. 329 .Pp 330 See 331 .Sx \&BI 332 for an equivalent example. 333 .Pp 334 See also 335 .Sx \&BI , 336 .Sx \&IB , 337 .Sx \&RB , 338 .Sx \&RI , 339 and 340 .Sx \&IR . 341 .Ss \&DT 342 Has no effect. 343 Included for compatibility. 344 .Ss \&HP 345 Begin a paragraph whose initial output line is left-justified, but 346 subsequent output lines are indented, with the following syntax: 347 .Bd -filled -offset indent 348 .Pf \. Sx \&HP 349 .Op Cm width 350 .Ed 351 .Pp 352 The 353 .Cm width 354 argument must conform to 355 .Sx Scaling Widths . 356 If specified, it's saved for later paragraph left-margins; if unspecified, the 357 saved or default width is used. 358 .Pp 359 See also 360 .Sx \&IP , 361 .Sx \&LP , 362 .Sx \&P , 363 .Sx \&PP , 364 and 365 .Sx \&TP . 366 .Ss \&I 367 Text is rendered in italics. 368 .Pp 369 See also 370 .Sx \&B 371 and 372 .Sx \&R . 373 .Ss \&IB 374 Text is rendered alternately in italics and bold face. 375 Whitespace between arguments is omitted in output. 376 .Pp 377 See 378 .Sx \&BI 379 for an equivalent example. 380 .Pp 381 See also 382 .Sx \&BI , 383 .Sx \&BR , 384 .Sx \&RB , 385 .Sx \&RI , 386 and 387 .Sx \&IR . 388 .Ss \&IP 389 Begin an indented paragraph with the following syntax: 390 .Bd -filled -offset indent 391 .Pf \. Sx \&IP 392 .Op Cm head Op Cm width 393 .Ed 394 .Pp 395 The 396 .Cm width 397 argument defines the width of the left margin and is defined by 398 .Sx Scaling Widths . 399 It's saved for later paragraph left-margins; if unspecified, the saved or 400 default width is used. 401 .Pp 402 The 403 .Cm head 404 argument is used as a leading term, flushed to the left margin. 405 This is useful for bulleted paragraphs and so on. 406 .Pp 407 See also 408 .Sx \&HP , 409 .Sx \&LP , 410 .Sx \&P , 411 .Sx \&PP , 412 and 413 .Sx \&TP . 414 .Ss \&IR 415 Text is rendered alternately in italics and roman (the default font). 416 Whitespace between arguments is omitted in output. 417 .Pp 418 See 419 .Sx \&BI 420 for an equivalent example. 421 .Pp 422 See also 423 .Sx \&BI , 424 .Sx \&IB , 425 .Sx \&BR , 426 .Sx \&RB , 427 and 428 .Sx \&RI . 429 .Ss \&LP 430 Begin an undecorated paragraph. 431 The scope of a paragraph is closed by a subsequent paragraph, 432 sub-section, section, or end of file. 433 The saved paragraph left-margin width is reset to the default. 434 .Pp 435 See also 436 .Sx \&HP , 437 .Sx \&IP , 438 .Sx \&P , 439 .Sx \&PP , 440 and 441 .Sx \&TP . 442 .Ss \&OP 443 Optional command-line argument. 444 This has the following syntax: 445 .Bd -filled -offset indent 446 .Pf \. Sx \&OP 447 .Cm key Op Cm value 448 .Ed 449 .Pp 450 The 451 .Cm key 452 is usually a command-line flag and 453 .Cm value 454 its argument. 455 .Ss \&P 456 Synonym for 457 .Sx \&LP . 458 .Pp 459 See also 460 .Sx \&HP , 461 .Sx \&IP , 462 .Sx \&LP , 463 .Sx \&PP , 464 and 465 .Sx \&TP . 466 .Ss \&PP 467 Synonym for 468 .Sx \&LP . 469 .Pp 470 See also 471 .Sx \&HP , 472 .Sx \&IP , 473 .Sx \&LP , 474 .Sx \&P , 475 and 476 .Sx \&TP . 477 .Ss \&R 478 Text is rendered in roman (the default font). 479 .Pp 480 See also 481 .Sx \&I 482 and 483 .Sx \&B . 484 .Ss \&RB 485 Text is rendered alternately in roman (the default font) and bold face. 486 Whitespace between arguments is omitted in output. 487 .Pp 488 See 489 .Sx \&BI 490 for an equivalent example. 491 .Pp 492 See also 493 .Sx \&BI , 494 .Sx \&IB , 495 .Sx \&BR , 496 .Sx \&RI , 497 and 498 .Sx \&IR . 499 .Ss \&RE 500 Explicitly close out the scope of a prior 501 .Sx \&RS . 502 The default left margin is restored to the state of the original 503 .Sx \&RS 504 invocation. 505 .Ss \&RI 506 Text is rendered alternately in roman (the default font) and italics. 507 Whitespace between arguments is omitted in output. 508 .Pp 509 See 510 .Sx \&BI 511 for an equivalent example. 512 .Pp 513 See also 514 .Sx \&BI , 515 .Sx \&IB , 516 .Sx \&BR , 517 .Sx \&RB , 518 and 519 .Sx \&IR . 520 .Ss \&RS 521 Temporarily reset the default left margin. 522 This has the following syntax: 523 .Bd -filled -offset indent 524 .Pf \. Sx \&RS 525 .Op Cm width 526 .Ed 527 .Pp 528 The 529 .Cm width 530 argument must conform to 531 .Sx Scaling Widths . 532 If not specified, the saved or default width is used. 533 .Pp 534 See also 535 .Sx \&RE . 536 .Ss \&SB 537 Text is rendered in small size (one point smaller than the default font) 538 bold face. 539 .Ss \&SH 540 Begin a section. 541 The scope of a section is only closed by another section or the end of 542 file. 543 The paragraph left-margin width is reset to the default. 544 .Ss \&SM 545 Text is rendered in small size (one point smaller than the default 546 font). 547 .Ss \&SS 548 Begin a sub-section. 549 The scope of a sub-section is closed by a subsequent sub-section, 550 section, or end of file. 551 The paragraph left-margin width is reset to the default. 552 .Ss \&TH 553 Sets the title of the manual page with the following syntax: 554 .Bd -filled -offset indent 555 .Pf \. Sx \&TH 556 .Ar title section date 557 .Op Ar source Op Ar volume 558 .Ed 559 .Pp 560 Conventionally, the document 561 .Ar title 562 is given in all caps. 563 The recommended 564 .Ar date 565 format is 566 .Sy YYYY-MM-DD 567 as specified in the ISO-8601 standard; 568 if the argument does not conform, it is printed verbatim. 569 If the 570 .Ar date 571 is empty or not specified, the current date is used. 572 The optional 573 .Ar source 574 string specifies the organisation providing the utility. 575 The 576 .Ar volume 577 string replaces the default rendered volume, which is dictated by the 578 manual section. 579 .Pp 580 Examples: 581 .Pp 582 .Dl \&.TH CVS 5 "1992-02-12" GNU 583 .Ss \&TP 584 Begin a paragraph where the head, if exceeding the indentation width, is 585 followed by a newline; if not, the body follows on the same line after a 586 buffer to the indentation width. 587 Subsequent output lines are indented. 588 The syntax is as follows: 589 .Bd -filled -offset indent 590 .Pf \. Sx \&TP 591 .Op Cm width 592 .Ed 593 .Pp 594 The 595 .Cm width 596 argument must conform to 597 .Sx Scaling Widths . 598 If specified, it's saved for later paragraph left-margins; if 599 unspecified, the saved or default width is used. 600 .Pp 601 See also 602 .Sx \&HP , 603 .Sx \&IP , 604 .Sx \&LP , 605 .Sx \&P , 606 and 607 .Sx \&PP . 608 .Ss \&UC 609 Sets the volume for the footer for compatibility with man pages from 610 BSD releases. 611 The optional first argument specifies which release it is from. 612 .Ss \&br 613 Breaks the current line. 614 Consecutive invocations have no further effect. 615 .Pp 616 See also 617 .Sx \&sp . 618 .Ss \&fi 619 End literal mode begun by 620 .Sx \&nf . 621 .Ss \&ft 622 Change the current font mode. 623 See 624 .Sx Text Decoration 625 for a listing of available font modes. 626 .Ss \&in 627 Indent relative to the current indentation: 628 .Pp 629 .D1 Pf \. Sx \&in Op Cm width 630 .Pp 631 If 632 .Cm width 633 is signed, the new offset is relative. 634 Otherwise, it is absolute. 635 This value is reset upon the next paragraph, section, or sub-section. 636 .Ss \&na 637 Don't align to the right margin. 638 .Ss \&nf 639 Begin literal mode: all subsequent free-form lines have their end of 640 line boundaries preserved. 641 May be ended by 642 .Sx \&fi . 643 Literal mode is implicitly ended by 644 .Sx \&SH 645 or 646 .Sx \&SS . 647 .Ss \&sp 648 Insert vertical spaces into output with the following syntax: 649 .Bd -filled -offset indent 650 .Pf \. Sx \&sp 651 .Op Cm height 652 .Ed 653 .Pp 654 Insert 655 .Cm height 656 spaces, which must conform to 657 .Sx Scaling Widths . 658 If 0, this is equivalent to the 659 .Sx \&br 660 macro. 661 Defaults to 1, if unspecified. 662 .Pp 663 See also 664 .Sx \&br . 665 .Sh MACRO SYNTAX 666 The 667 .Nm 668 macros are classified by scope: line scope or block scope. 669 Line macros are only scoped to the current line (and, in some 670 situations, the subsequent line). 671 Block macros are scoped to the current line and subsequent lines until 672 closed by another block macro. 673 .Ss Line Macros 674 Line macros are generally scoped to the current line, with the body 675 consisting of zero or more arguments. 676 If a macro is scoped to the next line and the line arguments are empty, 677 the next line, which must be text, is used instead. 678 Thus: 679 .Bd -literal -offset indent 680 \&.I 681 foo 682 .Ed 683 .Pp 684 is equivalent to 685 .Sq \&.I foo . 686 If next-line macros are invoked consecutively, only the last is used. 687 If a next-line macro is followed by a non-next-line macro, an error is 688 raised, except for 689 .Sx \&br , 690 .Sx \&sp , 691 and 692 .Sx \&na . 693 .Pp 694 The syntax is as follows: 695 .Bd -literal -offset indent 696 \&.YO \(lBbody...\(rB 697 \(lBbody...\(rB 698 .Ed 699 .Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent 700 .It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes 701 .It Sx \&AT Ta <=1 Ta current Ta \& 702 .It Sx \&B Ta n Ta next-line Ta \& 703 .It Sx \&BI Ta n Ta current Ta \& 704 .It Sx \&BR Ta n Ta current Ta \& 705 .It Sx \&DT Ta 0 Ta current Ta \& 706 .It Sx \&I Ta n Ta next-line Ta \& 707 .It Sx \&IB Ta n Ta current Ta \& 708 .It Sx \&IR Ta n Ta current Ta \& 709 .It Sx \&OP Ta 0, 1 Ta current Ta compat 710 .It Sx \&R Ta n Ta next-line Ta \& 711 .It Sx \&RB Ta n Ta current Ta \& 712 .It Sx \&RI Ta n Ta current Ta \& 713 .It Sx \&SB Ta n Ta next-line Ta \& 714 .It Sx \&SM Ta n Ta next-line Ta \& 715 .It Sx \&TH Ta >1, <6 Ta current Ta \& 716 .It Sx \&UC Ta <=1 Ta current Ta \& 717 .It Sx \&br Ta 0 Ta current Ta compat 718 .It Sx \&fi Ta 0 Ta current Ta compat 719 .It Sx \&ft Ta 1 Ta current Ta compat 720 .It Sx \&in Ta 1 Ta current Ta compat 721 .It Sx \&na Ta 0 Ta current Ta compat 722 .It Sx \&nf Ta 0 Ta current Ta compat 723 .It Sx \&sp Ta 1 Ta current Ta compat 724 .El 725 .Pp 726 Macros marked as 727 .Qq compat 728 are included for compatibility with the significant corpus of existing 729 manuals that mix dialects of roff. 730 These macros should not be used for portable 731 .Nm 732 manuals. 733 .Ss Block Macros 734 Block macros comprise a head and body. 735 As with in-line macros, the head is scoped to the current line and, in 736 one circumstance, the next line (the next-line stipulations as in 737 .Sx Line Macros 738 apply here as well). 739 .Pp 740 The syntax is as follows: 741 .Bd -literal -offset indent 742 \&.YO \(lBhead...\(rB 743 \(lBhead...\(rB 744 \(lBbody...\(rB 745 .Ed 746 .Pp 747 The closure of body scope may be to the section, where a macro is closed 748 by 749 .Sx \&SH ; 750 sub-section, closed by a section or 751 .Sx \&SS ; 752 part, closed by a section, sub-section, or 753 .Sx \&RE ; 754 or paragraph, closed by a section, sub-section, part, 755 .Sx \&HP , 756 .Sx \&IP , 757 .Sx \&LP , 758 .Sx \&P , 759 .Sx \&PP , 760 or 761 .Sx \&TP . 762 No closure refers to an explicit block closing macro. 763 .Pp 764 As a rule, block macros may not be nested; thus, calling a block macro 765 while another block macro scope is open, and the open scope is not 766 implicitly closed, is syntactically incorrect. 767 .Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent 768 .It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes 769 .It Sx \&HP Ta <2 Ta current Ta paragraph Ta \& 770 .It Sx \&IP Ta <3 Ta current Ta paragraph Ta \& 771 .It Sx \&LP Ta 0 Ta current Ta paragraph Ta \& 772 .It Sx \&P Ta 0 Ta current Ta paragraph Ta \& 773 .It Sx \&PP Ta 0 Ta current Ta paragraph Ta \& 774 .It Sx \&RE Ta 0 Ta current Ta none Ta compat 775 .It Sx \&RS Ta 1 Ta current Ta part Ta compat 776 .It Sx \&SH Ta >0 Ta next-line Ta section Ta \& 777 .It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \& 778 .It Sx \&TP Ta n Ta next-line Ta paragraph Ta \& 779 .El 780 .Pp 781 Macros marked 782 .Qq compat 783 are as mentioned in 784 .Sx Line Macros . 785 .Pp 786 If a block macro is next-line scoped, it may only be followed by in-line 787 macros for decorating text. 788 .Ss Font handling 789 In 790 .Nm 791 documents, both 792 .Sx Physical markup 793 macros and 794 .Xr roff 5 795 .Ql \ef 796 font escape sequences can be used to choose fonts. 797 In text lines, the effect of manual font selection by escape sequences 798 only lasts until the next macro invocation; in macro lines, it only lasts 799 until the end of the macro scope. 800 Note that macros like 801 .Sx \&BR 802 open and close a font scope for each argument. 803 .Sh COMPATIBILITY 804 This section documents areas of questionable portability between 805 implementations of the 806 .Nm 807 language. 808 .Pp 809 .Bl -dash -compact 810 .It 811 Do not depend on 812 .Sx \&SH 813 or 814 .Sx \&SS 815 to close out a literal context opened with 816 .Sx \&nf . 817 This behaviour may not be portable. 818 .It 819 In quoted literals, GNU troff allowed pair-wise double-quotes to produce 820 a standalone double-quote in formatted output. 821 It is not known whether this behaviour is exhibited by other formatters. 822 .It 823 troff suppresses a newline before 824 .Sq \(aq 825 macro output; in mandoc, it is an alias for the standard 826 .Sq \&. 827 control character. 828 .It 829 The 830 .Sq \eh 831 .Pq horizontal position , 832 .Sq \ev 833 .Pq vertical position , 834 .Sq \em 835 .Pq text colour , 836 .Sq \eM 837 .Pq text filling colour , 838 .Sq \ez 839 .Pq zero-length character , 840 .Sq \ew 841 .Pq string length , 842 .Sq \ek 843 .Pq horizontal position marker , 844 .Sq \eo 845 .Pq text overstrike , 846 and 847 .Sq \es 848 .Pq text size 849 escape sequences are all discarded in mandoc. 850 .It 851 The 852 .Sq \ef 853 scaling unit is accepted by mandoc, but rendered as the default unit. 854 .It 855 The 856 .Sx \&sp 857 macro does not accept negative values in mandoc. 858 In GNU troff, this would result in strange behaviour. 859 .It 860 In page header lines, GNU troff versions up to and including 1.21 861 only print 862 .Ar volume 863 names explicitly specified in the 864 .Sx \&TH 865 macro; mandoc and newer groff print the default volume name 866 corresponding to the 867 .Ar section 868 number when no 869 .Ar volume 870 is given, like in 871 .Xr mdoc 5 . 872 .El 873 .Pp 874 The 875 .Sx OP 876 macro is part of the extended 877 .Nm 878 macro set, and may not be portable to non-GNU troff implementations. 879 .Sh SEE ALSO 880 .Xr man 1 , 881 .Xr mandoc 1 , 882 .Xr eqn 5 , 883 .Xr mandoc_char 5 , 884 .Xr mdoc 5 , 885 .Xr roff 5 , 886 .Xr tbl 5 887 .Sh HISTORY 888 The 889 .Nm 890 language first appeared as a macro package for the roff typesetting 891 system in 892 .At v7 . 893 It was later rewritten by James Clark as a macro package for groff. 894 Eric S. Raymond wrote the extended 895 .Nm 896 macros for groff in 2007. 897 The stand-alone implementation that is part of the 898 .Xr mandoc 1 899 utility written by Kristaps Dzonsons appeared in 900 .Ox 4.6 . 901 .Sh AUTHORS 902 This 903 .Nm 904 reference was written by 905 .An Kristaps Dzonsons , 906 .Mt kristaps@bsd.lv . 907 .Sh CAVEATS 908 Do not use this language. 909 Use 910 .Xr mdoc 5 , 911 instead.