1.\" $Id: roff.7,v 1.42 2013/08/08 20:07:47 schwarze Exp $ 2.\" 3.\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2010, 2011 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: August 8 2013 $ 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 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. 45Only these requests 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 for 89.Sx Comments , 90.Sx Special Characters , 91.Sx Predefined Strings , 92and 93user-defined strings defined using the 94.Sx ds 95request. 96.Ss Comments 97Text following an escaped double-quote 98.Sq \e\(dq , 99whether in a request, macro, or text line, is ignored to the end of the line. 100A request line beginning with a control character and comment escape 101.Sq \&.\e\(dq 102is also ignored. 103Furthermore, request lines with only a control character and optional 104trailing whitespace are stripped from input. 105.Pp 106Examples: 107.Bd -literal -offset indent -compact 108\&.\e\(dq This is a comment line. 109\&.\e\(dq The next line is ignored: 110\&. 111\&.Sh EXAMPLES \e\(dq This is a comment, too. 112\&example text \e\(dq And so is this. 113.Ed 114.Ss Special Characters 115Special characters are used to encode special glyphs and are rendered 116differently across output media. 117They may occur in request, macro, and text lines. 118Sequences begin with the escape character 119.Sq \e 120followed by either an open-parenthesis 121.Sq \&( 122for two-character sequences; an open-bracket 123.Sq \&[ 124for n-character sequences (terminated at a close-bracket 125.Sq \&] ) ; 126or a single one character sequence. 127.Pp 128Examples: 129.Bl -tag -width Ds -offset indent -compact 130.It Li \e(em 131Two-letter em dash escape. 132.It Li \ee 133One-letter backslash escape. 134.El 135.Pp 136See 137.Xr mandoc_char 7 138for a complete list. 139.Ss Text Decoration 140Terms may be text-decorated using the 141.Sq \ef 142escape followed by an indicator: B (bold), I (italic), R (regular), or P 143(revert to previous mode). 144A numerical representation 3, 2, or 1 (bold, italic, and regular, 145respectively) may be used instead. 146The indicator or numerical representative may be preceded by C 147(constant-width), which is ignored. 148.Pp 149The two-character indicator 150.Sq BI 151requests a font that is both bold and italic. 152It may not be portable to old roff implementations. 153.Pp 154Examples: 155.Bl -tag -width Ds -offset indent -compact 156.It Li \efBbold\efR 157Write in \fBbold\fP, then switch to regular font mode. 158.It Li \efIitalic\efP 159Write in \fIitalic\fP, then return to previous font mode. 160.It Li \ef(BIbold italic\efP 161Write in \f(BIbold italic\fP, then return to previous font mode. 162.El 163.Pp 164Text decoration is 165.Em not 166recommended for 167.Xr mdoc 7 , 168which encourages semantic annotation. 169.Ss Predefined Strings 170Predefined strings, like 171.Sx Special Characters , 172mark special output glyphs. 173Predefined strings are escaped with the slash-asterisk, 174.Sq \e* : 175single-character 176.Sq \e*X , 177two-character 178.Sq \e*(XX , 179and N-character 180.Sq \e*[N] . 181.Pp 182Examples: 183.Bl -tag -width Ds -offset indent -compact 184.It Li \e*(Am 185Two-letter ampersand predefined string. 186.It Li \e*q 187One-letter double-quote predefined string. 188.El 189.Pp 190Predefined strings are not recommended for use, 191as they differ across implementations. 192Those supported by 193.Xr mandoc 1 194are listed in 195.Xr mandoc_char 7 . 196Manuals using these predefined strings are almost certainly not portable. 197.Ss Whitespace 198Whitespace consists of the space character. 199In text lines, whitespace is preserved within a line. 200In request and macro lines, whitespace delimits arguments and is discarded. 201.Pp 202Unescaped trailing spaces are stripped from text line input unless in a 203literal context. 204In general, trailing whitespace on any input line is discouraged for 205reasons of portability. 206In the rare case that a blank character is needed at the end of an 207input line, it may be forced by 208.Sq \e\ \e& . 209.Pp 210Literal space characters can be produced in the output 211using escape sequences. 212In macro lines, they can also be included in arguments using quotation; see 213.Sx MACRO SYNTAX 214for details. 215.Pp 216Blank text lines, which may include whitespace, are only permitted 217within literal contexts. 218If the first character of a text line is a space, that line is printed 219with a leading newline. 220.Ss Scaling Widths 221Many requests and macros support scaled widths for their arguments. 222The syntax for a scaled width is 223.Sq Li [+-]?[0-9]*.[0-9]*[:unit:] , 224where a decimal must be preceded or followed by at least one digit. 225Negative numbers, while accepted, are truncated to zero. 226.Pp 227The following scaling units are accepted: 228.Pp 229.Bl -tag -width Ds -offset indent -compact 230.It c 231centimetre 232.It i 233inch 234.It P 235pica (~1/6 inch) 236.It p 237point (~1/72 inch) 238.It f 239synonym for 240.Sq u 241.It v 242default vertical span 243.It m 244width of rendered 245.Sq m 246.Pq em 247character 248.It n 249width of rendered 250.Sq n 251.Pq en 252character 253.It u 254default horizontal span 255.It M 256mini-em (~1/100 em) 257.El 258.Pp 259Using anything other than 260.Sq m , 261.Sq n , 262.Sq u , 263or 264.Sq v 265is necessarily non-portable across output media. 266See 267.Sx COMPATIBILITY . 268.Pp 269If a scaling unit is not provided, the numerical value is interpreted 270under the default rules of 271.Sq v 272for vertical spaces and 273.Sq u 274for horizontal ones. 275.Pp 276Examples: 277.Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact 278.It Li \&.Bl -tag -width 2i 279two-inch tagged list indentation in 280.Xr mdoc 7 281.It Li \&.HP 2i 282two-inch tagged list indentation in 283.Xr man 7 284.It Li \&.sp 2v 285two vertical spaces 286.El 287.Ss Sentence Spacing 288Each sentence should terminate at the end of an input line. 289By doing this, a formatter will be able to apply the proper amount of 290spacing after the end of sentence (unescaped) period, exclamation mark, 291or question mark followed by zero or more non-sentence closing 292delimiters 293.Po 294.Sq \&) , 295.Sq \&] , 296.Sq \&' , 297.Sq \&" 298.Pc . 299.Pp 300The proper spacing is also intelligently preserved if a sentence ends at 301the boundary of a macro line. 302.Pp 303Examples: 304.Bd -literal -offset indent -compact 305Do not end sentences mid-line like this. Instead, 306end a sentence like this. 307A macro would end like this: 308\&.Xr mandoc 1 \&. 309.Ed 310.Sh REQUEST SYNTAX 311A request or macro line consists of: 312.Pp 313.Bl -enum -compact 314.It 315the control character 316.Sq \&. 317or 318.Sq \(aq 319at the beginning of the line, 320.It 321optionally an arbitrary amount of whitespace, 322.It 323the name of the request or the macro, which is one word of arbitrary 324length, terminated by whitespace, 325.It 326and zero or more arguments delimited by whitespace. 327.El 328.Pp 329Thus, the following request lines are all equivalent: 330.Bd -literal -offset indent 331\&.ig end 332\&.ig end 333\&. ig end 334.Ed 335.Sh MACRO SYNTAX 336Macros are provided by the 337.Xr mdoc 7 338and 339.Xr man 7 340languages and can be defined by the 341.Sx \&de 342request. 343When called, they follow the same syntax as requests, except that 344macro arguments may optionally be quoted by enclosing them 345in double quote characters 346.Pq Sq \(dq . 347Quoted text, even if it contains whitespace or would cause 348a macro invocation when unquoted, is always considered literal text. 349Inside quoted text, pairs of double quote characters 350.Pq Sq Qq 351resolve to single double quote characters. 352.Pp 353To be recognised as the beginning of a quoted argument, the opening 354quote character must be preceded by a space character. 355A quoted argument extends to the next double quote character that is not 356part of a pair, or to the end of the input line, whichever comes earlier. 357Leaving out the terminating double quote character at the end of the line 358is discouraged. 359For clarity, if more arguments follow on the same input line, 360it is recommended to follow the terminating double quote character 361by a space character; in case the next character after the terminating 362double quote character is anything else, it is regarded as the beginning 363of the next, unquoted argument. 364.Pp 365Both in quoted and unquoted arguments, pairs of backslashes 366.Pq Sq \e\e 367resolve to single backslashes. 368In unquoted arguments, space characters can alternatively be included 369by preceding them with a backslash 370.Pq Sq \e\~ , 371but quoting is usually better for clarity. 372.Pp 373Examples: 374.Bl -tag -width Ds -offset indent -compact 375.It Li .Fn strlen \(dqconst char *s\(dq 376Group arguments 377.Qq const char *s 378into one function argument. 379If unspecified, 380.Qq const , 381.Qq char , 382and 383.Qq *s 384would be considered separate arguments. 385.It Li .Op \(dqFl a\(dq 386Consider 387.Qq \&Fl a 388as literal text instead of a flag macro. 389.El 390.Sh REQUEST REFERENCE 391The 392.Xr mandoc 1 393.Nm 394parser recognises the following requests. 395Note that the 396.Nm 397language defines many more requests not implemented in 398.Xr mandoc 1 . 399.Ss \&ad 400Set line adjustment mode. 401This line-scoped request is intended to have one argument to select 402normal, left, right, or centre adjustment for subsequent text. 403Currently, it is ignored including its arguments, 404and the number of arguments is not checked. 405.Ss \&am 406Append to a macro definition. 407The syntax of this request is the same as that of 408.Sx \&de . 409It is currently ignored by 410.Xr mandoc 1 , 411as are its children. 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 . 416It is currently ignored by 417.Xr mandoc 1 , 418as are its children. 419.Ss \&am1 420Append to a macro definition, switching roff compatibility mode off 421during macro execution. 422The syntax of this request is the same as that of 423.Sx \&de1 . 424It is currently ignored by 425.Xr mandoc 1 , 426as are its children. 427.Ss \&cc 428Changes the control character. 429Its syntax is as follows: 430.Bd -literal -offset indent 431.Pf . Cm \&cc Op Ar c 432.Ed 433.Pp 434If 435.Ar c 436is not specified, the control character is reset to 437.Sq \&. . 438Trailing characters are ignored. 439.Ss \&de 440Define a 441.Nm 442macro. 443Its syntax can be either 444.Bd -literal -offset indent 445.Pf . Cm \&de Ar name 446.Ar macro definition 447\&.. 448.Ed 449.Pp 450or 451.Bd -literal -offset indent 452.Pf . Cm \&de Ar name Ar end 453.Ar macro definition 454.Pf . Ar end 455.Ed 456.Pp 457Both forms define or redefine the macro 458.Ar name 459to represent the 460.Ar macro definition , 461which may consist of one or more input lines, including the newline 462characters terminating each line, optionally containing calls to 463.Nm 464requests, 465.Nm 466macros or high-level macros like 467.Xr man 7 468or 469.Xr mdoc 7 470macros, whichever applies to the document in question. 471.Pp 472Specifying a custom 473.Ar end 474macro works in the same way as for 475.Sx \&ig ; 476namely, the call to 477.Sq Pf . Ar end 478first ends the 479.Ar macro definition , 480and after that, it is also evaluated as a 481.Nm 482request or 483.Nm 484macro, but not as a high-level macro. 485.Pp 486The macro can be invoked later using the syntax 487.Pp 488.D1 Pf . Ar name Op Ar argument Op Ar argument ... 489.Pp 490Regarding argument parsing, see 491.Sx MACRO SYNTAX 492above. 493.Pp 494The line invoking the macro will be replaced 495in the input stream by the 496.Ar macro definition , 497replacing all occurrences of 498.No \e\e$ Ns Ar N , 499where 500.Ar N 501is a digit, by the 502.Ar N Ns th Ar argument . 503For example, 504.Bd -literal -offset indent 505\&.de ZN 506\efI\e^\e\e$1\e^\efP\e\e$2 507\&.. 508\&.ZN XtFree . 509.Ed 510.Pp 511produces 512.Pp 513.D1 \efI\e^XtFree\e^\efP. 514.Pp 515in the input stream, and thus in the output: \fI\^XtFree\^\fP. 516.Pp 517Since macros and user-defined strings share a common string table, 518defining a macro 519.Ar name 520clobbers the user-defined string 521.Ar name , 522and the 523.Ar macro definition 524can also be printed using the 525.Sq \e* 526string interpolation syntax described below 527.Sx ds , 528but this is rarely useful because every macro definition contains at least 529one explicit newline character. 530.Pp 531In order to prevent endless recursion, both groff and 532.Xr mandoc 1 533limit the stack depth for expanding macros and strings 534to a large, but finite number. 535Do not rely on the exact value of this limit. 536.Ss \&dei 537Define a 538.Nm 539macro, specifying the macro name indirectly. 540The syntax of this request is the same as that of 541.Sx \&de . 542It is currently ignored by 543.Xr mandoc 1 , 544as are its children. 545.Ss \&de1 546Define a 547.Nm 548macro that will be executed with 549.Nm 550compatibility mode switched off during macro execution. 551This is a GNU extension not available in traditional 552.Nm 553implementations and not even in older versions of groff. 554Since 555.Xr mandoc 1 556does not implement 557.Nm 558compatibility mode at all, it handles this request as an alias for 559.Sx \&de . 560.Ss \&ds 561Define a user-defined string. 562Its syntax is as follows: 563.Pp 564.D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string 565.Pp 566The 567.Ar name 568and 569.Ar string 570arguments are space-separated. 571If the 572.Ar string 573begins with a double-quote character, that character will not be part 574of the string. 575All remaining characters on the input line form the 576.Ar string , 577including whitespace and double-quote characters, even trailing ones. 578.Pp 579The 580.Ar string 581can be interpolated into subsequent text by using 582.No \e* Ns Bq Ar name 583for a 584.Ar name 585of arbitrary length, or \e*(NN or \e*N if the length of 586.Ar name 587is two or one characters, respectively. 588Interpolation can be prevented by escaping the leading backslash; 589that is, an asterisk preceded by an even number of backslashes 590does not trigger string interpolation. 591.Pp 592Since user-defined strings and macros share a common string table, 593defining a string 594.Ar name 595clobbers the macro 596.Ar name , 597and the 598.Ar name 599used for defining a string can also be invoked as a macro, 600in which case the following input line will be appended to the 601.Ar string , 602forming a new input line passed to the 603.Nm 604parser. 605For example, 606.Bd -literal -offset indent 607\&.ds badidea .S 608\&.badidea 609H SYNOPSIS 610.Ed 611.Pp 612invokes the 613.Cm SH 614macro when used in a 615.Xr man 7 616document. 617Such abuse is of course strongly discouraged. 618.Ss \&el 619The 620.Qq else 621half of an if/else conditional. 622Pops a result off the stack of conditional evaluations pushed by 623.Sx \&ie 624and uses it as its conditional. 625If no stack entries are present (e.g., due to no prior 626.Sx \&ie 627calls) 628then false is assumed. 629The syntax of this request is similar to 630.Sx \&if 631except that the conditional is missing. 632.Ss \&EN 633End an equation block. 634See 635.Sx \&EQ . 636.Ss \&EQ 637Begin an equation block. 638See 639.Xr eqn 7 640for a description of the equation language. 641.Ss \&hy 642Set automatic hyphenation mode. 643This line-scoped request is currently ignored. 644.Ss \&ie 645The 646.Qq if 647half of an if/else conditional. 648The result of the conditional is pushed into a stack used by subsequent 649invocations of 650.Sx \&el , 651which may be separated by any intervening input (or not exist at all). 652Its syntax is equivalent to 653.Sx \&if . 654.Ss \&if 655Begins a conditional. 656Right now, the conditional evaluates to true 657if and only if it starts with the letter 658.Sy n , 659indicating processing in nroff style as opposed to troff style. 660If a conditional is false, its children are not processed, but are 661syntactically interpreted to preserve the integrity of the input 662document. 663Thus, 664.Pp 665.D1 \&.if t .ig 666.Pp 667will discard the 668.Sq \&.ig , 669which may lead to interesting results, but 670.Pp 671.D1 \&.if t .if t \e{\e 672.Pp 673will continue to syntactically interpret to the block close of the final 674conditional. 675Sub-conditionals, in this case, obviously inherit the truth value of 676the parent. 677This request has the following syntax: 678.Bd -literal -offset indent 679\&.if COND \e{\e 680BODY... 681\&.\e} 682.Ed 683.Bd -literal -offset indent 684\&.if COND \e{ BODY 685BODY... \e} 686.Ed 687.Bd -literal -offset indent 688\&.if COND \e{ BODY 689BODY... 690\&.\e} 691.Ed 692.Bd -literal -offset indent 693\&.if COND \e 694BODY 695.Ed 696.Pp 697COND is a conditional statement. 698roff allows for complicated conditionals; mandoc is much simpler. 699At this time, mandoc supports only 700.Sq n , 701evaluating to true; 702and 703.Sq t , 704.Sq e , 705and 706.Sq o , 707evaluating to false. 708All other invocations are read up to the next end of line or space and 709evaluate as false. 710.Pp 711If the BODY section is begun by an escaped brace 712.Sq \e{ , 713scope continues until a closing-brace escape sequence 714.Sq \.\e} . 715If the BODY is not enclosed in braces, scope continues until 716the end of the line. 717If the COND is followed by a BODY on the same line, whether after a 718brace or not, then requests and macros 719.Em must 720begin with a control character. 721It is generally more intuitive, in this case, to write 722.Bd -literal -offset indent 723\&.if COND \e{\e 724\&.foo 725bar 726\&.\e} 727.Ed 728.Pp 729than having the request or macro follow as 730.Pp 731.D1 \&.if COND \e{ .foo 732.Pp 733The scope of a conditional is always parsed, but only executed if the 734conditional evaluates to true. 735.Pp 736Note that the 737.Sq \e} 738is converted into a zero-width escape sequence if not passed as a 739standalone macro 740.Sq \&.\e} . 741For example, 742.Pp 743.D1 \&.Fl a \e} b 744.Pp 745will result in 746.Sq \e} 747being considered an argument of the 748.Sq \&Fl 749macro. 750.Ss \&ig 751Ignore input. 752Its syntax can be either 753.Bd -literal -offset indent 754.Pf . Cm \&ig 755.Ar ignored text 756\&.. 757.Ed 758.Pp 759or 760.Bd -literal -offset indent 761.Pf . Cm \&ig Ar end 762.Ar ignored text 763.Pf . Ar end 764.Ed 765.Pp 766In the first case, input is ignored until a 767.Sq \&.. 768request is encountered on its own line. 769In the second case, input is ignored until the specified 770.Sq Pf . Ar end 771macro is encountered. 772Do not use the escape character 773.Sq \e 774anywhere in the definition of 775.Ar end ; 776it would cause very strange behaviour. 777.Pp 778When the 779.Ar end 780macro is a roff request or a roff macro, like in 781.Pp 782.D1 \&.ig if 783.Pp 784the subsequent invocation of 785.Sx \&if 786will first terminate the 787.Ar ignored text , 788then be invoked as usual. 789Otherwise, it only terminates the 790.Ar ignored text , 791and arguments following it or the 792.Sq \&.. 793request are discarded. 794.Ss \&ne 795Declare the need for the specified minimum vertical space 796before the next trap or the bottom of the page. 797This line-scoped request is currently ignored. 798.Ss \&nh 799Turn off automatic hyphenation mode. 800This line-scoped request is currently ignored. 801.Ss \&rm 802Remove a request, macro or string. 803This request is intended to have one argument, 804the name of the request, macro or string to be undefined. 805Currently, it is ignored including its arguments, 806and the number of arguments is not checked. 807.Ss \&nr 808Define a register. 809A register is an arbitrary string value that defines some sort of state, 810which influences parsing and/or formatting. 811Its syntax is as follows: 812.Pp 813.D1 Pf \. Cm \&nr Ar name Ar value 814.Pp 815The 816.Ar value 817may, at the moment, only be an integer. 818So far, only the following register 819.Ar name 820is recognised: 821.Bl -tag -width Ds 822.It Cm nS 823If set to a positive integer value, certain 824.Xr mdoc 7 825macros will behave in the same way as in the 826.Em SYNOPSIS 827section. 828If set to 0, these macros will behave in the same way as outside the 829.Em SYNOPSIS 830section, even when called within the 831.Em SYNOPSIS 832section itself. 833Note that starting a new 834.Xr mdoc 7 835section with the 836.Cm \&Sh 837macro will reset this register. 838.El 839.Ss \&ns 840Turn on no-space mode. 841This line-scoped request is intended to take no arguments. 842Currently, it is ignored including its arguments, 843and the number of arguments is not checked. 844.Ss \&ps 845Change point size. 846This line-scoped request is intended to take one numerical argument. 847Currently, it is ignored including its arguments, 848and the number of arguments is not checked. 849.Ss \&so 850Include a source file. 851Its syntax is as follows: 852.Pp 853.D1 Pf \. Cm \&so Ar file 854.Pp 855The 856.Ar file 857will be read and its contents processed as input in place of the 858.Sq \&.so 859request line. 860To avoid inadvertent inclusion of unrelated files, 861.Xr mandoc 1 862only accepts relative paths not containing the strings 863.Qq ../ 864and 865.Qq /.. . 866.Pp 867This request requires 868.Xr man 1 869to change to the right directory before calling 870.Xr mandoc 1 , 871per convention to the root of the manual tree. 872Typical usage looks like: 873.Pp 874.Dl \&.so man3/Xcursor.3 875.Pp 876As the whole concept is rather fragile, the use of 877.Sx \&so 878is discouraged. 879Use 880.Xr ln 1 881instead. 882.Ss \&ta 883Set tab stops. 884This line-scoped request can take an arbitrary number of arguments. 885Currently, it is ignored including its arguments. 886.Ss \&tr 887Output character translation. 888Its syntax is as follows: 889.Pp 890.D1 Pf \. Cm \&tr Ar [ab]+ 891.Pp 892Pairs of 893.Ar ab 894characters are replaced 895.Ar ( a 896for 897.Ar b ) . 898Replacement (or origin) characters may also be character escapes; thus, 899.Pp 900.Dl tr \e(xx\e(yy 901.Pp 902replaces all invocations of \e(xx with \e(yy. 903.Ss \&T& 904Re-start a table layout, retaining the options of the prior table 905invocation. 906See 907.Sx \&TS . 908.Ss \&TE 909End a table context. 910See 911.Sx \&TS . 912.Ss \&TS 913Begin a table, which formats input in aligned rows and columns. 914See 915.Xr tbl 7 916for a description of the tbl language. 917.Sh COMPATIBILITY 918This section documents compatibility between mandoc and other 919.Nm 920implementations, at this time limited to GNU troff 921.Pq Qq groff . 922The term 923.Qq historic groff 924refers to groff version 1.15. 925.Pp 926.Bl -dash -compact 927.It 928In mandoc, the 929.Sx \&EQ , 930.Sx \&TE , 931.Sx \&TS , 932and 933.Sx \&T& , 934macros are considered regular macros. 935In all other 936.Nm 937implementations, these are special macros that must be specified without 938spacing between the control character (which must be a period) and the 939macro name. 940.It 941The 942.Cm nS 943register is only compatible with OpenBSD's groff-1.15. 944.It 945Historic groff did not accept white-space before a custom 946.Ar end 947macro for the 948.Sx \&ig 949request. 950.It 951The 952.Sx \&if 953and family would print funny white-spaces with historic groff when 954using the next-line syntax. 955.El 956.Sh SEE ALSO 957.Xr mandoc 1 , 958.Xr eqn 7 , 959.Xr man 7 , 960.Xr mandoc_char 7 , 961.Xr mdoc 7 , 962.Xr tbl 7 963.Rs 964.%A Joseph F. Ossanna 965.%A Brian W. Kernighan 966.%I AT&T Bell Laboratories 967.%T Troff User's Manual 968.%R Computing Science Technical Report 969.%N 54 970.%C Murray Hill, New Jersey 971.%D 1976 and 1992 972.%U http://www.kohala.com/start/troff/cstr54.ps 973.Re 974.Rs 975.%A Joseph F. Ossanna 976.%A Brian W. Kernighan 977.%A Gunnar Ritter 978.%T Heirloom Documentation Tools Nroff/Troff User's Manual 979.%D September 17, 2007 980.%U http://heirloom.sourceforge.net/doctools/troff.pdf 981.Re 982.Sh HISTORY 983The RUNOFF typesetting system, whose input forms the basis for 984.Nm , 985was written in MAD and FAP for the CTSS operating system by Jerome E. 986Saltzer in 1964. 987Doug McIlroy rewrote it in BCPL in 1969, renaming it 988.Nm . 989Dennis M. Ritchie rewrote McIlroy's 990.Nm 991in PDP-11 assembly for 992.At v1 , 993Joseph F. Ossanna improved roff and renamed it nroff 994for 995.At v2 , 996then ported nroff to C as troff, which Brian W. Kernighan released with 997.At v7 . 998In 1989, James Clarke re-implemented troff in C++, naming it groff. 999.Sh AUTHORS 1000.An -nosplit 1001This 1002.Nm 1003reference was written by 1004.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv 1005and 1006.An Ingo Schwarze Aq Mt schwarze@openbsd.org . 1007