.! .! This is a RUNOFF source file that produces part of a VMS-style HELP .! library for the August DECUS TeX Collection. To build the library, .! execute MAKE_TEX_HLB.COM. .! .! This file was created by adding RUNOFF directives to file DVIDIS.DOC. .! Pete Siemsen, 28-Feb-1990. .! .NO PAGING .NO FLAGS ALL .LEFT MARGIN 1 .RIGHT MARGIN 70 .SKIP .INDENT -1 1 DVIDIS DVIDIS is a program that displays TeX DVI files on a VaxStation running VWS. .SKIP Format: .SKIP .INDENT +3 $ DVIDIS .SKIP A large window will be created, and your text should start to appear in it; depending on the paper size and where you have located your window (by default it starts out centered), you may be able to see the "edge" of the paper as a gray bar. Meanwhile, your keyboard will remain attached to the window you were previously in, and you can enter commands. For a list of commands available to you, hit the HELP key. The effect of the various commands is easy to see, so experiment until you feel comfortable with them. .SKIP You can also specify a couple of options on the DVIDIS command line. These CANNOT be changed once DVIDIS has started. All options are of the form "-l" where "l" is any single letter, with the single exception of -verbose (for historical reasons). Some are followed (after a space) by one or a pair of numeric arguments; the -s command must be followed by a paper size specification. .SKIP For example: .SKIP .INDENT +3 $ DVIDIS -w -p 2 4 TEXT .SKIP means "display pages 2 to 4 of TEXT.DVI in 'wide' mode." .INDENT -1 2 -c .BREAK The fonts that DVIDIS uses are meant for a 300 dpi printer. A VAXStation display has about 78 dpi. As a result, if you display the glyphs from these fonts at a 1-1 pixel-to-pixel mapping, they are about 4 times as large as they would be on the page, and only about 1/9 of the page is visible at a time. Normally, DVIDIS compresses all fonts by a .INDENT -1 2-to-1 factor. The fonts are still readable, but you can now get most .BREAK of the width of a page - all, with any reasonable margins - and over half the height on the screen. Specifying "-c" turns off this compression; it's useful mainly for looking at the glyphs, not the text. .INDENT -1 2 -d .BREAK Debug. Generates a lot of output that's useful only to developers. .INDENT -1 2 -f .BREAK Causes the program to look in "USER$RST" rather than "TEX$RST" for the fonts. This command is meaningless for the PK version of DVIDIS, and of little use even in the RST version. .INDENT -1 2 -m .BREAK Tells DVIDIS to try to use smaller fonts, rather than compressing larger ones. This only works if you actually HAVE the small fonts on your system. When it works, it improves the appearance of individual characters, although it often makes lines come out with slightly different lengths than they should. -m is especially useful in conjunction with -w. -m in conjunction with -c is meaningless. .INDENT -1 2 -p .BREAK Limits the display to pages through inclusive. You can only specify one page range at a time, but you can specify multiple -p options, each specifying a page range. When you specify page ranges, DVIDIS will only "see" pages within the ranges given. Nothing you can do while the program is running will let you display any page not within any page range - DVIDIS will simply skip past the pages. .INDENT -1 2 -s ss .BREAK Set the paper size. This determines what size paper the program assumes you are printing on. The default is "letter", which is 8.5 x 11 inches. The argument is the name of a paper size; type DVIDIS -s ? for a list of possible values. .SKIP The paper size controls where DVIDIS places a visible gray border, and when it tells you that characters have "run off the page". It always displays the characters, however. .SKIP Paper size "huge" is meant for special purposes; using it will make many of the commands you can type to DVIDIS while it is running work in strange ways. You should generally avoid using size "huge". .INDENT -1 2 -verbose .BREAK Makes the program talkative. This is mainly useful for debugging, but since it displays all the font files it opens, successfully or not, it can be used to determine which files are needed. The needed files can be created if they don't already exist. They can also be put on your workstation's local disk to improve performance. .INDENT -1 2 -v , -h .BREAK Set the vertical (horizonal) margin. Next argument is the margin, in milli-inches. Default is 1000 milli-inches each, which is the same default used by many common DVI printing programs. If you find a lot of "off-screen glyph" errors, and you have the paper size set correctly, try changing these parameters. (Besides 1000, the second most common value expected is 0 for both margins.) .SKIP Note that the default corresponds to the current TeX standard. If you find you have to use some other value to make your output look right, some other piece of software you are running is obsolete. .INDENT -1 2 -w .BREAK Specifies a 4-to-1 glyph compression factor. This allows you to see how a whole page looks, but unfortunately it's rather hard to read the resulting text. .INDENT -1 2 Author .BREAK Jerry Leichter, based on work of Bill Gropp's, which in turn was based on a lot of earlier work by others; with additional input from Bert Beander at DEC. Comments/questions/suggestions to Jerry Leichter at .SKIP .LITERAL LEICHTER-JERRY@CS.YALE.EDU or LEICHTER@YALEVMS.BITNET .END LITERAL .INDENT -1 2 Bugs .BREAK DVIDIS is intended to report an error if it can't find a "close" match to a font called for in the file it is displaying. The test it makes for "closeness" is wrong, however, so it currently almost never reports a problem. The result may be grossly distorted output, with no indication that the problem isn't in the file, it's that DVIDIS had to chose an inappropriate font. .SKIP Characters actually appearing in the font file, but with no pixels (i.e., a "0 by 0" raster) cause DVIDIS to crash. This is known to occur with the CMAPL10 font (at least character '040 is a "space") and probably will occur with any of the LaTeX "invisible" slide fonts. .SKIP Stanford Version 2.2 of PXTOPK, and all distributed versions to date of Kellerman and Smith's PXTOPK for VMS, have distinct bugs that produce completely invalid PK files. Files produced using the Stanford V2.2 code can be recognized by using PKTYPE and looking at the X-offset and Y-offset values for a couple of characters. Typical values are small positive or negative integers - values outside the range -30 to 30 are very unlikely. The V2.2 code will produce random, often very large, values. I don't know the exact symptoms of the problems the Kellerman and Smith code will produce. See the article by Dan Hosek in TeXhax, Volume 88, #24 for a discussion. Version 2.3 of PXTOPK fixes the underlying problem; both PXTOPK.WEB and a corresponding version of PXTOPK.VMS-CHANGES should be available from "the usual sources", or from the same place you got DVIDIS, if all else fails. .SKIP DVIDIS uses the dx field of PK fonts to determine the width of the characters it displays. Width information can also be obtained from the "TFM width" field. It seems that most commonly-used DVI file drivers use the TFM width. As a result, bugs that result in PK files with invalid dx values can go undetected for years. The most common case, easily detectable with PKTYPE, will have dx=0 for all the characters. When such a font is displayed, what you'll see is bunches of characters displayed at the same position; since inter-word spacing doesn't depend on the dx values, you'll see one "blotch" per word. One place I've seen this come up is with the Hebrew fonts that come with Jacques Goldberg's SemiTeX. Examination of the GF files reveals that they have 0 dx values as well, so the problem seems to be some (as-yet undetermined) inappropriate parameter setting for Metafont. You can work around this problem by doing a round-about conversion: Rather than using GFTOPK, use GFTOPX (or PKTOPX, if you've already got PK files), then PXTOPK. PX files don't store the dx value at all, so a CORRECT PXTOPK will re-compute it. .SKIP If DVIDIS_FONT_SIZES specifies exactly one font size, unpredictable results, including crashes, may occur. This shouldn't happen under normal circumstances, but if you find a distorted display and other odd things happening, it could be that DVIDIS_FONT_SIZES is set up wrong. In particular, make sure that you've defined it to have a single translation that contains a list of sizes separated by commas, rather than as multiple translations, each of which is a single size. This is discussed above. .SKIP If the original TeX run specified a magnification value other than 1000, the spacing will be incorrect. The only current work-around is to re-run TeX without the magnification. Note that this restriction applies only to GLOBAL magnifications (i.e., uses of \magification). Individually magnified fonts are handled correctly. .SKIP There is a bug in the VAX C library for Versions 4.6 and 4.7 of VMS that will cause DVIDIS to die with a Reserved Operand Fault if it runs out of memory. The only work-around is to increase the amount of virtual memory available to the process running DVIDIS. (Note that, without the bug, DVIDIS would try to recover by discarding some font information it has already read in. The resulting performance loss would probably be substantial, so you'd probably want to run with a larger virtual memory limit anyway. On a workstation, there is little reason NOT to run this way in any case. You'll probably want to allow big working sets, too.) .INDENT -1 2 Font_Substitution .BREAK If DVIDIS is unable to find a font as specified, it will check to see if you have defined a substitute for it in any of three substitution files. If you are displaying file jobname.DVI, the files are: .SKIP .LITERAL jobname.SUB in the same directory as jobname.DVI; TEXFONTS.SUB in the current directory; TEX$INPUTS:TEXFONTS.SUB .END LITERAL .SKIP Every time a substitution is needed, the files present are checked, in the order given, each from beginning to end, to try to find a substitute. Only the first match is used, however. .SKIP Each of the substitution files has the same format. It's a simple ASCII file, with one substitution per line. Comments, as in TeX, are introduced by "%" and continue to the end of the line. .SKIP A substitution line has either of two forms: .SKIP .LITERAL oldname.oldsize -> subname.subsize oldname -> subname .END LITERAL .SKIP The first format substitutes only for a particular font name and size. The second format substitutes for a particular font name at any size. .SKIP Spaces can be used freely in substitution lines. .SKIP Since only the first match is used, and the files are always read from the first line onward, you should specify particular substitutions - those with a size - before generic ones. .SKIP It's not an error for the substituted font file not to be found - DVIDIS will proceed to look for "nearby" fonts, possibly substituting for them as well. .SKIP The DVIDIS distribution includes a TEXFONTS.SUB file that substitutes CM fonts for AM fonts. This should allow you to display DVI files created using older versions of TeX. .INDENT -1 2 Installation .BREAK DVIDIS consists of a single image, DVIDIS.EXE, that runs on an VAXStation with VWS V3.0 or later. It runs as a normal user-mode image, and needs no special privileges. DVIDIS uses a fair amount of memory as it runs, so be sure to provide a reasonable working set - at least 1200 pages, 2000 or more is better. In order for DVIDIS to receive its arguments, it must be started with a foreign command line, given by something like: .SKIP .INDENT +3 $ DVIDIS :== $DEV:[DIR]DVIDIS .SKIP Two "environment variables" can be set to control DVIDIS, and you can specify font substitutions. The environment variables - typically, logicals, but if no logicals are defined any DCL symbol of the same name will be used - are DVIDIS_FILE_FORMAT and DVIDIS_FONT_SIZES. .INDENT -1 3 DVIDIS_FILE_FORMAT .BREAK A string that specifies how to construct a file specification for a font file, given a font name and a dots-per-inch value. The font name will be substituted for %s; the dots-per-inch value for %d. You must have EXACTLY one of each, in either order; you may NOT have any additional occurences of "%". .SKIP There are two common schemes for storing PK font files: .SKIP .LITERAL One directory, DEV:[DIR], font "name" at "ddd" dots per inch is file name.dddPK. A format string for this case would look like "DEV:[DIR]%s.%dPK". One root directory, DEV:[DIR.]; fonts at "ddd" dots per inch are in subdirectory [.DPIddd], with font "name" in name.PK. A format string for this case would look like "DEV:[DIR.DPI%d]%s.PK". .END LITERAL .SKIP If DVIDIS_FILE_FORMAT is not defined, the default format string is "TEX_FONTS:[DPI%d]%s.PK". This corresponds to the second way of organizing the font files, and assumes that TEX_FONTS is a rooted logical translating to something like DEV:[DIR.]. .SKIP You can only specify a single file format, but that file format could involve a logical that translates to a search list. For example, using the default file format, you might do: .SKIP .INDENT +3 $ DEFINE TEX_FONTS $DISK1:[TEX.PK.],NODE::TEX_FONTS: .SKIP where "NODE" is the name of a node with more fonts than you are willing to store locally. On NODE, TEX_FONTS must be a SYSTEM logical name that translates to a rooted directory. (If you have proxy access to NODE, you could define TEX_FONTS in your login file on NODE). Because of a VMS bug, it isn't possible to use something like NODE::DEV:[DIR.] to avoid needing a logical name on NODE. (This bug appears in VMS Version 4.5. If you a more recent version, the bug may have been fixed.) .SKIP .LITERAL I M P O R T A N T N O T E .END LITERAL .SKIP The definition of DVIDIS_FILE_FORMAT will be used as a printf() format string. The "d" and "s" format specifiers MUST be in lower case; if you make them upper case, the format will not work. Note also that DCL forces characters to upper case unless they are inside a quoted string. Hence, your definition should look something like: .SKIP .INDENT +3 $ DEFINE DVIDIS_FILE_FORMAT "TEX_FONTS:%s.%dPK" .INDENT -1 3 DVIDIS_FONT_SIZES .BREAK This variable must translate to a list of all dot-per-inch values at which you have any fonts available. The list consist of just the numbers (the "ddd" values discussed above), separated by commas. DVIDIS will never find a font at a size not given in the list. .SKIP The default list is: .SKIP .LITERAL 100,121,145,174,180,208,210,225,240,250,263,270,274, 300,329,360,432,518,622,746,895,896,1074,1075,1289, 1290,1547,1548 .END LITERAL .SKIP which is the list of values I've got. Extra values will slow DVIDIS down a bit when it has to open a file, but not by much, so you can use the default unless you have some sizes I don't. .SKIP Note that this list is NOT a search list, use: .SKIP .INDENT +3 $ DEFINE DVIDIS_FONT_SIZES "300,329,360" .SKIP WITH THE QUOTATION MARKS. If you leave the quotation marks off, DVIDIS will never use anything but the first value you list. .INDENT -1 2 Keypad_keys .BREAK The Find and Remove keypad keys use OSC functions to control the terminal window. OSC's must be enabled; from questions I've received, it seems that many people are not enabling them. To enable OSC's, issue the following command from DCL (in a privileged account): .SKIP .INDENT +3 $ DEFINE/SYSTEM/EXEC UIS$VT_ENABLE_OSC_STRINGS TRUE .INDENT -1 2 Release_notes .BREAK If you have used previous versions of DVIDIS, note that this version is VERY different. The human interface is much better, but most important, the program now reads PK format font files, not the old, very obsolete RST format font files. It is possible to build a version with RST file support, but that hasn't been tested and is not recommended. PK fonts are MUCH better in every way.