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