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