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