## Windvi 0.67 User’s Manual

Fabrice Popineau
Fabrice.Popineau@supelec.fr
October 26, 2004

### Contents

1 Introduction
1.1 Why another Windows dvi viewer ?
1.2 Features
2 Installation
2.1 The home of Windvi
2.2 Unpacking
2.3 Conﬁguration
2.4 Generation of PK ﬁles
2.5 Type1 fonts
2.6 PostScript™ inclusions
3 Quick startup
3.1 HyperTEX support
4 Reference guide
4.1 Settings
4.2 Logging
4.3 Features
4.4 Printing
4.5 Command line options
4.6 Mouse
4.7 Shortcut keys
5 Ghostscript installation
6 FAQ
7 Known bugs and TODO list
A Color naming

### 1 Introduction

#### 1.1 Why another Windows dvi viewer ?

Note that throughout this document, when I say ‘Win32’, this means Windows 9x and Windows NT.

There are many previewers for dvi ﬁles under Win32. The most popular is probably Dviwin by H. Sendoukas. However it lacks some important features:

- the ability to recursively search directories for font ﬁles,
- the ability to use .vf ﬁles or display PostScript fonts,
- the ability to display PostScript images.

Unfortunately, the Dviwin sources were never put into the public domain; on the other side of the fence, Xdvi under Unix has these features, is widely used and its sources are available. Xdvi(k) uses the kpathsea library to search directories, already used in the Web2c-win32 port of TEX, so there was some interest in porting Xdvi(k) to Win32. It turned out that this was far more than just a port, since X Window is far from Win32. All the user interface and the graphical part has been rewritten.

#### 1.2 Features

The most important features of Windvi are as follows:

- monochrome or grey scale bitmaps (antialiasing) for fonts,
- easy navigation through the dvi ﬁle
  - page by page,
  - with diﬀerent increments (by 5 or 10 pages at a time)
  - goto home, end, or any page within the document,
- diﬀerent shrink factors to zoom page in and out,
- magnifying glass to show the page at the pixel level,
- use of .vf fonts
- display .pk .gf font ﬁles
- automatic generation of missing PK ﬁles even for PostScript fonts,
- tracking dvi ﬁle changes, and automatic reopening,
- understanding Omega extended dvi ﬁles,
- drag-and-drop ﬁle from the Windows shell explorer,
- color support (a-la dvips),
- real-time logging of background font generation,
- visualization of PostScript inclusions,
- graphical transformations under NT only,
- support of HyperTEX specials,
- printing support through the uniﬁed printer driver.

### 2 Installation

#### 2.1 The home of Windvi

Windvi is part of the fpTEX distribution, which is itself based on teTEX and Web2C.

You will ﬁnd the whole fpTEX distribution on any CTAN archive, for example:

ftp://ftp.tex.ac.uk/pub/tex/systems/win32/fptex

Beta versions of fpTEX and other tools are available from:

ftp://ftp.ese-metz.fr/pub/tex/win32-beta

If you want to retrieve only the windvi distribution, you should get:

ftp://ftp.tex.ac.uk/pub/tex/systems/win32/fptex/windvi.zip for the standalone released version;

ftp://ftp.ese-metz.fr/pub/tex/win32-beta/windvixx.zip for beta versions, xx being always as high as possible.

Announcements of beta version are made through the fptex mailing-list. Subscriptions can be sent to mailto:majordomo@tug.org. Send a message whose body is ’subscribe fptex’ to subscribe. The list address is ’fptex@tug.org’.

#### 2.2 Unpacking

Assuming you have retrieved one of the windvixx.zip ﬁles, you will have to unpack it at the <root> of some TDS conformant texmf tree like this one:

<root>/bin/win32 /texmf/ /dvips /tex /latex /web2c

- owindvi.exe, windvi.exe, mktex*.exe and gsftopk.exe go to bin/win32
- render.ps (used by gsftopk) goes to texmf/dvips
- texmf.cnf and mktex.cnf go to texmf/web2c.

In order not to overwrite the texmf.cnf and mktex.cnf ﬁles of people who are already using Web2C for win32, those ﬁles are distributed as texmf.xam and mktex.xam. You must rename them if you don’t already have .cnf ﬁles.

Next, add <root>\bin\win32 to your PATH. This is done by modifying autoexec.bat under Windows 9x or the Control Panel/System under NT/W2K.

#### 2.3 Conﬁguration

If you have respected the previous layout for the tree, ie the relative position of windvi.exe with respect to the texmf directory, you should not have anything more to conﬁgure than update your PATH environment variable.

If you want to use windvi.exe in another context, you may need to set the TEXMFMAIN and / or TEXMFCNF environment variable. TEXMFMAIN must point to the texmf directory and TEXMFCNF to the directory containing texmf.cnf.

#### 2.4 Generation of PK ﬁles

The generation of PK ﬁles is under control of the kpathsea library through the use of mktexpk.exe. You can choose the destination for generated ﬁles — the scheme is explained in detail in the kpathsea documentation.

The main points are:

- any generated ﬁle will go in the same texmf tree as the one in which the font source has been found,
- if the source directory is not writable, the directory named by VARTEXFONTS will be used, so you had better set this variable to something meaningful in texmf.cnf
- MT_FEATURES can be set either in mktex.cnf or in your environment to control the naming of generated ﬁles: you can add ’dosnames’, ’nomode’, ’stripsupplier’, ’striptypeface’, ’fontmaps’ and ’varfonts’ to the features. Feel free to experiment with them by setting MT_FEATURES in the environment and checking with ’mktexnam cmr10’ for the result you want.

#### 2.5 Type1 fonts

In order to use gsftopk.exe to generate PK ﬁles for Type1 fonts, you will need to install Ghostscript. Ghostscript is used in the background for computing the bitmaps. See section 5 about Ghostscript installation.

After that, Windvi should be able to generate PK ﬁles for your Type1 fonts, providing you have the corresponding vf and tfm ﬁles. It is however wise to try mktexnam.exe on some of your fonts (’mktexnam ptmr8r’ for example) to check that the fonts will be put at the right place.

#### 2.6 PostScript™ inclusions

Windvi is able to display some PostScript™ inclusions, thanks to Ghostscript. What is understood :

- graphics bundle from LA TEX2e,
- psfig inclusions,
- some raw PostScript™ like the pspicture package.

The bop / eop mechanism is not (yet) supported, so do not expect the draft package to display anything. Also, not all material is processed by Ghostscript, so rotated text will not appear so when displayed.

For performance reasons, the magnifying glass will not render your ps inclusions.

See section 5 about Ghostscript installation.

### 3 Quick startup

Create a shortcut to Windvi on your desktop:

- click right button on the desktop,
- New Shortcut,
- browse and ﬁnd windvi.exe
- OK.

Next, explore your computer, drag and drop some dvi ﬁle onto the Windvi icon. If everything goes well, Windvi will open your dvi ﬁle and choose a suitable shrink factor for the page to be fully displayed.

#### 3.1 HyperTEX support

Windvi will handle specials inserted by packages such as hyperref by Sebastian Rahtz. This means that you will be able to navigate inisde (and outside !) your document, much like with your usual browser.

Hyperlinks are automatically hilighted. The behaviour is modiﬁed in the following way :

- clicking on mouse left will move to the page the link is pointing to. That means if it is inside your document, the page pointed is displayed. If it is in another dvi ﬁle, this ﬁle is opened and the page displayed. If the link references anything else than a dvi ﬁle, the Windows shell is called to handle the reference. That means such an url as mailto:fabrice.popineau@supelec.fr will probably launch Outlook Express or whatever is your default mail tool.
- clicking on control plus mouse left will do the same, except that if the link points to another dvi ﬁle, your current dvi ﬁle will stay open, and another windvi will display the new ﬁle. If you are running in single-instance mode, there will be no diﬀerence between using control and not using it.
- there is a back icon tool to go back through the hyperlinks list you have browsed.

### 4 Reference guide

#### 4.1 Settings

Current settings are saved each time you quit in a windvi.cnf ﬁle. This ﬁle is located under the HOME directory if this environment variable is set, or under c:\ otherwise.

You can have a site-wide windvi.cnf ﬁle located in $TEXMFCNF/windvi.cnf. This ﬁle will be read before the user one and settings will be merged.

#### 4.2 Logging

Any error or informational message will make the log window pop up. Font generation and so on is displayed in real-time.

There is no way currently to avoid the pop-up feature.

#### 4.3 Features

##### 4.3.1 General features

All the features of Windvi are documented in this sample ﬁle. You are encouraged to look at it.

##### 4.3.2 Postscript inclusions

Windvi will allow you to preview many PostScript inclusions, including raw PostScript specials. See the Examples/wtest.tex ﬁle for examples. The bop / eop feature found in dvips is not yet supported.

Most of the features available are described in the document Examples/wtest.tex.

However, there is a drawback. The ghostscript interpreter will allow the whole page at the requested scaling factor to do its job. That means a color page on a 24bits device, A4 size at 600dpi will be as huge as 34Mb. This is enough to make your W9x crash. NT won’t crash but will slow down a lot and may become unusable.

Eventually, PostScript visualization will be turned oﬀ automatically if it is detected that ghostscript will use too much memory.

##### 4.3.3 Colors

Windvi will honor color specials as introduced either by colordvi (plain TEX) or color package (LA TEX).

However, it is recommended to use this feature on true color devices. That means at least 32768 colors available.

On 256 colors devices, no antialiasing is done for color text. Moreover, the rendering maybe wrong because of the low number of colors available.

#### 4.4 Printing

Currently, printing works provided that you used the right command line options to run windvi. The options needed are the metafont mode for your printer and the base dpi number. Once you have run it with the right parameters, they will be saved in your windvi.cnf ﬁle so no need to bother for them again, unless you change your printer. For example :

windvi -p 720 -mfmode esphi foo.dvi

will allow you to print at 720dpi on an Epson Stylus printer.

The ﬁle holding the modes is texmf/metafont/misc/modes.mf and if you ever change it, you might want to rebuild your METAFONTformats using fmtutil.

This will be made obsolete (or almost) by the forthcoming support for Type1 and TTF fonts.

#### 4.5 Command line options

+¡page¿
  Speciﬁes the ﬁrst page to show. If + is given without a number, the last page is assumed; the ﬁrst page is the default.
-allowshell
  This option enables the shell escape in PostScript specials. (For security reasons, shell escapes are disabled by default.) This option should be rarely used; in particular it should not be used just to uncompress ﬁles: that function is done automatically if the ﬁle name ends in .Z or .gz . Shell escapes are always turned oﬀ if the -safer option is used.
-altfont ¡font¿
  Declares a default font to use when the font in the dvi ﬁle cannot be found. This is useful, for example, with PostScript fonts. Defaults to cmr10
-background ¡color¿
  uses <color> as background color
-bg ¡color¿
  same as -background
-debug ¡bitmask¿
  If nonzero, prints additional information on standard output. The number is taken as a set of independent bits. The meaning of each bit follows. 1=bitmaps; 2=dvi translation; 4=pk reading; 8=batch operation; 16=events; 32=ﬁle opening; 64=PostScript communication; 128=Kpathsea stat(2) calls; 256=Kpathsea hash table lookups; 512=Kpathsea path deﬁnitions; 1024=Kpathsea path expansion; 2048=Kpathsea searches. To trace everything having to do with ﬁle searching and opening, use 4000. Some of these debugging options are actually provided by Kpathsea. See the ‘Debugging’ section in the Kpathsea manual.
-density ¡density¿
  Determines the density used when shrinking bitmaps for fonts. A higher value produces a lighter font. The default value is 40. For monochrome displays; for color displays, use -gamma. See also the ‘S’ keystroke. Same as -S.
-foreground ¡color¿
  Uses <color> as foreground color
-fg ¡color¿
  same as -foreground
-gamma ¡gamma¿
  Controls the interpolation of colors in the greyscale anti-aliasing color palette. Default value is 1.0. For 0 < gamma < 1, the fonts will be lighter (more like the background), and for gamma > 1, the fonts will be darker (more like the foreground). Negative values behave the same way, but use a slightly diﬀerent algorithm. For color and grayscale displays; for monochrome, see -density. For color and greyscale displays; for monochrome, see -density. See also the ‘S’ keystroke.
-geometry ¡string¿
  Speciﬁes an initial X-Window geometry string.
-grid1 ¡color¿
  Determines the color of level 1 grid (default as foreground)
-grid2 ¡color¿
  Determines the color of level 2 grid (default as foreground)
-grid3 ¡color¿
  Determines the color of level 3 grid (default as foreground)
-gspalette ¡palette¿
  Speciﬁes the palette to be used when using Ghostscript for rendering PostScript specials. Possible values are
  - Color,
  - Greyscale,
  - Monochrome.

  The default is Color.

-gsalpha
  Causes Ghostscript to be called with anti-aliasing enabled in PostScript ﬁgures, for a nicer appearance. It is available on newer versions of Ghostscript.
-hush
  Causes Windvi to suppress all suppressible warnings.
-hushchars
  Causes Windvi to suppress warnings about references to characters which are not deﬁned in the font.
-hushchecksums
  Causes Windvi to suppress warnings about checksum mismatches between the dvi ﬁle and the font ﬁle.
-hushspecials
  Causes Windvi to suppress warnings about special strings that it cannot process.
-keep
  Sets a ﬂag to indicate that Windvi should not move to the home position when moving to a new page. See also the ‘k’ keystroke.
-margins ¡dimen¿
  This determines the “home” position of the page within the window as follows. If the entire page ﬁts in the window, then the margin settings are ignored. If, even after removing the margins from the left, right, top, and bottom, the page still cannot ﬁt in the window, then the page is put in the window such that the top and left margins are hidden, and presumably the upper left-hand corner of the text on the page will be in the upper left-hand corner of the window. Otherwise, the text is centered in the window. The dimension should be a decimal number optionally followed by any of the two-letter abbreviations for units accepted by (pt, pc, in, bp, cm, mm, dd, cc or sp). See also -sidemargin, -topmargin , and the keystroke ‘ M .’
-mfmode ¡mode-def¿
  Speciﬁes a mode-def string, which can be used in searching for fonts. Generally, when changing the mode-def, it is also necessary to change the font size to the appropriate value for that mode. This is done by adding a colon and the value in dots per inch; for example, -mfmode ljfour:600. This method overrides any value given by the -p command-line argument. The metafont mode is also passed to METAFONT during automatic creation of fonts. By default, it is ljfour:600
-mgs ¡size¿
  Same as -mgs1 .
-mgs[n
  ¡size¿] Speciﬁes the size of the window to be used for the “magnifying glass” for Button n . The size may be given as an integer (indicating that the magnifying glass is to be square), or it may be given in the form width × height. Defaults are 200×150, 400×250, 700×500, 1000×800, and 1200×1200.
-nogrey
  Turns oﬀ the use of greyscale anti-aliasing when printing shrunken bitmaps. (For this option, the logic of the corresponding resource is reversed: -nogrey corresponds to grey:off and +nogrey to grey:on See also the ‘G’ keystroke.
-nomakepk
  Turns oﬀ automatic generation of font ﬁles that cannot be found by other means.
-nopostscript
  Turns oﬀ rendering of PostScript™ specials. Bounding boxes, if known, will be displayed instead. This option can also be toggled with the ‘ v ’ keystroke.
-noscan
  Normally, when PostScript™ is turned on, Windvi will do a preliminary scan of the dvi ﬁle, in order to send any necessary header ﬁles before sending the PostScript code that requires them. This option turns oﬀ such prescanning. (It will be automatically be turned back on if Windvi detects any specials that require headers.)
-oﬀsets
  Speciﬁes the size of both the horizontal and vertical oﬀsets of the output on the page. This should be a decimal number optionally followed by “ cm ”, e.g. , 1.5 or 3cm , giving a measurement in inches or centimeters. By decree of the Stanford TEX Project, the default TEX page origin is always 1 inch over and down from the top-left page corner, even when non-American paper sizes are used. Therefore, the default oﬀsets are 1.0 inch. See also -xoffset and -yoffset .
-p ¡dpi¿
  Deﬁnes the size of the fonts to use, in pixels per inch. The default value is 600.
-qpaper ¡papertype¿
  Speciﬁes the size of the printed page. This may be of the form width×height (or width×heightcm), where width is the width in inches (or cm) and height is the height in inches (or cm), respectively. There are also synonyms which may be used: us (8.5x11), usr (11x8.5), legal (8.5x14), foolscap (13.5x17), as well as the ISO sizes a1 - a7 , b1 - b7 , c1 - c7 , a1r - a7r ( a1 - a7rotated), etc. The default size is 21 x 29.7 cm.
-rv
  Causes the page to be displayed with white characters on a black background, instead of vice versa.
-s ¡shrinkfactor¿
  Deﬁnes the initial shrink factor. The default value is to choose en appropriate factor.
-S ¡density¿
  Same as -density, q.v.
-sidemargin ¡dimen¿
  Speciﬁes the side margin (see -margins).
-topmargin ¡dimen¿
  Speciﬁes the top and bottom margins (see -margins).
-version
  Displays the version number and exits.
-xoﬀset ¡dimen¿
  Speciﬁes the size of the horizontal oﬀset of the output on the page. See -offsets .
-yoﬀset ¡dimen¿
  Speciﬁes the size of the vertical oﬀset of the output on the page. See -offsets .
-xform
  Turns on graphical transformations, which allows to apply any transformation to glyph boxes.

#### 4.6 Mouse

left button
  pops up the small magnifying glass, as long as the button is down.
middle button
  pops up the medium magnifying glass, as long as the button is down.
right button
  pops up the big magnifying glass, as long as the button is down.
Shift + left button
  change the arrow cursor for a crossbar cursor and enter ’setting home position’ mode. Home position is set when the button is released. Usefule with the ’Keep Home’ feature.

#### 4.7 Shortcut keys

Home, ’ˆ’
  goto the upper left corner of the page. If margins are active, use them.
Next, ’n’, Enter
  goto next page.
Prior, ’b’, Backspace
  goto previous page.
Ctrl-Home, Ctrl-End
  goto ﬁrst (resp. last) page.
Numpad +, Numpad -
  zoom in (resp. out).
Arrow keys, ’l’, ’r’, ’u’, ’d’
  move in the corresponding direction (left, right, up, down).
’k’
  Normally when Windvi switches pages, it moves to the home position as well. The ‘ k ’ keystroke toggles a ‘keep-position’ ﬂag which, when set, will keep the same position when moving between pages.
’M’
  set margins at the cursor.
’t’
  change tick units (cursor position).

### 5 Ghostscript installation

Statring with Ghostscript 5.50 and fpTEX 0.4 (as on the TEX-Live 5 CD-ROM), no speciﬁc Ghostscript installation should be needed. All the tools are linked to some library that knows where to look for Ghostscript in the registry.

In doubt or in case of trouble, try to set your PATH so that gsdll32.dll be found:

PATH=c:\\gstools\\gs5.50;\%PATH\%

If you encounter error messages like:

Aladdin Ghostscript: Can’t find initialization file gs_init.ps. gsdll_init returns 255

or something about font not found, it is more than likely that Ghostscript has been installed in a strange way. You can solve this by telling Ghostscript explicitely where its ﬁles are located:

set GS_LIB=c:\gstools\gs5.50;c:\gstools\fonts

Also : make sure to have only one version of Ghostscript installed. Version 5.50 can’t work with initialization ﬁles of version 5.10 for example.

Also beware that if you are running any version of gsftopk older than 0.19.1 and you have upgraded Ghostscript to version 6.0 or later, then gsftopk will fail to build fonts.

### 6 FAQ

1. Windvi opens and closes immediately. You should check your installation:
   - did you rename the .xam ﬁles into .cnf ﬁles ?
   - have you .cnf ﬁles ?
   - what mktexnam cmr10 does report ?
   - in case of trouble, do the following:

     set KPATHSEA_DEBUG_OUTPUT=err.log mktexnam --debug=1536 cmr10

     and send the err.log ﬁle to mailto:Fabrice.Popineau@supelec.fr

2. Windvi is stuck with the hour glass cursor, displaying some font name in the status bar. Currently, when kpathsea is generating fonts, Windvi is blocked. You can’t see any progress status. This is because kpathsea-based programs are inherently console mode programs and Windvi is a GUI program. If it takes too long time and the status bar doesn’t change, there is the chance of an improper installation. Check with the previous question. In this case, you will need to kill Windvi by hand, and any process named mf.exe or mktexpk.exe too.
3. In any case, check in the Help -> View Log File window for any strange messages and report them.
4. I’m using MiKTeX. Can I use Windvi ? Yes. But even if the layout tree for MiKTeX is TDS-conformant, it is not quite the same as the layout for Web2C. This is what Jody Klymak mailto:jklymak@apl.washington.edu did :

   I got windvi running under Windows NT using the following steps. I’m sure the steps are very similar on a Win95 machine. They are essentially the same a Fabrice’s instructions. It seems to handle fonts correctly. If anyone has a better way to do it, let me know. I’m no NT wiz.

   Cheers, Jody

   *******************************************************************

   Installing windvi under MikTeX under WinNT 4.0 Assuming you are set up like I am:

   MikTeX in c:\texmf and GSTools in c:\gstools

   - Make a directory c:\texmf\windvi
   - unpack windvi.zip in this directory
   - Put *.exe in c:\texmf\miktex\bin
   - Put render.ps in c:\texmf\dvips
   - Under the system control panel click the Environment tab and add:

     TEXMFCNF c:\texmf\windvi TEXMFMAIN c:\texmf path c:\gstools\gs5.10 GS_LIB c:\gstools\gs5.10;c:\gstools\gs5.10\fonts

   - Edit c:\texmf\windvi\texmf.cnf
     - change TEXMFMAIN = c:/texmf
     - change VARTEXFONTS = c:/texmf/fonts

   Read carefully the kpathsea documentation, and try your settings with the mktexnam.exe and kpsewhich.exe programs. Report any settings needed to enhance this FAQ section.

5. How do I stop Windvi to randomly access my ﬂoppy drive ? Check the following url http://www.annoyances.org/win95/win95ann6.html. This is probably caused by some kind of anti-virus program. Try to disable it.

### 7 Known bugs and TODO list

- Windvi is uninterruptible during font loading;
- \pagecolor{} is not honoured if there are PostScript inclusions in the page;
- The ﬁrst PostScript inclusion is not drawn, the page has to be redrawn once, next everything is ﬁne;
- We need to add more support for ‘specials’;
- There are probably some other bugs left.

### A Color naming

You can use ‘rgb:/rr/gg/bb/’ where rr, gg and bb are the hexadecimal (00-FF) intensities of red, green and blue component, or any of the following symbolic names :

snow | MidnightBlue | MediumSpringGreen | red
GhostWhite | navy | GreenYellow | HotPink
WhiteSmoke | NavyBlue | LimeGreen | DeepPink
gainsboro | CornﬂowerBlue | YellowGreen | pink
FloralWhite | DarkSlateBlue | ForestGreen | LightPink
OldLace | SlateBlue | OliveDrab | PaleVioletRed
linen | MediumSlateBlue | DarkKhaki | maroon
AntiqueWhite | LightSlateBlue | khaki | MediumVioletRed
PapayaWhip | MediumBlue | PaleGoldenrod | VioletRed
BlanchedAlmond | RoyalBlue | LightGoldenrodYellow | magenta
bisque | blue | LightYellow | violet
PeachPuﬀ | DodgerBlue | yellow | plum
NavajoWhite | DeepSkyBlue | gold | orchid
moccasin | SkyBlue | LightGoldenrod | MediumOrchid
cornsilk | LightSkyBlue | goldenrod | DarkOrchid
ivory | SteelBlue | DarkGoldenrod | DarkViolet
LemonChiﬀon | LightSteelBlue | RosyBrown | BlueViolet
seashell | LightBlue | IndianRed | purple
honeydew | PowderBlue | SaddleBrown | MediumPurple
MintCream | PaleTurquoise | sienna | thistle
azure | DarkTurquoise | peru | gray0
AliceBlue | MediumTurquoise | burlywood | grey0
lavender | turquoise | beige | DarkGrey
LavenderBlush | cyan | wheat | DarkGray
MistyRose | LightCyan | SandyBrown | DarkBlue
white | CadetBlue | tan | DarkCyan
black | MediumAquamarine | chocolate | DarkMagenta
DarkSlateGray | aquamarine | ﬁrebrick | DarkRed
DarkSlateGrey | DarkGreen | brown | LightGreen
DimGray | DarkOliveGreen | DarkSalmon |
DimGrey | DarkSeaGreen | salmon |
SlateGray | SeaGreen | LightSalmon |
SlateGrey | MediumSeaGreen | orange |
LightSlateGray | LightSeaGreen | DarkOrange |
LightSlateGrey | PaleGreen | coral |
gray | SpringGreen | LightCoral |
grey | LawnGreen | tomato |
LightGrey | green | OrangeRed |
LightGray | chartreuse | red |