1.\" Id: roff.7,v 1.75 2015/09/24 18:41:22 schwarze Exp 2.\" 3.\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2010, 2011, 2013-2015 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 September 24, 2015 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 242scale 243.Sq u 244by 65536 245.It v 246default vertical span 247.It m 248width of rendered 249.Sq m 250.Pq em 251character 252.It n 253width of rendered 254.Sq n 255.Pq en 256character 257.It u 258default horizontal span for the terminal 259.It M 260mini-em (~1/100 em) 261.El 262.Pp 263Using anything other than 264.Sq m , 265.Sq n , 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. 398For requests marked as "ignored" or "unsupported", any arguments are 399ignored, and the number of arguments is not checked. 400.Ss \&ab 401Abort processing. 402Currently unsupported. 403.Ss \&ad 404Set line adjustment mode. 405It takes one argument to select normal, left, right, 406or center adjustment for subsequent text. 407Currently ignored. 408.Ss \&af 409Assign an output format to a number register. 410Currently ignored. 411.Ss \&aln 412Create an alias for a number register. 413Currently unsupported. 414.Ss \&als 415Create an alias for a request, string, macro, or diversion. 416Currently unsupported. 417.Ss \&am 418Append to a macro definition. 419The syntax of this request is the same as that of 420.Sx \&de . 421.Ss \&am1 422Append to a macro definition, switching roff compatibility mode off 423during macro execution (groff extension). 424The syntax of this request is the same as that of 425.Sx \&de1 . 426Since 427.Xr mandoc 1 428does not implement 429.Nm 430compatibility mode at all, it handles this request as an alias for 431.Sx \&am . 432.Ss \&ami 433Append to a macro definition, specifying the macro name indirectly 434(groff extension). 435The syntax of this request is the same as that of 436.Sx \&dei . 437.Ss \&ami1 438Append to a macro definition, specifying the macro name indirectly 439and switching roff compatibility mode off during macro execution 440(groff extension). 441The syntax of this request is the same as that of 442.Sx \&dei1 . 443Since 444.Xr mandoc 1 445does not implement 446.Nm 447compatibility mode at all, it handles this request as an alias for 448.Sx \&ami . 449.Ss \&as 450Append to a user-defined string. 451The syntax of this request is the same as that of 452.Sx \&ds . 453If a user-defined string with the specified name does not yet exist, 454it is set to the empty string before appending. 455.Ss \&as1 456Append to a user-defined string, switching roff compatibility mode off 457during macro execution (groff extension). 458The syntax of this request is the same as that of 459.Sx \&ds1 . 460Since 461.Xr mandoc 1 462does not implement 463.Nm 464compatibility mode at all, it handles this request as an alias for 465.Sx \&as . 466.Ss \&asciify 467Fully unformat a diversion. 468Currently unsupported. 469.Ss \&backtrace 470Print a backtrace of the input stack. 471This is a groff extension and currently ignored. 472.Ss \&bd 473Artificially embolden by repeated printing with small shifts. 474Currently ignored. 475.Ss \&bleedat 476Set the BleedBox page parameter for PDF generation. 477This is a Heirloom extension and currently ignored. 478.Ss \&blm 479Set a blank line trap. 480Currently unsupported. 481.Ss \&box 482Begin a diversion without including a partially filled line. 483Currently unsupported. 484.Ss \&boxa 485Add to a diversion without including a partially filled line. 486Currently unsupported. 487.Ss \&bp 488Begin new page. 489Currently ignored. 490.Ss \&BP 491Define a frame and place a picture in it. 492This is a Heirloom extension and currently unsupported. 493.Ss \&br 494Break the output line. 495See 496.Xr man 7 497and 498.Xr mdoc 7 . 499.Ss \&break 500Break out of a 501.Sx \&while 502loop. 503Currently unsupported. 504.Ss \&breakchar 505Optional line break characters. 506This is a Heirloom extension and currently ignored. 507.Ss \&brnl 508Break output line after next N input lines. 509This is a Heirloom extension and currently ignored. 510.Ss \&brp 511Break and spread output line. 512Currently, this is implemented as an alias for 513.Sx \&br . 514.Ss \&brpnl 515Break and spread output line after next N input lines. 516This is a Heirloom extension and currently ignored. 517.Ss \&c2 518Change the no-break control character. 519Currently unsupported. 520.Ss \&cc 521Change the control character. 522Its syntax is as follows: 523.Bd -literal -offset indent 524.Pf . Cm \&cc Op Ar c 525.Ed 526.Pp 527If 528.Ar c 529is not specified, the control character is reset to 530.Sq \&. . 531Trailing characters are ignored. 532.Ss \&ce 533Center some lines. 534It takes one integer argument, specifying how many lines to center. 535Currently ignored. 536.Ss \&cf 537Output the contents of a file. 538Ignored because insecure. 539.Ss \&cflags 540Set character flags. 541This is a groff extension and currently ignored. 542.Ss \&ch 543Change a trap location. 544Currently ignored. 545.Ss \&char 546Define a new glyph. 547Currently unsupported. 548.Ss \&chop 549Remove the last character from a macro, string, or diversion. 550Currently unsupported. 551.Ss \&class 552Define a character class. 553This is a groff extension and currently ignored. 554.Ss \&close 555Close an open file. 556Ignored because insecure. 557.Ss \&CL 558Print text in color. 559This is a Heirloom extension and currently unsupported. 560.Ss \&color 561Activate or deactivate colors. 562This is a groff extension and currently ignored. 563.Ss \&composite 564Define a name component for composite glyph names. 565This is a groff extension and currently unsupported. 566.Ss \&continue 567Immediately start the next iteration of a 568.Sx \&while 569loop. 570Currently unsupported. 571.Ss \&cp 572Switch 573.Nm 574compatibility mode on or off. 575Currently ignored. 576.Ss \&cropat 577Set the CropBox page parameter for PDF generation. 578This is a Heirloom extension and currently ignored. 579.Ss \&cs 580Constant character spacing mode. 581Currently ignored. 582.Ss \&cu 583Underline including whitespace. 584Currently ignored. 585.Ss \&da 586Append to a diversion. 587Currently unsupported. 588.Ss \&dch 589Change a trap location in the current diversion. 590This is a Heirloom extension and currently unsupported. 591.Ss \&de 592Define a 593.Nm 594macro. 595Its syntax can be either 596.Bd -literal -offset indent 597.Pf . Cm \&de Ar name 598.Ar macro definition 599\&.. 600.Ed 601.Pp 602or 603.Bd -literal -offset indent 604.Pf . Cm \&de Ar name Ar end 605.Ar macro definition 606.Pf . Ar end 607.Ed 608.Pp 609Both forms define or redefine the macro 610.Ar name 611to represent the 612.Ar macro definition , 613which may consist of one or more input lines, including the newline 614characters terminating each line, optionally containing calls to 615.Nm 616requests, 617.Nm 618macros or high-level macros like 619.Xr man 7 620or 621.Xr mdoc 7 622macros, whichever applies to the document in question. 623.Pp 624Specifying a custom 625.Ar end 626macro works in the same way as for 627.Sx \&ig ; 628namely, the call to 629.Sq Pf . Ar end 630first ends the 631.Ar macro definition , 632and after that, it is also evaluated as a 633.Nm 634request or 635.Nm 636macro, but not as a high-level macro. 637.Pp 638The macro can be invoked later using the syntax 639.Pp 640.D1 Pf . Ar name Op Ar argument Op Ar argument ... 641.Pp 642Regarding argument parsing, see 643.Sx MACRO SYNTAX 644above. 645.Pp 646The line invoking the macro will be replaced 647in the input stream by the 648.Ar macro definition , 649replacing all occurrences of 650.No \e\e$ Ns Ar N , 651where 652.Ar N 653is a digit, by the 654.Ar N Ns th Ar argument . 655For example, 656.Bd -literal -offset indent 657\&.de ZN 658\efI\e^\e\e$1\e^\efP\e\e$2 659\&.. 660\&.ZN XtFree . 661.Ed 662.Pp 663produces 664.Pp 665.D1 \efI\e^XtFree\e^\efP. 666.Pp 667in the input stream, and thus in the output: \fI\^XtFree\^\fP. 668Each occurrence of \e\e$* is replaced with all the arguments, 669joined together with single blank characters. 670.Pp 671Since macros and user-defined strings share a common string table, 672defining a macro 673.Ar name 674clobbers the user-defined string 675.Ar name , 676and the 677.Ar macro definition 678can also be printed using the 679.Sq \e* 680string interpolation syntax described below 681.Sx ds , 682but this is rarely useful because every macro definition contains at least 683one explicit newline character. 684.Pp 685In order to prevent endless recursion, both groff and 686.Xr mandoc 1 687limit the stack depth for expanding macros and strings 688to a large, but finite number, and 689.Xr mandoc 1 690also limits the length of the expanded input line. 691Do not rely on the exact values of these limits. 692.Ss \&de1 693Define a 694.Nm 695macro that will be executed with 696.Nm 697compatibility mode switched off during macro execution. 698This is a groff extension. 699Since 700.Xr mandoc 1 701does not implement 702.Nm 703compatibility mode at all, it handles this request as an alias for 704.Sx \&de . 705.Ss \&defcolor 706Define a color name. 707This is a groff extension and currently ignored. 708.Ss \&dei 709Define a 710.Nm 711macro, specifying the macro name indirectly (groff extension). 712The syntax of this request is the same as that of 713.Sx \&de . 714The request 715.Pp 716.D1 Pf . Cm \&dei Ar name Op Ar end 717.Pp 718has the same effect as: 719.Pp 720.D1 Pf . Cm \&de No \e* Ns Bo Ar name Bc Op \e* Ns Bq Ar end 721.Ss \&dei1 722Define a 723.Nm 724macro that will be executed with 725.Nm 726compatibility mode switched off during macro execution, 727specifying the macro name indirectly (groff extension). 728Since 729.Xr mandoc 1 730does not implement 731.Nm 732compatibility mode at all, it handles this request as an alias for 733.Sx \&dei . 734.Ss \&device 735This request only makes sense with the groff-specific intermediate 736output format and is unsupported. 737.Ss \&devicem 738This request only makes sense with the groff-specific intermediate 739output format and is unsupported. 740.Ss \&di 741Begin a diversion. 742Currently unsupported. 743.Ss \&do 744Execute 745.Nm 746request or macro line with compatibility mode disabled. 747Currently unsupported. 748.Ss \&ds 749Define a user-defined string. 750Its syntax is as follows: 751.Pp 752.D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string 753.Pp 754The 755.Ar name 756and 757.Ar string 758arguments are space-separated. 759If the 760.Ar string 761begins with a double-quote character, that character will not be part 762of the string. 763All remaining characters on the input line form the 764.Ar string , 765including whitespace and double-quote characters, even trailing ones. 766.Pp 767The 768.Ar string 769can be interpolated into subsequent text by using 770.No \e* Ns Bq Ar name 771for a 772.Ar name 773of arbitrary length, or \e*(NN or \e*N if the length of 774.Ar name 775is two or one characters, respectively. 776Interpolation can be prevented by escaping the leading backslash; 777that is, an asterisk preceded by an even number of backslashes 778does not trigger string interpolation. 779.Pp 780Since user-defined strings and macros share a common string table, 781defining a string 782.Ar name 783clobbers the macro 784.Ar name , 785and the 786.Ar name 787used for defining a string can also be invoked as a macro, 788in which case the following input line will be appended to the 789.Ar string , 790forming a new input line passed to the 791.Nm 792parser. 793For example, 794.Bd -literal -offset indent 795\&.ds badidea .S 796\&.badidea 797H SYNOPSIS 798.Ed 799.Pp 800invokes the 801.Cm SH 802macro when used in a 803.Xr man 7 804document. 805Such abuse is of course strongly discouraged. 806.Ss \&ds1 807Define a user-defined string that will be expanded with 808.Nm 809compatibility mode switched off during string expansion. 810This is a groff extension. 811Since 812.Xr mandoc 1 813does not implement 814.Nm 815compatibility mode at all, it handles this request as an alias for 816.Sx \&ds . 817.Ss \&dwh 818Set a location trap in the current diversion. 819This is a Heirloom extension and currently unsupported. 820.Ss \&dt 821Set a trap within a diversion. 822Currently unsupported. 823.Ss \&ec 824Change the escape character. 825Currently unsupported. 826.Ss \&ecs 827Restore the escape character. 828Currently unsupported. 829.Ss \&ecr 830Save the escape character. 831Currently unsupported. 832.Ss \&el 833The 834.Qq else 835half of an if/else conditional. 836Pops a result off the stack of conditional evaluations pushed by 837.Sx \&ie 838and uses it as its conditional. 839If no stack entries are present (e.g., due to no prior 840.Sx \&ie 841calls) 842then false is assumed. 843The syntax of this request is similar to 844.Sx \&if 845except that the conditional is missing. 846.Ss \&em 847Set a trap at the end of input. 848Currently unsupported. 849.Ss \&EN 850End an equation block. 851See 852.Sx \&EQ . 853.Ss \&eo 854Disable the escape mechanism completely. 855Currently unsupported. 856.Ss \&EP 857End a picture started by 858.Sx \&BP . 859This is a Heirloom extension and currently unsupported. 860.Ss \&EQ 861Begin an equation block. 862See 863.Xr eqn 7 864for a description of the equation language. 865.Ss \&errprint 866Print a string like an error message. 867This is a Heirloom extension and currently ignored. 868.Ss \&ev 869Switch to another environment. 870Currently unsupported. 871.Ss \&evc 872Copy an environment into the current environment. 873Currently unsupported. 874.Ss \&ex 875Abort processing and exit. 876Currently unsupported. 877.Ss \&fallback 878Select the fallback sequence for a font. 879This is a Heirloom extension and currently ignored. 880.Ss \&fam 881Change the font family. 882Takes one argument specifying the font family to be selected. 883It is a groff extension and currently ignored. 884.Ss \&fc 885Define a delimiting and a padding character for fields. 886Currently unsupported. 887.Ss \&fchar 888Define a fallback glyph. 889Currently unsupported. 890.Ss \&fcolor 891Set the fill color for \eD objects. 892This is a groff extension and currently ignored. 893.Ss \&fdeferlig 894Defer ligature building. 895This is a Heirloom extension and currently ignored. 896.Ss \&feature 897Enable or disable an OpenType feature. 898This is a Heirloom extension and currently ignored. 899.Ss \&fi 900Switch to fill mode. 901See 902.Xr man 7 . 903Ignored in 904.Xr mdoc 7 . 905.Ss \&fkern 906Control the use of kerning tables for a font. 907This is a Heirloom extension and currently ignored. 908.Ss \&fl 909Flush output. 910Currently ignored. 911.Ss \&flig 912Define ligatures. 913This is a Heirloom extension and currently ignored. 914.Ss \&fp 915Assign font position. 916Currently ignored. 917.Ss \&fps 918Mount a font with a special character map. 919This is a Heirloom extension and currently ignored. 920.Ss \&fschar 921Define a font-specific fallback glyph. 922This is a groff extension and currently unsupported. 923.Ss \&fspacewidth 924Set a font-specific width for the space character. 925This is a Heirloom extension and currently ignored. 926.Ss \&fspecial 927Conditionally define a special font. 928This is a groff extension and currently ignored. 929.Ss \&ft 930Change the font. 931Its syntax is as follows: 932.Pp 933.D1 Pf . Cm \&ft Op Ar font 934.Pp 935The following 936.Ar font 937arguments are supported: 938.Bl -tag -width 4n -offset indent 939.It Cm B , BI , 3 , 4 940switches to 941.Sy bold 942font 943.It Cm I , 2 944switches to 945.Em underlined 946font 947.It Cm R , CW , 1 948switches to normal font 949.It Cm P No "or no argument" 950switches back to the previous font 951.El 952.Pp 953This request takes effect only locally, may be overridden by macros 954and escape sequences, and is only supported in 955.Xr man 7 956for now. 957.Ss \&ftr 958Translate font name. 959This is a groff extension and currently ignored. 960.Ss \&fzoom 961Zoom font size. 962Currently ignored. 963.Ss \&gcolor 964Set glyph color. 965This is a groff extension and currently ignored. 966.Ss \&hc 967Set the hyphenation character. 968Currently ignored. 969.Ss \&hcode 970Set hyphenation codes of characters. 971Currently ignored. 972.Ss \&hidechar 973Hide characters in a font. 974This is a Heirloom extension and currently ignored. 975.Ss \&hla 976Set hyphenation language. 977This is a groff extension and currently ignored. 978.Ss \&hlm 979Set maximum number of consecutive hyphenated lines. 980Currently ignored. 981.Ss \&hpf 982Load hyphenation pattern file. 983This is a groff extension and currently ignored. 984.Ss \&hpfa 985Load hyphenation pattern file, appending to the current patterns. 986This is a groff extension and currently ignored. 987.Ss \&hpfcode 988Define mapping values for character codes in hyphenation patterns. 989This is a groff extension and currently ignored. 990.Ss \&hw 991Specify hyphenation points in words. 992Currently ignored. 993.Ss \&hy 994Set automatic hyphenation mode. 995Currently ignored. 996.Ss \&hylang 997Set hyphenation language. 998This is a Heirloom extension and currently ignored. 999.Ss \&hylen 1000Minimum word length for hyphenation. 1001This is a Heirloom extension and currently ignored. 1002.Ss \&hym 1003Set hyphenation margin. 1004This is a groff extension and currently ignored. 1005.Ss \&hypp 1006Define hyphenation penalties. 1007This is a Heirloom extension and currently ignored. 1008.Ss \&hys 1009Set hyphenation space. 1010This is a groff extension and currently ignored. 1011.Ss \&ie 1012The 1013.Qq if 1014half of an if/else conditional. 1015The result of the conditional is pushed into a stack used by subsequent 1016invocations of 1017.Sx \&el , 1018which may be separated by any intervening input (or not exist at all). 1019Its syntax is equivalent to 1020.Sx \&if . 1021.Ss \&if 1022Begins a conditional. 1023This request has the following syntax: 1024.Bd -literal -offset indent 1025\&.if COND BODY 1026.Ed 1027.Bd -literal -offset indent 1028\&.if COND \e{BODY 1029BODY...\e} 1030.Ed 1031.Bd -literal -offset indent 1032\&.if COND \e{\e 1033BODY... 1034\&.\e} 1035.Ed 1036.Pp 1037COND is a conditional statement. 1038Currently, 1039.Xr mandoc 1 1040supports the following subset of roff conditionals: 1041.Bl -bullet 1042.It 1043If 1044.Sq \&! 1045is prefixed to COND, the condition is logically inverted. 1046.It 1047If the first character of COND is 1048.Sq n 1049.Pq nroff mode 1050or 1051.Sq o 1052.Pq odd page , 1053COND evaluates to true. 1054.It 1055If the first character of COND is 1056.Sq c 1057.Pq character available , 1058.Sq d 1059.Pq string defined , 1060.Sq e 1061.Pq even page , 1062.Sq t 1063.Pq troff mode , 1064or 1065.Sq v 1066.Pq vroff mode , 1067COND evaluates to false. 1068.It 1069If the first character of COND is 1070.Sq r , 1071it evaluates to true if the rest of COND is the name of an existing 1072number register; otherwise, it evaluates to false. 1073.It 1074If COND starts with a parenthesis or with an optionally signed 1075integer number, it is evaluated according to the rules of 1076.Sx Numerical expressions 1077explained below. 1078It evaluates to true if the result is positive, 1079or to false if the result is zero or negative. 1080.It 1081Otherwise, the first character of COND is regarded as a delimiter 1082and COND evaluates to true if the string extending from its first 1083to its second occurrence is equal to the string extending from its 1084second to its third occurrence. 1085.It 1086If COND cannot be parsed, it evaluates to false. 1087.El 1088.Pp 1089If a conditional is false, its children are not processed, but are 1090syntactically interpreted to preserve the integrity of the input 1091document. 1092Thus, 1093.Pp 1094.D1 \&.if t .ig 1095.Pp 1096will discard the 1097.Sq \&.ig , 1098which may lead to interesting results, but 1099.Pp 1100.D1 \&.if t .if t \e{\e 1101.Pp 1102will continue to syntactically interpret to the block close of the final 1103conditional. 1104Sub-conditionals, in this case, obviously inherit the truth value of 1105the parent. 1106.Pp 1107If the BODY section is begun by an escaped brace 1108.Sq \e{ , 1109scope continues until the end of the input line containing the 1110matching closing-brace escape sequence 1111.Sq \e} . 1112If the BODY is not enclosed in braces, scope continues until 1113the end of the line. 1114If the COND is followed by a BODY on the same line, whether after a 1115brace or not, then requests and macros 1116.Em must 1117begin with a control character. 1118It is generally more intuitive, in this case, to write 1119.Bd -literal -offset indent 1120\&.if COND \e{\e 1121\&.foo 1122bar 1123\&.\e} 1124.Ed 1125.Pp 1126than having the request or macro follow as 1127.Pp 1128.D1 \&.if COND \e{ .foo 1129.Pp 1130The scope of a conditional is always parsed, but only executed if the 1131conditional evaluates to true. 1132.Pp 1133Note that the 1134.Sq \e} 1135is converted into a zero-width escape sequence if not passed as a 1136standalone macro 1137.Sq \&.\e} . 1138For example, 1139.Pp 1140.D1 \&.Fl a \e} b 1141.Pp 1142will result in 1143.Sq \e} 1144being considered an argument of the 1145.Sq \&Fl 1146macro. 1147.Ss \&ig 1148Ignore input. 1149Its syntax can be either 1150.Bd -literal -offset indent 1151.Pf . Cm \&ig 1152.Ar ignored text 1153\&.. 1154.Ed 1155.Pp 1156or 1157.Bd -literal -offset indent 1158.Pf . Cm \&ig Ar end 1159.Ar ignored text 1160.Pf . Ar end 1161.Ed 1162.Pp 1163In the first case, input is ignored until a 1164.Sq \&.. 1165request is encountered on its own line. 1166In the second case, input is ignored until the specified 1167.Sq Pf . Ar end 1168macro is encountered. 1169Do not use the escape character 1170.Sq \e 1171anywhere in the definition of 1172.Ar end ; 1173it would cause very strange behaviour. 1174.Pp 1175When the 1176.Ar end 1177macro is a roff request or a roff macro, like in 1178.Pp 1179.D1 \&.ig if 1180.Pp 1181the subsequent invocation of 1182.Sx \&if 1183will first terminate the 1184.Ar ignored text , 1185then be invoked as usual. 1186Otherwise, it only terminates the 1187.Ar ignored text , 1188and arguments following it or the 1189.Sq \&.. 1190request are discarded. 1191.Ss \&in 1192Change indentation. 1193See 1194.Xr man 7 . 1195Ignored in 1196.Xr mdoc 7 . 1197.Ss \&index 1198Find a substring in a string. 1199This is a Heirloom extension and currently unsupported. 1200.Ss \&it 1201Set an input line trap. 1202Its syntax is as follows: 1203.Pp 1204.D1 Pf . Cm it Ar expression macro 1205.Pp 1206The named 1207.Ar macro 1208will be invoked after processing the number of input text lines 1209specified by the numerical 1210.Ar expression . 1211While evaluating the 1212.Ar expression , 1213the unit suffixes described below 1214.Sx Scaling Widths 1215are ignored. 1216.Ss \&itc 1217Set an input line trap, not counting lines ending with \ec. 1218Currently unsupported. 1219.Ss \&IX 1220To support the generation of a table of contents, 1221.Xr pod2man 1 1222emits this user-defined macro, usually without defining it. 1223To avoid reporting large numbers of spurious errors, 1224.Xr mandoc 1 1225ignores it. 1226.Ss \&kern 1227Switch kerning on or off. 1228Currently ignored. 1229.Ss \&kernafter 1230Increase kerning after some characters. 1231This is a Heirloom extension and currently ignored. 1232.Ss \&kernbefore 1233Increase kerning before some characters. 1234This is a Heirloom extension and currently ignored. 1235.Ss \&kernpair 1236Add a kerning pair to the kerning table. 1237This is a Heirloom extension and currently ignored. 1238.Ss \&lc 1239Define a leader repetition character. 1240Currently unsupported. 1241.Ss \&lc_ctype 1242Set the 1243.Dv LC_CTYPE 1244locale. 1245This is a Heirloom extension and currently unsupported. 1246.Ss \&lds 1247Define a local string. 1248This is a Heirloom extension and currently unsupported. 1249.Ss \&length 1250Count the number of input characters in a user-defined string. 1251Currently unsupported. 1252.Ss \&letadj 1253Dynamic letter spacing and reshaping. 1254This is a Heirloom extension and currently ignored. 1255.Ss \&lf 1256Change the line number for error messages. 1257Ignored because insecure. 1258.Ss \&lg 1259Switch the ligature mechanism on or off. 1260Currently ignored. 1261.Ss \&lhang 1262Hang characters at left margin. 1263This is a Heirloom extension and currently ignored. 1264.Ss \&linetabs 1265Enable or disable line-tabs mode. 1266This is a groff extension and currently unsupported. 1267.Ss \&ll 1268Change the output line length. 1269Its syntax is as follows: 1270.Pp 1271.D1 Pf . Cm \&ll Op Oo +|- Oc Ns Ar width 1272.Pp 1273If the 1274.Ar width 1275argument is omitted, the line length is reset to its previous value. 1276The default setting for terminal output is 78n. 1277If a sign is given, the line length is added to or subtracted from; 1278otherwise, it is set to the provided value. 1279Using this request in new manuals is discouraged for several reasons, 1280among others because it overrides the 1281.Xr mandoc 1 1282.Fl O Cm width 1283command line option. 1284.Ss \&lnr 1285Set local number register. 1286This is a Heirloom extension and currently unsupported. 1287.Ss \&lnrf 1288Set local floating-point register. 1289This is a Heirloom extension and currently unsupported. 1290.Ss \&lpfx 1291Set a line prefix. 1292This is a Heirloom extension and currently unsupported. 1293.Ss \&ls 1294Set line spacing. 1295It takes one integer argument specifying the vertical distance of 1296subsequent output text lines measured in v units. 1297Currently ignored. 1298.Ss \&lsm 1299Set a leading spaces trap. 1300This is a groff extension and currently unsupported. 1301.Ss \< 1302Set title line length. 1303Currently ignored. 1304.Ss \&mc 1305Print margin character in the right margin. 1306Currently ignored. 1307.Ss \&mediasize 1308Set the device media size. 1309This is a Heirloom extension and currently ignored. 1310.Ss \&minss 1311Set minimum word space. 1312This is a Heirloom extension and currently ignored. 1313.Ss \&mk 1314Mark vertical position. 1315Currently ignored. 1316.Ss \&mso 1317Load a macro file. 1318Ignored because insecure. 1319.Ss \&na 1320Disable adjusting without changing the adjustment mode. 1321Currently ignored. 1322.Ss \&ne 1323Declare the need for the specified minimum vertical space 1324before the next trap or the bottom of the page. 1325Currently ignored. 1326.Ss \&nf 1327Switch to no-fill mode. 1328See 1329.Xr man 7 . 1330Ignored by 1331.Xr mdoc 7 . 1332.Ss \&nh 1333Turn off automatic hyphenation mode. 1334Currently ignored. 1335.Ss \&nhychar 1336Define hyphenation-inhibiting characters. 1337This is a Heirloom extension and currently ignored. 1338.Ss \&nm 1339Print line numbers. 1340Currently unsupported. 1341.Ss \&nn 1342Temporarily turn off line numbering. 1343Currently unsupported. 1344.Ss \&nop 1345Execute the rest of the input line as a request or macro line. 1346Currently unsupported. 1347.Ss \&nr 1348Define or change a register. 1349A register is an arbitrary string value that defines some sort of state, 1350which influences parsing and/or formatting. 1351Its syntax is as follows: 1352.Pp 1353.D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar expression 1354.Pp 1355For the syntax of 1356.Ar expression , 1357see 1358.Sx Numerical expressions 1359below. 1360If it is prefixed by a sign, the register will be 1361incremented or decremented instead of assigned to. 1362.Pp 1363The following register 1364.Ar name 1365is handled specially: 1366.Bl -tag -width Ds 1367.It Cm nS 1368If set to a positive integer value, certain 1369.Xr mdoc 7 1370macros will behave in the same way as in the 1371.Em SYNOPSIS 1372section. 1373If set to 0, these macros will behave in the same way as outside the 1374.Em SYNOPSIS 1375section, even when called within the 1376.Em SYNOPSIS 1377section itself. 1378Note that starting a new 1379.Xr mdoc 7 1380section with the 1381.Cm \&Sh 1382macro will reset this register. 1383.El 1384.Ss \&nrf 1385Define or change a floating-point register. 1386This is a Heirloom extension and currently unsupported. 1387.Ss \&nroff 1388Force nroff mode. 1389This is a groff extension and currently ignored. 1390.Ss \&ns 1391Turn on no-space mode. 1392Currently ignored. 1393.Ss \&nx 1394Abort processing of the current input file and process another one. 1395Ignored because insecure. 1396.Ss \&open 1397Open a file for writing. 1398Ignored because insecure. 1399.Ss \&opena 1400Open a file for appending. 1401Ignored because insecure. 1402.Ss \&os 1403Output saved vertical space. 1404Currently ignored. 1405.Ss \&output 1406Output directly to intermediate output. 1407Not supported. 1408.Ss \&padj 1409Globally control paragraph-at-once adjustment. 1410This is a Heirloom extension and currently ignored. 1411.Ss \&papersize 1412Set the paper size. 1413This is a Heirloom extension and currently ignored. 1414.Ss \&pc 1415Change the page number character. 1416Currently ignored. 1417.Ss \&pev 1418Print environments. 1419This is a groff extension and currently ignored. 1420.Ss \&pi 1421Pipe output to a shell command. 1422Ignored because insecure. 1423.Ss \&PI 1424Low-level request used by 1425.Sx \&BP . 1426This is a Heirloom extension and currently unsupported. 1427.Ss \&pl 1428Change page length. 1429Takes one height argument. 1430Currently ignored. 1431.Ss \&pm 1432Print names and sizes of macros, strings, and diversions. 1433Currently ignored. 1434.Ss \&pn 1435Change page number of the next page. 1436Currently ignored. 1437.Ss \&pnr 1438Print all number registers. 1439Currently ignored. 1440.Ss \&po 1441Set horizontal page offset. 1442Currently ignored. 1443.Ss \&ps 1444Change point size. 1445Takes one numerical argument. 1446Currently ignored. 1447.Ss \&psbb 1448Retrieve the bounding box of a PostScript file. 1449Currently unsupported. 1450.Ss \&pshape 1451Set a special shape for the current paragraph. 1452This is a Heirloom extension and currently unsupported. 1453.Ss \&pso 1454Include output of a shell command. 1455Ignored because insecure. 1456.Ss \&ptr 1457Print the names and positions of all traps. 1458This is a groff extension and currently ignored. 1459.Ss \&pvs 1460Change post-vertical spacing. 1461This is a groff extension and currently ignored. 1462.Ss \&rchar 1463Remove glyph definitions. 1464Currently unsupported. 1465.Ss \&rd 1466Read from standard input. 1467Currently ignored. 1468.Ss \&recursionlimit 1469Set the maximum stack depth for recursive macros. 1470This is a Heirloom extension and currently ignored. 1471.Ss \&return 1472Exit a macro and return to the caller. 1473Currently unsupported. 1474.Ss \&rfschar 1475Remove font-specific fallback glyph definitions. 1476Currently unsupported. 1477.Ss \&rhang 1478Hang characters at right margin. 1479This is a Heirloom extension and currently ignored. 1480.Ss \&rj 1481Justify unfilled text to the right margin. 1482Currently ignored. 1483.Ss \&rm 1484Remove a request, macro or string. 1485Its syntax is as follows: 1486.Pp 1487.D1 Pf \. Cm \&rm Ar name 1488.Ss \&rn 1489Rename a request, macro, diversion, or string. 1490Currently unsupported. 1491.Ss \&rnn 1492Rename a number register. 1493Currently unsupported. 1494.Ss \&rr 1495Remove a register. 1496Its syntax is as follows: 1497.Pp 1498.D1 Pf \. Cm \&rr Ar name 1499.Ss \&rs 1500End no-space mode. 1501Currently ignored. 1502.Ss \&rt 1503Return to marked vertical position. 1504Currently ignored. 1505.Ss \&schar 1506Define global fallback glyph. 1507This is a groff extension and currently unsupported. 1508.Ss \&sentchar 1509Define sentence-ending characters. 1510This is a Heirloom extension and currently ignored. 1511.Ss \&shc 1512Change the soft hyphen character. 1513Currently ignored. 1514.Ss \&shift 1515Shift macro arguments. 1516Currently unsupported. 1517.Ss \&sizes 1518Define permissible point sizes. 1519This is a groff extension and currently ignored. 1520.Ss \&so 1521Include a source file. 1522Its syntax is as follows: 1523.Pp 1524.D1 Pf \. Cm \&so Ar file 1525.Pp 1526The 1527.Ar file 1528will be read and its contents processed as input in place of the 1529.Sq \&.so 1530request line. 1531To avoid inadvertent inclusion of unrelated files, 1532.Xr mandoc 1 1533only accepts relative paths not containing the strings 1534.Qq ../ 1535and 1536.Qq /.. . 1537.Pp 1538This request requires 1539.Xr man 1 1540to change to the right directory before calling 1541.Xr mandoc 1 , 1542per convention to the root of the manual tree. 1543Typical usage looks like: 1544.Pp 1545.Dl \&.so man3/Xcursor.3 1546.Pp 1547As the whole concept is rather fragile, the use of 1548.Sx \&so 1549is discouraged. 1550Use 1551.Xr ln 1 1552instead. 1553.Ss \&spacewidth 1554Set the space width from the font metrics file. 1555This is a Heirloom extension and currently ignored. 1556.Ss \&special 1557Define a special font. 1558This is a groff extension and currently ignored. 1559.Ss \&spreadwarn 1560Warn about wide spacing between words. 1561Currently ignored. 1562.Ss \&ss 1563Set space character size. 1564Currently ignored. 1565.Ss \&sty 1566Associate style with a font position. 1567This is a groff extension and currently ignored. 1568.Ss \&substring 1569Replace a user-defined string with a substring. 1570Currently unsupported. 1571.Ss \&sv 1572Save vertical space. 1573Currently ignored. 1574.Ss \&sy 1575Execute shell command. 1576Ignored because insecure. 1577.Ss \&T& 1578Re-start a table layout, retaining the options of the prior table 1579invocation. 1580See 1581.Sx \&TS . 1582.Ss \&ta 1583Set tab stops. 1584Takes an arbitrary number of arguments. 1585Currently unsupported. 1586.Ss \&tc 1587Change tab repetition character. 1588Currently unsupported. 1589.Ss \&TE 1590End a table context. 1591See 1592.Sx \&TS . 1593.Ss \&ti 1594Temporary indent. 1595Currently unsupported. 1596.Ss \&tkf 1597Enable track kerning for a font. 1598Currently ignored. 1599.Ss \&tl 1600Print a title line. 1601Currently unsupported. 1602.Ss \&tm 1603Print to standard error output. 1604Currently ignored. 1605.Ss \&tm1 1606Print to standard error output, allowing leading blanks. 1607This is a groff extension and currently ignored. 1608.Ss \&tmc 1609Print to standard error output without a trailing newline. 1610This is a groff extension and currently ignored. 1611.Ss \&tr 1612Output character translation. 1613Its syntax is as follows: 1614.Pp 1615.D1 Pf \. Cm \&tr Ar [ab]+ 1616.Pp 1617Pairs of 1618.Ar ab 1619characters are replaced 1620.Ar ( a 1621for 1622.Ar b ) . 1623Replacement (or origin) characters may also be character escapes; thus, 1624.Pp 1625.Dl tr \e(xx\e(yy 1626.Pp 1627replaces all invocations of \e(xx with \e(yy. 1628.Ss \&track 1629Static letter space tracking. 1630This is a Heirloom extension and currently ignored. 1631.Ss \&transchar 1632Define transparent characters for sentence-ending. 1633This is a Heirloom extension and currently ignored. 1634.Ss \&trf 1635Output the contents of a file, disallowing invalid characters. 1636This is a groff extension and ignored because insecure. 1637.Ss \&trimat 1638Set the TrimBox page parameter for PDF generation. 1639This is a Heirloom extension and currently ignored. 1640.Ss \&trin 1641Output character translation, ignored by 1642.Cm \&asciify . 1643Currently unsupported. 1644.Ss \&trnt 1645Output character translation, ignored by \e!. 1646Currently unsupported. 1647.Ss \&troff 1648Force troff mode. 1649This is a groff extension and currently ignored. 1650.Ss \&TS 1651Begin a table, which formats input in aligned rows and columns. 1652See 1653.Xr tbl 7 1654for a description of the tbl language. 1655.Ss \&uf 1656Globally set the underline font. 1657Currently ignored. 1658.Ss \&ul 1659Underline. 1660Currently ignored. 1661.Ss \&unformat 1662Unformat spaces and tabs in a diversion. 1663Currently unsupported. 1664.Ss \&unwatch 1665Disable notification for string or macro. 1666This is a Heirloom extension and currently ignored. 1667.Ss \&unwatchn 1668Disable notification for register. 1669This is a Heirloom extension and currently ignored. 1670.Ss \&vpt 1671Enable or disable vertical position traps. 1672This is a groff extension and currently ignored. 1673.Ss \&vs 1674Change vertical spacing. 1675Currently ignored. 1676.Ss \&warn 1677Set warning level. 1678Currently ignored. 1679.Ss \&warnscale 1680Set the scaling indicator used in warnings. 1681This is a groff extension and currently ignored. 1682.Ss \&watch 1683Notify on change of string or macro. 1684This is a Heirloom extension and currently ignored. 1685.Ss \&watchlength 1686On change, report the contents of macros and strings 1687up to the specified length. 1688This is a Heirloom extension and currently ignored. 1689.Ss \&watchn 1690Notify on change of register. 1691This is a Heirloom extension and currently ignored. 1692.Ss \&wh 1693Set a page location trap. 1694Currently unsupported. 1695.Ss \&while 1696Repeated execution while a condition is true. 1697Currently unsupported. 1698.Ss \&write 1699Write to an open file. 1700Ignored because insecure. 1701.Ss \&writec 1702Write to an open file without appending a newline. 1703Ignored because insecure. 1704.Ss \&writem 1705Write macro or string to an open file. 1706Ignored because insecure. 1707.Ss \&xflag 1708Set the extension level. 1709This is a Heirloom extension and currently ignored. 1710.Ss Numerical expressions 1711The 1712.Sx \&nr , 1713.Sx \&if , 1714and 1715.Sx \&ie 1716requests accept integer numerical expressions as arguments. 1717These are always evaluated using the C 1718.Vt int 1719type; integer overflow works the same way as in the C language. 1720Numbers consist of an arbitrary number of digits 1721.Sq 0 1722to 1723.Sq 9 1724prefixed by an optional sign 1725.Sq + 1726or 1727.Sq - . 1728Each number may be followed by one optional scaling unit described below 1729.Sx Scaling Widths . 1730The following equations hold: 1731.Bd -literal -offset indent 17321i = 6v = 6P = 10m = 10n = 72p = 1000M = 240u = 240 1733254c = 100i = 24000u = 24000 17341f = 65536u = 65536 1735.Ed 1736.Pp 1737The following binary operators are implemented. 1738Unless otherwise stated, they behave as in the C language: 1739.Pp 1740.Bl -tag -width 2n -compact 1741.It Ic + 1742addition 1743.It Ic - 1744subtraction 1745.It Ic * 1746multiplication 1747.It Ic / 1748division 1749.It Ic % 1750remainder of division 1751.It Ic < 1752less than 1753.It Ic > 1754greater than 1755.It Ic == 1756equal to 1757.It Ic = 1758equal to, same effect as 1759.Ic == 1760(this differs from C) 1761.It Ic <= 1762less than or equal to 1763.It Ic >= 1764greater than or equal to 1765.It Ic <> 1766not equal to (corresponds to C 1767.Ic != ; 1768this one is of limited portability, it is supported by Heirloom roff, 1769but not by groff) 1770.It Ic & 1771logical and (corresponds to C 1772.Ic && ) 1773.It Ic \&: 1774logical or (corresponds to C 1775.Ic \&|| ) 1776.It Ic <? 1777minimum (not available in C) 1778.It Ic >? 1779maximum (not available in C) 1780.El 1781.Pp 1782There is no concept of precedence; evaluation proceeds from left to right, 1783except when subexpressions are enclosed in parantheses. 1784Inside parentheses, whitespace is ignored. 1785.Sh ESCAPE SEQUENCE REFERENCE 1786The 1787.Xr mandoc 1 1788.Nm 1789parser recognises the following escape sequences. 1790Note that the 1791.Nm 1792language defines more escape sequences not implemented in 1793.Xr mandoc 1 . 1794In 1795.Xr mdoc 7 1796and 1797.Xr man 7 1798documents, using escape sequences is discouraged except for those 1799described in the 1800.Sx LANGUAGE SYNTAX 1801section above. 1802.Pp 1803A backslash followed by any character not listed here 1804simply prints that character itself. 1805.Ss \e<newline> 1806A backslash at the end of an input line can be used to continue the 1807logical input line on the next physical input line, joining the text 1808on both lines together as if it were on a single input line. 1809.Ss \e<space> 1810The escape sequence backslash-space 1811.Pq Sq \e\ \& 1812is an unpaddable space-sized non-breaking space character; see 1813.Sx Whitespace . 1814.Ss \e\(dq 1815The rest of the input line is treated as 1816.Sx Comments . 1817.Ss \e% 1818Hyphenation allowed at this point of the word; ignored by 1819.Xr mandoc 1 . 1820.Ss \e& 1821Non-printing zero-width character; see 1822.Sx Whitespace . 1823.Ss \e\(aq 1824Acute accent special character; use 1825.Sq \e(aa 1826instead. 1827.Ss \e( Ns Ar cc 1828.Sx Special Characters 1829with two-letter names, see 1830.Xr mandoc_char 7 . 1831.Ss \e*[ Ns Ar name ] 1832Interpolate the string with the 1833.Ar name ; 1834see 1835.Sx Predefined Strings 1836and 1837.Sx ds . 1838For short names, there are variants 1839.No \e* Ns Ar c 1840and 1841.No \e*( Ns Ar cc . 1842.Ss \e, 1843Left italic correction (groff extension); ignored by 1844.Xr mandoc 1 . 1845.Ss \e- 1846Special character 1847.Dq mathematical minus sign . 1848.Ss \e/ 1849Right italic correction (groff extension); ignored by 1850.Xr mandoc 1 . 1851.Ss \e[ Ns Ar name ] 1852.Sx Special Characters 1853with names of arbitrary length, see 1854.Xr mandoc_char 7 . 1855.Ss \e^ 1856One-twelfth em half-narrow space character, effectively zero-width in 1857.Xr mandoc 1 . 1858.Ss \e` 1859Grave accent special character; use 1860.Sq \e(ga 1861instead. 1862.Ss \e{ 1863Begin conditional input; see 1864.Sx if . 1865.Ss \e\(ba 1866One-sixth em narrow space character, effectively zero-width in 1867.Xr mandoc 1 . 1868.Ss \e} 1869End conditional input; see 1870.Sx if . 1871.Ss \e~ 1872Paddable non-breaking space character. 1873.Ss \e0 1874Digit width space character. 1875.Ss \eA\(aq Ns Ar string Ns \(aq 1876Anchor definition; ignored by 1877.Xr mandoc 1 . 1878.Ss \eB\(aq Ns Ar string Ns \(aq 1879Interpolate 1880.Sq 1 1881if 1882.Ar string 1883conforms to the syntax of 1884.Sx Numerical expressions 1885explained above and 1886.Sq 0 1887otherwise. 1888.Ss \eb\(aq Ns Ar string Ns \(aq 1889Bracket building function; ignored by 1890.Xr mandoc 1 . 1891.Ss \eC\(aq Ns Ar name Ns \(aq 1892.Sx Special Characters 1893with names of arbitrary length. 1894.Ss \ec 1895When encountered at the end of an input text line, 1896the next input text line is considered to continue that line, 1897even if there are request or macro lines in between. 1898No whitespace is inserted. 1899.Ss \eD\(aq Ns Ar string Ns \(aq 1900Draw graphics function; ignored by 1901.Xr mandoc 1 . 1902.Ss \ed 1903Move down by half a line; ignored by 1904.Xr mandoc 1 . 1905.Ss \ee 1906Backslash special character. 1907.Ss \eF[ Ns Ar name ] 1908Switch font family (groff extension); ignored by 1909.Xr mandoc 1 . 1910For short names, there are variants 1911.No \eF Ns Ar c 1912and 1913.No \eF( Ns Ar cc . 1914.Ss \ef[ Ns Ar name ] 1915Switch to the font 1916.Ar name , 1917see 1918.Sx Text Decoration . 1919For short names, there are variants 1920.No \ef Ns Ar c 1921and 1922.No \ef( Ns Ar cc . 1923.Ss \eg[ Ns Ar name ] 1924Interpolate the format of a number register; ignored by 1925.Xr mandoc 1 . 1926For short names, there are variants 1927.No \eg Ns Ar c 1928and 1929.No \eg( Ns Ar cc . 1930.Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq 1931Set the height of the current font; ignored by 1932.Xr mandoc 1 . 1933.Ss \eh\(aq Ns Ar number Ns \(aq 1934Horizontal motion; ignored by 1935.Xr mandoc 1 . 1936.Ss \ek[ Ns Ar name ] 1937Mark horizontal input place in register; ignored by 1938.Xr mandoc 1 . 1939For short names, there are variants 1940.No \ek Ns Ar c 1941and 1942.No \ek( Ns Ar cc . 1943.Ss \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq 1944Vertical line drawing function; ignored by 1945.Xr mandoc 1 . 1946.Ss \el\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq 1947Horizontal line drawing function; ignored by 1948.Xr mandoc 1 . 1949.Ss \eM[ Ns Ar name ] 1950Set fill (background) color (groff extension); ignored by 1951.Xr mandoc 1 . 1952For short names, there are variants 1953.No \eM Ns Ar c 1954and 1955.No \eM( Ns Ar cc . 1956.Ss \em[ Ns Ar name ] 1957Set glyph drawing color (groff extension); ignored by 1958.Xr mandoc 1 . 1959For short names, there are variants 1960.No \em Ns Ar c 1961and 1962.No \em( Ns Ar cc . 1963.Ss \eN\(aq Ns Ar number Ns \(aq 1964Character 1965.Ar number 1966on the current font. 1967.Ss \en[ Ns Ar name ] 1968Interpolate the number register 1969.Ar name . 1970For short names, there are variants 1971.No \en Ns Ar c 1972and 1973.No \en( Ns Ar cc . 1974.Ss \eo\(aq Ns Ar string Ns \(aq 1975Overstrike, writing all the characters contained in the 1976.Ar string 1977to the same output position. 1978In terminal and HTML output modes, 1979only the last one of the characters is visible. 1980.Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq 1981Set number register; ignored by 1982.Xr mandoc 1 . 1983.Ss \eS\(aq Ns Ar number Ns \(aq 1984Slant output; ignored by 1985.Xr mandoc 1 . 1986.Ss \es\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq 1987Change point size; ignored by 1988.Xr mandoc 1 . 1989Alternative forms 1990.No \es Ns Oo +|- Oc Ns Ar n , 1991.No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq , 1992.No \es Ns [ Oo +|- Oc Ns Ar number ] , 1993and 1994.No \es Ns Oo +|- Oc Ns [ Ar number Ns ] 1995are also parsed and ignored. 1996.Ss \et 1997Horizontal tab; ignored by 1998.Xr mandoc 1 . 1999.Ss \eu 2000Move up by half a line; ignored by 2001.Xr mandoc 1 . 2002.Ss \eV[ Ns Ar name ] 2003Interpolate an environment variable; ignored by 2004.Xr mandoc 1 . 2005For short names, there are variants 2006.No \eV Ns Ar c 2007and 2008.No \eV( Ns Ar cc . 2009.Ss \ev\(aq Ns Ar number Ns \(aq 2010Vertical motion; ignored by 2011.Xr mandoc 1 . 2012.Ss \ew\(aq Ns Ar string Ns \(aq 2013Interpolate the width of the 2014.Ar string . 2015The 2016.Xr mandoc 1 2017implementation assumes that after expansion of user-defined strings, the 2018.Ar string 2019only contains normal characters, no escape sequences, and that each 2020character has a width of 24 basic units. 2021.Ss \eX\(aq Ns Ar string Ns \(aq 2022Output 2023.Ar string 2024as device control function; ignored in nroff mode and by 2025.Xr mandoc 1 . 2026.Ss \ex\(aq Ns Ar number Ns \(aq 2027Extra line space function; ignored by 2028.Xr mandoc 1 . 2029.Ss \eY[ Ns Ar name ] 2030Output a string as a device control function; ignored in nroff mode and by 2031.Xr mandoc 1 . 2032For short names, there are variants 2033.No \eY Ns Ar c 2034and 2035.No \eY( Ns Ar cc . 2036.Ss \eZ\(aq Ns Ar string Ns \(aq 2037Print 2038.Ar string 2039with zero width and height; ignored by 2040.Xr mandoc 1 . 2041.Ss \ez 2042Output the next character without advancing the cursor position. 2043.Sh COMPATIBILITY 2044The 2045.Xr mandoc 1 2046implementation of the 2047.Nm 2048language is intentionally incomplete. 2049Unimplemented features include: 2050.Pp 2051.Bl -dash -compact 2052.It 2053For security reasons, 2054.Xr mandoc 1 2055never reads or writes external files except via 2056.Sx \&so 2057requests with safe relative paths. 2058.It 2059There is no automatic hyphenation, no adjustment to the right margin, 2060and no centering; the output is always set flush-left. 2061.It 2062Support for setting tabulator positions 2063and tabulator and leader characters is missing, 2064and support for manually changing indentation is limited. 2065.It 2066The 2067.Sq u 2068scaling unit is the default terminal unit. 2069In traditional troff systems, this unit changes depending on the 2070output media. 2071.It 2072Width measurements are implemented in a crude way 2073and often yield wrong results. 2074Explicit movement requests and escapes are ignored. 2075.It 2076There is no concept of output pages, no support for floats, 2077graphics drawing, and picture inclusion; 2078terminal output is always continuous. 2079.It 2080Requests regarding color, font families, and glyph manipulation 2081are ignored. 2082Font support is very limited. 2083Kerning is not implemented, and no ligatures are produced. 2084.It 2085The 2086.Qq \(aq 2087macro control character does not suppress output line breaks. 2088.It 2089Diversions are not implemented, 2090and support for traps is very incomplete. 2091.It 2092While recursion is supported, 2093.Sx \&while 2094loops are not. 2095.El 2096.Pp 2097The special semantics of the 2098.Cm nS 2099number register is an idiosyncracy of 2100.Ox 2101manuals and not supported by other 2102.Xr mdoc 7 2103implementations. 2104.Sh SEE ALSO 2105.Xr mandoc 1 , 2106.Xr eqn 7 , 2107.Xr man 7 , 2108.Xr mandoc_char 7 , 2109.Xr mdoc 7 , 2110.Xr tbl 7 2111.Rs 2112.%A Joseph F. Ossanna 2113.%A Brian W. Kernighan 2114.%I AT&T Bell Laboratories 2115.%T Troff User's Manual 2116.%R Computing Science Technical Report 2117.%N 54 2118.%C Murray Hill, New Jersey 2119.%D 1976 and 1992 2120.%U http://www.kohala.com/start/troff/cstr54.ps 2121.Re 2122.Rs 2123.%A Joseph F. Ossanna 2124.%A Brian W. Kernighan 2125.%A Gunnar Ritter 2126.%T Heirloom Documentation Tools Nroff/Troff User's Manual 2127.%D September 17, 2007 2128.%U http://heirloom.sourceforge.net/doctools/troff.pdf 2129.Re 2130.Sh HISTORY 2131The RUNOFF typesetting system, whose input forms the basis for 2132.Nm , 2133was written in MAD and FAP for the CTSS operating system by Jerome E. 2134Saltzer in 1964. 2135Doug McIlroy rewrote it in BCPL in 1969, renaming it 2136.Nm . 2137Dennis M. Ritchie rewrote McIlroy's 2138.Nm 2139in PDP-11 assembly for 2140.At v1 , 2141Joseph F. Ossanna improved roff and renamed it nroff 2142for 2143.At v2 , 2144then ported nroff to C as troff, which Brian W. Kernighan released with 2145.At v7 . 2146In 1989, James Clarke re-implemented troff in C++, naming it groff. 2147.Sh AUTHORS 2148.An -nosplit 2149This 2150.Nm 2151reference was written by 2152.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv 2153and 2154.An Ingo Schwarze Aq Mt schwarze@openbsd.org . 2155