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