1.\" $OpenBSD: man.7,v 1.32 2013/08/14 08:39:29 jmc 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: August 14 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 \&in 669Indent relative to the current indentation: 670.Pp 671.D1 Pf \. Sx \&in Op Cm width 672.Pp 673If 674.Cm width 675is signed, the new offset is relative. 676Otherwise, it is absolute. 677This value is reset upon the next paragraph, section, or sub-section. 678.Ss \&na 679Don't align to the right margin. 680.Ss \&nf 681Begin literal mode: all subsequent free-form lines have their end of 682line boundaries preserved. 683May be ended by 684.Sx \&fi . 685Literal mode is implicitly ended by 686.Sx \&SH 687or 688.Sx \&SS . 689.Ss \&sp 690Insert vertical spaces into output with the following syntax: 691.Bd -filled -offset indent 692.Pf \. Sx \&sp 693.Op Cm height 694.Ed 695.Pp 696The 697.Cm height 698argument is a scaling width as described in 699.Xr roff 7 . 700If 0, this is equivalent to the 701.Sx \&br 702macro. 703Defaults to 1, if unspecified. 704.Pp 705See also 706.Sx \&br . 707.Sh MACRO SYNTAX 708The 709.Nm 710macros are classified by scope: line scope or block scope. 711Line macros are only scoped to the current line (and, in some 712situations, the subsequent line). 713Block macros are scoped to the current line and subsequent lines until 714closed by another block macro. 715.Ss Line Macros 716Line macros are generally scoped to the current line, with the body 717consisting of zero or more arguments. 718If a macro is scoped to the next line and the line arguments are empty, 719the next line, which must be text, is used instead. 720Thus: 721.Bd -literal -offset indent 722\&.I 723foo 724.Ed 725.Pp 726is equivalent to 727.Sq \&.I foo . 728If next-line macros are invoked consecutively, only the last is used. 729If a next-line macro is followed by a non-next-line macro, an error is 730raised, except for 731.Sx \&br , 732.Sx \&sp , 733and 734.Sx \&na . 735.Pp 736The syntax is as follows: 737.Bd -literal -offset indent 738\&.YO \(lBbody...\(rB 739\(lBbody...\(rB 740.Ed 741.Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent 742.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes 743.It Sx \&AT Ta <=1 Ta current Ta \& 744.It Sx \&B Ta n Ta next-line Ta \& 745.It Sx \&BI Ta n Ta current Ta \& 746.It Sx \&BR Ta n Ta current Ta \& 747.It Sx \&DT Ta 0 Ta current Ta \& 748.It Sx \&I Ta n Ta next-line Ta \& 749.It Sx \&IB Ta n Ta current Ta \& 750.It Sx \&IR Ta n Ta current Ta \& 751.It Sx \&OP Ta 0, 1 Ta current Ta compat 752.It Sx \&R Ta n Ta next-line Ta \& 753.It Sx \&RB Ta n Ta current Ta \& 754.It Sx \&RI Ta n Ta current Ta \& 755.It Sx \&SB Ta n Ta next-line Ta \& 756.It Sx \&SM Ta n Ta next-line Ta \& 757.It Sx \&TH Ta >1, <6 Ta current Ta \& 758.It Sx \&UC Ta <=1 Ta current Ta \& 759.It Sx \&br Ta 0 Ta current Ta compat 760.It Sx \&fi Ta 0 Ta current Ta compat 761.It Sx \&in Ta 1 Ta current Ta compat 762.It Sx \&na Ta 0 Ta current Ta compat 763.It Sx \&nf Ta 0 Ta current Ta compat 764.It Sx \&sp Ta 1 Ta current Ta compat 765.El 766.Pp 767Macros marked as 768.Qq compat 769are included for compatibility with the significant corpus of existing 770manuals that mix dialects of roff. 771These macros should not be used for portable 772.Nm 773manuals. 774.Ss Block Macros 775Block macros comprise a head and body. 776As with in-line macros, the head is scoped to the current line and, in 777one circumstance, the next line (the next-line stipulations as in 778.Sx Line Macros 779apply here as well). 780.Pp 781The syntax is as follows: 782.Bd -literal -offset indent 783\&.YO \(lBhead...\(rB 784\(lBhead...\(rB 785\(lBbody...\(rB 786.Ed 787.Pp 788The closure of body scope may be to the section, where a macro is closed 789by 790.Sx \&SH ; 791sub-section, closed by a section or 792.Sx \&SS ; 793part, closed by a section, sub-section, or 794.Sx \&RE ; 795or paragraph, closed by a section, sub-section, part, 796.Sx \&HP , 797.Sx \&IP , 798.Sx \&LP , 799.Sx \&P , 800.Sx \&PP , 801or 802.Sx \&TP . 803No closure refers to an explicit block closing macro. 804.Pp 805As a rule, block macros may not be nested; thus, calling a block macro 806while another block macro scope is open, and the open scope is not 807implicitly closed, is syntactically incorrect. 808.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent 809.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes 810.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \& 811.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \& 812.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \& 813.It Sx \&P Ta 0 Ta current Ta paragraph Ta \& 814.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \& 815.It Sx \&RE Ta 0 Ta current Ta none Ta compat 816.It Sx \&RS Ta 1 Ta current Ta part Ta compat 817.It Sx \&SH Ta >0 Ta next-line Ta section Ta \& 818.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \& 819.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \& 820.El 821.Pp 822Macros marked 823.Qq compat 824are as mentioned in 825.Sx Line Macros . 826.Pp 827If a block macro is next-line scoped, it may only be followed by in-line 828macros for decorating text. 829.Ss Font handling 830In 831.Nm 832documents, both 833.Sx Physical markup 834macros and 835.Xr roff 7 836.Ql \ef 837font escape sequences can be used to choose fonts. 838In text lines, the effect of manual font selection by escape sequences 839only lasts until the next macro invocation; in macro lines, it only lasts 840until the end of the macro scope. 841Note that macros like 842.Sx \&BR 843open and close a font scope for each argument. 844.Sh COMPATIBILITY 845This section documents areas of questionable portability between 846implementations of the 847.Nm 848language. 849.Pp 850.Bl -dash -compact 851.It 852Do not depend on 853.Sx \&SH 854or 855.Sx \&SS 856to close out a literal context opened with 857.Sx \&nf . 858This behaviour may not be portable. 859.It 860In quoted literals, GNU troff allowed pair-wise double-quotes to produce 861a standalone double-quote in formatted output. 862It is not known whether this behaviour is exhibited by other formatters. 863.It 864troff suppresses a newline before 865.Sq \(aq 866macro output; in mandoc, it is an alias for the standard 867.Sq \&. 868control character. 869.It 870The 871.Sq \eh 872.Pq horizontal position , 873.Sq \ev 874.Pq vertical position , 875.Sq \em 876.Pq text colour , 877.Sq \eM 878.Pq text filling colour , 879.Sq \ez 880.Pq zero-length character , 881.Sq \ew 882.Pq string length , 883.Sq \ek 884.Pq horizontal position marker , 885.Sq \eo 886.Pq text overstrike , 887and 888.Sq \es 889.Pq text size 890escape sequences are all discarded in mandoc. 891.It 892The 893.Sq \ef 894scaling unit is accepted by mandoc, but rendered as the default unit. 895.It 896The 897.Sx \&sp 898macro does not accept negative values in mandoc. 899In GNU troff, this would result in strange behaviour. 900.It 901In page header lines, GNU troff versions up to and including 1.21 902only print 903.Ar volume 904names explicitly specified in the 905.Sx \&TH 906macro; mandoc and newer groff print the default volume name 907corresponding to the 908.Ar section 909number when no 910.Ar volume 911is given, like in 912.Xr mdoc 7 . 913.El 914.Pp 915The 916.Sx OP 917macro is part of the extended 918.Nm 919macro set, and may not be portable to non-GNU troff implementations. 920.Sh SEE ALSO 921.Xr man 1 , 922.Xr mandoc 1 , 923.Xr eqn 7 , 924.Xr mandoc_char 7 , 925.Xr mdoc 7 , 926.Xr roff 7 , 927.Xr tbl 7 928.Sh HISTORY 929The 930.Nm 931language first appeared as a macro package for the roff typesetting 932system in 933.At v7 . 934It was later rewritten by James Clark as a macro package for groff. 935Eric S. Raymond wrote the extended 936.Nm 937macros for groff in 2007. 938The stand-alone implementation that is part of the 939.Xr mandoc 1 940utility written by Kristaps Dzonsons appeared in 941.Ox 4.6 . 942.Sh AUTHORS 943This 944.Nm 945reference was written by 946.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 947.Sh CAVEATS 948Do not use this language. 949Use 950.Xr mdoc 7 , 951instead. 952