wdvi.1 (38657B)
1 .\" Copyright (c) 1990-2013 Paul Vojta 2 .\" 3 .\" Permission is hereby granted, free of charge, to any person obtaining a copy 4 .\" of this software and associated documentation files (the "Software"), to 5 .\" deal in the Software without restriction, including without limitation the 6 .\" rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 7 .\" sell copies of the Software, and to permit persons to whom the Software is 8 .\" furnished to do so, subject to the following conditions: 9 .\" 10 .\" The above copyright notice and this permission notice shall be included in 11 .\" all copies or substantial portions of the Software. 12 .\" 13 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 14 .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 15 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 16 .\" IN NO EVENT SHALL PAUL VOJTA OR ANY OTHER AUTHOR OF OR CONTRIBUTOR TO 17 .\" THIS SOFTWARE BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 18 .\" WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 19 .\" OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 20 .\" IN THE SOFTWARE. 21 .\" 22 .if t .ds Te T\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X 23 .if n .ds Te TeX 24 ' # small and boldface (not all -man's provide it) 25 .de SB 26 \&\fB\s-1\&\\$1 \\$2\s0\fR 27 .. 28 .TH WDVI 1 "9 September 2021" "X Version 11" 29 .SH NAME 30 wdvi \- network DVI viewer for the X Window System 31 .SH SYNOPSIS 32 .B wdvi 33 .nh 34 [\fB\-s\fP \fIshrink\fP] 35 [\fB\-nocolor\fP] 36 [\fB\-gamma\fP \fIg\fP] 37 [\fB\-p\fP \fIpixels\fP] 38 [\fB\-altfont\fP \fIfont\fP] 39 [\fB\-mfmode\fP \fImode-def\fP[\fB:\fP\fIdpi\fP]] 40 [\fB\-l\fP] 41 [\fB\-rv\fP] 42 [\fB\-fg\fP \fIcolor\fP] 43 [\fB\-bg\fP \fIcolor\fP] 44 [\fB\-display\fP \fIhost:display\fP] 45 [\fB\-geometry\fP \fIgeometry\fP] 46 [\fB\-copy\fP] 47 [\fB\-thorough\fP] 48 [\fB\-debug\fP \fIbitmask\fP] 49 [\fB\-v\fP] 50 .I url 51 .hy 52 .SH DESCRIPTION 53 .B wdvi 54 is a program which runs under the X window system. It is used to view 55 .I dvi 56 files, such as are produced by 57 .BR tex (1). 58 It fetches these 59 .I dvi 60 files over the network using the hypertext transfer protocol secure (HTTPS). 61 .PP 62 This program has the capability of fetching a 63 .I dvi 64 file either from a url specified in the address bar or from a hyperlink 65 in the previously fetched document. 66 .PP 67 If 68 .B wdvi 69 is run without the 70 .I url 71 argument it opens a default document and waits for user input. 72 .SH OPTIONS 73 In addition to specifying a 74 .I url 75 .B wdvi 76 supports the following command line options. If the option begins with a 77 .RB ` + ' 78 instead of a 79 .RB ` \- ', 80 the option is restored to its default value. By default, these options can 81 be set via the resource names given in parentheses in the description of 82 each option. 83 .TP 84 .BI \-altfont " font" 85 .RB ( .altFont ) 86 Declares a default font to use when the font in the 87 .I dvi 88 file cannot be found. This is useful, for example, with PostScript <tm> fonts. 89 .TP 90 .BI \-background " color" 91 .RB ( .background ) 92 Same as 93 .BR -bg . 94 .TP 95 .BI \-bg " color" 96 .RB ( .background ) 97 Determines the color of the background. 98 .TP 99 .B \-copy 100 .RB ( .copy ) 101 Always use the 102 .I copy 103 operation when writing characters to the display. 104 This option may be necessary for correct operation on a color display, but 105 overstrike characters will be incorrect. 106 The 107 .B \-copy 108 operation will disable the use of colorplanes and make overstrikes come 109 out incorrectly. 110 See also 111 .BR \-thorough . 112 .TP 113 .BI \-debug " bitmask" 114 .RB ( .debugLevel ) 115 If nonzero, prints additional debugging information on standard output. 116 The bitmask should be given as a decimal number. The value of the bits 117 that can be combined are as follows: 118 .nf 119 .sp 1n 120 .ta 1L +8L +12L 121 1 bitmap Bitmap creation 122 2 dvi DVI translation 123 4 pk PK fonts handling 124 16 event Event handling 125 32 open File searching 126 64 ps Prescan information 127 128 client X client information 128 255 all Everything 129 .fi 130 .TP 131 .BI \-display " host" : display 132 Specifies the host and screen to be used for displaying the 133 .I dvi 134 file. By default this is obtained from the environment variable 135 .SB DISPLAY. 136 .TP 137 .BI \-fg " color" 138 .RB ( .foreground ) 139 Determines the color of the text (foreground). 140 .TP 141 .BI \-foreground " color" 142 Same as 143 .BR -fg . 144 .TP 145 .BI \-gamma " gamma" 146 .RB ( .gamma ) 147 Controls the interpolation of colors in the greyscale anti-aliasing color 148 palette. Default value is 1.0. For 0 < 149 .I gamma 150 < 1, the fonts will be lighter (more like the background), and for 151 .I gamma 152 > 1, the fonts will be darker (more like the foreground). Negative 153 values behave the same way, but use a slightly different algorithm. 154 See also the 155 .RB ` S ' 156 keystroke. 157 .TP 158 .BI \-geometry " geometry" 159 .RB ( *geometry ) 160 Specifies the initial geometry of the window. 161 .TP 162 .B \-l 163 .RB ( .listFonts ) 164 Causes the names of the fonts used to be listed. 165 .TP 166 .BI \-mfmode " mode-def\fR[\fP\fB:\fPdpi\fR]\fP" 167 .RB ( .mfMode ) 168 Specifies a 169 .I mode-def 170 string, which can be used in searching for fonts (see ENVIRONMENT, below). 171 Generally, when changing the 172 .IR mode-def , 173 it is also necessary to change the font size to the appropriate value 174 for that mode. This is done by adding a colon and the value in dots per inch; 175 for example, 176 .BR "\-mfmode ljfour:600" . 177 This method overrides any value given by the 178 .B pixelsPerInch 179 resource or the 180 .B \-p 181 command-line argument. 182 By default, it is 183 .BR "cx:600" . 184 .TP 185 .B \-nocolor 186 .RB ( .color ) 187 Turns off the use of color specials. This option can be toggled with the 188 .RB ` C ' 189 keystroke. 190 (For this option, the logic of the corresponding resource is reversed: 191 .B \-nocolor 192 corresponds to 193 .BR color:off ; 194 .B +nocolor 195 to 196 .BR color:on .) 197 .TP 198 .BI \-p " pixels" 199 .RB ( .pixelsPerInch ) 200 Defines the size of the fonts to use, in pixels per inch. The 201 default value is 600. This option is provided only for backwards 202 compatibility; the preferred way of setting the font size is by setting the 203 Metafont mode at the same time; see the 204 .B \-mfmode 205 option. 206 .TP 207 .B \-rv 208 .RB ( .reverseVideo ) 209 Causes the page to be displayed with white characters on a black background, 210 instead of vice versa. 211 .TP 212 .BI \-s " shrink" 213 .RB ( .shrinkFactor ) 214 Defines the initial shrink factor. The default value is 3. If 215 .I shrink 216 is given as 0, then the initial shrink factor is computed so that the 217 page fits within the window (as if the `s' keystroke were given without 218 a number). The maximum shrink factor is 10. 219 .TP 220 .B \-thorough 221 .RB ( .thorough ) 222 .B wdvi 223 will usually try to ensure that overstrike characters 224 .RI ( e.g. , 225 .BR \enotin ) 226 are printed correctly. On monochrome displays, this is always possible 227 with one logical operation, either 228 .I and 229 or 230 .IR or . 231 On color displays, however, this may take two operations, one to set the 232 appropriate bits and one to clear other bits. If this is the case, then 233 by default 234 .B wdvi 235 will instead use the 236 .I copy 237 operation, which does not handle overstriking correctly. The 238 .B \-thorough 239 option chooses the slower but more correct choice. See also 240 .BR \-copy . 241 .TP 242 .BI \-v 243 Print information on the version of 244 .BR wdvi . 245 .SH KEYSTROKES 246 .B wdvi 247 recognizes the following keystrokes when typed in its window. 248 Each may optionally be preceded by a (positive or negative) number, whose 249 interpretation will depend on the particular keystroke. 250 Also, the ``Home'', ``Prior'', ``Next'', and arrow cursor keys are synonyms for 251 .RB ` ^ ', 252 .RB ` b ', 253 .RB ` n ', 254 .RB ` l ', 255 .RB ` r ', 256 .RB ` u ', 257 and 258 .RB ` d ' 259 keys, respectively. 260 .TP 261 .B q 262 .RB [ quit() ] 263 Quits the program. Control-C and control-D will do this, too. 264 .TP 265 .B n 266 .RB [ forward-page() ] 267 Moves to the next page (or to the 268 .IR n th 269 next page if a number is given). 270 .TP 271 .I Space 272 .RB [ down-or-next() ] 273 Moves down two-thirds of a window-full, or to the next page if already at 274 the bottom of the page. 275 .TP 276 .B f 277 .RB [ show-links() ] 278 Highlights a single letter inside each hyperlink that is currently visible, 279 and waits for another keystroke. If the next keystroke is one of the 280 highlighted letters then fetch that link, otherwise highlights are erased 281 and normal operation continues. 282 .TP 283 .I Return 284 .RB [ addr-go() ] 285 Fetches the current document in the address bar. If an error occurs, the 286 current document will not be replaced. 287 .TP 288 .B p 289 .RB [ back-page() ] 290 Moves to the previous page (or back 291 .I n 292 pages). Synonyms are 293 .RB ` b ' 294 and control-H. 295 .TP 296 .I Delete 297 .RB [ up-or-previous() ] 298 Moves up two-thirds of a window-full, or to the bottom of the previous page 299 if already at the top of the page. The BackSpace key will also do this. 300 .TP 301 .B g 302 .RB [ goto-page() ] 303 Moves to the page with the given number. Initially, the first page is assumed 304 to be page number 1, but this can be changed with the 305 .RB ` P ' 306 keystroke, below. If no page number is given, then it goes to the last page. 307 .TP 308 .B P 309 .RB [ declare-page-number() ] 310 ``This is page number 311 .IR n .'' 312 This can be used to make the 313 .RB ` g ' 314 keystroke refer to actual page numbers instead of absolute page numbers. 315 .TP 316 .IB Control\- L 317 .RB [ forward-page(0) ] 318 Redisplays the current page. 319 .TP 320 .B ^ 321 .RB [ home() ] 322 Move to the ``home'' position of the page. This is normally the upper 323 left-hand corner of the page, depending on the margins as described in the 324 .B \-margins 325 option, above. 326 .TP 327 .B u 328 .RB [ up() ] 329 Moves up two thirds of a window-full. 330 .TP 331 .B d 332 .RB [ down() ] 333 Moves down two thirds of a window-full. 334 .TP 335 .B l 336 .RB [ left() ] 337 Moves left two thirds of a window-full. 338 .TP 339 .B r 340 .RB [ right() ] 341 Moves right two thirds of a window-full. 342 .TP 343 .B c 344 .RB [ center() ] 345 Moves the page so that the point currently beneath the cursor is moved to 346 the middle of the window. It also (gasp!) warps the cursor to the same place. 347 .TP 348 .IB Control\- P 349 .RB [ print() ] 350 Pop up a window to allow 351 .B wdvi 352 to print the 353 .I dvi 354 file or a range of pages from it. The popup window is mostly self-explanatory, 355 but the window showing 356 .B dvips 357 progress accepts some keystrokes that are not obvious. In that second window, 358 .IB Control\- C 359 is equivalent to clicking on the 360 .B Cancel 361 button, 362 .I Return 363 is equivalent to clicking on the 364 .B Close window 365 button, and 366 .IB Control\- S 367 and 368 .IB Control\- Q 369 select and deselect, respectively, the option of keeping the window open after 370 .B dvips 371 finishes. 372 .TP 373 .B s 374 .RB [ set-shrink-factor() ] 375 Changes the shrink factor to the given number. If no number is given, the 376 smallest factor that makes the entire page fit in the window will be used. 377 (Margins are ignored in this computation.) 378 .TP 379 .B S 380 .RB [ set-density() ] 381 Sets the gamma factor to be used when shrinking bitmaps. This should 382 be a number between 0 and 1000; higher numbers produce darker characters. 383 The new value of gamma is the given number divided by 100; negative values 384 are allowed. 385 .TP 386 .B C 387 .RB [ set-color() ] 388 This key toggles the use of color specials. The key sequences 389 .RB ` 0C ' 390 and 391 .RB ` 1C ' 392 turn interpretation of color specials off and on, respectively. 393 See also the 394 .B \-nocolor 395 option. 396 .SH MOUSE ACTIONS 397 If the shrink factor is set to any number other than one, then clicking 398 any mouse button will pop up a ``magnifying glass'' which shows the unshrunk 399 image in the vicinity of the mouse click. This subwindow disappears when 400 the mouse button is released. Different mouse buttons produce different sized 401 windows. 402 Moving the cursor while holding the button down will move the 403 magnifying glass. To access this feature via customization, use the 404 .B magnifier 405 action. Its argument is either a string of the form 406 .IR width x height , 407 or one of the strings 408 .B *1 409 through 410 .BR *5 . 411 .PP 412 The scrollbars (if present) behave in the standard way: pushing Button 2 413 in a scrollbar moves the top or left edge of the scrollbar to that point 414 and optionally drags it; 415 pushing Button 1 moves the image up or right by an amount equal to the distance 416 from the button press to the upper left-hand corner of the window; pushing 417 Button 3 moves the image down or left by the same amount. 418 .PP 419 The image can also be dragged around, by holding down the shift key 420 and a mouse button. Shift-button 1 will allow vertical dragging only; 421 Shift-button 3, horizontal dragging; and Shift-button 2 allows dragging 422 in either direction. To access these actions via customization, use the 423 .B drag 424 action. This action should have one parameter, the character 425 .RB `` | '', 426 .RB `` - '', 427 or 428 .RB `` + '', 429 indicating vertical dragging, horizontal dragging, or dragging in both 430 directions. 431 .PP 432 Wheel mice are supported: motion of the wheel on such a mouse moves the 433 image up, down, left, or right. 434 To access this option via customization, use the 435 .B wheel 436 and 437 .B hwheel 438 action for vertical and horizontal scrolling, respectively. These actions 439 take one parameter, giving the distance to scroll 440 the image. If the parameter contains a decimal point, the distance is given 441 in wheel units; otherwise, pixels. Not all wheel mice support horizontal 442 scrolling. 443 .SH UNBOUND ACTIONS 444 The following actions have not been assigned any keystroke, but are available 445 if customization is used. 446 .TP 447 .B shrink-to-dpi() 448 This action takes one (required) argument. It sets the shrink factor to 449 an integer so as to approximate the use of fonts with the corresponding 450 number of dots per inch. If 451 .B wdvi 452 is using fonts scaled for 453 .I p 454 dots per inch, and the argument to 455 .B shrink-to-dpi 456 is 457 .IR n , 458 then the corresponding shrink factor is the ratio 459 .IR p / n , 460 rounded to the nearest integer. 461 .SH CUSTOMIZATION 462 Key and mouse button assignments can be changed by setting the 463 .B mainTranslations 464 resource to a string of translations as defined in the documentation for the 465 X toolkit. The actions should take the form of action names as given in the 466 KEYSTROKES and MOUSE ACTIONS sections. 467 .PP 468 Key actions will usually be without arguments, or they may give an argument 469 to replace an optional number typed immediately prior to the action. The keys 470 .BR 0 \- 9 471 and hyphen cannot be reassigned, since they are used for inputting numbers. 472 .PP 473 Some key actions may take special arguments, as follows. 474 The argument of 475 .B goto-page 476 may be the letter 477 .RB ` e ', 478 indicating the action of going to the end of the document. 479 The argument of 480 .B set-shrink-factor 481 may be the letter 482 .RB ` a ', 483 indicating that the shrink factor should be set to the smallest value such that 484 the page will fit in the window. 485 The actions 486 .BR up , 487 .BR down , 488 .BR left , 489 .BR right , 490 .BR up-or-previous , 491 and 492 .BR down-or-next 493 may give a decimal number, indicating what fraction of a window-full to move 494 (in place of two thirds). 495 Finally, for actions that would perform a toggle 496 the argument may be the letter 497 .RB ` t ', 498 indicating that the action should toggle regardless of what number may have 499 been typed recently. 500 .PP 501 Mouse actions should refer only to 502 .B ButtonPress 503 events (e.g., 504 .BR "<Btn1Down>:magnifier(*1)" ). 505 The corresponding motion and release events will then be handled internally. 506 A key action may be bound to a mouse event, but not vice versa. 507 .PP 508 Usually the string of translations should begin with 509 .RB `` #override '', 510 indicating that the default key and mouse button assignments should not 511 be discarded. 512 .PP 513 When keys or mouse buttons involving modifiers (such as Ctrl or Shift) 514 are customized together with their non-modified equivalents, the modified 515 keys should come first, for example: 516 .RS 5 517 .nf 518 .ft 3 519 .sp 1n 520 XDvi.mainTranslations: #override \\ 521 Ctrl<Btn1Down>: magnifier(*3)\\n\\ 522 Shift<Btn1Down>: magnifier(*2)\\n\\ 523 <Btn1Down>: magnifier(*1) 524 .sp 1n 525 .ft 526 .fi 527 .RE 528 .PP 529 Because 530 .B wdvi 531 needs to capture pointer motion events, and because the X Toolkit 532 translations mechanism cannot accommodate both motion events and double-click 533 events at the same time, it is not possible to specify double-click 534 actions in 535 .B wdvi 536 customizations. For information on this and other aspects of translations, 537 see the X Toolkit Intrinsics documentation. 538 .PP 539 There is no command-line option to set the 540 .B mainTranslations 541 resource, since changing this resource on the command line would be cumbersome. 542 However, see the section on CUSTOMIZATION EXAMPLES for information on how 543 to set the resource for testing purposes using the 544 .B \-xrm 545 command-line option. 546 .PP 547 Support of wheel mice is controlled by the 548 .B wheelTranslations 549 resource. Generally the only action routines called by this resource should be 550 .B wheel 551 and 552 .BR hwheel . 553 Its default value is 554 .RS 5 555 .nf 556 .ft 3 557 .sp 1n 558 <Btn4Down>:wheel(-1.)\\n\\ 559 <Btn5Down>:wheel(1.)\\n\\ 560 <Btn6Down>:hwheel(-1.)\\n\\ 561 <Btn7Down>:hwheel(1.) 562 .sp 1n 563 .ft 564 .fi 565 .RE 566 .PP 567 When specifying a value for this resource, all wheel actions should be 568 included. 569 .PP 570 The X Toolkit routines that implement translations do not support event 571 types of 572 .B Btn6Down 573 or 574 .BR Btn7Down . 575 Because of this, 576 .B wdvi 577 implements its own parser for translations given in 578 .BR wheelTranslations . 579 This parser is more limited than the parser built in to the X Toolkit. 580 It should not begin with 581 .RB `` #replace '', 582 .RB `` #augment '', 583 or 584 .RB `` #override ''. 585 Modifiers of the form 586 .BI @ keysym 587 are not supported, and the event type must be of the form 588 .B BtnDown 589 or 590 .BI Btn n Down\fR,\fP 591 where 592 .I n 593 is a positive integer without leading zeroes. Also, some limitations apply 594 to the action field. 595 .SH CUSTOMIZATION EXAMPLES 596 .PP 597 Some users prefer that the window scroll smoothly when they hold down the 598 arrow keys, instead of giving a large motion each time they type the keys. 599 To get this scrolling behavior, the following resource can be used. 600 .RS 5 601 .nf 602 .ft 3 603 .sp 1n 604 XDvi.mainTranslations: #override \\ 605 <Key>Up:up(.01)\\n\\ 606 <Key>Down:down(.01)\\n\\ 607 <Key>Left:left(.01)\\n\\ 608 <Key>Right:right(.01) 609 .sp 1n 610 .ft 611 .fi 612 .RE 613 .PP 614 To set the 615 .B mainTranslations 616 resource for testing purposes, use the 617 .B \-xrm 618 command-line option provided by the X toolkit. For example, 619 .RS 5 620 .nf 621 .ft 3 622 .sp 1n 623 wdvi \-xrm 'XDvi.mainTranslations: #override "z":quit()' ... 624 .sp 1n 625 .ft 626 .fi 627 .RE 628 or 629 .RS 5 630 .nf 631 .ft 3 632 .sp 1n 633 wdvi \-xrm 'XDvi.mainTranslations: #override <Key>z:quit()' ... 634 .sp 1n 635 .ft 636 .fi 637 .RE 638 will cause the key 639 .RB ` z ' 640 to quit 641 .BR wdvi . 642 This method also works with the other translation resources. 643 .SH SPECIALS (GENERALLY) 644 Any of the specials used by 645 .B wdvi 646 may be preceded by the characters 647 .RB `` xdvi: ''. 648 Doing so does not change the behavior of the special under 649 .BR wdvi , 650 but it causes other 651 .I dvi 652 viewers to ignore the special. 653 .SH PAPERSIZE SPECIALS 654 .B wdvi 655 accepts specials to set the paper size for the document. These specials 656 should be of the form 657 .RS 5 658 .nf 659 .sp 1n 660 \fBpapersize=\fIwidth\fP,\fIheight\fP 661 .sp 1n 662 .fi 663 .RE 664 .PP 665 where 666 .I width 667 and 668 .I height 669 give the width and height of the paper, respectively. Each of these should 670 appear in the form of a decimal number followed by any of the two-letter 671 abbreviations for units accepted by \*(Te\& 672 .RB ( pt , 673 .BR pc , 674 .BR in , 675 .BR bp , 676 .BR cm , 677 .BR mm , 678 .BR dd , 679 .BR cc , 680 or 681 .BR sp ). 682 This format is compatible with 683 .BR dvips . 684 .P 685 The last 686 .B papersize 687 special on a page determines the size of that page. If there is no such 688 special on a given page, the most recent 689 .B papersize 690 is used, or, if there are no 691 .B papersize 692 specials on any preceding page, 693 then the default paper size of 8.5 x 11 inches is used. 694 Thus the paper size may vary for different pages of the 695 .I dvi 696 file. 697 .SH COLOR SPECIALS 698 The color specials supported by 699 .B wdvi 700 are the same as those supported by 701 .BR dvips , 702 except that the literal PostScript color specification (as in the 703 .B AggiePattern 704 example in the 705 .B dvips 706 documentation) is not supported. In particular, the LaTeX 707 .B color 708 package will work with 709 .BR wdvi . 710 See the documentation of the LaTeX 711 .B color 712 package for details on its use, and also see the 713 .B dvips 714 documentation file 715 .B dvips.tex 716 for details on the syntax and semantics of the color specials. 717 .P 718 Support for color specials includes the same list of named colors as 719 .BR dvips , 720 namely: 721 .BR Apricot , 722 .BR Aquamarine , 723 .BR Bittersweet , 724 .BR Black , 725 .BR Blue , 726 .BR BlueGreen , 727 .BR BlueViolet , 728 .BR BrickRed , 729 .BR Brown , 730 .BR BurntOrange , 731 .BR CadetBlue , 732 .BR CarnationPink , 733 .BR Cerulean , 734 .BR CornflowerBlue , 735 .BR Cyan , 736 .BR Dandelion , 737 .BR DarkOrchid , 738 .BR Emerald , 739 .BR ForestGreen , 740 .BR Fuchsia , 741 .BR Goldenrod , 742 .BR Gray , 743 .BR Green , 744 .BR GreenYellow , 745 .BR JungleGreen , 746 .BR Lavender , 747 .BR LimeGreen , 748 .BR Magenta , 749 .BR Mahogany , 750 .BR Maroon , 751 .BR Melon , 752 .BR MidnightBlue , 753 .BR Mulberry , 754 .BR NavyBlue , 755 .BR OliveGreen , 756 .BR Orange , 757 .BR OrangeRed , 758 .BR Orchid , 759 .BR Peach , 760 .BR Periwinkle , 761 .BR PineGreen , 762 .BR Plum , 763 .BR ProcessBlue , 764 .BR Purple , 765 .BR RawSienna , 766 .BR Red , 767 .BR RedOrange , 768 .BR RedViolet , 769 .BR Rhodamine , 770 .BR RoyalBlue , 771 .BR RoyalPurple , 772 .BR RubineRed , 773 .BR Salmon , 774 .BR SeaGreen , 775 .BR Sepia , 776 .BR SkyBlue , 777 .BR SpringGreen , 778 .BR Tan , 779 .BR TealBlue , 780 .BR Thistle , 781 .BR Turquoise , 782 .BR Violet , 783 .BR VioletRed , 784 .BR White , 785 .BR WildStrawberry , 786 .BR Yellow , 787 .BR YellowGreen , 788 .BR YellowOrange . 789 Note that these names are case sensitive. 790 .P 791 At present, the 792 .B \ecolorbox 793 and 794 .B \efcolorbox 795 macros are not supported. This includes use of the 796 .B columncolor 797 macro in the 798 .B colortbl 799 package, and the 800 .B shaded 801 environment in the 802 .B framed 803 La\*(Te\&2e package. 804 .SH ENVIRONMENT 805 .TP 806 .SB DISPLAY 807 Specifies which graphics display terminal to use. 808 .TP 809 .SB TEXMF 810 Indicates the top directory of \*(Te\& Directory Structure (TDS) trees to use 811 when searching for files. It should be a list of directories, separated by 812 colons. An extra colon anywhere in the variable incorporates the compiled-in 813 default value at that point. 814 See the section on FILE SEARCHING for more details. 815 .TP 816 .SB XDVISIZES 817 A list of font resolutions separated by colons. If a font cannot be found 818 or made at its stated size, then these sizes are tried as a fallback. 819 .B wdvi 820 tries the actual size of the font before trying any of the given sizes. 821 Each font resolution should be a positive integer, specifying the number 822 of dots per inch, or a string of the form 823 .BR magstep\fIn\fP , 824 where 825 .I n 826 is a number -9.5, -9, -8.5, ..., 8, 8.5, 9, or 9.5. The string 827 .B magstep 828 may be shortened to any non-empty initial substring (so that 829 .B magstep0.5 830 may be shortened to 831 .B mag0.5 832 or 833 .B m0.5 834 (but not 835 .BR mag.5 )). 836 The entries 837 .BI magstep n 838 signify the current pixels-per-inch value, multiplied by 1.2 raised to the 839 .IR n th 840 power, and rounded to the nearest integer. 841 If the list begins with a colon, the system default sizes are used, as well. 842 Sizes are expressed in dots per inch and must be integers. 843 The current default set of sizes is m0:m0.5:m1:m2:m3:m4:m5. 844 .B wdvi 845 will also try the actual size of the font before trying any of the given sizes. 846 .TP 847 .SB XDVIFONTS 848 Determines the path(s) searched for 849 .I pk 850 and 851 .I gf 852 font pixel files. See the section on FILE SEARCHING for more details. 853 .TP 854 .SB PKFONTS 855 Determines the path(s) searched for 856 .I pk 857 and 858 .I gf 859 font pixel files if 860 .SB XDVIFONTS 861 is not set. 862 .TP 863 .SB TEXPKS 864 Determines the path(s) searched for 865 .I pk 866 and 867 .I gf 868 font pixel files if neither 869 .SB XDVIFONTS 870 nor 871 .SB PKFONTS 872 is set. 873 .TP 874 .SB TEXFONTS 875 Determines the path(s) searched for 876 .I pk 877 and 878 .I gf 879 font pixel files if none of 880 .SB XDVIFONTS, 881 .SB PKFONTS, 882 and 883 .SB TEXPKS 884 are set. It may also be used for searching for fontmap files, encoding files, 885 and Type 1 font files. 886 If 887 .SB TEXFONTS 888 is used, it should not contain any 889 .RB ` % ' 890 signs, since 891 .B wdvi 892 interprets this as a special character, but other applications do not. 893 .TP 894 .SB XDVIVFS 895 Determines the path(s) searched for virtual fonts 896 .RI ( vf 897 files). See the section on FILE SEARCHING for more details. 898 .TP 899 .SB VFFONTS 900 Determines the path(s) searched for 901 .I vf 902 fonts if 903 .SB XDVIVFS 904 is not set. If this is used, it should not contain any 905 .RB ` % ' 906 signs, since 907 .B wdvi 908 interprets this as a special character, but other applications do not. 909 .TP 910 .SB XDVIT1FONTS 911 Determines the path(s) searched for PostScript Type 1 fonts. 912 See the section on FILE SEARCHING for more details. 913 .TP 914 .SB T1FONTS 915 Determines the path(s) searched for PostScript Type 1 fonts if 916 .SB XDVIT1FONTS 917 is not set. 918 .TP 919 .SB T1INPUTS 920 Determines the path(s) searched for PostScript Type 1 fonts if neither 921 .SB XDVIT1FONTS 922 nor 923 .SB T1FONTS 924 is set. If none of these three variables is set, then 925 .SB TEXFONTS, 926 .SB XDVIHEADERS, 927 .SB TEXPSHEADERS, 928 and 929 .SB PSHEADERS 930 are checked (in that order) before using the compiled-in default value. 931 .TP 932 .SB XDVITYPE1CONFIG 933 Determines the path(s) searched for dvips-style configuration files (such as 934 .B config.ps 935 and 936 .BR config.xdvi ) 937 to determine which fontmap files to read when mapping TeX font names to 938 Type 1 font names, Type 1 font files, encodings, etc. 939 See the section on FILE SEARCHING for more details. 940 .TP 941 .SB TEXCONFIG 942 Determines the path(s) searched for dvips-style configuration files if 943 .SB XDVITYPE1CONFIG 944 is not set. 945 .TP 946 .SB XDVIFONTMAPS 947 Determines the path(s) searched for fontmap files. 948 See the section on FILE SEARCHING for more details. 949 .TP 950 .SB TEXFONTMAPS 951 Determines the path(s) searched for fontmap files if 952 .SB XDVIFONTMAPS 953 is not set. If neither of these variables is set, then 954 .SB TEXFONTS 955 is also checked before using the compiled-in default value. 956 .TP 957 .SB XDVIENCS 958 Determines the path(s) searched for encoding files. 959 See the section on FILE SEARCHING for more details. 960 .TP 961 .SB ENCFONTS 962 Determines the path(s) searched for encoding files if 963 .SB XDVIENCS 964 is not set. If neither of these variables is set, then 965 .SB TEXFONTS 966 is also checked before using the compiled-in default value. 967 .TP 968 .SB XDVI_GS_LIB 969 Determines the path(s) searched for Ghostscript-style Fontmap files. 970 See the Ghostscript documentation for more details. 971 .TP 972 .SB GS_LIB 973 Determines the path(s) searched for Ghostscript-style Fontmap files if 974 .SB XDVI_GS_LIB 975 is not set. 976 .SH FILE SEARCHING 977 In order to accommodate the wide variety of ways in which fonts are stored 978 on various sites, 979 .B wdvi 980 has a fairly elaborate mechanism for indicating where to look for font files. 981 For other types of files, the mechanism is similar, but simpler. The method 982 for looking for font pixel files will be described first; other file types will 983 then be described. This section is quite technical; on first reading, it 984 would probably be better to skip to the section on EXAMPLES OF FONT SEARCHING. 985 .PP 986 The environment variable 987 .SB XDVIFONTS 988 (or 989 .SB PKFONTS, 990 etc., if 991 .SB XDVIFONTS 992 is not set) contains a list of specifiers, separated by colons. An extra 993 colon anywhere in that list causes the compiled-in default value to be 994 substituted at that point. Or, if no such environment variable is used, 995 the compiled-in default is also used instead. 996 .PP 997 In each specifier, the following substitutions are first made: 998 .TP 999 .B %f 1000 Replaced by the font name. 1001 .TP 1002 .B %F 1003 Replaced by the font name (but without side effects; see below). 1004 .TP 1005 .B %d 1006 Replaced by the size of the font (in dots per inch). 1007 .TP 1008 .B %b 1009 Replaced by the base resolution; i.e., the value of the 1010 .B \-p 1011 parameter or the 1012 .B .pixelsPerInch 1013 resource. 1014 .TP 1015 .B %p 1016 Replaced by the font file format 1017 .RB (`` pk '' 1018 or 1019 .RB `` gf ''). 1020 .TP 1021 .B %m 1022 Replaced by the 1023 .IR mode-def , 1024 as given in the 1025 .B \-mfmode 1026 argument or the 1027 .B .mfMode 1028 resource. 1029 .TP 1030 .B %t 1031 Replaced, sequentially, by the directories given by the 1032 .B TEXMF 1033 environment variable (or its compiled-in default). This may only be used 1034 at the beginning of a specifier. 1035 .TP 1036 .B %s 1037 Replaced by 1038 .RB `` %qfonts/%p/{%m,modeless}// ''. 1039 This is compatible with the \*(Te\& Directory Structure (TDS) standard. 1040 This string may only be used at the end of a specifier. 1041 .TP 1042 .B %S 1043 Replaced by 1044 .RB `` %t/%s ''. 1045 .TP 1046 .B %q 1047 Replaced by the empty string. This has the side effect of enabling the 1048 ``quick find'' feature, which is described below. 1049 .TP 1050 .B %Q 1051 Replaced by the empty string. Like 1052 .BR %q , 1053 this enables the ``quick find'' feature. It also inhibits searching for the 1054 file by normal means if ``quick find'' is not available. 1055 .TP 1056 .B %% 1057 Replaced by a single percent sign. Likewise, 1058 .BR %: , 1059 .BR %* , 1060 etc. can be used to insert those special characters into the destination 1061 string. 1062 .PP 1063 If no 1064 .RB `` %f '' 1065 appears in the specifier, then the string 1066 .RB `` /%f.%d%p '' 1067 is added on the end. 1068 .PP 1069 The characters 1070 .BR * , 1071 .BR ? , 1072 .BR [ , 1073 .BR ] , 1074 .BR { , 1075 and 1076 .B } 1077 are interpreted as wild cards, as in the C-shell 1078 .RB ( csh ). 1079 (This is here to pave the way for 1080 .I fli 1081 files, which have not been implemented yet.) 1082 In addition, a double slash 1083 .RB (`` // '') 1084 in the specifier indicates that any number of subdirectories may be inserted 1085 at that point. 1086 .PP 1087 There is an exception to the above procedure. If the font name begins 1088 with a slash 1089 .RB ( / ), 1090 then the font name is treated as an absolute path: the single specifier 1091 .RB `` %f.%d%p '' 1092 is used instead of the specifier(s) given by 1093 .SB XDVIFONTS. 1094 .PP 1095 The recursive search over subdirectories triggered by a double slash often 1096 causes a severe performance penalty; therefore, 1097 .B wdvi 1098 implements a speedup called ``quick find.'' This is triggered by the presence 1099 of a 1100 .RB `` %q '' 1101 or 1102 .RB `` %Q '' 1103 in the specifier. The location of such a string indicates that a file named 1104 .B ls-R 1105 should exist in that directory; that file should be the output of a 1106 .B ls -R 1107 or 1108 .B ls -LR 1109 command executed while in that directory. If such a file exists, then 1110 .B wdvi 1111 will search that file instead of searching through the directory tree. 1112 If such a file does not exist, and if 1113 .RB `` %Q '' 1114 was used, then 1115 .B wdvi 1116 will skip the specifier entirely. 1117 .PP 1118 In order for ``quick find'' to work, 1119 a few conditions must be met. First of all, the 1120 .RB `` %q '' 1121 or 1122 .RB `` %Q '' 1123 must occur immediately after a slash, and no later than immediately following 1124 the double slash. Secondly, there must be exactly one double slash in the 1125 specifier (having more than one double slash requires more complicated 1126 code in 1127 .BR wdvi ; 1128 if there are no double slashes then there is no need for ``quick find''). 1129 Third, there may be no wild cards other than 1130 .B { 1131 and 1132 .B } 1133 in the specifier. Finally, 1134 .BR %f , 1135 .BR %F , 1136 and 1137 .B %d 1138 may not occur in the specifier prior to the double slash. These conditions 1139 are all satisfied in the case of the \*(Te\& Directory Structure (TDS) standard. 1140 .PP 1141 An additional exception is that if a specifier or one of the alternatives in the 1142 .SB TEXMF 1143 environment variable begins with two exclamation points 1144 .RB (`` !! ''), 1145 then those characters are stripped off, and any subordinate search that 1146 could use an 1147 .B ls-R 1148 file, will be skipped if the 1149 .B ls-R 1150 file does not exist. In other words, any 1151 .RB `` %q '' 1152 strings are treated as 1153 .RB `` %Q ''. 1154 This feature has been included for compatibility with the 1155 .B Kpathsea 1156 library. 1157 .PP 1158 Finally, if a specifier or one of the alternatives in the 1159 .SB TEXMF 1160 environment variable begins with a tilde 1161 .RB ( ~ ) 1162 (after the 1163 .RB `` !! '', 1164 if any), then 1165 .B wdvi 1166 will attempt to replace a string of the form 1167 .BI ~ username 1168 with the home directory of 1169 .IR username . 1170 The 1171 .I username 1172 is taken to be everything up through the next slash or the end of the string; 1173 if it is empty, then the current user's home directory is substituted instead. 1174 If the username does not exist, then the string is left unchanged. 1175 .SH SEARCHING FOR FONTS 1176 When 1177 .B wdvi 1178 searches for a font, the first thing it does is to look for a 1179 PostScript Type 1 font. 1180 It does so by the following method. 1181 1182 .PP 1183 First, it compiles a list of dvips-style map files, using the same procedure as 1184 .B dvips 1185 would use for a hypothetical printer named 1186 .BR wdvi . 1187 In other words, it searches the files 1188 .BR config.ps , 1189 .B $HOME/.dvipsrc 1190 (where 1191 .B $HOME 1192 refers to the user's home directory), and 1193 .B config.xdvi 1194 to determine a list of map files to search for the font. It then searches 1195 those map files for an entry pertaining to the font in question. If an entry 1196 for the font is found, then that entry must give the PostScript name for 1197 the font, and may also give additional information such as the file name 1198 of a Type 1 font file containing the font, an encoding file to use for 1199 the font, or information on transformations to apply to the font 1200 (expansion/contraction and slanting). If the map files contain more than 1201 one entry for a given font, then the first entry encountered will be used. 1202 See the 1203 .B dvips 1204 documentation for details on this procedure. 1205 .PP 1206 If the map entry for the font gives a file name, then the named file is 1207 searched for and used (if found) to provide the font. Otherwise (if the 1208 map entry does not give a file name), then 1209 .B wdvi 1210 uses the PostScript name given in the map entry to search for the font in 1211 .B Fontmap 1212 files, using the same method as Ghostscript uses to search for PostScript 1213 fonts. 1214 .PP 1215 If an entry for the font is not found in one of the dvips map files, then 1216 it is assumed not to be available in Type 1 format, and 1217 .B wdvi 1218 will then search for a 1219 .I pk 1220 or 1221 .I gf 1222 file, at the size required for the 1223 .I dvi 1224 file, using the strategy mentioned in the above subheading. 1225 It will also try a slightly different size, in case of rounding errors. 1226 .PP 1227 If no such bitmap file is found, it then searches for a virtual font. 1228 (A virtual font is a recipe for creating a font from characters in other fonts 1229 and from rectangles.) This uses the procedure described under FILE SEARCHING, 1230 except that: (1) the environment variable 1231 .SB XDVIVFS 1232 or its associated defaults is used in place of the environment variable 1233 .SB XDVIFONTS 1234 or its associated defaults; 1235 (2) 1236 .RB `` %d '', 1237 .RB `` %b '', 1238 .RB `` %p '', 1239 and 1240 .RB `` %m '' 1241 are not substituted; 1242 (3) 1243 .RB `` %s '' 1244 is replaced by 1245 .RB `` %qfonts/vf// ''; 1246 (4) if no 1247 .RB `` %f '' 1248 appears in a specifier, then 1249 .RB `` /%f.vf '' 1250 is added at the end; and finally 1251 (5) if the file name begins with a slash, then 1252 .RB `` %f.vf '' 1253 replaces all the specifiers. 1254 .PP 1255 If no virtual font is found, then 1256 .B wdvi 1257 will 1258 try to find the nearest size. 1259 If the font cannot be found at all, then 1260 .B wdvi 1261 will try to vary the point size of the font (within a certain range), 1262 and if this fails, then it will use the font specified as the alternate 1263 font (see 1264 .BR \-altfont ). 1265 .SH EXAMPLE OF FONT SEARCHING 1266 This example describes how 1267 .B wdvi 1268 would search for the font 1269 .B cmr10 1270 at 300 dots per inch. First, 1271 .B wdvi 1272 searches the map files for an entry describing a font with TeX name 1273 .BR cmr10 . 1274 It will likely find a line 1275 .RS 5 1276 .nf 1277 .ft 3 1278 .sp 1n 1279 cmr10 CMR10 <cmr10.pfb 1280 .sp 1n 1281 .ft 1282 .fi 1283 .RE 1284 The (space-separated) entries in this line mean (in order) that the TeX name 1285 of the font is 1286 .BR cmr10 , 1287 the PostScript name is 1288 .BR CMR10 , 1289 and the font is located in the file 1290 .BR cmr10.pfb . 1291 This file is searched for using the methods listed in the section on 1292 FILE SEARCHING. This is done using the same procedure as for font files, 1293 except that: 1294 (1) 1295 .RB `` %f '' 1296 and 1297 .RB `` %F '' 1298 refer to the file name, not the font name; 1299 (2) 1300 .RB `` %d '', 1301 .RB `` %b '', 1302 .RB `` %p '', 1303 and 1304 .RB `` %m '' 1305 are not substituted; 1306 (3) 1307 .RB `` %s '' 1308 is replaced by 1309 .RB `` %qfonts/type1// ''; 1310 (4) if no 1311 .RB `` %f '' 1312 appears in a specifier, then 1313 .RB `` /%f '' 1314 is added at the end; and finally 1315 (5) if the file name begins with a slash, then 1316 .RB `` %f '' 1317 replaces all the specifiers. 1318 .PP 1319 If no such map file entry is found, if the file 1320 .B cmr10.pfb 1321 cannot be found, or if Type 1 fonts have been turned off, then 1322 .B wdvi 1323 searches for the font in raster format at 300 dpi. For example, if the 1324 specifier is 1325 .RB `` /usr/local/tex/fonts '', 1326 then 1327 .B wdvi 1328 looks for 1329 .B /usr/local/tex/fonts/cmr10.300pk 1330 and 1331 .BR /usr/local/tex/fonts/cmr10.300gf , 1332 in that order (provided that 1333 .B wdvi 1334 is compiled to accept both 1335 .I pk 1336 and 1337 .I gf 1338 files, which is not necessarily the case). 1339 .PP 1340 For sites using the \*(Te\& Directory Structure (TDS) standard, 1341 .SB XDVIFONTS 1342 (or, better yet, its compiled-in default) should be set to 1343 .RB `` .:%S ''; 1344 in that case, if 1345 .SB TEXMF 1346 (or, again, its compiled-in default) is set to 1347 .RB `` /usr/local/texmf '', 1348 then 1349 .B wdvi 1350 will look within that directory for the font file, in accordance with the 1351 TDS standard. 1352 .PP 1353 There may be several such TDS trees. 1354 .PP 1355 A common situation is one in which a user wishes to augment the set of fonts 1356 provided by the system. It is possible to do this without having to know 1357 or remember what the defaults are. For example, if the user has a small 1358 number of fonts, and keeps them all in one directory, say 1359 .BR /home/user/fonts , 1360 then setting 1361 .SB XDVIFONTS 1362 to 1363 .RB `` /home/user/fonts: '' 1364 will cause 1365 .B wdvi 1366 to check that directory for font files before checking its default list. 1367 Similarly, setting 1368 .SB XDVIFONTS 1369 to 1370 .RB `` :/home/user/fonts '' 1371 will cause 1372 .B wdvi 1373 to check that directory 1374 .I after 1375 checking its default locations. This is true even if the system uses a TDS 1376 tree. 1377 .PP 1378 If that directory also contains 1379 .I tfm 1380 files, then it is possible to set 1381 .SB TEXFONTS 1382 instead of 1383 .SB XDVIFONTS; 1384 in that case, \*(Te\& will also look for the 1385 .I tfm 1386 files in that directory. This feature depends on which implementation 1387 of \*(Te\& is in use. The 1388 .SB XDVIFONTS 1389 variable overrides the 1390 .SB TEXFONTS 1391 variable, so that on those sites where 1392 .SB TEXFONTS 1393 must be set explicitly, and therefore this feature is not useful, the 1394 .SB XDVIFONTS 1395 variable may be set to an empty string (i.e., 1396 .RB `` "setenv XDVIFONTS" '') 1397 to cause 1398 .B wdvi 1399 to ignore 1400 .SB TEXFONTS. 1401 .PP 1402 If the user has a large number of fonts and wishes to keep them in a TDS 1403 tree, then that is also possible with 1404 .BR wdvi : 1405 if, for example, the TDS tree is 1406 .BR /home/user/texmf , 1407 then setting 1408 .SB TEXMF 1409 to 1410 .RB `` /home/user/texmf: '' 1411 will cause 1412 .B wdvi 1413 to check that TDS tree before its default actions. This assumes, however, 1414 that the site uses a TDS tree also (since 1415 .SB TEXMF 1416 is not used unless 1417 .RB `` %t '' 1418 or 1419 .RB `` %S '' 1420 occurs in a specifier somewhere). If the site does not use a TDS tree, 1421 then it would be best to set 1422 .SB XDVIFONTS 1423 to 1424 .RB `` /home/user/texmf/%s: '', 1425 instead. 1426 .SH FILES 1427 .PD 0 1428 .TP 40 1429 .B /usr/local/share/texmf-local 1430 .TP 1431 .B /usr/local/share/texmf-dist 1432 .TP 1433 .B /usr/local/share/texmf 1434 .TP 1435 .B /usr/local/texlive/texmf-local 1436 .TP 1437 .B /usr/local/texlive/texmf-dist 1438 .TP 1439 .B /usr/local/texlive/texmf 1440 .TP 1441 .B /usr/share/texmf-local 1442 .TP 1443 .B /usr/share/texmf-dist 1444 .TP 1445 .B /usr/share/texmf 1446 .TP 1447 .B /usr/share/texlive/texmf-local 1448 .TP 1449 .B /usr/share/texlive/texmf-dist 1450 .TP 1451 .B /usr/share/texlive/texmf 1452 \*(Te\& Directory Structure (TDS) directories. 1453 .TP 40 1454 .B . 1455 .TP 1456 .B %S 1457 Font pixel files. 1458 .TP 1459 .B . 1460 .TP 1461 .B %S 1462 Virtual font files. 1463 .TP 1464 .B . 1465 .TP 1466 .B %S 1467 Directories containing dvips configuration files. 1468 .TP 1469 .B . 1470 .TP 1471 .B %S 1472 Directories containing dvips-style fontmap files. 1473 .TP 1474 .B . 1475 .TP 1476 .B %S 1477 Directories containing encoding files. 1478 .TP 1479 .B . 1480 .TP 1481 .B %S 1482 Directories containing PostScript Type 1 font files. 1483 .PD 1484 .SH SEE ALSO 1485 .BR X (1), 1486 .BR xdvi (1), 1487 .BR dvips (1). 1488 .SH AUTHORS 1489 Eric Cooper, CMU, did a version for direct output to a QVSS. 1490 Modified for X by Bob Scheifler, MIT Laboratory for Computer Science. 1491 Modified for X11 by Mark Eichin, MIT SIPB. 1492 Additional enhancements by many others. 1493 The current maintainer of 1494 .BR xdvi (1) 1495 is Paul Vojta, U.C. Berkeley. 1496 .PP