1.\" $Id: man.7,v 1.113 2012/01/03 15:16:24 kristaps Exp $ 2.\" 3.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2011 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: January 3 2012 $ 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 \&br Ta force output line break in text mode (no arguments) 257.It Sx \&sp Ta force vertical space: Op Ar height 258.It Sx fi , nf Ta fill mode and no-fill mode (no arguments) 259.It Sx in Ta additional indent: Op Ar width 260.El 261.Ss Physical markup 262.Bl -column "PP, LP, P" description 263.It Sx B Ta boldface font 264.It Sx I Ta italic font 265.It Sx R Ta roman (default) font 266.It Sx SB Ta small boldface font 267.It Sx SM Ta small roman font 268.It Sx BI Ta alternate between boldface and italic fonts 269.It Sx BR Ta alternate between boldface and roman fonts 270.It Sx IB Ta alternate between italic and boldface fonts 271.It Sx IR Ta alternate between italic and roman fonts 272.It Sx RB Ta alternate between roman and boldface fonts 273.It Sx RI Ta alternate between roman and italic fonts 274.El 275.Ss Semantic markup 276.Bl -column "PP, LP, P" description 277.It Sx OP Ta optional arguments 278.El 279.Sh MACRO REFERENCE 280This section is a canonical reference to all macros, arranged 281alphabetically. 282For the scoping of individual macros, see 283.Sx MACRO SYNTAX . 284.Ss \&AT 285Sets the volume for the footer for compatibility with man pages from 286.Tn AT&T UNIX 287releases. 288The optional arguments specify which release it is from. 289.Ss \&B 290Text is rendered in bold face. 291.Pp 292See also 293.Sx \&I 294and 295.Sx \&R . 296.Ss \&BI 297Text is rendered alternately in bold face and italic. 298Thus, 299.Sq .BI this word and that 300causes 301.Sq this 302and 303.Sq and 304to render in bold face, while 305.Sq word 306and 307.Sq that 308render in italics. 309Whitespace between arguments is omitted in output. 310.Pp 311Examples: 312.Pp 313.Dl \&.BI bold italic bold italic 314.Pp 315The output of this example will be emboldened 316.Dq bold 317and italicised 318.Dq italic , 319with spaces stripped between arguments. 320.Pp 321See also 322.Sx \&IB , 323.Sx \&BR , 324.Sx \&RB , 325.Sx \&RI , 326and 327.Sx \&IR . 328.Ss \&BR 329Text is rendered alternately in bold face and roman (the default font). 330Whitespace between arguments is omitted in output. 331.Pp 332See 333.Sx \&BI 334for an equivalent example. 335.Pp 336See also 337.Sx \&BI , 338.Sx \&IB , 339.Sx \&RB , 340.Sx \&RI , 341and 342.Sx \&IR . 343.Ss \&DT 344Has no effect. 345Included for compatibility. 346.Ss \&HP 347Begin a paragraph whose initial output line is left-justified, but 348subsequent output lines are indented, with the following syntax: 349.Bd -filled -offset indent 350.Pf \. Sx \&HP 351.Op Cm width 352.Ed 353.Pp 354The 355.Cm width 356argument must conform to 357.Sx Scaling Widths . 358If specified, it's saved for later paragraph left-margins; if unspecified, the 359saved or default width is used. 360.Pp 361See also 362.Sx \&IP , 363.Sx \&LP , 364.Sx \&P , 365.Sx \&PP , 366and 367.Sx \&TP . 368.Ss \&I 369Text is rendered in italics. 370.Pp 371See also 372.Sx \&B 373and 374.Sx \&R . 375.Ss \&IB 376Text is rendered alternately in italics and bold face. 377Whitespace between arguments is omitted in output. 378.Pp 379See 380.Sx \&BI 381for an equivalent example. 382.Pp 383See also 384.Sx \&BI , 385.Sx \&BR , 386.Sx \&RB , 387.Sx \&RI , 388and 389.Sx \&IR . 390.Ss \&IP 391Begin an indented paragraph with the following syntax: 392.Bd -filled -offset indent 393.Pf \. Sx \&IP 394.Op Cm head Op Cm width 395.Ed 396.Pp 397The 398.Cm width 399argument defines the width of the left margin and is defined by 400.Sx Scaling Widths . 401It's saved for later paragraph left-margins; if unspecified, the saved or 402default width is used. 403.Pp 404The 405.Cm head 406argument is used as a leading term, flushed to the left margin. 407This is useful for bulleted paragraphs and so on. 408.Pp 409See also 410.Sx \&HP , 411.Sx \&LP , 412.Sx \&P , 413.Sx \&PP , 414and 415.Sx \&TP . 416.Ss \&IR 417Text is rendered alternately in italics and roman (the default font). 418Whitespace between arguments is omitted in output. 419.Pp 420See 421.Sx \&BI 422for an equivalent example. 423.Pp 424See also 425.Sx \&BI , 426.Sx \&IB , 427.Sx \&BR , 428.Sx \&RB , 429and 430.Sx \&RI . 431.Ss \&LP 432Begin an undecorated paragraph. 433The scope of a paragraph is closed by a subsequent paragraph, 434sub-section, section, or end of file. 435The saved paragraph left-margin width is reset to the default. 436.Pp 437See also 438.Sx \&HP , 439.Sx \&IP , 440.Sx \&P , 441.Sx \&PP , 442and 443.Sx \&TP . 444.Ss \&OP 445Optional command-line argument. 446This has the following syntax: 447.Bd -filled -offset indent 448.Pf \. Sx \&OP 449.Cm key Op Cm value 450.Ed 451.Pp 452The 453.Cm key 454is usually a command-line flag and 455.Cm value 456its argument. 457.Ss \&P 458Synonym for 459.Sx \&LP . 460.Pp 461See also 462.Sx \&HP , 463.Sx \&IP , 464.Sx \&LP , 465.Sx \&PP , 466and 467.Sx \&TP . 468.Ss \&PP 469Synonym for 470.Sx \&LP . 471.Pp 472See also 473.Sx \&HP , 474.Sx \&IP , 475.Sx \&LP , 476.Sx \&P , 477and 478.Sx \&TP . 479.Ss \&R 480Text is rendered in roman (the default font). 481.Pp 482See also 483.Sx \&I 484and 485.Sx \&B . 486.Ss \&RB 487Text is rendered alternately in roman (the default font) and bold face. 488Whitespace between arguments is omitted in output. 489.Pp 490See 491.Sx \&BI 492for an equivalent example. 493.Pp 494See also 495.Sx \&BI , 496.Sx \&IB , 497.Sx \&BR , 498.Sx \&RI , 499and 500.Sx \&IR . 501.Ss \&RE 502Explicitly close out the scope of a prior 503.Sx \&RS . 504The default left margin is restored to the state of the original 505.Sx \&RS 506invocation. 507.Ss \&RI 508Text is rendered alternately in roman (the default font) and italics. 509Whitespace between arguments is omitted in output. 510.Pp 511See 512.Sx \&BI 513for an equivalent example. 514.Pp 515See also 516.Sx \&BI , 517.Sx \&IB , 518.Sx \&BR , 519.Sx \&RB , 520and 521.Sx \&IR . 522.Ss \&RS 523Temporarily reset the default left margin. 524This has the following syntax: 525.Bd -filled -offset indent 526.Pf \. Sx \&RS 527.Op Cm width 528.Ed 529.Pp 530The 531.Cm width 532argument must conform to 533.Sx Scaling Widths . 534If not specified, the saved or default width is used. 535.Pp 536See also 537.Sx \&RE . 538.Ss \&SB 539Text is rendered in small size (one point smaller than the default font) 540bold face. 541.Ss \&SH 542Begin a section. 543The scope of a section is only closed by another section or the end of 544file. 545The paragraph left-margin width is reset to the default. 546.Ss \&SM 547Text is rendered in small size (one point smaller than the default 548font). 549.Ss \&SS 550Begin a sub-section. 551The scope of a sub-section is closed by a subsequent sub-section, 552section, or end of file. 553The paragraph left-margin width is reset to the default. 554.Ss \&TH 555Sets the title of the manual page with the following syntax: 556.Bd -filled -offset indent 557.Pf \. Sx \&TH 558.Ar title section date 559.Op Ar source Op Ar volume 560.Ed 561.Pp 562Conventionally, the document 563.Ar title 564is given in all caps. 565The recommended 566.Ar date 567format is 568.Sy YYYY-MM-DD 569as specified in the ISO-8601 standard; 570if the argument does not conform, it is printed verbatim. 571If the 572.Ar date 573is empty or not specified, the current date is used. 574The optional 575.Ar source 576string specifies the organisation providing the utility. 577The 578.Ar volume 579string replaces the default rendered volume, which is dictated by the 580manual section. 581.Pp 582Examples: 583.Pp 584.Dl \&.TH CVS 5 "1992-02-12" GNU 585.Ss \&TP 586Begin a paragraph where the head, if exceeding the indentation width, is 587followed by a newline; if not, the body follows on the same line after a 588buffer to the indentation width. 589Subsequent output lines are indented. 590The syntax is as follows: 591.Bd -filled -offset indent 592.Pf \. Sx \&TP 593.Op Cm width 594.Ed 595.Pp 596The 597.Cm width 598argument must conform to 599.Sx Scaling Widths . 600If specified, it's saved for later paragraph left-margins; if 601unspecified, the saved or default width is used. 602.Pp 603See also 604.Sx \&HP , 605.Sx \&IP , 606.Sx \&LP , 607.Sx \&P , 608and 609.Sx \&PP . 610.Ss \&UC 611Sets the volume for the footer for compatibility with man pages from 612BSD releases. 613The optional first argument specifies which release it is from. 614.Ss \&br 615Breaks the current line. 616Consecutive invocations have no further effect. 617.Pp 618See also 619.Sx \&sp . 620.Ss \&fi 621End literal mode begun by 622.Sx \&nf . 623.Ss \&ft 624Change the current font mode. 625See 626.Sx Text Decoration 627for a listing of available font modes. 628.Ss \&in 629Indent relative to the current indentation: 630.Pp 631.D1 Pf \. Sx \&in Op Cm width 632.Pp 633If 634.Cm width 635is signed, the new offset is relative. 636Otherwise, it is absolute. 637This value is reset upon the next paragraph, section, or sub-section. 638.Ss \&na 639Don't align to the right margin. 640.Ss \&nf 641Begin literal mode: all subsequent free-form lines have their end of 642line boundaries preserved. 643May be ended by 644.Sx \&fi . 645Literal mode is implicitly ended by 646.Sx \&SH 647or 648.Sx \&SS . 649.Ss \&sp 650Insert vertical spaces into output with the following syntax: 651.Bd -filled -offset indent 652.Pf \. Sx \&sp 653.Op Cm height 654.Ed 655.Pp 656Insert 657.Cm height 658spaces, which must conform to 659.Sx Scaling Widths . 660If 0, this is equivalent to the 661.Sx \&br 662macro. 663Defaults to 1, if unspecified. 664.Pp 665See also 666.Sx \&br . 667.Sh MACRO SYNTAX 668The 669.Nm 670macros are classified by scope: line scope or block scope. 671Line macros are only scoped to the current line (and, in some 672situations, the subsequent line). 673Block macros are scoped to the current line and subsequent lines until 674closed by another block macro. 675.Ss Line Macros 676Line macros are generally scoped to the current line, with the body 677consisting of zero or more arguments. 678If a macro is scoped to the next line and the line arguments are empty, 679the next line, which must be text, is used instead. 680Thus: 681.Bd -literal -offset indent 682\&.I 683foo 684.Ed 685.Pp 686is equivalent to 687.Sq \&.I foo . 688If next-line macros are invoked consecutively, only the last is used. 689If a next-line macro is followed by a non-next-line macro, an error is 690raised, except for 691.Sx \&br , 692.Sx \&sp , 693and 694.Sx \&na . 695.Pp 696The syntax is as follows: 697.Bd -literal -offset indent 698\&.YO \(lBbody...\(rB 699\(lBbody...\(rB 700.Ed 701.Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent 702.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes 703.It Sx \&AT Ta <=1 Ta current Ta \& 704.It Sx \&B Ta n Ta next-line Ta \& 705.It Sx \&BI Ta n Ta current Ta \& 706.It Sx \&BR Ta n Ta current Ta \& 707.It Sx \&DT Ta 0 Ta current Ta \& 708.It Sx \&I Ta n Ta next-line Ta \& 709.It Sx \&IB Ta n Ta current Ta \& 710.It Sx \&IR Ta n Ta current Ta \& 711.It Sx \&OP Ta 0, 1 Ta current Ta compat 712.It Sx \&R Ta n Ta next-line Ta \& 713.It Sx \&RB Ta n Ta current Ta \& 714.It Sx \&RI Ta n Ta current Ta \& 715.It Sx \&SB Ta n Ta next-line Ta \& 716.It Sx \&SM Ta n Ta next-line Ta \& 717.It Sx \&TH Ta >1, <6 Ta current Ta \& 718.It Sx \&UC Ta <=1 Ta current Ta \& 719.It Sx \&br Ta 0 Ta current Ta compat 720.It Sx \&fi Ta 0 Ta current Ta compat 721.It Sx \&ft Ta 1 Ta current Ta compat 722.It Sx \&in Ta 1 Ta current Ta compat 723.It Sx \&na Ta 0 Ta current Ta compat 724.It Sx \&nf Ta 0 Ta current Ta compat 725.It Sx \&sp Ta 1 Ta current Ta compat 726.El 727.Pp 728Macros marked as 729.Qq compat 730are included for compatibility with the significant corpus of existing 731manuals that mix dialects of roff. 732These macros should not be used for portable 733.Nm 734manuals. 735.Ss Block Macros 736Block macros comprise a head and body. 737As with in-line macros, the head is scoped to the current line and, in 738one circumstance, the next line (the next-line stipulations as in 739.Sx Line Macros 740apply here as well). 741.Pp 742The syntax is as follows: 743.Bd -literal -offset indent 744\&.YO \(lBhead...\(rB 745\(lBhead...\(rB 746\(lBbody...\(rB 747.Ed 748.Pp 749The closure of body scope may be to the section, where a macro is closed 750by 751.Sx \&SH ; 752sub-section, closed by a section or 753.Sx \&SS ; 754part, closed by a section, sub-section, or 755.Sx \&RE ; 756or paragraph, closed by a section, sub-section, part, 757.Sx \&HP , 758.Sx \&IP , 759.Sx \&LP , 760.Sx \&P , 761.Sx \&PP , 762or 763.Sx \&TP . 764No closure refers to an explicit block closing macro. 765.Pp 766As a rule, block macros may not be nested; thus, calling a block macro 767while another block macro scope is open, and the open scope is not 768implicitly closed, is syntactically incorrect. 769.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent 770.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes 771.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \& 772.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \& 773.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \& 774.It Sx \&P Ta 0 Ta current Ta paragraph Ta \& 775.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \& 776.It Sx \&RE Ta 0 Ta current Ta none Ta compat 777.It Sx \&RS Ta 1 Ta current Ta part Ta compat 778.It Sx \&SH Ta >0 Ta next-line Ta section Ta \& 779.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \& 780.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \& 781.El 782.Pp 783Macros marked 784.Qq compat 785are as mentioned in 786.Sx Line Macros . 787.Pp 788If a block macro is next-line scoped, it may only be followed by in-line 789macros for decorating text. 790.Ss Font handling 791In 792.Nm 793documents, both 794.Sx Physical markup 795macros and 796.Xr roff 7 797.Ql \ef 798font escape sequences can be used to choose fonts. 799In text lines, the effect of manual font selection by escape sequences 800only lasts until the next macro invocation; in macro lines, it only lasts 801until the end of the macro scope. 802Note that macros like 803.Sx \&BR 804open and close a font scope for each argument. 805.Sh COMPATIBILITY 806This section documents areas of questionable portability between 807implementations of the 808.Nm 809language. 810.Pp 811.Bl -dash -compact 812.It 813Do not depend on 814.Sx \&SH 815or 816.Sx \&SS 817to close out a literal context opened with 818.Sx \&nf . 819This behaviour may not be portable. 820.It 821In quoted literals, GNU troff allowed pair-wise double-quotes to produce 822a standalone double-quote in formatted output. 823It is not known whether this behaviour is exhibited by other formatters. 824.It 825troff suppresses a newline before 826.Sq \(aq 827macro output; in mandoc, it is an alias for the standard 828.Sq \&. 829control character. 830.It 831The 832.Sq \eh 833.Pq horizontal position , 834.Sq \ev 835.Pq vertical position , 836.Sq \em 837.Pq text colour , 838.Sq \eM 839.Pq text filling colour , 840.Sq \ez 841.Pq zero-length character , 842.Sq \ew 843.Pq string length , 844.Sq \ek 845.Pq horizontal position marker , 846.Sq \eo 847.Pq text overstrike , 848and 849.Sq \es 850.Pq text size 851escape sequences are all discarded in mandoc. 852.It 853The 854.Sq \ef 855scaling unit is accepted by mandoc, but rendered as the default unit. 856.It 857The 858.Sx \&sp 859macro does not accept negative values in mandoc. 860In GNU troff, this would result in strange behaviour. 861.It 862In page header lines, GNU troff versions up to and including 1.21 863only print 864.Ar volume 865names explicitly specified in the 866.Sx \&TH 867macro; mandoc and newer groff print the default volume name 868corresponding to the 869.Ar section 870number when no 871.Ar volume 872is given, like in 873.Xr mdoc 7 . 874.El 875.Pp 876The 877.Sx OP 878macro is part of the extended 879.Nm 880macro set, and may not be portable to non-GNU troff implementations. 881.Sh SEE ALSO 882.Xr man 1 , 883.Xr mandoc 1 , 884.Xr eqn 7 , 885.Xr mandoc_char 7 , 886.Xr mdoc 7 , 887.Xr roff 7 , 888.Xr tbl 7 889.Sh HISTORY 890The 891.Nm 892language first appeared as a macro package for the roff typesetting 893system in 894.At v7 . 895It was later rewritten by James Clark as a macro package for groff. 896Eric S. Raymond wrote the extended 897.Nm 898macros for groff in 2007. 899The stand-alone implementation that is part of the 900.Xr mandoc 1 901utility written by Kristaps Dzonsons appeared in 902.Ox 4.6 . 903.Sh AUTHORS 904This 905.Nm 906reference was written by 907.An Kristaps Dzonsons , 908.Mt kristaps@bsd.lv . 909.Sh CAVEATS 910Do not use this language. 911Use 912.Xr mdoc 7 , 913instead. 914