troff.man revision 79543
1.ig 2Copyright (C) 1989-2000, 2001 Free Software Foundation, Inc. 3 4Permission is granted to make and distribute verbatim copies of 5this manual provided the copyright notice and this permission notice 6are preserved on all copies. 7 8Permission is granted to copy and distribute modified versions of this 9manual under the conditions for verbatim copying, provided that the 10entire resulting derived work is distributed under the terms of a 11permission notice identical to this one. 12 13Permission is granted to copy and distribute translations of this 14manual into another language, under the above conditions for modified 15versions, except that this permission notice may be included in 16translations approved by the Free Software Foundation instead of in 17the original English. 18.. 19. 20.\" define a string tx for the TeX logo 21.ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X 22.el .ds tx TeX 23. 24.de TQ 25.br 26.ns 27.TP \\$1 28.. 29. 30.\" Like TP, but if specified indent is more than half 31.\" the current line-length - indent, use the default indent. 32.de Tp 33.ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP 34.el .TP "\\$1" 35.. 36. 37.\" The BSD man macros can't handle " in arguments to font change macros, 38.\" so use \(ts instead of ". 39.tr \(ts" 40. 41. 42.TH @G@TROFF @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@" 43. 44. 45.SH NAME 46. 47. 48@g@troff \- format documents 49. 50. 51.SH SYNOPSIS 52. 53. 54.nr a \n(.j 55.ad l 56.nr i \n(.i 57.in +\w'\fB@g@troff 'u 58.ti \niu 59.B @g@troff 60.de OP 61.ie \\n(.$-1 .RI "[\ \fB\\$1\fP" "\\$2" "\ ]" 62.el .RB "[\ " "\\$1" "\ ]" 63.. 64.OP \-abivzCERU 65.OP \-w name 66.OP \-W name 67.OP \-d cs 68.OP \-f fam 69.OP \-m name 70.OP \-n num 71.OP \-o list 72.OP \-r cn 73.OP \-T name 74.OP \-F dir 75.OP \-M dir 76.RI "[\ " files\|.\|.\|. "\ ]" 77.br 78.ad \na 79.PP 80It is possible to have whitespace between a command line option and its 81parameter. 82. 83. 84.SH DESCRIPTION 85. 86. 87This manual page describes the GNU version of 88.BR troff , 89which is part of the groff document formatting system. 90It is highly compatible with UNIX troff. 91Usually it should be invoked using the groff command, which will 92also run preprocessors and postprocessors in the appropriate 93order and with the appropriate options. 94. 95. 96.SH OPTIONS 97. 98. 99.TP \w'\-dname=s'u+2n 100.B \-a 101Generate an 102.SM ASCII 103approximation of the typeset output. 104.TP 105.B \-b 106Print a backtrace with each warning or error message. This backtrace 107should help track down the cause of the error. The line numbers given 108in the backtrace may not always be correct: 109.BR troff 's 110idea of line numbers 111gets confused by 112.B as 113or 114.B am 115requests. 116.TP 117.B \-i 118Read the standard input after all the named input files have been 119processed. 120.TP 121.B \-v 122Print the version number. 123.TP 124.BI \-w name 125Enable warning 126.IR name . 127Available warnings are described in 128the Warnings subsection below. 129Multiple 130.B \-w 131options are allowed. 132.TP 133.BI \-W name 134Inhibit warning 135.IR name . 136Multiple 137.B \-W 138options are allowed. 139.TP 140.B \-E 141Inhibit all error messages. 142.TP 143.B \-z 144Suppress formatted output. 145.TP 146.B \-C 147Enable compatibility mode. 148.TP 149.BI \-d cs 150.TQ 151.BI \-d name = s 152Define 153.I c 154or 155.I name 156to be a string 157.IR s ; 158.I c 159must be a one letter name. 160.TP 161.BI \-f fam 162Use 163.I fam 164as the default font family. 165.TP 166.BI \-m name 167Read in the file 168.IB name .tmac\fR. 169If it isn't found, try 170.BI tmac. name 171instead. 172It will be first searched for in directories given with the 173.B \-M 174command line option, then in directories given 175in the 176.B GROFF_TMAC_PATH 177environment variable, then in the current directory (only if in unsafe 178mode), the home directory, @SYSTEMMACRODIR@, @LOCALMACRODIR@, and 179@MACRODIR@. 180.TP 181.B \-U 182Unsafe mode. 183This will enable the following requests: 184.BR .open , 185.BR .opena , 186.BR .pso , 187.BR .sy , 188and 189.BR .pi . 190For security reasons, these potentially dangerous requests are disabled 191otherwise. It will also add the current directory to the macro search path. 192.TP 193.B \-R 194Don't load 195.B troffrc 196and 197.BR troffrc-end . 198.TP 199.BI \-n num 200Number the first page 201.IR num . 202.TP 203.BI \-o list 204Output only pages in 205.IR list , 206which is a comma-separated list of page ranges; 207.I n 208means print page 209.IR n , 210.IB m \- n 211means print every page between 212.I m 213and 214.IR n , 215.BI \- n 216means print every page up to 217.IR n , 218.IB n \- 219means print every page from 220.IR n . 221.B Troff 222will exit after printing the last page in the list. 223.TP 224.BI \-r cn 225.TQ 226.BI \-r name = n 227Set number register 228.I c 229or 230.I name 231to 232.IR n ; 233.I c 234must be a one character name; 235.I n 236can be any troff numeric expression. 237.TP 238.BI \-T name 239Prepare output for device 240.IR name , 241rather than the default 242.BR @DEVICE@ . 243.TP 244.BI \-F dir 245Search in directory (or directory path) 246.I dir 247for subdirectories 248.BI dev name 249.RI ( name 250is the name of the device) and there for the 251.B DESC 252file and font files. 253.I dir 254is scanned before all other font directories. 255.TP 256.BI \-M dir 257Search directory (or directory path) 258.I dir 259for macro files. 260This is scanned before all other macro directories. 261. 262. 263.SH USAGE 264. 265. 266Only the features not in UNIX troff are described here. 267. 268.SS Long names 269. 270The names of number registers, fonts, strings/macros/diversions, 271special characters can be of any length. In escape sequences, where 272you can use 273.BI ( xx 274for a two character name, you can use 275.BI [ xxx ] 276for a name of arbitrary length: 277.TP 278.BI \e[ xxx ] 279Print the special character called 280.IR xxx . 281.TP 282.BI \ef[ xxx ] 283Set font 284.IR xxx . 285.TP 286.BI \e*[ xxx ] 287Interpolate string 288.IR xxx . 289.TP 290.BI \en[ xxx ] 291Interpolate number register 292.IR xxx . 293. 294.SS Fractional pointsizes 295. 296A 297.I 298scaled point 299is equal to 1/sizescale 300points, where 301sizescale is specified in the 302.B DESC 303file (1 by default). 304There is a new scale indicator 305.B z 306which has the effect of multiplying by sizescale. 307Requests and escape sequences in troff 308interpret arguments that represent a pointsize as being in units 309of scaled points, but they evaluate each such argument 310using a default scale indicator of 311.BR z . 312Arguments treated in this way are 313the argument to the 314.B ps 315request, 316the third argument to the 317.B cs 318request, 319the second and fourth arguments to the 320.B tkf 321request, 322the argument to the 323.B \eH 324escape sequence, 325and those variants of the 326.B \es 327escape sequence that take a numeric expression as their argument. 328.LP 329For example, suppose sizescale is 1000; 330then a scaled point will be equivalent to a millipoint; 331the request 332.B .ps 10.25 333is equivalent to 334.B .ps 10.25z 335and so sets the pointsize to 10250 scaled points, 336which is equal to 10.25 points. 337.LP 338The number register 339.B \en[.s] 340returns the pointsize in points as decimal fraction. 341There is also a new number register 342.B \en[.ps] 343that returns the pointsize in scaled points. 344.LP 345It would make no sense to use the 346.B z 347scale indicator in a numeric expression 348whose default scale indicator was neither 349.B u 350nor 351.BR z , 352and so 353.B troff 354disallows this. 355Similarly it would make no sense to use a scaling indicator 356other than 357.B z 358or 359.B u 360in a numeric expression whose default scale indicator was 361.BR z , 362and so 363.B troff 364disallows this as well. 365.LP 366There is also new scale indicator 367.B s 368which multiplies by the number of units in a scaled point. 369So, for example, 370.B \en[.ps]s 371is equal to 372.BR 1m . 373Be sure not to confuse the 374.B s 375and 376.B z 377scale indicators. 378. 379.SS Numeric expressions 380. 381.LP 382Spaces are permitted in a number expression within parentheses. 383.LP 384.B M 385indicates a scale of 100ths of an em. 386.TP 387.IB e1 >? e2 388The maximum of 389.I e1 390and 391.IR e2 . 392.TP 393.IB e1 <? e2 394The minimum of 395.I e1 396and 397.IR e2 . 398.TP 399.BI ( c ; e ) 400Evaluate 401.I e 402using 403.I c 404as the default scaling indicator. 405If 406.I c 407is missing, ignore scaling indicators in the evaluation of 408.IR e . 409. 410.SS New escape sequences 411. 412.TP 413.BI \eA' anything ' 414This expands to 415.B 1 416or 417.B 0 418according as 419.I anything 420is or is not acceptable as the name of a string, macro, diversion, 421number register, environment or font. 422It will return 423.B 0 424if 425.I anything 426is empty. 427This is useful if you want to lookup user input in some sort of 428associative table. 429.TP 430.BI \eB' anything ' 431This expands to 432.B 1 433or 434.B 0 435according as 436.I anything 437is or is not a valid numeric expression. 438It will return 439.B 0 440if 441.I anything 442is empty. 443.TP 444.BI \eC' xxx ' 445Typeset character named 446.IR xxx . 447Normally it is more convenient to use 448.BI \e[ xxx ]\fR. 449But 450.B \eC 451has the advantage that it is compatible with recent versions of 452.SM UNIX 453and is available in compatibility mode. 454.TP 455.B \eE 456This is equivalent to an escape character, 457but it's not interpreted in copy-mode. 458For example, strings to start and end superscripting could be defined 459like this: 460.RS 461.IP 462\&.ds { \ev'\-.3m'\es'\eEn[.s]*6u/10u' 463.br 464\&.ds } \es0\ev'.3m' 465.LP 466The use of 467.B \eE 468ensures that these definitions will work even if 469.B \e*{ 470gets interpreted in copy-mode 471(for example, by being used in a macro argument). 472.RE 473.TP 474.BI \eN' n ' 475Typeset the character with code 476.I n 477in the current font. 478.I n 479can be any integer. 480Most devices only have characters with codes between 0 and 255. 481If the current font does not contain a character with that code, 482special fonts will 483.I not 484be searched. 485The 486.B \eN 487escape sequence can be conveniently used on conjunction with the 488.B char 489request: 490.RS 491.IP 492.B 493\&.char \e[phone] \ef(ZD\eN'37' 494.RE 495.IP 496The code of each character is given in the fourth column in the font 497description file after the 498.B charset 499command. 500It is possible to include unnamed characters in the font description 501file by using a name of 502.BR \-\-\- ; 503the 504.B \eN 505escape sequence is the only way to use these. 506.TP 507.BI \eR' name\ \(+-n ' 508This has the same effect as 509.RS 510.IP 511.BI .nr\ name\ \(+-n 512.RE 513.TP 514.BI \es( nn 515.TQ 516.BI \es\(+-( nn 517Set the point size to 518.I nn 519points; 520.I nn 521must be exactly two digits. 522.TP 523.BI \es[\(+- n ] 524.TQ 525.BI \es\(+-[ n ] 526.TQ 527.BI \es'\(+- n ' 528.TQ 529.BI \es\(+-' n ' 530Set the point size to 531.I n 532scaled points; 533.I n 534is a numeric expression with a default scale indicator of 535.BR z . 536.TP 537.BI \eV x 538.TQ 539.BI \eV( xx 540.TQ 541.BI \eV[ xxx ] 542Interpolate the contents of the environment variable 543.IR xxx , 544as returned by 545.BR getenv (3). 546.B \eV 547is interpreted in copy-mode. 548.TP 549.BI \eY x 550.TQ 551.BI \eY( xx 552.TQ 553.BI \eY[ xxx ] 554This is approximately equivalent to 555.BI \eX'\e*[ xxx ]'\fR. 556However the contents of the string or macro 557.I xxx 558are not interpreted; 559also it is permitted for 560.I xxx 561to have been defined as a macro and thus contain newlines 562(it is not permitted for the argument to 563.B \eX 564to contain newlines). 565The inclusion of newlines requires an extension to the UNIX troff output 566format, and will confuse drivers that do not know about this 567extension. 568.TP 569.BI \eZ' anything ' 570Print anything and then restore the horizontal and vertical 571position; 572.I anything 573may not contain tabs or leaders. 574.TP 575.B \e$0 576The name by which the current macro was invoked. 577The 578.B als 579request can make a macro have more than one name. 580.TP 581.B \e$* 582In a macro, the concatenation of all the arguments separated by spaces. 583.TP 584.B \e$@ 585In a macro, the concatenation of all the arguments with each surrounded by 586double quotes, and separated by spaces. 587.TP 588.BI \e$( nn 589.TQ 590.BI \e$[ nnn ] 591In a macro, this gives the 592.IR nn -th 593or 594.IR nnn -th 595argument. 596Macros can have an unlimited number of arguments. 597.TP 598.BI \e? anything \e? 599When used in a diversion, this will transparently embed 600.I anything 601in the diversion. 602.I anything 603is read in copy mode. 604When the diversion is reread, 605.I anything 606will be interpreted. 607.I anything 608may not contain newlines; use 609.B \e!\& 610if you want to embed newlines in a diversion. 611The escape sequence 612.B \e?\& 613is also recognised in copy mode and turned into a single internal 614code; it is this code that terminates 615.IR anything . 616Thus 617.RS 618.RS 619.ft B 620.nf 621.ne 15 622\&.nr x 1 623\&.nf 624\&.di d 625\e?\e\e?\e\e\e\e?\e\e\e\e\e\e\e\enx\e\e\e\e?\e\e?\e? 626\&.di 627\&.nr x 2 628\&.di e 629\&.d 630\&.di 631\&.nr x 3 632\&.di f 633\&.e 634\&.di 635\&.nr x 4 636\&.f 637.fi 638.ft 639.RE 640.RE 641.IP 642will print 643.BR 4 . 644.TP 645.B \e/ 646This increases the width of the preceding character so that 647the spacing between that character and the following character 648will be correct if the following character is a roman character. 649For example, if an italic f is immediately followed by a roman 650right parenthesis, then in many fonts the top right portion of the f 651will overlap the top left of the right parenthesis producing \fIf\fR)\fR, 652which is ugly. 653Inserting 654.B \e/ 655produces 656.ie \n(.g \fIf\/\fR)\fR 657.el \fIf\|\fR)\fR 658and avoids this problem. 659It is a good idea to use this escape sequence whenever an 660italic character is immediately followed by a roman character without any 661intervening space. 662.TP 663.B \e, 664This modifies the spacing of the following character so that the spacing 665between that character and the preceding character will correct if 666the preceding character is a roman character. 667For example, inserting 668.B \e, 669between the parenthesis and the f changes 670\fR(\fIf\fR to 671.ie \n(.g \fR(\,\fIf\fR. 672.el \fR(\^\fIf\fR. 673It is a good idea to use this escape sequence whenever a 674roman character is immediately followed by an italic character without any 675intervening space. 676.TP 677.B \e) 678Like 679.B \e& 680except that it behaves like a character declared with the 681.B cflags 682request to be transparent for the purposes of end of sentence recognition. 683.TP 684.B \e~ 685This produces an unbreakable space that stretches like a normal inter-word 686space when a line is adjusted. 687.TP 688.B \e: 689This causes the insertion of a zero-width break point. 690It is equal to 691.B \e% 692but without insertion of a soft hyphen character. 693.TP 694.B \e# 695Everything up to and including the next newline is ignored. 696This is interpreted in copy mode. 697This is like 698.B \e" 699except that 700.B \e" 701does not ignore the terminating newline. 702. 703.SS New requests 704. 705.TP 706.BI .aln\ xx\ yy 707Create an alias 708.I xx 709for number register object named 710.IR yy . 711The new name and the old name will be exactly equivalent. 712If 713.I yy 714is undefined, a warning of type 715.B reg 716will be generated, and the request will be ignored. 717.TP 718.BI .als\ xx\ yy 719Create an alias 720.I xx 721for request, string, macro, or diversion object named 722.IR yy . 723The new name and the old name will be exactly equivalent (it is similar to a 724hard rather than a soft link). 725If 726.I yy 727is undefined, a warning of type 728.B mac 729will be generated, and the request will be ignored. 730The 731.BR de , 732.BR am , 733.BR di , 734.BR da , 735.BR ds , 736and 737.B as 738requests only create a new object if the name of the macro, diversion 739or string diversion is currently undefined or if it is defined to be a 740request; normally they modify the value of an existing object. 741.TP 742.BI .am1\ xx\ yy 743Similar to 744.BR .am , 745but compatibility mode is switched off during execution. 746On entry, the current compatibility mode is saved and restored at exit. 747.TP 748.BI .asciify\ xx 749This request `unformats' the diversion 750.I xx 751in such a way that 752.SM ASCII 753and space characters (and some escape sequences) that were formatted and 754diverted into 755.I xx 756will be treated like ordinary input characters when 757.I xx 758is reread. 759Useful for diversions in conjunction with the 760.B .writem 761request. 762It can be also used for gross hacks; for example, this 763.RS 764.IP 765.ne 7v+\n(.Vu 766.ft B 767.nf 768\&.tr @. 769\&.di x 770\&@nr n 1 771\&.br 772\&.di 773\&.tr @@ 774\&.asciify x 775\&.x 776.fi 777.RE 778.IP 779will set register 780.B n 781to 1. 782Note that glyph information (font, font size, etc.) is not preserved; use 783.B .unformat 784instead. 785.TP 786.B .backtrace 787Print a backtrace of the input stack on stderr. 788.TP 789.BI .blm\ xx 790Set the blank line macro to 791.IR xx . 792If there is a blank line macro, 793it will be invoked when a blank line is encountered instead of the usual 794troff behaviour. 795.TP 796.BI .box\ xx 797.TQ 798.BI .boxa\ xx 799These requests are similar to the 800.B di 801and 802.B da 803requests with the exception that a partially filled line will not become 804part of the diversion (i.e., the diversion always starts with a new line) 805but restored after ending the diversion, discarding the partially filled 806line which possibly comes from the diversion. 807.TP 808.B .break 809Break out of a while loop. 810See also the 811.B while 812and 813.B continue 814requests. 815Be sure not to confuse this with the 816.B br 817request. 818.TP 819.B .brp 820This is the same as 821.BR \ep . 822.TP 823.BI .cflags\ n\ c1\ c2\|.\|.\|. 824Characters 825.IR c1 , 826.IR c2 ,\|.\|.\|. 827have properties determined by 828.IR n , 829which is ORed from the following: 830.RS 831.TP 8321 833the character ends sentences 834(initially characters 835.B .?!\& 836have this property); 837.TP 8382 839lines can be broken before the character 840(initially no characters have this property); 841a line will not be broken at a character with this property 842unless the characters on each side both have non-zero 843hyphenation codes. 844.TP 8454 846lines can be broken after the character 847(initially characters 848.B \-\e(hy\e(em 849have this property); 850a line will not be broken at a character with this property 851unless the characters on each side both have non-zero 852hyphenation codes. 853.TP 8548 855the character overlaps horizontally 856(initially characters 857.B \e(ul\e(rn\e(ru 858have this property); 859.TP 86016 861the character overlaps vertically 862(initially character 863.B \e(br 864has this property); 865.TP 86632 867an end of sentence character followed by any number of characters 868with this property will be treated 869as the end of a sentence if followed by a newline or two spaces; 870in other words 871the character is transparent for the purposes of end of sentence 872recognition; 873this is the same as having a zero space factor in \*(tx 874(initially characters 875.B \(ts')]*\e(dg\e(rq 876have this property). 877.RE 878.TP 879.BI .char\ c\ string 880Define character 881.I c 882to be 883.IR string . 884Every time character 885.I c 886needs to be printed, 887.I string 888will be processed in a temporary environment and the result 889will be wrapped up into a single object. 890Compatibility mode will be turned off 891and the escape character will be set to 892.B \e 893while 894.I string 895is being processed. 896Any emboldening, constant spacing or track kerning will be applied 897to this object rather than to individual characters in 898.IR string . 899A character defined by this request can be used just like 900a normal character provided by the output device. 901In particular other characters can be translated to it 902with the 903.B tr 904request; 905it can be made the leader character by the 906.B lc 907request; 908repeated patterns can be drawn with the character using the 909.B \el 910and 911.B \eL 912escape sequences; 913words containing the character can be hyphenated 914correctly, if the 915.B hcode 916request is used to give the character a hyphenation code. 917There is a special anti-recursion feature: 918use of character within the character's definition 919will be handled like normal characters not defined with 920.BR char . 921A character definition can be removed with the 922.B rchar 923request. 924.TP 925.BI .chop\ xx 926Chop the last character off macro, string, or diversion 927.IR xx . 928This is useful for removing the newline from the end of diversions 929that are to be interpolated as strings. 930.TP 931.BI .close\ stream 932Close the stream named 933.IR stream ; 934.I stream 935will no longer be an acceptable argument to the 936.B write 937request. 938See the 939.B open 940request. 941.TP 942.B .continue 943Finish the current iteration of a while loop. 944See also the 945.B while 946and 947.B break 948requests. 949.TP 950.BI .cp\ n 951If 952.I n 953is non-zero or missing, enable compatibility mode, otherwise 954disable it. 955In compatibility mode, long names are not recognised, and the 956incompatibilities caused by long names do not arise. 957.TP 958.BI .dei\ xx\ yy 959Define macro indirectly. 960The following example 961.RS 962.IP 963.ne 2v+\n(.Vu 964.ft B 965.nf 966\&.ds xx aa 967\&.ds yy bb 968\&.dei xx yy 969.fi 970.RE 971.IP 972is equivalent to 973.RS 974.IP 975.B 976\&.de aa bb 977.RE 978.TP 979.BI .de1\ xx\ yy 980Similar to 981.BR .de , 982but compatibility mode is switched off during execution. 983On entry, the current compatibility mode is saved and restored at exit. 984.TP 985.BI .do\ xxx 986Interpret 987.I .xxx 988with compatibility mode disabled. 989For example, 990.RS 991.IP 992.B 993\&.do fam T 994.LP 995would have the same effect as 996.IP 997.B 998\&.fam T 999.LP 1000except that it would work even if compatibility mode had been enabled. 1001Note that the previous compatibility mode is restored before any files 1002sourced by 1003.I xxx 1004are interpreted. 1005.RE 1006.TP 1007.B .ecs 1008Save current escape character. 1009.TP 1010.B .ecr 1011Restore escape character saved with 1012.BR ecs . 1013Without a previous call to 1014.BR ecs , 1015.RB ` \e ' 1016will be the new escape character. 1017.TP 1018.BI .evc\ xx 1019Copy the contents of environment 1020.I xx 1021to the current environment. 1022No pushing or popping of environents will be done. 1023.TP 1024.BI .fam\ xx 1025Set the current font family to 1026.IR xx . 1027The current font family is part of the current environment. 1028If 1029.I xx 1030is missing, switch back to previous font family. 1031See the description of the 1032.B sty 1033request for more information on font families. 1034.TP 1035.BI .fspecial\ f\ s1\ s2\|.\|.\|. 1036When the current font is 1037.IR f , 1038fonts 1039.IR s1 , 1040.IR s2 ,\|.\|.\|. 1041will be special, that is, they will searched for characters not in 1042the current font. 1043Any fonts specified in the 1044.B special 1045request will be searched after fonts specified in the 1046.B fspecial 1047request. 1048.TP 1049.BI .ftr\ f\ g 1050Translate font 1051.I f 1052to 1053.IR g . 1054Whenever a font named 1055.I f 1056is referred to in 1057.B \ef 1058escape sequence, 1059or in the 1060.BR ft , 1061.BR ul , 1062.BR bd , 1063.BR cs , 1064.BR tkf , 1065.BR special , 1066.BR fspecial , 1067.BR fp , 1068or 1069.BR sty 1070requests, 1071font 1072.I g 1073will be used. 1074If 1075.I g 1076is missing, 1077or equal to 1078.I f 1079then font 1080.I f 1081will not be translated. 1082.TP 1083.BI .hcode \ c1\ code1\ c2\ code2\|.\|.\|. 1084Set the hyphenation code of character 1085.I c1 1086to 1087.I code1 1088and that of 1089.I c2 1090to 1091.IR code2 . 1092A hyphenation code must be a single input 1093character (not a special character) other than a digit or a space. 1094Initially each lower-case letter has a hyphenation code, which 1095is itself, and each upper-case letter has a hyphenation code 1096which is the lower case version of itself. 1097See also the 1098.B hpf 1099request. 1100.TP 1101.BI .hla\ lang 1102Set the current hyphenation language to 1103.IR lang . 1104Hyphenation exceptions specified with the 1105.B hw 1106request and hyphenation patterns specified with the 1107.B hpf 1108request are both associated with the current hyphenation language. 1109The 1110.B hla 1111request is usually invoked by the 1112.B troffrc 1113file. 1114.TP 1115.BI .hlm\ n 1116Set the maximum number of consecutive hyphenated lines to 1117.IR n . 1118If 1119.I n 1120is negative, there is no maximum. 1121The default value is \-1. 1122This value is associated with the current environment. 1123Only lines output from an environment count towards the maximum associated 1124with that environment. 1125Hyphens resulting from 1126.B \e% 1127are counted; explicit hyphens are not. 1128.TP 1129.BI .hpf\ file 1130Read hyphenation patterns from 1131.IR file ; 1132this will be searched for in the same way that 1133.IB name .tmac 1134is searched for when the 1135.BI \-m name 1136option is specified. 1137It should have the same format as the argument to 1138the \epatterns primitive in \*(tx; 1139the letters appearing in this file are interpreted as hyphenation 1140codes. 1141A 1142.B % 1143character in the patterns file introduces a comment that continues 1144to the end of the line. 1145The set of hyphenation patterns is associated with the current language 1146set by the 1147.B hla 1148request. 1149The 1150.B hpf 1151request 1152is usually invoked by the 1153.B troffrc 1154file. 1155.TP 1156.BI .hym\ n 1157Set the 1158.I hyphenation margin 1159to 1160.IR n : 1161when the current adjustment mode is not 1162.BR b , 1163the line will not be hyphenated if the line is no more than 1164.I n 1165short. 1166The default hyphenation margin is 0. 1167The default scaling indicator for this request is 1168.IR m . 1169The hyphenation margin is associated with the current environment. 1170The current hyphenation margin is available in the 1171.B \en[.hym] 1172register. 1173.TP 1174.BI .hys\ n 1175Set the 1176.I hyphenation space 1177to 1178.IR n : 1179when the current adjustment mode is 1180.B b 1181don't hyphenate the line if the line can be justified by adding no more than 1182.I n 1183extra space to each word space. 1184The default hyphenation space is 0. 1185The default scaling indicator for this request is 1186.BR m . 1187The hyphenation space is associated with the current environment. 1188The current hyphenation space is available in the 1189.B \en[.hys] 1190register. 1191.TP 1192.BI .kern\ n 1193If 1194.I n 1195is non-zero or missing, enable pairwise kerning, otherwise disable it. 1196.TP 1197.BI .length\ xx\ string 1198Compute the length of 1199.I string 1200and return it in the number register 1201.I xx 1202(which is not necessarily defined before). 1203.TP 1204.BI .linetabs\ n 1205If 1206.I n 1207is non-zero or missing, enable line-tabs mode, otherwise disable it (which 1208is the default). 1209In line-tabs mode, tab distances are computed relative to the (current) 1210output line. 1211Otherwise they are taken relative to the input line. 1212For example, the following 1213.RS 1214.IP 1215.ne 6v+\n(.Vu 1216.ft B 1217.nf 1218\&.ds x a\et\ec 1219\&.ds y b\et\ec 1220\&.ds z c 1221\&.ta 1i 3i 1222\e*x 1223\e*y 1224\e*z 1225.fi 1226.RE 1227.IP 1228yields 1229.RS 1230.IP 1231a b c 1232.RE 1233.IP 1234In line-tabs mode, the same code gives 1235.RS 1236.IP 1237a b c 1238.RE 1239.IP 1240Line-tabs mode is associated with the current environment; the read-only 1241number register 1242.B \\en[.linetabs] 1243is set to\~1 if in line-tabs mode, and 0 otherwise. 1244.TP 1245.BI .mso\ file 1246The same as the 1247.B so 1248request except that 1249.I file 1250is searched for in the same directories as macro files for the 1251the 1252.B \-m 1253command line option. 1254If the file name to be included 1255has the form 1256.IB name .tmac 1257and it isn't found, 1258.B mso 1259tries to include 1260.BI tmac. name 1261instead and vice versa. 1262.TP 1263.BI .nop \ anything 1264Execute 1265.IR anything . 1266This is similar to `.if\ 1'. 1267.TP 1268.B .nroff 1269Make the 1270.B n 1271built-in condition true 1272and the 1273.B t 1274built-in condition false. 1275This can be reversed using the 1276.B troff 1277request. 1278.TP 1279.BI .open\ stream\ filename 1280Open 1281.I filename 1282for writing and associate the stream named 1283.I stream 1284with it. 1285See also the 1286.B close 1287and 1288.B write 1289requests. 1290.TP 1291.BI .opena\ stream\ filename 1292Like 1293.BR open , 1294but if 1295.I filename 1296exists, append to it instead of truncating it. 1297.TP 1298.B .pnr 1299Print the names and contents of all currently defined number registers 1300on stderr. 1301.TP 1302.BI .psbb \ filename 1303Get the bounding box of a PostScript image 1304.IR filename . 1305This file must conform to Adobe's Document Structuring Conventions; the 1306command looks for a 1307.B %%BoundingBox 1308comment to extract the bounding box values. 1309After a successful call, the coordinates (in PostScript units) of the lower 1310left and upper right corner can be found in the registers 1311.BR \en[llx] , 1312.BR \en[lly] , 1313.BR \en[urx] , 1314and 1315.BR \en[ury] , 1316respectively. 1317If some error has occurred, the four registers are set to zero. 1318.TP 1319.BI .pso \ command 1320This behaves like the 1321.B so 1322request except that input comes from the standard output of 1323.IR command . 1324.TP 1325.B .ptr 1326Print the names and positions of all traps (not including input line 1327traps and diversion traps) on stderr. Empty slots in the page trap 1328list are printed as well, because they can affect the priority of 1329subsequently planted traps. 1330.TP 1331.BI .rchar\ c1\ c2\|.\|.\|. 1332Remove the definitions of characters 1333.IR c1 , 1334.IR c2 ,\|.\|.\|. 1335This undoes the effect of a 1336.B char 1337request. 1338.TP 1339.B .return 1340Within a macro, return immediately. 1341No effect otherwise. 1342.TP 1343.B .rj 1344.TQ 1345.BI .rj\ n 1346Right justify the next 1347.I n 1348input lines. 1349Without an argument right justify the next input line. 1350The number of lines to be right justified is available in the 1351.B \en[.rj] 1352register. 1353This implicitly does 1354.BR .ce\ 0 . 1355The 1356.B ce 1357request implicitly does 1358.BR .rj\ 0 . 1359.TP 1360.BI .rnn \ xx\ yy 1361Rename number register 1362.I xx 1363to 1364.IR yy . 1365.TP 1366.BI .shc\ c 1367Set the soft hyphen character to 1368.IR c . 1369If 1370.I c 1371is omitted, 1372the soft hyphen character will be set to the default 1373.BR \e(hy . 1374The soft hyphen character is the character which will be inserted 1375when a word is hyphenated at a line break. 1376If the soft hyphen character does not exist in the font of the character 1377immediately preceding a potential break point, 1378then the line will not be broken at that point. 1379Neither definitions (specified with the 1380.B char 1381request) 1382nor translations (specified with the 1383.B tr 1384request) 1385are considered when finding the soft hyphen character. 1386.TP 1387.BI .shift\ n 1388In a macro, shift the arguments by 1389.I n 1390positions: 1391argument 1392.I i 1393becomes argument 1394.IR i \- n ; 1395arguments 1 to 1396.I n 1397will no longer be available. 1398If 1399.I n 1400is missing, 1401arguments will be shifted by 1. 1402Shifting by negative amounts is currently undefined. 1403.TP 1404.BI .special\ s1\ s2\|.\|.\|. 1405Fonts 1406.IR s1 , 1407.IR s2 , 1408are special and will be searched for characters not in the 1409current font. 1410.TP 1411.BI .sty\ n\ f 1412Associate style 1413.I f 1414with font position 1415.IR n . 1416A font position can be associated either with a font or 1417with a style. 1418The current font is the index of a font position and so is also 1419either a font or a style. 1420When it is a style, the font that is actually used is the font the 1421name of which is the concatenation of the name of the current family 1422and the name of the current style. 1423For example, if the current font is 1 and font position 1 is 1424associated with style 1425.B R 1426and the current 1427font family is 1428.BR T , 1429then font 1430.BR TR 1431will be used. 1432If the current font is not a style, then the current family is ignored. 1433When the requests 1434.BR cs , 1435.BR bd , 1436.BR tkf , 1437.BR uf , 1438or 1439.B fspecial 1440are applied to a style, 1441then they will instead be applied to the member of the 1442current family corresponding to that style. 1443The default family can be set with the 1444.B \-f 1445option. 1446The styles command in the 1447.SM DESC 1448file controls which font positions 1449(if any) are initially associated with styles rather than fonts. 1450.TP 1451.BI .substring\ xx\ n1\ [ n2 ] 1452Replace the string in register 1453.I xx 1454with the substring defined by the indices 1455.I n1 1456and 1457.IR n2 . 1458The first character in the string has index one. 1459If 1460.I n2 1461is omitted, it is taken to be equal to the string's length. If the 1462index value 1463.I n1 1464or 1465.I n2 1466is negative or zero, it will be counted from the end of the string, 1467going backwards: The last character has index 0, the character before 1468the last character has index -1, etc. 1469.TP 1470.BI .tkf\ f\ s1\ n1\ s2\ n2 1471Enable track kerning for font 1472.IR f . 1473When the current font is 1474.I f 1475the width of every character will be increased by an amount 1476between 1477.I n1 1478and 1479.IR n2 ; 1480when the current point size is less than or equal to 1481.I s1 1482the width will be increased by 1483.IR n1 ; 1484when it is greater than or equal to 1485.I s2 1486the width will be increased by 1487.IR n2 ; 1488when the point size is greater than or equal to 1489.I s1 1490and less than or equal to 1491.I s2 1492the increase in width is a linear function of the point size. 1493.TP 1494.BI .tm1\ string 1495Similar to the 1496.B tm 1497request, 1498.I string 1499is read in copy mode and written on the standard error, but an initial 1500double quote in 1501.I string 1502is stripped off to allow initial blanks. 1503.TP 1504.BI .tmc\ string 1505Similar to 1506.BR tm1 1507but without writing a final newline. 1508.TP 1509.BI .trf\ filename 1510Transparently output the contents of file 1511.IR filename . 1512Each line is output as it would be were it preceded by 1513.BR \e! ; 1514however, the lines are not subject to copy-mode interpretation. 1515If the file does not end with a newline, then a newline will 1516be added. 1517For example, you can define a macro 1518.I x 1519containing the contents of file 1520.IR f , 1521using 1522.RS 1523.IP 1524.BI .di\ x 1525.br 1526.BI .trf\ f 1527.br 1528.B .di 1529.LP 1530Unlike with the 1531.B cf 1532request, 1533the file cannot contain characters such as 1534.SM NUL 1535that are not legal troff input characters. 1536.RE 1537.TP 1538.B .trnt abcd 1539This is the same as the 1540.B tr 1541request except that the translations do not apply to text that is 1542transparently throughput into a diversion with 1543.BR \e! . 1544For example, 1545.RS 1546.IP 1547.nf 1548.ft B 1549\&.tr ab 1550\&.di x 1551\e!.tm a 1552\&.di 1553\&.x 1554.fi 1555.ft 1556.LP 1557will print 1558.BR b ; 1559if 1560.B trnt 1561is used instead of 1562.B tr 1563it will print 1564.BR a . 1565.RE 1566.TP 1567.B .troff 1568Make the 1569.B n 1570built-in condition false, 1571and the 1572.B t 1573built-in condition true. 1574This undoes the effect of the 1575.B nroff 1576request. 1577.TP 1578.BI .unformat\ xx 1579This request `unformats' the diversion 1580.IR xx . 1581Contrary to the 1582.B .asciify 1583request, which tries to convert formatted elements of the diversion back 1584to input tokens as much as possible, 1585.B .unformat 1586will only handle tabs and spaces between words (usually caused by spaces 1587or newlines in the input) specially. 1588The former are treated as if they were input tokens, and the latter are 1589stretchable again. 1590Note that the vertical size of lines is not preserved. 1591Glyph information (font, font size, space width, etc.) is retained. 1592Useful in conjunction with the 1593.B .box 1594and 1595.B .boxa 1596requests. 1597.TP 1598.BI .vpt\ n 1599Enable vertical position traps if 1600.I n 1601is non-zero, disable them otherwise. 1602Vertical position traps are traps set by the 1603.B wh 1604or 1605.B dt 1606requests. 1607Traps set by the 1608.B it 1609request are not vertical position traps. 1610The parameter that controls whether vertical position traps are enabled 1611is global. 1612Initially vertical position traps are enabled. 1613.TP 1614.BI .warn\ n 1615Control warnings. 1616.I n 1617is the sum of the numbers associated with each warning that is to be enabled; 1618all other warnings will be disabled. 1619The number associated with each warning is listed in the `Warnings' section. 1620For example, 1621.B .warn 0 1622will disable all warnings, and 1623.B .warn 1 1624will disable all warnings except that about missing characters. 1625If 1626.I n 1627is not given, 1628all warnings will be enabled. 1629.TP 1630.BI .while \ c\ anything 1631While condition 1632.I c 1633is true, accept 1634.I anything 1635as input; 1636.I c 1637can be any condition acceptable to an 1638.B if 1639request; 1640.I anything 1641can comprise multiple lines if the first line starts with 1642.B \e{ 1643and the last line ends with 1644.BR \e} . 1645See also the 1646.B break 1647and 1648.B continue 1649requests. 1650.TP 1651.BI .write\ stream\ anything 1652Write 1653.I anything 1654to the stream named 1655.IR stream . 1656.I stream 1657must previously have been the subject of an 1658.B open 1659request. 1660.I anything 1661is read in copy mode; 1662a leading 1663.B \(ts 1664will be stripped. 1665.TP 1666.BI .writem\ stream\ xx 1667Write the contents of the macro or string 1668.I xx 1669to the stream named 1670.IR stream . 1671.I stream 1672must previously have been the subject of an 1673.B open 1674request. 1675.I xx 1676is read in copy mode. 1677. 1678.SS Extended requests 1679. 1680.TP 1681.BI .cf\ filename 1682When used in a diversion, this will embed in the diversion an object which, 1683when reread, will cause the contents of 1684.I filename 1685to be transparently copied through to the output. 1686In UNIX troff, the 1687contents of 1688.I filename 1689is immediately copied through to the output regardless of whether 1690there is a current diversion; this behaviour is so anomalous that it 1691must be considered a bug. 1692.TP 1693.BI .ev\ xx 1694If 1695.I xx 1696is not a number, this will switch to a named environment called 1697.IR xx . 1698The environment should be popped with a matching 1699.B ev 1700request without any arguments, just as for numbered environments. 1701There is no limit on the number of named environments; they will be 1702created the first time that they are referenced. 1703.TP 1704.BI .fp\ n\ f1\ f2 1705The 1706.B fp 1707request has an optional third argument. 1708This argument gives the external name of the font, 1709which is used for finding the font description file. 1710The second argument gives the internal name of the font 1711which is used to refer to the font in troff after it has been mounted. 1712If there is no third argument then the internal name will be used 1713as the external name. 1714This feature allows you to use fonts with long names in compatibility mode. 1715.TP 1716.BI .ss\ m\ n 1717When two arguments are given to the 1718.B ss 1719request, the second argument gives the 1720.IR "sentence space size" . 1721If the second argument is not given, the sentence space size 1722will be the same as the word space size. 1723Like the word space size, the sentence space is in units of 1724one twelfth of the spacewidth parameter for the current font. 1725Initially both the word space size and the sentence 1726space size are 12. 1727Contrary to UNIX troff, GNU troff handles this request in nroff mode 1728also; a given value is then rounded down to the nearest multiple of\~12. 1729The sentence space size is used in two circumstances: 1730if the end of a sentence occurs at the end of a line in fill mode, then 1731both an inter-word space and a sentence space will be added; 1732if two spaces follow the end of a sentence in the middle of a line, 1733then the second space will be a sentence space. 1734Note that the behaviour of UNIX troff will be exactly 1735that exhibited by GNU troff if a second argument is never given to the 1736.B ss 1737request. 1738In GNU troff, as in UNIX troff, you should always 1739follow a sentence with either a newline or two spaces. 1740.TP 1741.BI .ta\ n1\ n2\|.\|.\|.nn \ T\ r1\ r2\|.\|.\|.\|rn 1742Set tabs at positions 1743.IR n1 , 1744.IR n2 ,\|.\|.\|.\|, 1745.I nn 1746and then set tabs at 1747.IR nn + r1 , 1748.IR nn + r2 ,\|.\|.\|.\|.\|, 1749.IR nn + rn 1750and then at 1751.IR nn + rn + r1 , 1752.IR nn + rn + r2 ,\|.\|.\|.\|, 1753.IR nn + rn + rn , 1754and so on. 1755For example, 1756.RS 1757.IP 1758.B 1759\&.ta T .5i 1760.LP 1761will set tabs every half an inch. 1762.RE 1763. 1764.SS New number registers 1765. 1766The following read-only registers are available: 1767.TP 1768.B \en[.C] 17691 if compatibility mode is in effect, 0 otherwise. 1770.TP 1771.B \en[.cdp] 1772The depth of the last character added to the current environment. 1773It is positive if the character extends below the baseline. 1774.TP 1775.B \en[.ce] 1776The number of lines remaining to be centered, as set by the 1777.B ce 1778request. 1779.TP 1780.B \en[.cht] 1781The height of the last character added to the current environment. 1782It is positive if the character extends above the baseline. 1783.TP 1784.B \en[.csk] 1785The skew of the last character added to the current environment. 1786The 1787.I skew 1788of a character is how far to the right of the center of a character 1789the center of an accent over that character should be placed. 1790.TP 1791.B \en[.ev] 1792The name or number of the current environment. 1793This is a string-valued register. 1794.TP 1795.B \en[.fam] 1796The current font family. 1797This is a string-valued register. 1798.TP 1799.B \en[.fp] 1800The number of the next free font position. 1801.TP 1802.B \en[.g] 1803Always 1. 1804Macros should use this to determine whether they are running 1805under GNU troff. 1806.TP 1807.B \en[.hla] 1808The current hyphenation language as set by the 1809.B hla 1810request. 1811.TP 1812.B \en[.hlc] 1813The number of immediately preceding consecutive hyphenated lines. 1814.TP 1815.B \en[.hlm] 1816The maximum allowed number of consecutive hyphenated lines, as set by the 1817.B hlm 1818request. 1819.TP 1820.B \en[.hy] 1821The current hyphenation flags (as set by the 1822.B hy 1823request). 1824.TP 1825.B \en[.hym] 1826The current hyphenation margin (as set by the 1827.B hym 1828request). 1829.TP 1830.B \en[.hys] 1831The current hyphenation space (as set by the 1832.B hys 1833request). 1834.TP 1835.B \en[.in] 1836The indent that applies to the current output line. 1837.TP 1838.B \en[.int] 1839Set to a positive value if last output line is interrupted (i.e., if it 1840contains 1841.IR \ec ). 1842.TP 1843.B \en[.kern] 1844.B 1 1845if pairwise kerning is enabled, 1846.B 0 1847otherwise. 1848.TP 1849.B \en[.lg] 1850The current ligature mode (as set by the 1851.B lg 1852request). 1853.TP 1854.B \en[.linetabs] 1855The current line-tabs mode (as set by the 1856.B linetabs 1857request). 1858.TP 1859.B \en[.ll] 1860The line length that applies to the current output line. 1861.TP 1862.B \en[.lt] 1863The title length as set by the 1864.B lt 1865request. 1866.TP 1867.B \en[.ne] 1868The amount of space that was needed in the last 1869.B ne 1870request that caused a trap to be sprung. 1871Useful in conjunction with the 1872.B \en[.trunc] 1873register. 1874.TP 1875.B \en[.ns] 1876.B 1 1877if no-space mode is active, 1878.B 0 1879otherwise. 1880.TP 1881.B \en[.pn] 1882The number of the next page: 1883either the value set by a 1884.B pn 1885request, or the number of the current page plus 1. 1886.TP 1887.B \en[.ps] 1888The current pointsize in scaled points. 1889.TP 1890.B \en[.psr] 1891The last-requested pointsize in scaled points. 1892.TP 1893.B \en[.rj] 1894The number of lines to be right-justified as set by the 1895.B rj 1896request. 1897.TP 1898.B \en[.sr] 1899The last requested pointsize in points as a decimal fraction. 1900This is a string-valued register. 1901.TP 1902.B \en[.tabs] 1903A string representation of the current tab settings suitable for use as 1904an argument to the 1905.B ta 1906request. 1907.TP 1908.B \en[.trunc] 1909The amount of vertical space truncated by the most recently sprung 1910vertical position trap, or, 1911if the trap was sprung by a 1912.B ne 1913request, 1914minus the amount of vertical motion produced by the 1915.B ne 1916request. 1917In other words, at the point a trap is sprung, it represents the difference 1918of what the vertical position would have been but for the trap, 1919and what the vertical position actually is. 1920Useful in conjunction with the 1921.B \en[.ne] 1922register. 1923.TP 1924.B \en[.ss] 1925.TQ 1926.B \en[.sss] 1927These give the values of the parameters set by the 1928first and second arguments of the 1929.B ss 1930request. 1931.TP 1932.B \en[.vpt] 19331 if vertical position traps are enabled, 0 otherwise. 1934.TP 1935.B \en[.warn] 1936The sum of the numbers associated with each of the currently enabled 1937warnings. 1938The number associated with each warning is listed in the `Warnings' 1939subsection. 1940.TP 1941.B \en[.x] 1942The major version number. 1943For example, if the version number is 1944.B 1.03 1945then 1946.B \en[.x] 1947will contain 1948.BR 1 . 1949.TP 1950.B \en[.y] 1951The minor version number. 1952For example, if the version number is 1953.B 1.03 1954then 1955.B \en[.y] 1956will contain 1957.BR 03 . 1958.TP 1959.B \en[.Y] 1960The revision number of groff. 1961.TP 1962.B \en[llx] 1963.TQ 1964.B \en[lly] 1965.TQ 1966.B \en[urx] 1967.TQ 1968.B \en[ury] 1969These four registers are set by the 1970.B \&.psbb 1971request and contain the bounding box values (in PostScript units) of a given 1972PostScript image. 1973.LP 1974The following read/write registers are set by the 1975.B \ew 1976escape sequence: 1977.TP 1978.B \en[rst] 1979.TQ 1980.B \en[rsb] 1981Like the 1982.B st 1983and 1984.B sb 1985registers, but takes account of the heights and depths of characters. 1986.TP 1987.B \en[ssc] 1988The amount of horizontal space (possibly negative) that should 1989be added to the last character before a subscript. 1990.TP 1991.B \en[skw] 1992How far to right of the center of the last character 1993in the 1994.B \ew 1995argument, 1996the center of an accent from a roman font should be placed over that character. 1997.LP 1998Other available read/write number registers are: 1999.TP 2000.B \en[c.] 2001The current input line number. 2002.B \en[.c] 2003is a read-only alias to this register. 2004.TP 2005.B \en[hp] 2006The current horizontal position at input line. 2007.TP 2008.B \en[systat] 2009The return value of the system() function executed by the last 2010.B sy 2011request. 2012.TP 2013.B \en[slimit] 2014If greater than 0, the maximum number of objects on the input stack. 2015If less than or equal to 0, there is no limit on the number of objects 2016on the input stack. With no limit, recursion can continue until 2017virtual memory is exhausted. 2018.TP 2019.B \en[year] 2020The current year. 2021Note that the traditional 2022.B troff 2023number register 2024.B \en[yr] 2025is the current year minus 1900. 2026. 2027.SS Miscellaneous 2028. 2029.B @g@troff 2030predefines a single (read/write) string-based register, 2031.BR \e*(.T , 2032which contains the argument given to the 2033.B -T 2034command line option, namely the current output device (for example, 2035.I latin1 2036or 2037.IR ascii ). 2038Note that this is not the same as the (read-only) number register 2039.B \en[.T] 2040which is defined to be\ 1 if 2041.B troff 2042is called with the 2043.B -T 2044command line option, and zero otherwise. This behaviour is different to 2045UNIX troff. 2046.LP 2047Fonts not listed in the 2048.SM DESC 2049file are automatically mounted on the next available font position 2050when they are referenced. 2051If a font is to be mounted explicitly with the 2052.B fp 2053request on an unused font position, 2054it should be mounted on the first unused font position, 2055which can be found in the 2056.B \en[.fp] 2057register; 2058although 2059.B troff 2060does not enforce this strictly, 2061it will not allow a font to be mounted at a position whose number is much 2062greater than that of any currently used position. 2063.LP 2064Interpolating a string does not hide existing macro arguments. 2065Thus in a macro, a more efficient way of doing 2066.IP 2067.BI . xx\ \e\e$@ 2068.LP 2069is 2070.IP 2071.BI \e\e*[ xx ]\e\e 2072.LP 2073If the font description file contains pairwise kerning information, 2074characters from that font will be kerned. 2075Kerning between two characters can be inhibited by placing a 2076.B \e& 2077between them. 2078.LP 2079In a string comparison in a condition, 2080characters that appear at different input levels 2081to the first delimiter character will not be recognised 2082as the second or third delimiters. 2083This applies also to the 2084.B tl 2085request. 2086In a 2087.B \ew 2088escape sequence, 2089a character that appears at a different input level to 2090the starting delimiter character will not be recognised 2091as the closing delimiter character. 2092When decoding a macro argument that is delimited 2093by double quotes, a character that appears at a different 2094input level to the starting delimiter character will not 2095be recognised as the closing delimiter character. 2096The implementation of 2097.B \e$@ 2098ensures that the double quotes surrounding an argument 2099will appear the same input level, which will be different 2100to the input level of the argument itself. 2101In a long escape name 2102.B ] 2103will not be recognized as a closing delimiter except 2104when it occurs at the same input level as the opening 2105.BR ] . 2106In compatibility mode, no attention is paid to the input-level. 2107.LP 2108There are some new types of condition: 2109.TP 2110.BI .if\ r xxx 2111True if there is a number register named 2112.IR xxx . 2113.TP 2114.BI .if\ d xxx 2115True if there is a string, macro, diversion, or request named 2116.IR xxx . 2117.TP 2118.BI .if\ c ch 2119True if there is a character 2120.IR ch 2121available; 2122.I ch 2123is either an 2124.SM ASCII 2125character 2126or a special character 2127.BI \e( xx 2128or 2129.BI \e[ xxx ]\fR; 2130the condition will also be true if 2131.I ch 2132has been defined by the 2133.B char 2134request. 2135.LP 2136The 2137.B tr 2138request can now map characters onto 2139.BR \e~ . 2140. 2141.SS Warnings 2142. 2143The warnings that can be given by 2144.B troff 2145are divided into the following categories. 2146The name associated with each warning is used by the 2147.B \-w 2148and 2149.B \-W 2150options; 2151the number is used by the 2152.B warn 2153request, and by the 2154.B .warn 2155register. 2156.nr x \w'\fBright-brace'+1n+\w'0000'u 2157.ta \nxuR 2158.TP \nxu+3n 2159.BR char \t1 2160Non-existent characters. 2161This is enabled by default. 2162.TP 2163.BR number \t2 2164Invalid numeric expressions. 2165This is enabled by default. 2166.TP 2167.BR break \t4 2168In fill mode, lines which could not be broken so that their length was 2169less than the line length. 2170This is enabled by default. 2171.TP 2172.BR delim \t8 2173Missing or mismatched closing delimiters. 2174.TP 2175.BR el \t16 2176Use of the 2177.B el 2178request with no matching 2179.B ie 2180request. 2181.TP 2182.BR scale \t32 2183Meaningless scaling indicators. 2184.TP 2185.BR range \t64 2186Out of range arguments. 2187.TP 2188.BR syntax \t128 2189Dubious syntax in numeric expressions. 2190.TP 2191.BR di \t256 2192Use of 2193.B di 2194or 2195.B da 2196without an argument when there is no current diversion. 2197.TP 2198.BR mac \t512 2199Use of undefined strings, macros and diversions. 2200When an undefined string, macro or diversion is used, 2201that string is automatically defined as empty. 2202So, in most cases, at most one warning will be given for 2203each name. 2204.TP 2205.BR reg \t1024 2206Use of undefined number registers. 2207When an undefined number register is used, 2208that register is automatically defined to have a value of 0. 2209a definition is automatically made with a value of 0. 2210So, in most cases, at most one warning will be given for 2211use of a particular name. 2212.TP 2213.BR tab \t2048 2214Inappropriate use of a tab character. 2215Either use of a tab character where a number was expected, 2216or use of tab character in an unquoted macro argument. 2217.TP 2218.BR right-brace \t4096 2219Use of 2220.B \e} 2221where a number was expected. 2222.TP 2223.BR missing \t8192 2224Requests that are missing non-optional arguments. 2225.TP 2226.BR input \t16384 2227Illegal input characters. 2228.TP 2229.BR escape \t32768 2230Unrecognized escape sequences. 2231When an unrecognized escape sequence is encountered, 2232the escape character is ignored. 2233.TP 2234.BR space \t65536 2235Missing space between a request or macro and its argument. 2236This warning will be given 2237when an undefined name longer than two characters is encountered, 2238and the first two characters of the name make a defined name. 2239The request or macro will not be invoked. 2240When this warning is given, no macro is automatically defined. 2241This is enabled by default. 2242This warning will never occur in compatibility mode. 2243.TP 2244.BR font \t131072 2245Non-existent fonts. 2246This is enabled by default. 2247.TP 2248.BR ig \t262144 2249Illegal escapes in text ignored with the 2250.B ig 2251request. 2252These are conditions that are errors when they do not occur 2253in ignored text. 2254.LP 2255There are also names that can be used to refer to groups of warnings: 2256.TP 2257.B all 2258All warnings except 2259.BR di , 2260.B mac 2261and 2262.BR reg . 2263It is intended that this covers all warnings 2264that are useful with traditional macro packages. 2265.TP 2266.B w 2267All warnings. 2268. 2269.SS Incompatibilities 2270. 2271.LP 2272Long names cause some incompatibilities. 2273UNIX troff will interpret 2274.IP 2275.B 2276\&.dsabcd 2277.LP 2278as defining a string 2279.B ab 2280with contents 2281.BR cd . 2282Normally, GNU troff will interpret this as a call of a macro named 2283.BR dsabcd . 2284Also UNIX troff will interpret 2285.B \e*[ 2286or 2287.B \en[ 2288as references to a string or number register called 2289.BR [ . 2290In GNU troff, however, this will normally be interpreted as the start 2291of a long name. 2292In 2293.I compatibility mode 2294GNU troff will interpret these things in the traditional way. 2295In compatibility mode, however, long names are not recognised. 2296Compatibility mode can be turned on with the 2297.B \-C 2298command line option, and turned on or off with the 2299.B cp 2300request. 2301The number register 2302.B \en[.C] 2303is 1 if compatibility mode is on, 0 otherwise. 2304.LP 2305GNU troff 2306does not allow the use of the escape sequences 2307.BR \\e\e|\e^\e&\e}\e{\e (space) \e'\e`\e-\e_\e!\e%\ec 2308in names of strings, macros, diversions, number registers, 2309fonts or environments; UNIX troff does. 2310The 2311.B \eA 2312escape sequence may be helpful in avoiding use of these 2313escape sequences in names. 2314.LP 2315Fractional pointsizes cause one noteworthy incompatibility. 2316In UNIX troff the 2317.B ps 2318request ignores scale indicators and so 2319.IP 2320.B .ps\ 10u 2321.LP 2322will set the pointsize to 10 points, whereas in 2323GNU troff it will set the pointsize to 10 scaled points. 2324.LP 2325In GNU troff there is a fundamental difference between unformatted, 2326input characters, and formatted, output characters. 2327Everything that affects how an output character 2328will be output is stored with the character; once an output 2329character has been constructed it is unaffected by any subsequent 2330requests that are executed, including 2331.BR bd , 2332.BR cs , 2333.BR tkf , 2334.BR tr , 2335or 2336.B fp 2337requests. 2338Normally output characters are constructed from input 2339characters at the moment immediately before the character 2340is added to the current output line. 2341Macros, diversions and strings are all, in fact, the same type 2342of object; they contain lists of input characters and output 2343characters in any combination. 2344An output character does not behave like an input character 2345for the purposes of macro processing; it does not inherit any 2346of the special properties that the input character from which it 2347was constructed might have had. 2348For example, 2349.IP 2350.nf 2351.ft B 2352\&.di x 2353\e\e\e\e 2354\&.br 2355\&.di 2356\&.x 2357.ft 2358.fi 2359.LP 2360will print 2361.B \e\e 2362in GNU troff; 2363each pair of input 2364.BR \e s 2365is turned into one output 2366.B \e 2367and the resulting output 2368.BR \e s 2369are not interpreted as escape characters when they are reread. 2370UNIX troff would interpret them as escape characters 2371when they were reread and would end up printing one 2372.BR \e . 2373The correct way to obtain a printable 2374.B \e 2375is to use the 2376.B \ee 2377escape sequence: this will always print a single instance of the 2378current escape character, regardless of whether or not it is used in a 2379diversion; it will also work in both GNU troff and UNIX troff. 2380If you wish for some reason to store in a diversion an escape 2381sequence that will be interpreted when the diversion is reread, 2382you can either use the traditional 2383.B \e!\& 2384transparent output facility, or, if this is unsuitable, the new 2385.B \e?\& 2386escape sequence. 2387. 2388. 2389.SH ENVIRONMENT 2390. 2391. 2392.TP 2393.SM 2394.B GROFF_TMAC_PATH 2395A colon separated list of directories in which to search for 2396macro files. 2397.B troff 2398will scan directories given in 2399the 2400.B \-M 2401option before these, and in standard directories (current directory if in 2402unsafe mode, home directory, 2403.BR @LOCALMACRODIR@ , 2404.BR @SYSTEMMACRODIR@ , 2405.BR @MACRODIR@ ) 2406after these. 2407.TP 2408.SM 2409.B GROFF_TYPESETTER 2410Default device. 2411.TP 2412.SM 2413.B GROFF_FONT_PATH 2414A colon separated list of directories in which to search for the 2415.BI dev name 2416directory. 2417.B troff 2418will scan directories given in the 2419.B \-F 2420option before these, and in standard directories 2421.RB ( @FONTPATH@ ) 2422after these. 2423. 2424. 2425.SH FILES 2426. 2427. 2428.Tp \w'@FONTDIR@/devname/DESC'u+3n 2429.B @MACRODIR@/troffrc 2430Initialization file (called before any other macro package). 2431.TP 2432.B @MACRODIR@/troffrc-end 2433Initialization file (called after any other macro package). 2434.TP 2435.BI @MACRODIR@/ name .tmac 2436.TQ 2437.BI @MACRODIR@/tmac. name 2438Macro files 2439.TP 2440.BI @FONTDIR@/dev name /DESC 2441Device description file for device 2442.IR name . 2443.TP 2444.BI @FONTDIR@/dev name / F 2445Font file for font 2446.I F 2447of device 2448.IR name . 2449.LP 2450Note that 2451.B troffrc 2452and 2453.B troffrc-end 2454are neither searched in the current nor in the home directory by default for 2455security reasons (even if the 2456.B \-U 2457option is given). 2458Use the 2459.B \-M 2460command line option or the 2461.B GROFF_TMAC_PATH 2462environment variable to add these directories to the search path if 2463necessary. 2464. 2465. 2466.SH "SEE ALSO" 2467. 2468. 2469.BR groff (@MAN7EXT@) 2470-- This is a short but complete reference of all requests, registers, and 2471escapes. 2472.PP 2473.BR groff (@MAN1EXT@), 2474.BR @g@tbl (@MAN1EXT@), 2475.BR @g@pic (@MAN1EXT@), 2476.BR @g@eqn (@MAN1EXT@), 2477.BR @g@refer (@MAN1EXT@), 2478.BR @g@soelim (@MAN1EXT@), 2479.BR @g@grn (@MAN1EXT@), 2480.BR grops (@MAN1EXT@), 2481.BR grodvi (@MAN1EXT@), 2482.BR grotty (@MAN1EXT@), 2483.BR grohtml (@MAN1EXT@), 2484.BR grolj4 (@MAN1EXT@), 2485.BR groff_font (@MAN5EXT@), 2486.BR groff_out (@MAN5EXT@), 2487.BR groff_char (@MAN7EXT@) 2488. 2489.\" Local Variables: 2490.\" mode: nroff 2491.\" End: 2492