1.\" $Id: roff.7,v 1.46 2013/12/26 02:43:18 schwarze Exp $ 2.\" 3.\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2010, 2011, 2013 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: December 26 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 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 . 412It is currently ignored by 413.Xr mandoc 1 , 414as are its children. 415.Ss \&ami 416Append to a macro definition, specifying the macro name indirectly. 417The syntax of this request is the same as that of 418.Sx \&dei . 419It is currently ignored by 420.Xr mandoc 1 , 421as are its children. 422.Ss \&am1 423Append to a macro definition, switching roff compatibility mode off 424during macro execution. 425The syntax of this request is the same as that of 426.Sx \&de1 . 427It is currently ignored by 428.Xr mandoc 1 , 429as are its children. 430.Ss \&cc 431Changes the control character. 432Its syntax is as follows: 433.Bd -literal -offset indent 434.Pf . Cm \&cc Op Ar c 435.Ed 436.Pp 437If 438.Ar c 439is not specified, the control character is reset to 440.Sq \&. . 441Trailing characters are ignored. 442.Ss \&de 443Define a 444.Nm 445macro. 446Its syntax can be either 447.Bd -literal -offset indent 448.Pf . Cm \&de Ar name 449.Ar macro definition 450\&.. 451.Ed 452.Pp 453or 454.Bd -literal -offset indent 455.Pf . Cm \&de Ar name Ar end 456.Ar macro definition 457.Pf . Ar end 458.Ed 459.Pp 460Both forms define or redefine the macro 461.Ar name 462to represent the 463.Ar macro definition , 464which may consist of one or more input lines, including the newline 465characters terminating each line, optionally containing calls to 466.Nm 467requests, 468.Nm 469macros or high-level macros like 470.Xr man 7 471or 472.Xr mdoc 7 473macros, whichever applies to the document in question. 474.Pp 475Specifying a custom 476.Ar end 477macro works in the same way as for 478.Sx \&ig ; 479namely, the call to 480.Sq Pf . Ar end 481first ends the 482.Ar macro definition , 483and after that, it is also evaluated as a 484.Nm 485request or 486.Nm 487macro, but not as a high-level macro. 488.Pp 489The macro can be invoked later using the syntax 490.Pp 491.D1 Pf . Ar name Op Ar argument Op Ar argument ... 492.Pp 493Regarding argument parsing, see 494.Sx MACRO SYNTAX 495above. 496.Pp 497The line invoking the macro will be replaced 498in the input stream by the 499.Ar macro definition , 500replacing all occurrences of 501.No \e\e$ Ns Ar N , 502where 503.Ar N 504is a digit, by the 505.Ar N Ns th Ar argument . 506For example, 507.Bd -literal -offset indent 508\&.de ZN 509\efI\e^\e\e$1\e^\efP\e\e$2 510\&.. 511\&.ZN XtFree . 512.Ed 513.Pp 514produces 515.Pp 516.D1 \efI\e^XtFree\e^\efP. 517.Pp 518in the input stream, and thus in the output: \fI\^XtFree\^\fP. 519.Pp 520Since macros and user-defined strings share a common string table, 521defining a macro 522.Ar name 523clobbers the user-defined string 524.Ar name , 525and the 526.Ar macro definition 527can also be printed using the 528.Sq \e* 529string interpolation syntax described below 530.Sx ds , 531but this is rarely useful because every macro definition contains at least 532one explicit newline character. 533.Pp 534In order to prevent endless recursion, both groff and 535.Xr mandoc 1 536limit the stack depth for expanding macros and strings 537to a large, but finite number. 538Do not rely on the exact value of this limit. 539.Ss \&dei 540Define a 541.Nm 542macro, specifying the macro name indirectly. 543The syntax of this request is the same as that of 544.Sx \&de . 545It is currently ignored by 546.Xr mandoc 1 , 547as are its children. 548.Ss \&de1 549Define a 550.Nm 551macro that will be executed with 552.Nm 553compatibility mode switched off during macro execution. 554This is a GNU extension not available in traditional 555.Nm 556implementations and not even in older versions of groff. 557Since 558.Xr mandoc 1 559does not implement 560.Nm 561compatibility mode at all, it handles this request as an alias for 562.Sx \&de . 563.Ss \&ds 564Define a user-defined string. 565Its syntax is as follows: 566.Pp 567.D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string 568.Pp 569The 570.Ar name 571and 572.Ar string 573arguments are space-separated. 574If the 575.Ar string 576begins with a double-quote character, that character will not be part 577of the string. 578All remaining characters on the input line form the 579.Ar string , 580including whitespace and double-quote characters, even trailing ones. 581.Pp 582The 583.Ar string 584can be interpolated into subsequent text by using 585.No \e* Ns Bq Ar name 586for a 587.Ar name 588of arbitrary length, or \e*(NN or \e*N if the length of 589.Ar name 590is two or one characters, respectively. 591Interpolation can be prevented by escaping the leading backslash; 592that is, an asterisk preceded by an even number of backslashes 593does not trigger string interpolation. 594.Pp 595Since user-defined strings and macros share a common string table, 596defining a string 597.Ar name 598clobbers the macro 599.Ar name , 600and the 601.Ar name 602used for defining a string can also be invoked as a macro, 603in which case the following input line will be appended to the 604.Ar string , 605forming a new input line passed to the 606.Nm 607parser. 608For example, 609.Bd -literal -offset indent 610\&.ds badidea .S 611\&.badidea 612H SYNOPSIS 613.Ed 614.Pp 615invokes the 616.Cm SH 617macro when used in a 618.Xr man 7 619document. 620Such abuse is of course strongly discouraged. 621.Ss \&el 622The 623.Qq else 624half of an if/else conditional. 625Pops a result off the stack of conditional evaluations pushed by 626.Sx \&ie 627and uses it as its conditional. 628If no stack entries are present (e.g., due to no prior 629.Sx \&ie 630calls) 631then false is assumed. 632The syntax of this request is similar to 633.Sx \&if 634except that the conditional is missing. 635.Ss \&EN 636End an equation block. 637See 638.Sx \&EQ . 639.Ss \&EQ 640Begin an equation block. 641See 642.Xr eqn 7 643for a description of the equation language. 644.Ss \&fam 645Change the font family. 646This line-scoped request is intended to have one argument specifying 647the font family to be selected. 648It is a groff extension, and currently, it is ignored including its 649arguments, and the number of arguments is not checked. 650.Ss \&hw 651Specify hyphenation points in words. 652This line-scoped request is currently ignored. 653.Ss \&hy 654Set automatic hyphenation mode. 655This line-scoped request is currently ignored. 656.Ss \&ie 657The 658.Qq if 659half of an if/else conditional. 660The result of the conditional is pushed into a stack used by subsequent 661invocations of 662.Sx \&el , 663which may be separated by any intervening input (or not exist at all). 664Its syntax is equivalent to 665.Sx \&if . 666.Ss \&if 667Begins a conditional. 668Right now, the conditional evaluates to true 669if and only if it starts with the letter 670.Sy n , 671indicating processing in nroff style as opposed to troff style. 672If a conditional is false, its children are not processed, but are 673syntactically interpreted to preserve the integrity of the input 674document. 675Thus, 676.Pp 677.D1 \&.if t .ig 678.Pp 679will discard the 680.Sq \&.ig , 681which may lead to interesting results, but 682.Pp 683.D1 \&.if t .if t \e{\e 684.Pp 685will continue to syntactically interpret to the block close of the final 686conditional. 687Sub-conditionals, in this case, obviously inherit the truth value of 688the parent. 689This request has the following syntax: 690.Bd -literal -offset indent 691\&.if COND \e{\e 692BODY... 693\&.\e} 694.Ed 695.Bd -literal -offset indent 696\&.if COND \e{ BODY 697BODY... \e} 698.Ed 699.Bd -literal -offset indent 700\&.if COND \e{ BODY 701BODY... 702\&.\e} 703.Ed 704.Bd -literal -offset indent 705\&.if COND \e 706BODY 707.Ed 708.Pp 709COND is a conditional statement. 710roff allows for complicated conditionals; mandoc is much simpler. 711At this time, mandoc supports only 712.Sq n , 713evaluating to true; 714and 715.Sq t , 716.Sq e , 717and 718.Sq o , 719evaluating to false. 720All other invocations are read up to the next end of line or space and 721evaluate as false. 722.Pp 723If the BODY section is begun by an escaped brace 724.Sq \e{ , 725scope continues until a closing-brace escape sequence 726.Sq \.\e} . 727If the BODY is not enclosed in braces, scope continues until 728the end of the line. 729If the COND is followed by a BODY on the same line, whether after a 730brace or not, then requests and macros 731.Em must 732begin with a control character. 733It is generally more intuitive, in this case, to write 734.Bd -literal -offset indent 735\&.if COND \e{\e 736\&.foo 737bar 738\&.\e} 739.Ed 740.Pp 741than having the request or macro follow as 742.Pp 743.D1 \&.if COND \e{ .foo 744.Pp 745The scope of a conditional is always parsed, but only executed if the 746conditional evaluates to true. 747.Pp 748Note that the 749.Sq \e} 750is converted into a zero-width escape sequence if not passed as a 751standalone macro 752.Sq \&.\e} . 753For example, 754.Pp 755.D1 \&.Fl a \e} b 756.Pp 757will result in 758.Sq \e} 759being considered an argument of the 760.Sq \&Fl 761macro. 762.Ss \&ig 763Ignore input. 764Its syntax can be either 765.Bd -literal -offset indent 766.Pf . Cm \&ig 767.Ar ignored text 768\&.. 769.Ed 770.Pp 771or 772.Bd -literal -offset indent 773.Pf . Cm \&ig Ar end 774.Ar ignored text 775.Pf . Ar end 776.Ed 777.Pp 778In the first case, input is ignored until a 779.Sq \&.. 780request is encountered on its own line. 781In the second case, input is ignored until the specified 782.Sq Pf . Ar end 783macro is encountered. 784Do not use the escape character 785.Sq \e 786anywhere in the definition of 787.Ar end ; 788it would cause very strange behaviour. 789.Pp 790When the 791.Ar end 792macro is a roff request or a roff macro, like in 793.Pp 794.D1 \&.ig if 795.Pp 796the subsequent invocation of 797.Sx \&if 798will first terminate the 799.Ar ignored text , 800then be invoked as usual. 801Otherwise, it only terminates the 802.Ar ignored text , 803and arguments following it or the 804.Sq \&.. 805request are discarded. 806.Ss \&ne 807Declare the need for the specified minimum vertical space 808before the next trap or the bottom of the page. 809This line-scoped request is currently ignored. 810.Ss \&nh 811Turn off automatic hyphenation mode. 812This line-scoped request is currently ignored. 813.Ss \&rm 814Remove a request, macro or string. 815This request is intended to have one argument, 816the name of the request, macro or string to be undefined. 817Currently, it is ignored including its arguments, 818and the number of arguments is not checked. 819.Ss \&nr 820Define or change a register. 821A register is an arbitrary string value that defines some sort of state, 822which influences parsing and/or formatting. 823Its syntax is as follows: 824.Pp 825.D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar value 826.Pp 827The 828.Ar value 829may, at the moment, only be an integer. 830If it is prefixed by a sign, the register will be 831incremented or decremented instead of assigned to. 832.Pp 833The following register 834.Ar name 835is handled specially: 836.Bl -tag -width Ds 837.It Cm nS 838If set to a positive integer value, certain 839.Xr mdoc 7 840macros will behave in the same way as in the 841.Em SYNOPSIS 842section. 843If set to 0, these macros will behave in the same way as outside the 844.Em SYNOPSIS 845section, even when called within the 846.Em SYNOPSIS 847section itself. 848Note that starting a new 849.Xr mdoc 7 850section with the 851.Cm \&Sh 852macro will reset this register. 853.El 854.Ss \&ns 855Turn on no-space mode. 856This line-scoped request is intended to take no arguments. 857Currently, it is ignored including its arguments, 858and the number of arguments is not checked. 859.Ss \&ps 860Change point size. 861This line-scoped request is intended to take one numerical argument. 862Currently, it is ignored including its arguments, 863and the number of arguments is not checked. 864.Ss \&so 865Include a source file. 866Its syntax is as follows: 867.Pp 868.D1 Pf \. Cm \&so Ar file 869.Pp 870The 871.Ar file 872will be read and its contents processed as input in place of the 873.Sq \&.so 874request line. 875To avoid inadvertent inclusion of unrelated files, 876.Xr mandoc 1 877only accepts relative paths not containing the strings 878.Qq ../ 879and 880.Qq /.. . 881.Pp 882This request requires 883.Xr man 1 884to change to the right directory before calling 885.Xr mandoc 1 , 886per convention to the root of the manual tree. 887Typical usage looks like: 888.Pp 889.Dl \&.so man3/Xcursor.3 890.Pp 891As the whole concept is rather fragile, the use of 892.Sx \&so 893is discouraged. 894Use 895.Xr ln 1 896instead. 897.Ss \&ta 898Set tab stops. 899This line-scoped request can take an arbitrary number of arguments. 900Currently, it is ignored including its arguments. 901.Ss \&tr 902Output character translation. 903Its syntax is as follows: 904.Pp 905.D1 Pf \. Cm \&tr Ar [ab]+ 906.Pp 907Pairs of 908.Ar ab 909characters are replaced 910.Ar ( a 911for 912.Ar b ) . 913Replacement (or origin) characters may also be character escapes; thus, 914.Pp 915.Dl tr \e(xx\e(yy 916.Pp 917replaces all invocations of \e(xx with \e(yy. 918.Ss \&T& 919Re-start a table layout, retaining the options of the prior table 920invocation. 921See 922.Sx \&TS . 923.Ss \&TE 924End a table context. 925See 926.Sx \&TS . 927.Ss \&TS 928Begin a table, which formats input in aligned rows and columns. 929See 930.Xr tbl 7 931for a description of the tbl language. 932.Sh ESCAPE SEQUENCE REFERENCE 933The 934.Xr mandoc 1 935.Nm 936parser recognises the following escape sequences. 937Note that the 938.Nm 939language defines more escape sequences not implemented in 940.Xr mandoc 1 . 941In 942.Xr mdoc 7 943and 944.Xr man 7 945documents, using escape sequences is discouraged except for those 946described in the 947.Sx LANGUAGE SYNTAX 948section above. 949.Pp 950A backslash followed by any character not listed here 951simply prints that character itself. 952.Ss \e<newline> 953A backslash at the end of an input line can be used to continue the 954logical input line on the next physical input line, joining the text 955on both lines together as if it were on a single input line. 956.Ss \e<space> 957The escape sequence backslash-space 958.Pq Sq \e\ \& 959is an unpaddable space-sized non-breaking space character; see 960.Sx Whitespace . 961.Ss \e\(dq 962The rest of the input line is treated as 963.Sx Comments . 964.Ss \e% 965Hyphenation allowed at this point of the word; ignored by 966.Xr mandoc 1 . 967.Ss \e& 968Non-printing zero-width character; see 969.Sx Whitespace . 970.Ss \e\(aq 971Acute accent special character; use 972.Sq \e(aa 973instead. 974.Ss \e( Ns Ar cc 975.Sx Special Characters 976with two-letter names, see 977.Xr mandoc_char 7 . 978.Ss \e*[ Ns Ar name ] 979Interpolate the string with the 980.Ar name ; 981see 982.Sx Predefined Strings 983and 984.Sx ds . 985For short names, there are variants 986.No \e* Ns Ar c 987and 988.No \e*( Ns Ar cc . 989.Ss \e- 990Special character 991.Dq mathematical minus sign . 992.Ss \e[ Ns Ar name ] 993.Sx Special Characters 994with names of arbitrary length, see 995.Xr mandoc_char 7 . 996.Ss \e^ 997One-twelfth em half-narrow space character, effectively zero-width in 998.Xr mandoc 1 . 999.Ss \e` 1000Grave accent special character; use 1001.Sq \e(ga 1002instead. 1003.Ss \e{ 1004Begin conditional input; see 1005.Sx if . 1006.Ss \e\(ba 1007One-sixth em narrow space character, effectively zero-width in 1008.Xr mandoc 1 . 1009.Ss \e} 1010End conditional input; see 1011.Sx if . 1012.Ss \e~ 1013Paddable non-breaking space character. 1014.Ss \e0 1015Digit width space character. 1016.Ss \eA\(aq Ns Ar string Ns \(aq 1017Anchor definition; ignored by 1018.Xr mandoc 1 . 1019.Ss \eB\(aq Ns Ar string Ns \(aq 1020Test whether 1021.Ar string 1022is a numerical expession; ignored by 1023.Xr mandoc 1 . 1024.Ss \eb\(aq Ns Ar string Ns \(aq 1025Bracket building function; ignored by 1026.Xr mandoc 1 . 1027.Ss \eC\(aq Ns Ar name Ns \(aq 1028.Sx Special Characters 1029with names of arbitrary length. 1030.Ss \ec 1031Interrupt text processing to insert requests or macros; ignored by 1032.Xr mandoc 1 . 1033.Ss \eD\(aq Ns Ar string Ns \(aq 1034Draw graphics function; ignored by 1035.Xr mandoc 1 . 1036.Ss \ed 1037Move down by half a line; ignored by 1038.Xr mandoc 1 . 1039.Ss \ee 1040Backslash special character. 1041.Ss \eF[ Ns Ar name ] 1042Switch font family (groff extension); ignored by 1043.Xr mandoc 1 . 1044For short names, there are variants 1045.No \eF Ns Ar c 1046and 1047.No \eF( Ns Ar cc . 1048.Ss \ef[ Ns Ar name ] 1049Switch to the font 1050.Ar name , 1051see 1052.Sx Text Decoration . 1053For short names, there are variants 1054.No \ef Ns Ar c 1055and 1056.No \ef( Ns Ar cc . 1057.Ss \eg[ Ns Ar name ] 1058Interpolate the format of a number register; ignored by 1059.Xr mandoc 1 . 1060For short names, there are variants 1061.No \eg Ns Ar c 1062and 1063.No \eg( Ns Ar cc . 1064.Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq 1065Set the height of the current font; ignored by 1066.Xr mandoc 1 . 1067.Ss \eh\(aq Ns Ar number Ns \(aq 1068Horizontal motion; ignored by 1069.Xr mandoc 1 . 1070.Ss \ek[ Ns Ar name ] 1071Mark horizontal input place in register; ignored by 1072.Xr mandoc 1 . 1073For short names, there are variants 1074.No \ek Ns Ar c 1075and 1076.No \ek( Ns Ar cc . 1077.Ss \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq 1078Vertical line drawing function; ignored by 1079.Xr mandoc 1 . 1080.Ss \el\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq 1081Horizontal line drawing function; ignored by 1082.Xr mandoc 1 . 1083.Ss \eM[ Ns Ar name ] 1084Set fill (background) color (groff extension); ignored by 1085.Xr mandoc 1 . 1086For short names, there are variants 1087.No \eM Ns Ar c 1088and 1089.No \eM( Ns Ar cc . 1090.Ss \em[ Ns Ar name ] 1091Set glyph drawing color (groff extension); ignored by 1092.Xr mandoc 1 . 1093For short names, there are variants 1094.No \em Ns Ar c 1095and 1096.No \em( Ns Ar cc . 1097.Ss \eN\(aq Ns Ar number Ns \(aq 1098Character 1099.Ar number 1100on the current font. 1101.Ss \en[ Ns Ar name ] 1102Interpolate the number register 1103.Ar name . 1104For short names, there are variants 1105.No \en Ns Ar c 1106and 1107.No \en( Ns Ar cc . 1108.Ss \eo\(aq Ns Ar string Ns \(aq 1109Overstrike 1110.Ar string ; 1111ignored by 1112.Xr mandoc 1 . 1113.Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq 1114Set number register; ignored by 1115.Xr mandoc 1 . 1116.Ss \eS\(aq Ns Ar number Ns \(aq 1117Slant output; ignored by 1118.Xr mandoc 1 . 1119.Ss \es\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq 1120Change point size; ignored by 1121.Xr mandoc 1 . 1122Alternative forms 1123.No \es Ns Oo +|- Oc Ns Ar n , 1124.No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq , 1125.No \es Ns [ Oo +|- Oc Ns Ar number ] , 1126and 1127.No \es Ns Oo +|- Oc Ns [ Ar number Ns ] 1128are also parsed and ignored. 1129.Ss \et 1130Horizontal tab; ignored by 1131.Xr mandoc 1 . 1132.Ss \eu 1133Move up by half a line; ignored by 1134.Xr mandoc 1 . 1135.Ss \eV[ Ns Ar name ] 1136Interpolate an environment variable; ignored by 1137.Xr mandoc 1 . 1138For short names, there are variants 1139.No \eV Ns Ar c 1140and 1141.No \eV( Ns Ar cc . 1142.Ss \ev\(aq Ns Ar number Ns \(aq 1143Vertical motion; ignored by 1144.Xr mandoc 1 . 1145.Ss \ew\(aq Ns Ar string Ns \(aq 1146Interpolate the width of the 1147.Ar string ; 1148ignored by 1149.Xr mandoc 1 . 1150.Ss \eX\(aq Ns Ar string Ns \(aq 1151Output 1152.Ar string 1153as device control function; ignored in nroff mode and by 1154.Xr mandoc 1 . 1155.Ss \ex\(aq Ns Ar number Ns \(aq 1156Extra line space function; ignored by 1157.Xr mandoc 1 . 1158.Ss \eY[ Ns Ar name ] 1159Output a string as a device control function; ignored in nroff mode and by 1160.Xr mandoc 1 . 1161For short names, there are variants 1162.No \eY Ns Ar c 1163and 1164.No \eY( Ns Ar cc . 1165.Ss \eZ\(aq Ns Ar string Ns \(aq 1166Print 1167.Ar string 1168with zero width and height; ignored by 1169.Xr mandoc 1 . 1170.Ss \ez 1171Output the next character without advancing the cursor position; 1172approximated in 1173.Xr mandoc 1 1174by simply skipping the next character. 1175.Sh COMPATIBILITY 1176This section documents compatibility between mandoc and other 1177.Nm 1178implementations, at this time limited to GNU troff 1179.Pq Qq groff . 1180The term 1181.Qq historic groff 1182refers to groff version 1.15. 1183.Pp 1184.Bl -dash -compact 1185.It 1186In mandoc, the 1187.Sx \&EQ , 1188.Sx \&TE , 1189.Sx \&TS , 1190and 1191.Sx \&T& , 1192macros are considered regular macros. 1193In all other 1194.Nm 1195implementations, these are special macros that must be specified without 1196spacing between the control character (which must be a period) and the 1197macro name. 1198.It 1199The 1200.Cm nS 1201register is only compatible with OpenBSD's groff-1.15. 1202.It 1203Historic groff did not accept white-space before a custom 1204.Ar end 1205macro for the 1206.Sx \&ig 1207request. 1208.It 1209The 1210.Sx \&if 1211and family would print funny white-spaces with historic groff when 1212using the next-line syntax. 1213.El 1214.Sh SEE ALSO 1215.Xr mandoc 1 , 1216.Xr eqn 7 , 1217.Xr man 7 , 1218.Xr mandoc_char 7 , 1219.Xr mdoc 7 , 1220.Xr tbl 7 1221.Rs 1222.%A Joseph F. Ossanna 1223.%A Brian W. Kernighan 1224.%I AT&T Bell Laboratories 1225.%T Troff User's Manual 1226.%R Computing Science Technical Report 1227.%N 54 1228.%C Murray Hill, New Jersey 1229.%D 1976 and 1992 1230.%U http://www.kohala.com/start/troff/cstr54.ps 1231.Re 1232.Rs 1233.%A Joseph F. Ossanna 1234.%A Brian W. Kernighan 1235.%A Gunnar Ritter 1236.%T Heirloom Documentation Tools Nroff/Troff User's Manual 1237.%D September 17, 2007 1238.%U http://heirloom.sourceforge.net/doctools/troff.pdf 1239.Re 1240.Sh HISTORY 1241The RUNOFF typesetting system, whose input forms the basis for 1242.Nm , 1243was written in MAD and FAP for the CTSS operating system by Jerome E. 1244Saltzer in 1964. 1245Doug McIlroy rewrote it in BCPL in 1969, renaming it 1246.Nm . 1247Dennis M. Ritchie rewrote McIlroy's 1248.Nm 1249in PDP-11 assembly for 1250.At v1 , 1251Joseph F. Ossanna improved roff and renamed it nroff 1252for 1253.At v2 , 1254then ported nroff to C as troff, which Brian W. Kernighan released with 1255.At v7 . 1256In 1989, James Clarke re-implemented troff in C++, naming it groff. 1257.Sh AUTHORS 1258.An -nosplit 1259This 1260.Nm 1261reference was written by 1262.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv 1263and 1264.An Ingo Schwarze Aq Mt schwarze@openbsd.org . 1265