1 Introduction

1.1 Why another Windows dvi viewer ?

There are many previewers for dvi files 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 files,
• the ability to use .vf files or display PostScript fonts.

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. As it turned out, this turned into far more than just a port, as X Windows is far from Win32. All the user interface and the graphical part has been rewritten.

For the future, when the base functionality of Xdvi(k) is available and stable under Win32, we can expect to add the interesting features of Dviwin to Windvi.

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 file
  • page by page,
  • with different increments (by 5 or 10 pages at a time)
  • goto home, end, or any page within the document,

• different 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 files
• automatic generation of missing PK files even for PostScript fonts,
• tracking dvi file changes, and automatic reopening,
• understanding Omega extended dvi files,
• drag-and-drop file from the Windows shell explorer,
• some color support (foreground and background),
• real-time logging of background font generation,
• visualization of PostScript inclusions.

2 Installation

2.1 The home of Windvi

Windvi is part of the Web2C package for win32. You will find the whole Web2C package on any CTAN archive, for example:

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

Beta versions of Web2C for Win32 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/web2c/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 texk-win32 mailing-list. Subscriptions can be sent to mailto:texk-win32-request@ese-metz.fr. Send 'help' in the subject for more information.

2.2 Unpacking

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

• 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 files of people who are already using Web2C for win32, those files are distributed as texmf.xam and mktex.xam. You must rename them if you don't already have .cnf files.

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

2.3 Configuration

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 configure 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 files

The generation of PK files is under control of the Kpathsea library through the use of mktexpk.exe. You can choose the destination for generated files --- the scheme is explained in detail in the Kpathsea documentation.

The main points are:

• any generated file 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 files: 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 files for Type1 fonts, you will need to install Ghostscript. Ghostscript is used in the background for computing the bitmaps. Setting it up is quite easy; assuming that Ghostscript has been installed in c:\gstools\gs5.10 and fonts in c:\gstools\fonts, add to your environment:

After that, Windvi should be able to generate PK files for your Type1 fonts, providing you have the corresponding vf and tfm files. 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 nclusions

Windvi s able to display some PostScript nclusions, thanks to Ghostscript. What is understood 

• graphics bundle from LaTeX2e,
• psfig inclusions,
• some raw PostScript ike the pspicture package.

The bop / eop mechanism is not (yet) understood, 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 resons, the magnifying glass will not render your ps inclusions.

For Windvi eing able to call Ghostscript, you will need to put gsdll32.dll in your PATH and set GS_LIB 

3 Quick startup

Create a shortcut to Windvi on your desktop:

• click right button on the desktop,
• New Shortcut,
• browse and find windvi.exe
• OK.

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

4 Reference guide

4.1 Settings

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

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

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 Command line options

+

Specifies the first page to show. If + is given without a number, the last page is assumed; the first page is the default.

-altfont

Declares a default font to use when the font in the dvi file cannot be found. This is useful, for example, with PostScript fonts. Defaults to cmr10

-background

uses <color> as background color

-bg

same as -background

-debug

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=file opening; 64=PostScript communication; 128=Kpathsea stat(2) calls; 256=Kpathsea hash table lookups; 512=Kpathsea path definitions; 1024=Kpathsea path expansion; 2048=Kpathsea searches. To trace everything having to do with file searching and opening, use 4000. Some of these debugging options are actually provided by Kpathsea. See the `Debugging' section in the Kpathsea manual.

-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. Same as -S.

-foreground

Uses <color> as foreground color

-fg

same as -foreground

-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 different algorithm. For color and grayscale displays; for monochrome, see -density.

-geometry

Specifies an initial X-Window geometry string.

-hush

Causes Windvi to suppress all suppressible warnings.

-hushchars

Causes Windvi to suppress warnings about references to characters which are not defined in the font.

-hushchecksums

Causes Windvi to suppress warnings about checksum mismatches between the dvi file and the font file.

-hushspecials

Causes Windvi to suppress warnings about special strings that it cannot process.

-keep

Sets a flag to indicate that Windvi should not move to the home position when moving to a new page. See also the ` k ' keystroke.

-margins

Specifies the size of both the top margin and side margin. This should be a decimal number optionally followed by " cm ", e.g. , 1.5 or 3cm , giving a measurement in inches or centimeters. It determines the "home" position of the page within the window as follows. If the entire page fits 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 fit 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. See also -sidemargin, -topmargin , and the keystroke ` M .'

-mfmode

Specifies a mode-def string, which can be used in searching for fonts. It is also passed to Metafont during automatic creation of fonts.

-mgs

Same as -mgs1 .

-mgs[n

] Specifies 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 off the use of greyscale anti-aliasing when printing shrunken bitmaps.

-nomakepk

Turns off automatic generation of font files that cannot be found by other means.

-nopostscript

Turns off rendering of PostScript pecials. Bounding boxes, if known, will be displayed instead. This option can also be toggled with the ` v ' keystroke.

-noscan

Normally, when PostScript s turned on, Windvi ill do a preliminary scan of the dvi file, in order to send any necessary header files before sending the PostScript code that requires them. This option turns off such prescanning. (It will be automatically be turned back on if Windvi etects any specials that require headers.)

-offsets

Specifies the size of both the horizontal and vertical offsets 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 roject, 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 offsets are 1.0 inch. See also -xoffset and -yoffset .

-p

Defines the size of the fonts to use, in pixels per inch. The default value is 600.

-qpaper

Specifies 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

Defines the initial shrink factor. The default value is to choose en appropriate factor.

-S

Same as -density, q.v.

-sidemargin

Specifies the side margin (see -margins).

-topmargin

Specifies the top and bottom margins (see -margins).

-version

Displays the version number and exits.

-xoffset

Specifies the size of the horizontal offset of the output on the page. See -offsets .

-yoffset

Specifies the size of the vertical offset of the output on the page. See -offsets .