1.\" $OpenBSD: man.7,v 1.53 2018/12/16 02:20:26 schwarze Exp $ 2.\" 3.\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2011-2015, 2017, 2018 Ingo Schwarze <schwarze@openbsd.org> 5.\" Copyright (c) 2017 Anthony Bentley <bentley@openbsd.org> 6.\" Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org> 7.\" 8.\" Permission to use, copy, modify, and distribute this software for any 9.\" purpose with or without fee is hereby granted, provided that the above 10.\" copyright notice and this permission notice appear in all copies. 11.\" 12.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 13.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 14.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 15.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 16.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 17.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 18.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 19.\" 20.Dd $Mdocdate: December 16 2018 $ 21.Dt MAN 7 22.Os 23.Sh NAME 24.Nm man 25.Nd legacy formatting language for manual pages 26.Sh DESCRIPTION 27The 28.Nm man 29language was the standard formatting language for 30.At 31manual pages from 1979 to 1989. 32Do not use it to write new manual pages: it is a purely presentational 33language and lacks support for semantic markup. 34Use the 35.Xr mdoc 7 36language, instead. 37.Pp 38In a 39.Nm 40document, lines beginning with the control character 41.Sq \&. 42are called 43.Dq macro lines . 44The first word is the macro name. 45It usually consists of two capital letters. 46For a list of portable macros, see 47.Sx MACRO OVERVIEW . 48The words following the macro name are arguments to the macro. 49.Pp 50Lines not beginning with the control character are called 51.Dq text lines . 52They provide free-form text to be printed; the formatting of the text 53depends on the respective processing context: 54.Bd -literal -offset indent 55\&.SH Macro lines change control state. 56Text lines are interpreted within the current state. 57.Ed 58.Pp 59Many aspects of the basic syntax of the 60.Nm 61language are based on the 62.Xr roff 7 63language; see the 64.Em LANGUAGE SYNTAX 65and 66.Em MACRO SYNTAX 67sections in the 68.Xr roff 7 69manual for details, in particular regarding 70comments, escape sequences, whitespace, and quoting. 71.Pp 72Each 73.Nm 74document starts with the 75.Sx \&TH 76macro specifying the document's name and section, followed by the 77.Sx NAME 78section formatted as follows: 79.Bd -literal -offset indent 80\&.TH PROGNAME 1 1979-01-10 81\&.SH NAME 82\efBprogname\efR \e(en one line about what it does 83.Ed 84.Sh MACRO OVERVIEW 85This overview is sorted such that macros of similar purpose are listed 86together. 87Deprecated and non-portable macros are not included in the overview, 88but can be found in the alphabetical reference below. 89.Ss Page header and footer meta-data 90.Bl -column "RS, RE" description 91.It Sx TH Ta set the title: Ar name section date Op Ar source Op Ar volume 92.It Sx AT Ta display AT&T UNIX version in the page footer (<= 1 argument) 93.It Sx UC Ta display BSD version in the page footer (<= 1 argument) 94.El 95.Ss Sections and paragraphs 96.Bl -column "RS, RE" description 97.It Sx SH Ta section header (one line) 98.It Sx SS Ta subsection header (one line) 99.It Sx PP Ta start an undecorated paragraph (no arguments) 100.It Sx RS , RE Ta reset the left margin: Op Ar width 101.It Sx IP Ta indented paragraph: Op Ar head Op Ar width 102.It Sx TP Ta tagged paragraph: Op Ar width 103.It Sx PD Ta set vertical paragraph distance: Op Ar height 104.It Sx fi , nf Ta fill mode and no-fill mode (no arguments) 105.It Sx in Ta additional indent: Op Ar width 106.El 107.Ss Physical markup 108.Bl -column "RS, RE" description 109.It Sx B Ta boldface font 110.It Sx I Ta italic font 111.It Sx SB Ta small boldface font 112.It Sx SM Ta small roman font 113.It Sx BI Ta alternate between boldface and italic fonts 114.It Sx BR Ta alternate between boldface and roman fonts 115.It Sx IB Ta alternate between italic and boldface fonts 116.It Sx IR Ta alternate between italic and roman fonts 117.It Sx RB Ta alternate between roman and boldface fonts 118.It Sx RI Ta alternate between roman and italic fonts 119.El 120.Sh MACRO REFERENCE 121This section is a canonical reference to all macros, arranged 122alphabetically. 123For the scoping of individual macros, see 124.Sx MACRO SYNTAX . 125.Ss \&AT 126Sets the volume for the footer for compatibility with man pages from 127.At 128releases. 129The optional arguments specify which release it is from. 130.Ss \&B 131Text is rendered in bold face. 132.Ss \&BI 133Text is rendered alternately in bold face and italic. 134Thus, 135.Sq .BI this word and that 136causes 137.Sq this 138and 139.Sq and 140to render in bold face, while 141.Sq word 142and 143.Sq that 144render in italics. 145Whitespace between arguments is omitted in output. 146.Pp 147Example: 148.Pp 149.Dl \&.BI bold italic bold italic 150.Ss \&BR 151Text is rendered alternately in bold face and roman (the default font). 152Whitespace between arguments is omitted in output. 153See also 154.Sx \&BI . 155.Ss \&DT 156Restore the default tabulator positions. 157They are at intervals of 0.5 inches. 158This has no effect unless the tabulator positions were changed with the 159.Xr roff 7 160.Ic \&ta 161request. 162.Ss \&EE 163This is a non-standard GNU extension. 164In 165.Xr mandoc 1 , 166it does the same as 167.Sx \&fi . 168.Ss \&EX 169This is a non-standard GNU extension. 170In 171.Xr mandoc 1 , 172it does the same as 173.Sx \&nf . 174.Ss \&HP 175Begin a paragraph whose initial output line is left-justified, but 176subsequent output lines are indented, with the following syntax: 177.Bd -filled -offset indent 178.Pf \. Sx \&HP 179.Op Ar width 180.Ed 181.Pp 182The 183.Ar width 184argument is a 185.Xr roff 7 186scaling width. 187If specified, it's saved for later paragraph left margins; 188if unspecified, the saved or default width is used. 189.Pp 190This macro is portable, but deprecated 191because it has no good representation in HTML output, 192usually ending up indistinguishable from 193.Sx \&PP . 194.Ss \&I 195Text is rendered in italics. 196.Ss \&IB 197Text is rendered alternately in italics and bold face. 198Whitespace between arguments is omitted in output. 199See also 200.Sx \&BI . 201.Ss \&IP 202Begin an indented paragraph with the following syntax: 203.Bd -filled -offset indent 204.Pf \. Sx \&IP 205.Op Ar head Op Ar width 206.Ed 207.Pp 208The 209.Ar width 210argument is a 211.Xr roff 7 212scaling width defining the left margin. 213It's saved for later paragraph left-margins; if unspecified, the saved or 214default width is used. 215.Pp 216The 217.Ar head 218argument is used as a leading term, flushed to the left margin. 219This is useful for bulleted paragraphs and so on. 220.Ss \&IR 221Text is rendered alternately in italics and roman (the default font). 222Whitespace between arguments is omitted in output. 223See also 224.Sx \&BI . 225.Ss \&LP 226A synonym for 227.Sx \&PP . 228.Ss \&ME 229End a mailto block started with 230.Sx \&MT . 231This is a non-standard GNU extension. 232.Ss \&MT 233Begin a mailto block. 234This is a non-standard GNU extension. 235It has the following syntax: 236.Bd -literal -offset indent 237.Pf \. Sx \&MT Ar address 238link description to be shown 239.Pf \. Sx ME 240.Ed 241.Ss \&OP 242Optional command-line argument. 243This is a non-standard GNU extension. 244It has the following syntax: 245.Bd -filled -offset indent 246.Pf \. Sx \&OP 247.Ar key Op Ar value 248.Ed 249.Pp 250The 251.Ar key 252is usually a command-line flag and 253.Ar value 254its argument. 255.Ss \&P 256A synonym for 257.Sx \&PP . 258.Ss \&PD 259Specify the vertical space to be inserted before each new paragraph. 260.br 261The syntax is as follows: 262.Bd -filled -offset indent 263.Pf \. Sx \&PD 264.Op Ar height 265.Ed 266.Pp 267The 268.Ar height 269argument is a 270.Xr roff 7 271scaling width. 272It defaults to 273.Cm 1v . 274If the unit is omitted, 275.Cm v 276is assumed. 277.Pp 278This macro affects the spacing before any subsequent instances of 279.Sx \&HP , 280.Sx \&IP , 281.Sx \&LP , 282.Sx \&P , 283.Sx \&PP , 284.Sx \&SH , 285.Sx \&SS , 286.Sx \&SY , 287and 288.Sx \&TP . 289.Ss \&PP 290Begin an undecorated paragraph. 291The scope of a paragraph is closed by a subsequent paragraph, 292sub-section, section, or end of file. 293The saved paragraph left-margin width is reset to the default. 294.Ss \&RB 295Text is rendered alternately in roman (the default font) and bold face. 296Whitespace between arguments is omitted in output. 297See also 298.Sx \&BI . 299.Ss \&RE 300Explicitly close out the scope of a prior 301.Sx \&RS . 302The default left margin is restored to the state before that 303.Sx \&RS 304invocation. 305.Pp 306The syntax is as follows: 307.Bd -filled -offset indent 308.Pf \. Sx \&RE 309.Op Ar level 310.Ed 311.Pp 312Without an argument, the most recent 313.Sx \&RS 314block is closed out. 315If 316.Ar level 317is 1, all open 318.Sx \&RS 319blocks are closed out. 320Otherwise, 321.Ar level No \(mi 1 322nested 323.Sx \&RS 324blocks remain open. 325.Ss \&RI 326Text is rendered alternately in roman (the default font) and italics. 327Whitespace between arguments is omitted in output. 328See also 329.Sx \&BI . 330.Ss \&RS 331Temporarily reset the default left margin. 332This has the following syntax: 333.Bd -filled -offset indent 334.Pf \. Sx \&RS 335.Op Ar width 336.Ed 337.Pp 338The 339.Ar width 340argument is a 341.Xr roff 7 342scaling width. 343If not specified, the saved or default width is used. 344.Pp 345See also 346.Sx \&RE . 347.Ss \&SB 348Text is rendered in small size (one point smaller than the default font) 349bold face. 350.Ss \&SH 351Begin a section. 352The scope of a section is only closed by another section or the end of 353file. 354The paragraph left-margin width is reset to the default. 355.Ss \&SM 356Text is rendered in small size (one point smaller than the default 357font). 358.Ss \&SS 359Begin a sub-section. 360The scope of a sub-section is closed by a subsequent sub-section, 361section, or end of file. 362The paragraph left-margin width is reset to the default. 363.Ss \&SY 364Begin a synopsis block with the following syntax: 365.Bd -unfilled -offset indent 366.Pf \. Sx \&SY Ar command 367.Ar arguments 368.Pf \. Sx \&YS 369.Ed 370.Pp 371This is a non-standard GNU extension 372and very rarely used even in GNU manual pages. 373Formatting is similar to 374.Sx \&IP . 375.Ss \&TH 376Set the name of the manual page for use in the page header 377and footer with the following syntax: 378.Bd -filled -offset indent 379.Pf \. Sx \&TH 380.Ar name section date 381.Op Ar source Op Ar volume 382.Ed 383.Pp 384Conventionally, the document 385.Ar name 386is given in all caps. 387The 388.Ar section 389is usually a single digit, in a few cases followed by a letter. 390The recommended 391.Ar date 392format is 393.Sy YYYY-MM-DD 394as specified in the ISO-8601 standard; 395if the argument does not conform, it is printed verbatim. 396If the 397.Ar date 398is empty or not specified, the current date is used. 399The optional 400.Ar source 401string specifies the organisation providing the utility. 402When unspecified, 403.Xr mandoc 1 404uses its 405.Fl Ios 406argument. 407The 408.Ar volume 409string replaces the default volume title of the 410.Ar section . 411.Pp 412Examples: 413.Pp 414.Dl \&.TH CVS 5 "1992-02-12" GNU 415.Ss \&TP 416Begin a paragraph where the head, if exceeding the indentation width, is 417followed by a newline; if not, the body follows on the same line after 418advancing to the indentation width. 419Subsequent output lines are indented. 420The syntax is as follows: 421.Bd -unfilled -offset indent 422.Pf \. Sx \&TP Op Ar width 423.Ar head No \e" one line 424.Ar body 425.Ed 426.Pp 427The 428.Ar width 429argument is a 430.Xr roff 7 431scaling width. 432If specified, it's saved for later paragraph left-margins; if 433unspecified, the saved or default width is used. 434.Ss \&TQ 435Like 436.Sx \&TP , 437except that no vertical spacing is inserted before the paragraph. 438This is a non-standard GNU extension 439and very rarely used even in GNU manual pages. 440.Ss \&UC 441Sets the volume for the footer for compatibility with man pages from 442.Bx 443releases. 444The optional first argument specifies which release it is from. 445.Ss \&UE 446End a uniform resource identifier block started with 447.Sx \&UR . 448This is a non-standard GNU extension. 449.Ss \&UR 450Begin a uniform resource identifier block. 451This is a non-standard GNU extension. 452It has the following syntax: 453.Bd -literal -offset indent 454.Pf \. Sx \&UR Ar uri 455link description to be shown 456.Pf \. Sx UE 457.Ed 458.Ss \&YS 459End a synopsis block started with 460.Sx \&SY . 461This is a non-standard GNU extension. 462.Ss \&fi 463End literal mode started with 464.Sx \&nf . 465.Ss \&in 466Indent relative to the current indentation: 467.Pp 468.D1 Pf \. Sx \&in Op Ar width 469.Pp 470If 471.Ar width 472is signed, the new offset is relative. 473Otherwise, it is absolute. 474This value is reset upon the next paragraph, section, or sub-section. 475.Ss \&nf 476Begin literal mode: all subsequent free-form lines have their end of 477line boundaries preserved. 478May be ended by 479.Sx \&fi . 480Literal mode is implicitly ended by 481.Sx \&SH 482or 483.Sx \&SS . 484.Sh MACRO SYNTAX 485The 486.Nm 487macros are classified by scope: line scope or block scope. 488Line macros are only scoped to the current line (and, in some 489situations, the subsequent line). 490Block macros are scoped to the current line and subsequent lines until 491closed by another block macro. 492.Ss Line Macros 493Line macros are generally scoped to the current line, with the body 494consisting of zero or more arguments. 495If a macro is scoped to the next line and the line arguments are empty, 496the next line, which must be text, is used instead. 497Thus: 498.Bd -literal -offset indent 499\&.I 500foo 501.Ed 502.Pp 503is equivalent to 504.Sq \&.I foo . 505If next-line macros are invoked consecutively, only the last is used. 506If a next-line macro is followed by a non-next-line macro, an error is 507raised. 508.Pp 509The syntax is as follows: 510.Bd -literal -offset indent 511\&.YO \(lBbody...\(rB 512\(lBbody...\(rB 513.Ed 514.Bl -column "MacroX" "ArgumentsX" "ScopeXXXXX" "CompatX" -offset indent 515.It Em Macro Ta Em Arguments Ta Em Scope Ta Em Notes 516.It Sx \&AT Ta <=1 Ta current Ta \& 517.It Sx \&B Ta n Ta next-line Ta \& 518.It Sx \&BI Ta n Ta current Ta \& 519.It Sx \&BR Ta n Ta current Ta \& 520.It Sx \&DT Ta 0 Ta current Ta \& 521.It Sx \&EE Ta 0 Ta current Ta GNU 522.It Sx \&EX Ta 0 Ta current Ta GNU 523.It Sx \&I Ta n Ta next-line Ta \& 524.It Sx \&IB Ta n Ta current Ta \& 525.It Sx \&IR Ta n Ta current Ta \& 526.It Sx \&OP Ta >=1 Ta current Ta GNU 527.It Sx \&PD Ta 1 Ta current Ta \& 528.It Sx \&RB Ta n Ta current Ta \& 529.It Sx \&RI Ta n Ta current Ta \& 530.It Sx \&SB Ta n Ta next-line Ta \& 531.It Sx \&SM Ta n Ta next-line Ta \& 532.It Sx \&TH Ta >1, <6 Ta current Ta \& 533.It Sx \&UC Ta <=1 Ta current Ta \& 534.It Sx \&fi Ta 0 Ta current Ta Xr roff 7 535.It Sx \&in Ta 1 Ta current Ta Xr roff 7 536.It Sx \&nf Ta 0 Ta current Ta Xr roff 7 537.El 538.Ss Block Macros 539Block macros comprise a head and body. 540As with in-line macros, the head is scoped to the current line and, in 541one circumstance, the next line (the next-line stipulations as in 542.Sx Line Macros 543apply here as well). 544.Pp 545The syntax is as follows: 546.Bd -literal -offset indent 547\&.YO \(lBhead...\(rB 548\(lBhead...\(rB 549\(lBbody...\(rB 550.Ed 551.Pp 552The closure of body scope may be to the section, where a macro is closed 553by 554.Sx \&SH ; 555sub-section, closed by a section or 556.Sx \&SS ; 557or paragraph, closed by a section, sub-section, 558.Sx \&HP , 559.Sx \&IP , 560.Sx \&LP , 561.Sx \&P , 562.Sx \&PP , 563.Sx \&RE , 564.Sx \&SY , 565or 566.Sx \&TP . 567No closure refers to an explicit block closing macro. 568.Pp 569As a rule, block macros may not be nested; thus, calling a block macro 570while another block macro scope is open, and the open scope is not 571implicitly closed, is syntactically incorrect. 572.Bl -column "MacroX" "ArgumentsX" "Head ScopeX" "sub-sectionX" "compatX" -offset indent 573.It Em Macro Ta Em Arguments Ta Em Head Scope Ta Em Body Scope Ta Em Notes 574.It Sx \&HP Ta <2 Ta current Ta paragraph Ta \& 575.It Sx \&IP Ta <3 Ta current Ta paragraph Ta \& 576.It Sx \&LP Ta 0 Ta current Ta paragraph Ta \& 577.It Sx \&ME Ta 0 Ta none Ta none Ta GNU 578.It Sx \&MT Ta 1 Ta current Ta to \&ME Ta GNU 579.It Sx \&P Ta 0 Ta current Ta paragraph Ta \& 580.It Sx \&PP Ta 0 Ta current Ta paragraph Ta \& 581.It Sx \&RE Ta <=1 Ta current Ta none Ta \& 582.It Sx \&RS Ta 1 Ta current Ta to \&RE Ta \& 583.It Sx \&SH Ta >0 Ta next-line Ta section Ta \& 584.It Sx \&SS Ta >0 Ta next-line Ta sub-section Ta \& 585.It Sx \&SY Ta 1 Ta current Ta to \&YS Ta GNU 586.It Sx \&TP Ta n Ta next-line Ta paragraph Ta \& 587.It Sx \&TQ Ta n Ta next-line Ta paragraph Ta GNU 588.It Sx \&UE Ta 0 Ta current Ta none Ta GNU 589.It Sx \&UR Ta 1 Ta current Ta part Ta GNU 590.It Sx \&YS Ta 0 Ta none Ta none Ta GNU 591.El 592.Pp 593If a block macro is next-line scoped, it may only be followed by in-line 594macros for decorating text. 595.Ss Font handling 596In 597.Nm 598documents, both 599.Sx Physical markup 600macros and 601.Xr roff 7 602.Ql \ef 603font escape sequences can be used to choose fonts. 604In text lines, the effect of manual font selection by escape sequences 605only lasts until the next macro invocation; in macro lines, it only lasts 606until the end of the macro scope. 607Note that macros like 608.Sx \&BR 609open and close a font scope for each argument. 610.Sh SEE ALSO 611.Xr man 1 , 612.Xr mandoc 1 , 613.Xr eqn 7 , 614.Xr mandoc_char 7 , 615.Xr mdoc 7 , 616.Xr roff 7 , 617.Xr tbl 7 618.Sh HISTORY 619The 620.Nm 621language first appeared as a macro package for the roff typesetting 622system in 623.At v7 . 624It was later rewritten by James Clark as a macro package for groff. 625Eric S. Raymond wrote the extended 626.Nm 627macros for groff in 2007. 628The stand-alone implementation that is part of the 629.Xr mandoc 1 630utility written by Kristaps Dzonsons appeared in 631.Ox 4.6 . 632.Sh AUTHORS 633This 634.Nm 635reference was written by 636.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 637