[Lowerbounds, Upperbounds]

(Most recently updated on 2008-02-08, but I have kept the referenced MiKTeX version at 2.5. As far as I know, none of the changes in MiKTeX 2.6 and 2.7 matters to the topic of this post.)

I have recently upgraded my MiKTeX to the latest version 2.5 for some reason. And as much as I love MiKTeX, I have switched from YAP (Yet Another Previewer, the DVI previewer in MiKTeX) to Dviout.

Dviout may not be very familiar to non-Japanese users because, to my understanding, it is primarily developed to deal with Japanese usage (think about fonts). However, it works equally well in English too. I can recommend Dviout over YAP 2.5 for several reasons:

• Dviout pretty much does everything YAP is capable of: color specials, HyperTeX jumps (you use the hyperref package, don’t you?), and perhaps most importantly, round-tripping using source specials (but see the note below).
• Unlike YAP 2.5, it does not seem to have any DVI locking issue, at least not in my daily usage of working on a large document. (To me, this alone is worth the switch until YAP eliminates the lock issue.)
• In my experience, Dviout is much faster than YAP ever since it had a major change in version 2.5. Unlike YAP, Dviout does not make you choose between “dvips” vs “pk font” rendering—the former is slow, and the latter cannot be used when your document has any graphics. There is really no good choice in YAP.
• The particular document I am working with is also somewhat graphics intensive. Like YAP, Dviout is able to call Ghostscript to show the included graphics in the DVI preview. But it also caches the generated bitmaps and use them later for unmodified figures. This saves me a lot of time. (And this is the primary reason why I expect to stick with Dviout for a while. I sprinkle \parpics and wrapfigures quite liberally on my spaghetti.)
• Dviout allows you to customize the shortcut keys. I like to exercise my left hand more often and so I set some shortcuts on my left hand.
• Dviout can do a text search directly inside DVIs. This can be handy if all you have is a DVI file. (Package documentation comes to mind. And yes, you could have converted it to PS and then do the search in the PS…)

(Note: there is an issue that I am still puzzling on. In the forward search, sometimes Dviout will land on a few paragraphs earlier than the intended destination. I will update this post once I figure out the solution.

Update 2007-03-07: Nailed it. First, recall that source specials are implemented by inserting tags that specify the source file and the corresponding line number into the DVI file. The problem is that sometimes the line numbers in the tags are not in increasing order. Here is how the stream of tags might look like: {src:1003main.tex}{src:1055main.tex}{src:1015main.tex}{src:1019main.tex}. In this case, if you ask the DVI previewer to go to line 1015 of main.tex, a simple scan algorithm will hit the second tag and then incorrectly conclude that no further reading is necessary. This is exactly what happened. Workaround? I guess I will have to wait until I finish my current project and patch the source directly.)

Below I will show how to get Dviout working with MiKTeX 2.5. (Update 2007-11-15: The same instruction works for MiKTeX 2.6 because there is no change in directory layout.)

1. Remove the directory C:\localtexmf\fonts if you have one. It contains your existing PK font files. We can afford to regenerate them. MiKTeX 2.5 by default put PK files in a different location too.
2. Create a new file dviout.par and put it in the same directory with dviout.exe. It’s the preference file for Dviout.
3. I have included the non-default parameters that I use at the end of this post. You can use it as your first dviout.par and start from there. As you can see, there are some hard-coded path names that you will need to change. The following is a list of parameters that you want to pay attention to, in the order of appearance in my dviout.par below:

   GS

   This means “On” with “Direct PS” turned off in the Graphic tab. Keeping Direct PS off can mitigate a class of problems due to dvi files prepared with source specials containing postscript. For instance, you can generate such a dvi file by using hyperref with the dvips driver, which is usually the default. The right driver for dviout is hypertex, used like this \usepackage[hypertex]{hyperref}.

   gsx

   You may have installed Ghostscript somewhere else. I note that MiKTeX comes with Ghoscript these days, but I usually keep an installation of the most recent Ghoscript so I don’t use the one that comes with MiKTeX.

   gdat

   All my documents store their figures in a figure subdirectory. The current setting tells Dviout to cache the preview bitmaps in the same subdirectory instead of the parent directory where the DVI is located.

   gen

   I installed my MiKTeX there. The default for 2.7 would be `C:\Progra~1\miktex~1.7\bin\makepk.exe ^s ^d ^D ^M. There should be no space in the path name and so you must use short path. Also, be careful with the backquote character.

   key

   I have added four shortcut keys to my config. “z” and “x” are for back and forward, “-” and “=” are for zooming out and in. Also, note that “space” is by default mapped to next-page, and so the pair “z” and “space” is all I use most of the time. Remember, the shortcuts are fully configurable in the Option->Set Parameter->Key tab.

   BMP and scale

   I have made an unusual choice here because of my late-night TeXing. The negative numbers represent negative gamma, which is to say that the DVI text is displayed in white on black. If you want the normal black on white, change the -400 to 1100. The particular number depends largely on the font you use and your monitor, but 1100 is in the ball park. (This answers rmcd’s comment.)

   TEXROOT

   For MiKTeX 2.6, the current setting is a sensible choice. This is what ^r in the TEXPK option expands into.

   TEXPK

   If you have installed MiKTeX 2.6 at its default destination, use TEXPK=”^r\fonts\pk\\dpi^d\^s.pk;C:\Program Files\MiKTeX 2.6\fonts\vf\\^s.vf” instead. You can read my comment on 2007-03-23 to understand what it does and how you can come up with the right setting for your machine with the help of YAP.

   TEXFONTS

   According to the Dviout manual, this option is needed when you cannot generate a PK font but you want to replace the missing characters with spaces of the correct size, hence the need to locate the TFM (font metric) files. I would say that if you cannot generate an English PK font, then you want to resolve the issue completely instead of relying on this feature.

   src

   I use GNU Emacs on Windows since a long time ago and I am still at version 21. That explains why I picked gnuclientw as my src editor. In the comments, rmcd explained how to use emacsclient instead. Dviout supports DDE as well and so you can use many other editors. See the help file for instructions.

   gsrc

   I use Ipe for most of my graphics. That explains the path in gsrc.

   isp

   With the GS option above, we have turned off Direct PS. This “ignore some source specials” setting further suppresses a whole bunch of (mostly harmless) warnings. There are pros and cons, but I think this together with the GS setting above is a sensible default.

   file

   This is where you put dviout.par. Of course, you don’t really change this setting by changing it inside dviout.par, but this is a non-default setting with a hardcoded path.

4. Finally, to make AUCTeX use Dviout instead of YAP, here is a snip from my tex-site.el. Note that I am showing you Emacs Lisp here and as rmcd pointed out in his comment, you do not want to enter the backslashes before the two inner double-quotes if you are using Emacs’s customize-variable command to change your TeX-view-style. The backslashes are only necessary in Emacs Lisp so that we escape the two inner double-quotes.
   

   (setq TeX-view-style
'(("^a5$" "yap %d -paper a5")
("^landscape$" "yap %d -paper a4r -s 4")
("^epsf$" "gsview32 %f")
;;("." "yap -1 -s%n%b %d")
("." "dviout -1 %d \"# %n %b\"")))


Here are some usage tips on Dviout:

• As much as I prefer not to ask you to touch the registry, you want to know that Dviout remembers some of its settings in HKCU\Software\SHIMA\DVIOUT. For instance, it stores the window dimensions there. (I set my xPos, yPos, Height and Width in the registry once and for all.) I believe that all options set outside of Option->Set Parameters, such as Option->Continuous Renew, are stored in the registry.
• You may also want to disable Options->Check color specials from the menu in case Dviout complains about your DVI file. It happens when your color specials have certain issues as explained in the manual. I meet these issues too frequently.
• Make sure you enable Options->Setup Parameters...->System->Auto Renew. (It’s on by default, but it’s worth checking in case you turned it off by accident.) It forces a update check when you switch into Dviout from another application. This behavior is shared among most, if not all, DVI previewers.
• Options->Continuous Renew is a good thing if you have a large monitor or a dual monitor to let you see both your text editor and Dviout without overlap. This option will cause Dviout to pop into foreground when the DVI file is updated. Using Microsoft’s Tweak UI, in General->Focus, enable Prevent applications from stealing focus and set it to flash the taskbar button one time. That will make Dviout always show you the latest DVI without stealing the focus from your text editor. (I use this with the continuous mode in latexmk.)
• Most importantly, once you have customized the options using Option->Setup Parameters to your own liking, select Option->Non-default Parameters. A small text box will pop up and you can copy and paste its content into your dviout.par. (That’s how I get the file below.)

Have fun with Dviout!

Finally here is my current dviout.par (last updated 2008-02-08). I have also uploaded it as a file to avoid line wrapping and other funny things due to quotes.

br=0x800000
bf=0x800000
bb=0x1d4c000
multi=4
button=+
dpi=600
GIF=5
GS=17
gsx=C:\Progra~1\gs\gs\bin\gswin32c.exe^-IC:\Progra~1\gs\fonts;C:\Progra~1\gs\gs\lib;C:\Progra~1\gs\gs\Resource^-dTextAlphaBits=4^-dGraphicsAlphaBits=4
gdat=./figures
gsize=+
search=448
sdpi=600
hyper=0x1d030
hbuf=0x400000
ToEdit=^c^V
FB=2
varf=+
gen="`C:\texmf\miktex\bin\makepk.exe ^s ^d ^D ^M"
y=F614.295pt:794.96999ptP
key=DR=-:DM==:JL=x:JF=z
log=C:\temp\dviout.log
BMP=6:6:-400
scale=2:2:-400:4:4:-400:2:2:1100:4:4:1100
TEXROOT="C:\Documents and Settings\All Users\Application Data\MiKTeX\2.6"
TEXPK=^r\fonts\pk\\dpi^d\^s.pk;C:\texmf\fonts\vf\\^s.vf
TEXFONTS=C:\texmf\fonts\tfm\\
src='gnuclientw^s+%d "%s"'
gsrc=.eps.pdf=C:\UnixHome\ipe\bin\ipe.exe^s"%n.ipe"
isp=ps:SDict;!
file=c:\unixhome\dviout\dviout.par


P.S. I should mention that staying with MiKTeX 2.4 would not be a bad choice if I could… You should also be reminded of potential issues if you decide to upgrade to Vista before MiKTeX 2.6 comes out.