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