3 The image-generating process

3.1 Strategy for creating bitmaps

As explained in section 2, TEX4ht needs external utilities for creating the bitmaps used in the web-documents. The default set up is a combination of dvips, gs (GhostScript) and ImageMagick’s convert utility [4]. Unfortunately this is a rather slow process, and not a very good one when it comes to antialiasing, and it’s definetely not suited for typesetting uses. However, the dvi2bitmap tool available freely from [3] is efficient and converts dvi files directly to png or gif files. Dvi2bitmap works almost like a normal dvi-driver, but has no support for so-called dvi-specials (such as included eps-figures et.c.) Thus, a combination of the two is required: We use dvi2bitmap whenever we encounter maths and special symbols as this is efficient and produce good results, but use the aforementioned dvips/gs/convert-process for items that dvi2bitmap cannot handle, such as included PostScript figures.
Note:
In the trouble-shooting section on the official web page for TEX4ht [2] it is mentioned that you can directly configure TEX4ht inside your document to process e.g. \includegraphics in a special way. I have not been able to use the method successfully myself, though you might give it a try if you are not satisfied with the results.

3.2 All the bad things: tex4ht.env

The converting process is initiated in the TEX4ht configuration file tex4ht.env. From the man pages of TEX4ht one can locate this. It is useful to have a copy in your working directory and edit it when needed. TEX4ht will use whatever configuration file it finds first, and the current working directory is the first place it looks. You may also get the configuration file in the package from section 5.

The converting process is the lines in tex4ht.env starting with G. I have simply replaced those lines with a call to a small script. Thus, the converting-process in my tex4ht.env file looks like:

G./cscript.sh %%1 %%2 %%3 2

The configuration file format is ugly and crammy, and it takes some effort to get into it. (And to make things worse, blank lines are actually harmful, as the documentations so nicely puts it.) For the image-generating process however, all that is needed is to replace the few lines that begin with a G.

3.3 Making amends with cscript.sh

The Bash script cscript.sh (“c” for conversion) obviously takes four parameters: We pass the parameters %%1-%%3 on the command line in tex4ht.env. The three parameters are the name of the dvi file, the page number and the name of the desired output file, respectively. (This is a good thing with tex4ht.env: An external utility may get all the information it needs from it.) As the fourth parameter the script takes an integer between 0 and 3 indicating the desired output quality of the bitmaps: 0 is quick-and-very-dirty, 1 has no antialiasing while 2 and 3 employ antialiasing, with 3 the best and by all means the slowest.4 The quality settings only apply to the dvips-gs-convert-process, as dvi2bitmap’s quality is always quite good. For example, the following call to cscript.sh reads page 42 of mydvi.dvi and creates the bitmap outfilename.png with the lowest quality:

./cscript.sh mydvi 42 outfilename.png 0

Several minor problems were encountered while investigating the conversion process, and all of them are fixed in the script. For example, the default for dvi2bitmap is to employ an alpha-channel (for semi-transparent pixels) when outputting png files. This is not compatible with Microsoft’s Internet Explorer browser and many imaging applications. The fix is to employ a white background instead, but this means that when choosing background colors in the HTML document, one needs to adjust cscript.sh directly.

TEX4ht is defining a lot of strings and macros, and really puts a strain on TEX’ capacity. If this is the case, be a wizard and increase it in your texmf.cnf file.

The program dvi2bitmap relies on the kpathsea library for finding fonts, but not all TEX distributions install this. If this is the case, then dvi2bitmap must use other means for locating the font files. This may turn out to be complicated. Luckily, the newest version (as of time of writing) can also employ the standalone version kpsewhich and this works fine. Note however, that the presence of either the library or the standalone is needed for the current script to work.