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