1.\" $Id: roff.7,v 1.55 2014/07/07 11:35:06 schwarze Exp $ 2.\" 3.\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2010, 2011, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: July 7 2014 $ 19.Dt ROFF 7 20.Os 21.Sh NAME 22.Nm roff 23.Nd roff language reference for mandoc 24.Sh DESCRIPTION 25The 26.Nm roff 27language is a general purpose text formatting language. 28Since traditional implementations of the 29.Xr mdoc 7 30and 31.Xr man 7 32manual formatting languages are based on it, 33many real-world manuals use small numbers of 34.Nm 35requests and escape sequences intermixed with their 36.Xr mdoc 7 37or 38.Xr man 7 39code. 40To properly format such manuals, the 41.Xr mandoc 1 42utility supports a tiny subset of 43.Nm 44requests and escapes. 45Only these requests and escapes supported by 46.Xr mandoc 1 47are documented in the present manual, 48together with the basic language syntax shared by 49.Nm , 50.Xr mdoc 7 , 51and 52.Xr man 7 . 53For complete 54.Nm 55manuals, consult the 56.Sx SEE ALSO 57section. 58.Pp 59Input lines beginning with the control character 60.Sq \&. 61are parsed for requests and macros. 62Such lines are called 63.Dq request lines 64or 65.Dq macro lines , 66respectively. 67Requests change the processing state and manipulate the formatting; 68some macros also define the document structure and produce formatted 69output. 70The single quote 71.Pq Qq \(aq 72is accepted as an alternative control character, 73treated by 74.Xr mandoc 1 75just like 76.Ql \&. 77.Pp 78Lines not beginning with control characters are called 79.Dq text lines . 80They provide free-form text to be printed; the formatting of the text 81depends on the respective processing context. 82.Sh LANGUAGE SYNTAX 83.Nm 84documents may contain only graphable 7-bit ASCII characters, the space 85character, and, in certain circumstances, the tab character. 86The backslash character 87.Sq \e 88indicates the start of an escape sequence, used for example for 89.Sx Comments , 90.Sx Special Characters , 91.Sx Predefined Strings , 92and 93user-defined strings defined using the 94.Sx ds 95request. 96For a listing of escape sequences, consult the 97.Sx ESCAPE SEQUENCE REFERENCE 98below. 99.Ss Comments 100Text following an escaped double-quote 101.Sq \e\(dq , 102whether in a request, macro, or text line, is ignored to the end of the line. 103A request line beginning with a control character and comment escape 104.Sq \&.\e\(dq 105is also ignored. 106Furthermore, request lines with only a control character and optional 107trailing whitespace are stripped from input. 108.Pp 109Examples: 110.Bd -literal -offset indent -compact 111\&.\e\(dq This is a comment line. 112\&.\e\(dq The next line is ignored: 113\&. 114\&.Sh EXAMPLES \e\(dq This is a comment, too. 115\&example text \e\(dq And so is this. 116.Ed 117.Ss Special Characters 118Special characters are used to encode special glyphs and are rendered 119differently across output media. 120They may occur in request, macro, and text lines. 121Sequences begin with the escape character 122.Sq \e 123followed by either an open-parenthesis 124.Sq \&( 125for two-character sequences; an open-bracket 126.Sq \&[ 127for n-character sequences (terminated at a close-bracket 128.Sq \&] ) ; 129or a single one character sequence. 130.Pp 131Examples: 132.Bl -tag -width Ds -offset indent -compact 133.It Li \e(em 134Two-letter em dash escape. 135.It Li \ee 136One-letter backslash escape. 137.El 138.Pp 139See 140.Xr mandoc_char 7 141for a complete list. 142.Ss Text Decoration 143Terms may be text-decorated using the 144.Sq \ef 145escape followed by an indicator: B (bold), I (italic), R (regular), or P 146(revert to previous mode). 147A numerical representation 3, 2, or 1 (bold, italic, and regular, 148respectively) may be used instead. 149The indicator or numerical representative may be preceded by C 150(constant-width), which is ignored. 151.Pp 152The two-character indicator 153.Sq BI 154requests a font that is both bold and italic. 155It may not be portable to old roff implementations. 156.Pp 157Examples: 158.Bl -tag -width Ds -offset indent -compact 159.It Li \efBbold\efR 160Write in \fBbold\fP, then switch to regular font mode. 161.It Li \efIitalic\efP 162Write in \fIitalic\fP, then return to previous font mode. 163.It Li \ef(BIbold italic\efP 164Write in \f(BIbold italic\fP, then return to previous font mode. 165.El 166.Pp 167Text decoration is 168.Em not 169recommended for 170.Xr mdoc 7 , 171which encourages semantic annotation. 172.Ss Predefined Strings 173Predefined strings, like 174.Sx Special Characters , 175mark special output glyphs. 176Predefined strings are escaped with the slash-asterisk, 177.Sq \e* : 178single-character 179.Sq \e*X , 180two-character 181.Sq \e*(XX , 182and N-character 183.Sq \e*[N] . 184.Pp 185Examples: 186.Bl -tag -width Ds -offset indent -compact 187.It Li \e*(Am 188Two-letter ampersand predefined string. 189.It Li \e*q 190One-letter double-quote predefined string. 191.El 192.Pp 193Predefined strings are not recommended for use, 194as they differ across implementations. 195Those supported by 196.Xr mandoc 1 197are listed in 198.Xr mandoc_char 7 . 199Manuals using these predefined strings are almost certainly not portable. 200.Ss Whitespace 201Whitespace consists of the space character. 202In text lines, whitespace is preserved within a line. 203In request and macro lines, whitespace delimits arguments and is discarded. 204.Pp 205Unescaped trailing spaces are stripped from text line input unless in a 206literal context. 207In general, trailing whitespace on any input line is discouraged for 208reasons of portability. 209In the rare case that a blank character is needed at the end of an 210input line, it may be forced by 211.Sq \e\ \e& . 212.Pp 213Literal space characters can be produced in the output 214using escape sequences. 215In macro lines, they can also be included in arguments using quotation; see 216.Sx MACRO SYNTAX 217for details. 218.Pp 219Blank text lines, which may include whitespace, are only permitted 220within literal contexts. 221If the first character of a text line is a space, that line is printed 222with a leading newline. 223.Ss Scaling Widths 224Many requests and macros support scaled widths for their arguments. 225The syntax for a scaled width is 226.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , 227where a decimal must be preceded or followed by at least one digit. 228Negative numbers, while accepted, are truncated to zero. 229.Pp 230The following scaling units are accepted: 231.Pp 232.Bl -tag -width Ds -offset indent -compact 233.It c 234centimetre 235.It i 236inch 237.It P 238pica (~1/6 inch) 239.It p 240point (~1/72 inch) 241.It f 242synonym for 243.Sq u 244.It v 245default vertical span 246.It m 247width of rendered 248.Sq m 249.Pq em 250character 251.It n 252width of rendered 253.Sq n 254.Pq en 255character 256.It u 257default horizontal span 258.It M 259mini-em (~1/100 em) 260.El 261.Pp 262Using anything other than 263.Sq m , 264.Sq n , 265.Sq u , 266or 267.Sq v 268is necessarily non-portable across output media. 269See 270.Sx COMPATIBILITY . 271.Pp 272If a scaling unit is not provided, the numerical value is interpreted 273under the default rules of 274.Sq v 275for vertical spaces and 276.Sq u 277for horizontal ones. 278.Pp 279Examples: 280.Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact 281.It Li \&.Bl -tag -width 2i 282two-inch tagged list indentation in 283.Xr mdoc 7 284.It Li \&.HP 2i 285two-inch tagged list indentation in 286.Xr man 7 287.It Li \&.sp 2v 288two vertical spaces 289.El 290.Ss Sentence Spacing 291Each sentence should terminate at the end of an input line. 292By doing this, a formatter will be able to apply the proper amount of 293spacing after the end of sentence (unescaped) period, exclamation mark, 294or question mark followed by zero or more non-sentence closing 295delimiters 296.Po 297.Sq \&) , 298.Sq \&] , 299.Sq \&' , 300.Sq \&" 301.Pc . 302.Pp 303The proper spacing is also intelligently preserved if a sentence ends at 304the boundary of a macro line. 305.Pp 306Examples: 307.Bd -literal -offset indent -compact 308Do not end sentences mid-line like this. Instead, 309end a sentence like this. 310A macro would end like this: 311\&.Xr mandoc 1 \&. 312.Ed 313.Sh REQUEST SYNTAX 314A request or macro line consists of: 315.Pp 316.Bl -enum -compact 317.It 318the control character 319.Sq \&. 320or 321.Sq \(aq 322at the beginning of the line, 323.It 324optionally an arbitrary amount of whitespace, 325.It 326the name of the request or the macro, which is one word of arbitrary 327length, terminated by whitespace, 328.It 329and zero or more arguments delimited by whitespace. 330.El 331.Pp 332Thus, the following request lines are all equivalent: 333.Bd -literal -offset indent 334\&.ig end 335\&.ig end 336\&. ig end 337.Ed 338.Sh MACRO SYNTAX 339Macros are provided by the 340.Xr mdoc 7 341and 342.Xr man 7 343languages and can be defined by the 344.Sx \&de 345request. 346When called, they follow the same syntax as requests, except that 347macro arguments may optionally be quoted by enclosing them 348in double quote characters 349.Pq Sq \(dq . 350Quoted text, even if it contains whitespace or would cause 351a macro invocation when unquoted, is always considered literal text. 352Inside quoted text, pairs of double quote characters 353.Pq Sq Qq 354resolve to single double quote characters. 355.Pp 356To be recognised as the beginning of a quoted argument, the opening 357quote character must be preceded by a space character. 358A quoted argument extends to the next double quote character that is not 359part of a pair, or to the end of the input line, whichever comes earlier. 360Leaving out the terminating double quote character at the end of the line 361is discouraged. 362For clarity, if more arguments follow on the same input line, 363it is recommended to follow the terminating double quote character 364by a space character; in case the next character after the terminating 365double quote character is anything else, it is regarded as the beginning 366of the next, unquoted argument. 367.Pp 368Both in quoted and unquoted arguments, pairs of backslashes 369.Pq Sq \e\e 370resolve to single backslashes. 371In unquoted arguments, space characters can alternatively be included 372by preceding them with a backslash 373.Pq Sq \e\~ , 374but quoting is usually better for clarity. 375.Pp 376Examples: 377.Bl -tag -width Ds -offset indent -compact 378.It Li .Fn strlen \(dqconst char *s\(dq 379Group arguments 380.Qq const char *s 381into one function argument. 382If unspecified, 383.Qq const , 384.Qq char , 385and 386.Qq *s 387would be considered separate arguments. 388.It Li .Op \(dqFl a\(dq 389Consider 390.Qq \&Fl a 391as literal text instead of a flag macro. 392.El 393.Sh REQUEST REFERENCE 394The 395.Xr mandoc 1 396.Nm 397parser recognises the following requests. 398Note that the 399.Nm 400language defines many more requests not implemented in 401.Xr mandoc 1 . 402.Ss \&ad 403Set line adjustment mode. 404This line-scoped request is intended to have one argument to select 405normal, left, right, or centre adjustment for subsequent text. 406Currently, it is ignored including its arguments, 407and the number of arguments is not checked. 408.Ss \&am 409Append to a macro definition. 410The syntax of this request is the same as that of 411.Sx \&de . 412.Ss \&ami 413Append to a macro definition, specifying the macro name indirectly. 414The syntax of this request is the same as that of 415.Sx \&dei . 416.Ss \&am1 417Append to a macro definition, switching roff compatibility mode off 418during macro execution. 419The syntax of this request is the same as that of 420.Sx \&de1 . 421Since 422.Xr mandoc 1 423does not implement 424.Nm 425compatibility mode at all, it handles this request as an alias for 426.Sx \&am . 427.Ss \&as 428Append to a user-defined string. 429The syntax of this request is the same as that of 430.Sx \&ds . 431If a user-defined string with the specified name does not yet exist, 432it is set to the empty string before appending. 433.Ss \&cc 434Changes the control character. 435Its syntax is as follows: 436.Bd -literal -offset indent 437.Pf . Cm \&cc Op Ar c 438.Ed 439.Pp 440If 441.Ar c 442is not specified, the control character is reset to 443.Sq \&. . 444Trailing characters are ignored. 445.Ss \&ce 446Center some lines. 447This line-scoped request is intended to take one integer argument, 448specifying how many lines to center. 449Currently, it is ignored including its arguments, and the number 450of arguments is not checked. 451.Ss \&de 452Define a 453.Nm 454macro. 455Its syntax can be either 456.Bd -literal -offset indent 457.Pf . Cm \&de Ar name 458.Ar macro definition 459\&.. 460.Ed 461.Pp 462or 463.Bd -literal -offset indent 464.Pf . Cm \&de Ar name Ar end 465.Ar macro definition 466.Pf . Ar end 467.Ed 468.Pp 469Both forms define or redefine the macro 470.Ar name 471to represent the 472.Ar macro definition , 473which may consist of one or more input lines, including the newline 474characters terminating each line, optionally containing calls to 475.Nm 476requests, 477.Nm 478macros or high-level macros like 479.Xr man 7 480or 481.Xr mdoc 7 482macros, whichever applies to the document in question. 483.Pp 484Specifying a custom 485.Ar end 486macro works in the same way as for 487.Sx \&ig ; 488namely, the call to 489.Sq Pf . Ar end 490first ends the 491.Ar macro definition , 492and after that, it is also evaluated as a 493.Nm 494request or 495.Nm 496macro, but not as a high-level macro. 497.Pp 498The macro can be invoked later using the syntax 499.Pp 500.D1 Pf . Ar name Op Ar argument Op Ar argument ... 501.Pp 502Regarding argument parsing, see 503.Sx MACRO SYNTAX 504above. 505.Pp 506The line invoking the macro will be replaced 507in the input stream by the 508.Ar macro definition , 509replacing all occurrences of 510.No \e\e$ Ns Ar N , 511where 512.Ar N 513is a digit, by the 514.Ar N Ns th Ar argument . 515For example, 516.Bd -literal -offset indent 517\&.de ZN 518\efI\e^\e\e$1\e^\efP\e\e$2 519\&.. 520\&.ZN XtFree . 521.Ed 522.Pp 523produces 524.Pp 525.D1 \efI\e^XtFree\e^\efP. 526.Pp 527in the input stream, and thus in the output: \fI\^XtFree\^\fP. 528.Pp 529Since macros and user-defined strings share a common string table, 530defining a macro 531.Ar name 532clobbers the user-defined string 533.Ar name , 534and the 535.Ar macro definition 536can also be printed using the 537.Sq \e* 538string interpolation syntax described below 539.Sx ds , 540but this is rarely useful because every macro definition contains at least 541one explicit newline character. 542.Pp 543In order to prevent endless recursion, both groff and 544.Xr mandoc 1 545limit the stack depth for expanding macros and strings 546to a large, but finite number. 547Do not rely on the exact value of this limit. 548.Ss \&dei 549Define a 550.Nm 551macro, specifying the macro name indirectly. 552The syntax of this request is the same as that of 553.Sx \&de . 554The request 555.Pp 556.D1 Pf . Cm \&dei Ar name Op Ar end 557.Pp 558has the same effect as: 559.Pp 560.D1 Pf . Cm \&de No \e* Ns Bo Ar name Bc Op \e* Ns Bq Ar end 561.Ss \&de1 562Define a 563.Nm 564macro that will be executed with 565.Nm 566compatibility mode switched off during macro execution. 567This is a GNU extension not available in traditional 568.Nm 569implementations and not even in older versions of groff. 570Since 571.Xr mandoc 1 572does not implement 573.Nm 574compatibility mode at all, it handles this request as an alias for 575.Sx \&de . 576.Ss \&ds 577Define a user-defined string. 578Its syntax is as follows: 579.Pp 580.D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string 581.Pp 582The 583.Ar name 584and 585.Ar string 586arguments are space-separated. 587If the 588.Ar string 589begins with a double-quote character, that character will not be part 590of the string. 591All remaining characters on the input line form the 592.Ar string , 593including whitespace and double-quote characters, even trailing ones. 594.Pp 595The 596.Ar string 597can be interpolated into subsequent text by using 598.No \e* Ns Bq Ar name 599for a 600.Ar name 601of arbitrary length, or \e*(NN or \e*N if the length of 602.Ar name 603is two or one characters, respectively. 604Interpolation can be prevented by escaping the leading backslash; 605that is, an asterisk preceded by an even number of backslashes 606does not trigger string interpolation. 607.Pp 608Since user-defined strings and macros share a common string table, 609defining a string 610.Ar name 611clobbers the macro 612.Ar name , 613and the 614.Ar name 615used for defining a string can also be invoked as a macro, 616in which case the following input line will be appended to the 617.Ar string , 618forming a new input line passed to the 619.Nm 620parser. 621For example, 622.Bd -literal -offset indent 623\&.ds badidea .S 624\&.badidea 625H SYNOPSIS 626.Ed 627.Pp 628invokes the 629.Cm SH 630macro when used in a 631.Xr man 7 632document. 633Such abuse is of course strongly discouraged. 634.Ss \&el 635The 636.Qq else 637half of an if/else conditional. 638Pops a result off the stack of conditional evaluations pushed by 639.Sx \&ie 640and uses it as its conditional. 641If no stack entries are present (e.g., due to no prior 642.Sx \&ie 643calls) 644then false is assumed. 645The syntax of this request is similar to 646.Sx \&if 647except that the conditional is missing. 648.Ss \&EN 649End an equation block. 650See 651.Sx \&EQ . 652.Ss \&EQ 653Begin an equation block. 654See 655.Xr eqn 7 656for a description of the equation language. 657.Ss \&fam 658Change the font family. 659This line-scoped request is intended to have one argument specifying 660the font family to be selected. 661It is a groff extension, and currently, it is ignored including its 662arguments, and the number of arguments is not checked. 663.Ss \&ft 664Change the font. 665Its syntax is as follows: 666.Pp 667.D1 Pf . Cm \&ft Op Ar font 668.Pp 669The following 670.Ar font 671arguments are supported: 672.Bl -tag -width 4n -offset indent 673.It Cm B , BI , 3 , 4 674switches to 675.Sy bold 676font 677.It Cm I , 2 678switches to 679.Em underlined 680font 681.It Cm R , CW , 1 682switches to normal font 683.It Cm P No "or no argument" 684switches back to the previous font 685.El 686.Pp 687This request takes effect only locally, may be overridden by macros 688and escape sequences, and is only supported in 689.Xr man 7 690for now. 691.Ss \&hw 692Specify hyphenation points in words. 693This line-scoped request is currently ignored. 694.Ss \&hy 695Set automatic hyphenation mode. 696This line-scoped request is currently ignored. 697.Ss \&ie 698The 699.Qq if 700half of an if/else conditional. 701The result of the conditional is pushed into a stack used by subsequent 702invocations of 703.Sx \&el , 704which may be separated by any intervening input (or not exist at all). 705Its syntax is equivalent to 706.Sx \&if . 707.Ss \&if 708Begins a conditional. 709This request has the following syntax: 710.Bd -literal -offset indent 711\&.if COND BODY 712.Ed 713.Bd -literal -offset indent 714\&.if COND \e{BODY 715BODY...\e} 716.Ed 717.Bd -literal -offset indent 718\&.if COND \e{\e 719BODY... 720\&.\e} 721.Ed 722.Pp 723COND is a conditional statement. 724Currently, 725.Xr mandoc 1 726supports the following subset of roff conditionals: 727.Bl -bullet 728.It 729If 730.Sq \&! 731is prefixed to COND, the condition is logically inverted. 732.It 733If the first character of COND is 734.Sq n 735.Pq nroff mode 736or 737.Sq o 738.Pq odd page , 739COND evaluates to true. 740.It 741If the first character of COND is 742.Sq c 743.Pq character available , 744.Sq d 745.Pq string defined , 746.Sq e 747.Pq even page , 748.Sq r 749.Pq register accessed , 750or 751.Sq t 752.Pq troff mode , 753COND evaluates to false. 754.It 755If COND starts with a parenthesis or with an optionally signed 756integer number, it is evaluated according to the rules of 757.Sx Numerical expressions 758explained below. 759It evaluates to true if the the result is positive, 760or to false if the result is zero or negative. 761.It 762Otherwise, the first character of COND is regarded as a delimiter 763and COND evaluates to true if the string extending from its first 764to its second occurrence is equal to the string extending from its 765second to its third occurrence. 766.It 767If COND cannot be parsed, it evaluates to false. 768.El 769.Pp 770If a conditional is false, its children are not processed, but are 771syntactically interpreted to preserve the integrity of the input 772document. 773Thus, 774.Pp 775.D1 \&.if t .ig 776.Pp 777will discard the 778.Sq \&.ig , 779which may lead to interesting results, but 780.Pp 781.D1 \&.if t .if t \e{\e 782.Pp 783will continue to syntactically interpret to the block close of the final 784conditional. 785Sub-conditionals, in this case, obviously inherit the truth value of 786the parent. 787.Pp 788If the BODY section is begun by an escaped brace 789.Sq \e{ , 790scope continues until the end of the input line containing the 791matching closing-brace escape sequence 792.Sq \e} . 793If the BODY is not enclosed in braces, scope continues until 794the end of the line. 795If the COND is followed by a BODY on the same line, whether after a 796brace or not, then requests and macros 797.Em must 798begin with a control character. 799It is generally more intuitive, in this case, to write 800.Bd -literal -offset indent 801\&.if COND \e{\e 802\&.foo 803bar 804\&.\e} 805.Ed 806.Pp 807than having the request or macro follow as 808.Pp 809.D1 \&.if COND \e{ .foo 810.Pp 811The scope of a conditional is always parsed, but only executed if the 812conditional evaluates to true. 813.Pp 814Note that the 815.Sq \e} 816is converted into a zero-width escape sequence if not passed as a 817standalone macro 818.Sq \&.\e} . 819For example, 820.Pp 821.D1 \&.Fl a \e} b 822.Pp 823will result in 824.Sq \e} 825being considered an argument of the 826.Sq \&Fl 827macro. 828.Ss \&ig 829Ignore input. 830Its syntax can be either 831.Bd -literal -offset indent 832.Pf . Cm \&ig 833.Ar ignored text 834\&.. 835.Ed 836.Pp 837or 838.Bd -literal -offset indent 839.Pf . Cm \&ig Ar end 840.Ar ignored text 841.Pf . Ar end 842.Ed 843.Pp 844In the first case, input is ignored until a 845.Sq \&.. 846request is encountered on its own line. 847In the second case, input is ignored until the specified 848.Sq Pf . Ar end 849macro is encountered. 850Do not use the escape character 851.Sq \e 852anywhere in the definition of 853.Ar end ; 854it would cause very strange behaviour. 855.Pp 856When the 857.Ar end 858macro is a roff request or a roff macro, like in 859.Pp 860.D1 \&.ig if 861.Pp 862the subsequent invocation of 863.Sx \&if 864will first terminate the 865.Ar ignored text , 866then be invoked as usual. 867Otherwise, it only terminates the 868.Ar ignored text , 869and arguments following it or the 870.Sq \&.. 871request are discarded. 872.Ss \&ll 873Change the output line length. 874Its syntax is as follows: 875.Pp 876.D1 Pf . Cm \&ll Op Oo +|- Oc Ns Ar width 877.Pp 878If the 879.Ar width 880argument is omitted, the line length is reset to its previous value. 881The default setting for terminal output is 78n. 882If a sign is given, the line length is added to or subtracted from; 883otherwise, it is set to the provided value. 884Using this request in new manuals is discouraged for several reasons, 885among others because it overrides the 886.Xr mandoc 1 887.Fl O Cm width 888command line option. 889.Ss \&ne 890Declare the need for the specified minimum vertical space 891before the next trap or the bottom of the page. 892This line-scoped request is currently ignored. 893.Ss \&nh 894Turn off automatic hyphenation mode. 895This line-scoped request is currently ignored. 896.Ss \&nr 897Define or change a register. 898A register is an arbitrary string value that defines some sort of state, 899which influences parsing and/or formatting. 900Its syntax is as follows: 901.Pp 902.D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar expression 903.Pp 904For the syntax of 905.Ar expression , 906see 907.Sx Numerical expressions 908below. 909If it is prefixed by a sign, the register will be 910incremented or decremented instead of assigned to. 911.Pp 912The following register 913.Ar name 914is handled specially: 915.Bl -tag -width Ds 916.It Cm nS 917If set to a positive integer value, certain 918.Xr mdoc 7 919macros will behave in the same way as in the 920.Em SYNOPSIS 921section. 922If set to 0, these macros will behave in the same way as outside the 923.Em SYNOPSIS 924section, even when called within the 925.Em SYNOPSIS 926section itself. 927Note that starting a new 928.Xr mdoc 7 929section with the 930.Cm \&Sh 931macro will reset this register. 932.El 933.Ss \&ns 934Turn on no-space mode. 935This line-scoped request is intended to take no arguments. 936Currently, it is ignored including its arguments, 937and the number of arguments is not checked. 938.Ss \&ps 939Change point size. 940This line-scoped request is intended to take one numerical argument. 941Currently, it is ignored including its arguments, 942and the number of arguments is not checked. 943.Ss \&rm 944Remove a request, macro or string. 945Its syntax is as follows: 946.Pp 947.D1 Pf \. Cm \&rm Ar name 948.Ss \&rr 949Remove a register. 950Its syntax is as follows: 951.Pp 952.D1 Pf \. Cm \&rr Ar name 953.Ss \&so 954Include a source file. 955Its syntax is as follows: 956.Pp 957.D1 Pf \. Cm \&so Ar file 958.Pp 959The 960.Ar file 961will be read and its contents processed as input in place of the 962.Sq \&.so 963request line. 964To avoid inadvertent inclusion of unrelated files, 965.Xr mandoc 1 966only accepts relative paths not containing the strings 967.Qq ../ 968and 969.Qq /.. . 970.Pp 971This request requires 972.Xr man 1 973to change to the right directory before calling 974.Xr mandoc 1 , 975per convention to the root of the manual tree. 976Typical usage looks like: 977.Pp 978.Dl \&.so man3/Xcursor.3 979.Pp 980As the whole concept is rather fragile, the use of 981.Sx \&so 982is discouraged. 983Use 984.Xr ln 1 985instead. 986.Ss \&ta 987Set tab stops. 988This line-scoped request can take an arbitrary number of arguments. 989Currently, it is ignored including its arguments. 990.Ss \&tr 991Output character translation. 992Its syntax is as follows: 993.Pp 994.D1 Pf \. Cm \&tr Ar [ab]+ 995.Pp 996Pairs of 997.Ar ab 998characters are replaced 999.Ar ( a 1000for 1001.Ar b ) . 1002Replacement (or origin) characters may also be character escapes; thus, 1003.Pp 1004.Dl tr \e(xx\e(yy 1005.Pp 1006replaces all invocations of \e(xx with \e(yy. 1007.Ss \&T& 1008Re-start a table layout, retaining the options of the prior table 1009invocation. 1010See 1011.Sx \&TS . 1012.Ss \&TE 1013End a table context. 1014See 1015.Sx \&TS . 1016.Ss \&TS 1017Begin a table, which formats input in aligned rows and columns. 1018See 1019.Xr tbl 7 1020for a description of the tbl language. 1021.Ss Numerical expressions 1022The 1023.Sx \&nr , 1024.Sx \&if , 1025and 1026.Sx \&ie 1027requests accept integer numerical expressions as arguments. 1028These are always evaluated using the C 1029.Vt int 1030type; integer overflow works the same way as in the C language. 1031Numbers consist of an arbitrary number of digits 1032.Sq 0 1033to 1034.Sq 9 1035prefixed by an optional sign 1036.Sq + 1037or 1038.Sq - . 1039.Pp 1040The following binary operators are implemented. 1041Unless otherwise stated, they behave as in the C language: 1042.Pp 1043.Bl -tag -width 2n -compact 1044.It Ic + 1045addition 1046.It Ic - 1047subtraction 1048.It Ic * 1049multiplication 1050.It Ic / 1051division 1052.It Ic % 1053remainder of division 1054.It Ic < 1055less than 1056.It Ic > 1057greater than 1058.It Ic == 1059equal to 1060.It Ic = 1061equal to, same effect as 1062.Ic == 1063(this differs from C) 1064.It Ic <= 1065less than or equal to 1066.It Ic >= 1067greater than or equal to 1068.It Ic <> 1069not equal to (corresponds to C 1070.Ic != ; 1071this one is of limited portability, it is supported by Heirloom roff, 1072but not by groff) 1073.It Ic & 1074logical and (corresponds to C 1075.Ic && ) 1076.It Ic \&: 1077logical or (corresponds to C 1078.Ic \&|| ) 1079.It Ic <? 1080minimum (not available in C) 1081.It Ic >? 1082maximum (not available in C) 1083.El 1084.Pp 1085There is no concept of precendence; evaluation proceeds from left to right, 1086except when subexpressions are enclosed in parantheses. 1087Inside parentheses, whitespace is ignored. 1088.Sh ESCAPE SEQUENCE REFERENCE 1089The 1090.Xr mandoc 1 1091.Nm 1092parser recognises the following escape sequences. 1093Note that the 1094.Nm 1095language defines more escape sequences not implemented in 1096.Xr mandoc 1 . 1097In 1098.Xr mdoc 7 1099and 1100.Xr man 7 1101documents, using escape sequences is discouraged except for those 1102described in the 1103.Sx LANGUAGE SYNTAX 1104section above. 1105.Pp 1106A backslash followed by any character not listed here 1107simply prints that character itself. 1108.Ss \e<newline> 1109A backslash at the end of an input line can be used to continue the 1110logical input line on the next physical input line, joining the text 1111on both lines together as if it were on a single input line. 1112.Ss \e<space> 1113The escape sequence backslash-space 1114.Pq Sq \e\ \& 1115is an unpaddable space-sized non-breaking space character; see 1116.Sx Whitespace . 1117.Ss \e\(dq 1118The rest of the input line is treated as 1119.Sx Comments . 1120.Ss \e% 1121Hyphenation allowed at this point of the word; ignored by 1122.Xr mandoc 1 . 1123.Ss \e& 1124Non-printing zero-width character; see 1125.Sx Whitespace . 1126.Ss \e\(aq 1127Acute accent special character; use 1128.Sq \e(aa 1129instead. 1130.Ss \e( Ns Ar cc 1131.Sx Special Characters 1132with two-letter names, see 1133.Xr mandoc_char 7 . 1134.Ss \e*[ Ns Ar name ] 1135Interpolate the string with the 1136.Ar name ; 1137see 1138.Sx Predefined Strings 1139and 1140.Sx ds . 1141For short names, there are variants 1142.No \e* Ns Ar c 1143and 1144.No \e*( Ns Ar cc . 1145.Ss \e- 1146Special character 1147.Dq mathematical minus sign . 1148.Ss \e[ Ns Ar name ] 1149.Sx Special Characters 1150with names of arbitrary length, see 1151.Xr mandoc_char 7 . 1152.Ss \e^ 1153One-twelfth em half-narrow space character, effectively zero-width in 1154.Xr mandoc 1 . 1155.Ss \e` 1156Grave accent special character; use 1157.Sq \e(ga 1158instead. 1159.Ss \e{ 1160Begin conditional input; see 1161.Sx if . 1162.Ss \e\(ba 1163One-sixth em narrow space character, effectively zero-width in 1164.Xr mandoc 1 . 1165.Ss \e} 1166End conditional input; see 1167.Sx if . 1168.Ss \e~ 1169Paddable non-breaking space character. 1170.Ss \e0 1171Digit width space character. 1172.Ss \eA\(aq Ns Ar string Ns \(aq 1173Anchor definition; ignored by 1174.Xr mandoc 1 . 1175.Ss \eB\(aq Ns Ar string Ns \(aq 1176Interpolate 1177.Sq 1 1178if 1179.Ar string 1180conforms to the syntax of 1181.Sx Numerical expressions 1182explained above and 1183.Sq 0 1184otherwise. 1185.Ss \eb\(aq Ns Ar string Ns \(aq 1186Bracket building function; ignored by 1187.Xr mandoc 1 . 1188.Ss \eC\(aq Ns Ar name Ns \(aq 1189.Sx Special Characters 1190with names of arbitrary length. 1191.Ss \ec 1192Interrupt text processing to insert requests or macros; ignored by 1193.Xr mandoc 1 . 1194.Ss \eD\(aq Ns Ar string Ns \(aq 1195Draw graphics function; ignored by 1196.Xr mandoc 1 . 1197.Ss \ed 1198Move down by half a line; ignored by 1199.Xr mandoc 1 . 1200.Ss \ee 1201Backslash special character. 1202.Ss \eF[ Ns Ar name ] 1203Switch font family (groff extension); ignored by 1204.Xr mandoc 1 . 1205For short names, there are variants 1206.No \eF Ns Ar c 1207and 1208.No \eF( Ns Ar cc . 1209.Ss \ef[ Ns Ar name ] 1210Switch to the font 1211.Ar name , 1212see 1213.Sx Text Decoration . 1214For short names, there are variants 1215.No \ef Ns Ar c 1216and 1217.No \ef( Ns Ar cc . 1218.Ss \eg[ Ns Ar name ] 1219Interpolate the format of a number register; ignored by 1220.Xr mandoc 1 . 1221For short names, there are variants 1222.No \eg Ns Ar c 1223and 1224.No \eg( Ns Ar cc . 1225.Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq 1226Set the height of the current font; ignored by 1227.Xr mandoc 1 . 1228.Ss \eh\(aq Ns Ar number Ns \(aq 1229Horizontal motion; ignored by 1230.Xr mandoc 1 . 1231.Ss \ek[ Ns Ar name ] 1232Mark horizontal input place in register; ignored by 1233.Xr mandoc 1 . 1234For short names, there are variants 1235.No \ek Ns Ar c 1236and 1237.No \ek( Ns Ar cc . 1238.Ss \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq 1239Vertical line drawing function; ignored by 1240.Xr mandoc 1 . 1241.Ss \el\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq 1242Horizontal line drawing function; ignored by 1243.Xr mandoc 1 . 1244.Ss \eM[ Ns Ar name ] 1245Set fill (background) color (groff extension); ignored by 1246.Xr mandoc 1 . 1247For short names, there are variants 1248.No \eM Ns Ar c 1249and 1250.No \eM( Ns Ar cc . 1251.Ss \em[ Ns Ar name ] 1252Set glyph drawing color (groff extension); ignored by 1253.Xr mandoc 1 . 1254For short names, there are variants 1255.No \em Ns Ar c 1256and 1257.No \em( Ns Ar cc . 1258.Ss \eN\(aq Ns Ar number Ns \(aq 1259Character 1260.Ar number 1261on the current font. 1262.Ss \en[ Ns Ar name ] 1263Interpolate the number register 1264.Ar name . 1265For short names, there are variants 1266.No \en Ns Ar c 1267and 1268.No \en( Ns Ar cc . 1269.Ss \eo\(aq Ns Ar string Ns \(aq 1270Overstrike 1271.Ar string ; 1272ignored by 1273.Xr mandoc 1 . 1274.Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq 1275Set number register; ignored by 1276.Xr mandoc 1 . 1277.Ss \eS\(aq Ns Ar number Ns \(aq 1278Slant output; ignored by 1279.Xr mandoc 1 . 1280.Ss \es\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq 1281Change point size; ignored by 1282.Xr mandoc 1 . 1283Alternative forms 1284.No \es Ns Oo +|- Oc Ns Ar n , 1285.No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq , 1286.No \es Ns [ Oo +|- Oc Ns Ar number ] , 1287and 1288.No \es Ns Oo +|- Oc Ns [ Ar number Ns ] 1289are also parsed and ignored. 1290.Ss \et 1291Horizontal tab; ignored by 1292.Xr mandoc 1 . 1293.Ss \eu 1294Move up by half a line; ignored by 1295.Xr mandoc 1 . 1296.Ss \eV[ Ns Ar name ] 1297Interpolate an environment variable; ignored by 1298.Xr mandoc 1 . 1299For short names, there are variants 1300.No \eV Ns Ar c 1301and 1302.No \eV( Ns Ar cc . 1303.Ss \ev\(aq Ns Ar number Ns \(aq 1304Vertical motion; ignored by 1305.Xr mandoc 1 . 1306.Ss \ew\(aq Ns Ar string Ns \(aq 1307Interpolate the width of the 1308.Ar string . 1309The 1310.Xr mandoc 1 1311implementation assumes that after expansion of user-defined strings, the 1312.Ar string 1313only contains normal characters, no escape sequences, and that each 1314character has a width of 24 basic units. 1315.Ss \eX\(aq Ns Ar string Ns \(aq 1316Output 1317.Ar string 1318as device control function; ignored in nroff mode and by 1319.Xr mandoc 1 . 1320.Ss \ex\(aq Ns Ar number Ns \(aq 1321Extra line space function; ignored by 1322.Xr mandoc 1 . 1323.Ss \eY[ Ns Ar name ] 1324Output a string as a device control function; ignored in nroff mode and by 1325.Xr mandoc 1 . 1326For short names, there are variants 1327.No \eY Ns Ar c 1328and 1329.No \eY( Ns Ar cc . 1330.Ss \eZ\(aq Ns Ar string Ns \(aq 1331Print 1332.Ar string 1333with zero width and height; ignored by 1334.Xr mandoc 1 . 1335.Ss \ez 1336Output the next character without advancing the cursor position; 1337approximated in 1338.Xr mandoc 1 1339by simply skipping the next character. 1340.Sh COMPATIBILITY 1341This section documents compatibility between mandoc and other 1342.Nm 1343implementations, at this time limited to GNU troff 1344.Pq Qq groff . 1345The term 1346.Qq historic groff 1347refers to groff version 1.15. 1348.Pp 1349.Bl -dash -compact 1350.It 1351In mandoc, the 1352.Sx \&EQ , 1353.Sx \&TE , 1354.Sx \&TS , 1355and 1356.Sx \&T& , 1357macros are considered regular macros. 1358In all other 1359.Nm 1360implementations, these are special macros that must be specified without 1361spacing between the control character (which must be a period) and the 1362macro name. 1363.It 1364The 1365.Cm nS 1366register is only compatible with OpenBSD's groff-1.15. 1367.It 1368Historic groff did not accept white-space before a custom 1369.Ar end 1370macro for the 1371.Sx \&ig 1372request. 1373.It 1374The 1375.Sx \&if 1376and family would print funny white-spaces with historic groff when 1377using the next-line syntax. 1378.El 1379.Sh SEE ALSO 1380.Xr mandoc 1 , 1381.Xr eqn 7 , 1382.Xr man 7 , 1383.Xr mandoc_char 7 , 1384.Xr mdoc 7 , 1385.Xr tbl 7 1386.Rs 1387.%A Joseph F. Ossanna 1388.%A Brian W. Kernighan 1389.%I AT&T Bell Laboratories 1390.%T Troff User's Manual 1391.%R Computing Science Technical Report 1392.%N 54 1393.%C Murray Hill, New Jersey 1394.%D 1976 and 1992 1395.%U http://www.kohala.com/start/troff/cstr54.ps 1396.Re 1397.Rs 1398.%A Joseph F. Ossanna 1399.%A Brian W. Kernighan 1400.%A Gunnar Ritter 1401.%T Heirloom Documentation Tools Nroff/Troff User's Manual 1402.%D September 17, 2007 1403.%U http://heirloom.sourceforge.net/doctools/troff.pdf 1404.Re 1405.Sh HISTORY 1406The RUNOFF typesetting system, whose input forms the basis for 1407.Nm , 1408was written in MAD and FAP for the CTSS operating system by Jerome E. 1409Saltzer in 1964. 1410Doug McIlroy rewrote it in BCPL in 1969, renaming it 1411.Nm . 1412Dennis M. Ritchie rewrote McIlroy's 1413.Nm 1414in PDP-11 assembly for 1415.At v1 , 1416Joseph F. Ossanna improved roff and renamed it nroff 1417for 1418.At v2 , 1419then ported nroff to C as troff, which Brian W. Kernighan released with 1420.At v7 . 1421In 1989, James Clarke re-implemented troff in C++, naming it groff. 1422.Sh AUTHORS 1423.An -nosplit 1424This 1425.Nm 1426reference was written by 1427.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv 1428and 1429.An Ingo Schwarze Aq Mt schwarze@openbsd.org . 1430