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