Contents

Part I
Overview

1 Introduction

This paper explains how to set upTeX4ht, Eitan Gurari’s TeX/LaTeX-to-hypertext translation system, when the underlying TeX system is MiKTeX for Win32 platforms. Thanks to Eitan for answering lots of TeX4ht questions and to Steve Mayer for extensive tests and valuable suggestions regarding htrun.

2 MikTeX 2.5

As of version 2.5 (and possibly also 2.4) MikTeX almost supports TeX4ht “out-of-the-box”, so I’m beginning to phase out my support for installing the system. I believe that that support will still work, if you really want to use it; however, it is not integrated into the MikTeX update system, which may or may not be a disadvantage (there was a time when MikTeX updates were well behind updates issued by package authors; but this seems to have changed).

Why do I say almost? Well, as of early September 2006, TeX4ht does work out-of-the-box if you want to do something very simple, like htlatex myfile. However, if you want to something more complicated, for example run a TeX4ht command with options (like tex4ht myfile "html,imgdir:images/" which creates HTML with all graphics references to the images subdirectory of wherever the HTML file is stored; or htlatex myfile "xhtml,jsmath" " -cmozhtf" (note the required space before -cmozhtf) which constructs jsmath representations) then, at least right now, the system fails to make the graphics. I believe that the problem is with the .exe versions of the TeX4ht batch files that MikTeX supplies. I’ve reported the problem, and maybe it’ll get fixed. (It’s worth noting that MiKTeX supplies specially compiled versions of these files: the problem is not with Eitan’s distribution, so it’s no use complaining to him).

Meantime, there’s a fairly straightforward solution: run TeX4ht from the batch files, which MikTeX also supplies. The difficulty with this, however, is that batch files are confused by paths containing spaces. This means that you really have two options:

1. Install MikTeX to a top-level folder whose name does not contain spaces. Unfortunately, this means installing MikTeX to a non-default folder: the setup utility suggests c:\Program Files\miktex, which just doesn’t work here. In addition, you will need to add a folder to your path, manually (instructions on this are given below). In my view, this is the recommended option: the advantage is that you can automatically take advantage of any updates to the batch files, which will be installed by the normal MikTeX update procedure.
2. Make a copy of the batch files and put them into some folder in your path. This should allow you to work with a MikTeX installed into c:\Program Files; the downside is that you will need to copy any updated batch files from the normal MikTeX installation to the location in your path.

2.1 Installation

Given the problems with the TeX4ht .exe files, here’s how I think you should proceed, when installing MikTeX and TeX4ht:

1. If you are doing a fresh installation of MikTeX 2.5, or you can do a re-installation, do so using the installer, but do not install to the default folder. Instead, use one which does not contain spaces: one suggestion is c:\texmf; but it’s up to you. Tell the installer that you want to install the TeX4ht package. (If you are setting up the full MikTeX system, TeX4ht is installed automatically).

   If you’re not in a position to install to a no-spaces folder, don’t panic. Just read on.

2. MikTeX installs its own version of GhostScript, called mgs.exe. Thus, there’s no reason to worry about upgrading or even installing GhostScript (if your only use for GhostScript is with TeX and friends).
3. You must install ImageMagick (IM) yourself. (Instructions below in section 6). You must also ensure that IM places itself in your PATH statement before the system32 folder of your Windows installation (because system32 contains another program called convert.exe). I’m pretty sure that the IM installation takes care of this for you; but if you get an unusual error message, it’s one thing to check. Also, TeX4ht assumes a recent (at least 6.1) version of IM: if you are using an older version, by far the simplest thing to do is to upgrade. But if for some reason you don’t want to upgrade, then you should read through the discussion in the rest of this document, concerning the convert command line, and be prepared to edit tex4ht.env manually.
4. As far as I can tell, MikTeX’s TeX4ht does not include the two test files test.tex and testa.tex. For your convenience, I’ve added them to my installation package (it’s a faster download than the TeX4ht distribution, and the files are easier to find). You can get it here . I suggest you create a test folder in the main MikTeX folder, and place the two files there.

2.2 Testing TeX4ht

Now you should see just what is working and what isn’t. Start a DOS session, and navigate to the directory where you placed the TeX4ht test files.

1. Issue the command htlatex test . This is a basic run of the system, and produces no graphics. If you get an error from pdfLaTeX saying: latex: Not enough room in an internal buffer then you need to use the MikTeX Update Wizard and update TeX4ht. Early versions of MikTeX’s TeX4ht were compiled so that running TeX4ht with no-explicit-package support would fail. When you’ve done this, try again. There should not be any errors.
2. Issue the command htlatex testa. This exercises TeX4ht’s graphics-producing ability. You should watch this part of the program carefully — the part that comes up on screen after the third LaTeX invocation.

   If you get an error message referring to an “unknown color” (this will be when GhostScript/mgs and IM are making an image) then you need to edit tex4ht.env. You should do this only after you’ve updated TeX4ht to take care of the internal buffer problem. Also, the update may have dealt with the entire problem automatically.

   If you do see this error: Load tex4ht.env (in …/tex4ht/base/win32) into a text editor and make sure that every instance of #FFFFFF (this is the parameter of the -transparency switch in the call to convert) is double-quoted. As distributed, the files may contain this parameter either unquoted or with single quotes. Now try again. If this doesn’t work, try changing the quotes from double to single. If there are still problems, try removing them all.

3. Now see if the exe file problem as been resolved. Issue the command htlatex testa "html,imgdir:images/". What you’re looking for here is an indication that the graphics-making commands still work, just as they did in the previous test. If the .exe system still has problems, you should see that graphics generation is not being done, and when the system calls the tex4ht.exe utility there will be a error message beginning tex4ht: Windows API error 123 ….

   If something goes wrong at this step, then you should probably switch over to using the batch files (unless you’re absolutely sure that the only way you’ll run TeX4ht is with simple commands like htlatex myfile).

4. As noted above, there are two ways of doing switching to batch file use. If MiKTeX is already in a no-spaces folder, then all you need to do is add a certain folder to your path; see next step. Otherwise you need to put the batch files into a no-spaces folder. Many of us have a folder called something like utility already in our paths for just this purpose. If you have such a folder, just copy all the batch files from …/scripts/tax4ht/bat to this folder. Otherwise, create a folder whose location does not contain spaces, and copy the batch files to there. Note that if you do copy the batch files, you will need to re-copy them if TeX4ht updates them; my understanding is that this is relatively rare.
5. Here is how to add a folder to your path (all Windows versions since NT). Remember that if you are working with a MikTeX system in a no-spaces folder, you will be adding MiKTeX’s scripts folder; if you moved the batch files, you will be adding that folder.
   1. Open the Control Panel applet (Start -> Settings -> Control Panel).
   2. Double-click on the System icon
   3. Select the Advanced tab and then click on the Environment Variables button at the bottom.
   4. Under System variables select PATH and then click Edit
   5. In the resulting dialog box, hit the Home key on your keyboard. This moves the cursor to the beginning of the entry.
   6. Now type in the new path element. If your MiKTeX system is in a no-spaces folder this will be x:\yyy\scripts\tex4ht\bat; where x is the drive and yyy is the folder where you installed MikTeX (eg c:\texmf\scripts\tex4ht\bat;). Otherwise, it will be the name of the folder to which you copied thae batch files. In either case note that the string you are entering ends with a semi-colon ( ;).
   7. Click OK to accept the new entry, and then back out of the Control Panel.

   Now close your DOS session (if it’s still open) and start a new one (needed for the new path to take effect). If you type path you should see your new entry at the beginning of the response. Check that the spelling is correct; and if necessary, go through the Control Panel again until it is.

   Finally issue the command htlatex testa "html,imgdir:images/" again. This time graphics generation should be OK.

   At this point, you should have a working TeX4ht+MikTeX system.

2.3 Htrun

Htrun is my own utility, designed to call the “right” TeX4ht batch file, depending on its analysis of your source file. It is really useful only if (1) you produce both LaTeX and plain-TeX source files (or any two flavors of .tex source) ; or (2) you want to run Steve Mayer TeXConverter. Otherwise, it’s simple to train yourself to call the correct TeX4ht batch file — typically htlatex — directly. But if you do need htrun, see the next section.

2.4 The TeXConverter

Steve Mayer’s TeX Converter is a graphical interface for doing several types of conversions, including use of TeX4ht. It is available from here . For TeX4ht support, the TeX Converter is dependent on my htrun utility. The principal complication here is that you need to install htrun.exe and htrun.ini into the folder containing the files which actually run the TeX4ht system. However, if you are content to run the .exe files, then it couild be … miktex/bin. So here’s how to set up to use htrun.

1. In order to avoid problems with source files that do and do not explicitly request the tex4ht package, Steve Mayer has kindly patched the TeXConverter; you should obtain a version dated September 4, 2006 or later.
2. Place htrun.exe and htrun.ini into the folder containing the programs (eg htlatex.bat or htlatex.exe, depending) which actually run TeX4ht.
3. Edit htrun.ini to make sure that it’s using the right files. As distributed, the .ini file distinguishes between source files that do and do not explicitly load the tex4ht package. You should use the same file for both these cases: that is, the distinction is no longer necessary in TeX4ht. So for all kinds of LaTeX translations, the entry here should be latex.bat (or latex.exe). Remember that the format for the file names is the name of the batch/executable without the prefix which is supplied in your command line via the initial switch. Thus htrun -ht myfile or, for the default case, htrun myfile, requests a run of htlatex while htrun -mz myfile asks for mzlatex.

3 Updates

This section lists changes and updates to my old (pre-MikTeX2.5) instructions, for easy reference.

• MikTeX 2.5, August 2006: as noted in the previous section, MikTeX’s distribution of TeX4ht can be made to work with very little additional work; and I’m now beginning to phase out my customized installation utility, described in the remainder of this document.
• ImageMagick: the saga continues. Unfortunately, the non-cropping problem noted (and fixed) in IM 6.0.8 has recurred. The new fix (in addition to the old one involving +repage) is to change -crop 0x0 to -trim. This seems to work in all IM version in the 6.x series.

  The current version of the TeX4ht-MiKTeX installation routine makes all the required changes, and on the assumption that you’re using 6.0.8 or later, everything should work. Existing TeX4ht users will need to make the changes yourself. Here’s what you need to do: the files concerned are tex4ht.env and glyphgif.bat. Note that these may contain several invocations of convert: all need to be changed.

  1. All versions of IM in the 6.x series: change -crop 0x0 to -trim
  2. All versions of IM in the 6.x series: make sure that the name of the input file is the first argument to convert.
  3. IM 6.1.0 or later: add +repage after -trim
  4. ImageMagick 6.0.0 only: if the convert’s command line contains +repage, remove it.

  You should watching closely the first time you run TeX4ht to be sure that ImageMagick recognizes all options: the error message for +repage, which you will see with IM 6.0.0, is convert.exe: unrecognized option ‘+repage’.

  Note that if you are using the image caching F-script (glyphgif.bat) you may have made and cached non-cropped versions of the glyphs. You need to delete them, both in the cache and in the folder containing the original .tex source. These files will have names like cmsy-7e.gif, as opposed to names based on the name of the source document. My suggestion is to delete any of these files whose size is 500 bytes or greater. Nowadays the effort involved to remake glyph-gif files is minimal.

• October 13: the updated tex4ht.env in newt4ht.zip wasn’t being processed, sorry. This is now fixed. the update system (update.bat in the updatem folder) is also changed to (re)-process tex4ht.env.
• October 3, 2004: with some help from the ImageMagick bugs people, we have a fix for the Sept 17 problem. Eitan has incorporated the fix into the latest TeX4ht update files, so if you are just now installing, the latest ImageMagick programs should be OK.

  If you want to make the fix by hand in an existing TeX4ht installation, this is what’s involved. In tex4ht.env and glyphgif.bat, in the lines calling the convert utility (note that there may be more than one such line, and you need to change them all):

  1. After -crop 0x0 add +repage (NB: preceded by a + , not a - , and separated by the surrounding material by at least one space).
  2. Move the name of the source file — which will be a name involving batch parameters, and with extension usually being .ppm) to right after the convert name. For example, in tex4ht.env you’d change the existing call to

     Gc:\ProgramFiles\IM6\convert zz%%4.ppm -crop 0x0 +repage -density 110x110 -transparent #FFFFFF %%3

     (where of course your path may differ from mine: you don’t need to change the path at all).

• September 17, 2004: It looks to me as if ImageMagick 6.0.8 — the current version as of today — does not crop GIF images correctly: the symptom is very large gifs, containing lots of whitespace. I have verified that ImageMagick 6.0.0 does not have this problem, so until the problem is fixed, I recommend that you get 6.0.0 It is available from here .
• April 14, 2004: Bug fixes in the install routine:
  • The l script entry in tex4ht.env was not getting changed. If TeX4ht fails on the test files, this is the first thing you should check. Fortunately, it’s easy to fix by hand: find the entry beginning lc:\tex4ht and change it appropriately. But if you’d rather not, you can just re-install the system.
  • If you use htrun, it was unable to process testa.tex due to a missing htlatexp.bat file. This is now supplied. Note that testa.tex is a source file with an included \usepackage{tex4ht} which is not the preferred TeX4ht approach anyway.
  • Typo in <tex4ht>/updatem/getnewt4ht.bat : in the section dealing with the *.4ht files, change unzip -o to unzip -jo

  Good news: the GIF problem appears to be solved! It looks as if ImageMagick 6.0.0 has finally resolved the problem of GIFs not being visible in Mozilla-based browsers. For this reason, I’ve removed the possibility of forcing your GIFs to be in GIF87 format: you should just upgrade ImageMagick instead. Please let me know if there are still problems: if there are, we’ll need to re-visit the issue.

• March 17, 2004: Note that MikTeX 2.4 includes TeX4ht among the packages installed when you set up the system. However, as best I can tell, the install procedure does not perform the fairly extensive editing on the support files (batch files and tex4ht.env) needed to get the system running correctly. Until it does, I recommend that you continue to set up TeX4ht using the distribution available here; and if you have already installed TeX4ht from the MikTeX distribution, that you uninstall it first. See below, section 4.1, for detailed instructions.
• March 15, 2003: There is a typo in the call to convert in the current distribution of tex4ht.env: the argument #FFFFF is single-quoted, and this can cause problems. As of today, the automatic install will fix this for you; existing users should check whether their version has the problem and correct it by hand, using a plain-text editor.
• September 15, 2003: We now convert Unix line endings to MS-DOS endings automatically, if you are running Win95/98/ME, using Filescan. The old unix2win archive has been removed. Archive name changed.
• September 12, 2003: more bug fixes, to accommodate Win 95/98/ME.
• September 8, 2003: A couple of bug fixes in the automatic installation procedure. In particular, the ht command wouldn’t work, because the env file wasn’t found.
• August 10, 2003: Revised installation instructions to match the current distributions, including MikTeX 2.3. The installation is now pretty much automated.

  It does not appear that the GIF problem mentioned on February 22 is being solved. That being so, you have two alternatives: (1) switch to PNG graphics. These are as easy to produce as GIF, and have no problems; (2) if you know that you will always be using GIFS, you can guarantee that you get the right images by forcing ImageMagick to produce GIF87 format. See below (section 7, describing the decisions you need to make before installing) on how to do this. You can force this via the new automated installation.

• February 22, 2003: It appears that the current versions of ImageMagick’s convert utility produce gifs which are not readable in (at least) the following browsers: Phoenix 0.4, Firebird 0.6–0.7, Firefox 0.8, Mozilla 1.2x+, Netscape 4.7x; no error is reported, but the images simply don’t show up. The gifs are readable in (at least) IE 6.0 SP-1, Opera 7.01, and Amaya 7.1 (thanks to Murray Eisenberg for verifying some of these). This has been reported as a bug to ImageMagick. Until it is solved, probably the best thing to do is to use an old version of ImageMagick: I have put a copy of ImageMagick 5.2.3, which does work, on my website: you can retrieve it from here . Unzip it to c:\: the files will go into c:\ImageMagick-win2. When the bug is resolved, I’ll post an update here.
• March 6, 2002: The latest version of ImageMagick’s convert uses the switch -transparent where previous versions used -transparency. To see which switch you should be using, open convert.html (in ImageMagick’s www directory) in a browser, and read down the list of switches. Then check that both glyphgif.bat and tex4ht.env have the appropriate switch in their call to ImageMagick.
• June 11, 2001: Portuguese Translation Available! Alexandra Bernados has kindly prepared a Portuguese translation of these instructions. You can read it here as a 250K HTML file, or download it as a 32K zip file for offline-reading. Note that Alexandra doesn’t have the time, and I don’t have the ability, to keep the translation up-to-date; so Portuguese users may at least want to skim these Update notes to see what has changed.
• January 12, 2001: Under Win95/98/ME LaTeX can apparently crash if called from a batch file with Unix line-endings. Section 9 explains how to fix this. As far as I know, this is never a problem with WinNT4 or Win2k.
• February 22, 2000:
  • Steve Mayer has produced a very nice GUI interface to TeX4ht (and some other TeX/LaTeX utilities running under Win32) called the TeX Converter. Here is a link to his web site.
  • Added a section on Getting Help, using redir.exe.

Part II
Installation

4 Get the Software

4.1 MiKTeX

The approved way to use TeX4ht is via a series of batch files. Therefore, it is important that you install MiKTeX to a folder whose name (and path) does not include a space. The default location, c:\texmf, is perfect. If you really don’t want MiKTeX in c:\texmf, you should place it in some subdirectory whose name does not include spaces, like c:\ProgramFiles (note: no space here) or c:\DosPrograms. You could also place GhostScript and ImageMagick in that folder. 

In addition, the instructions here assume that you told the MiKTeX install routine to add MiKTeX’s bin directory to your path. That is, you should be able to process a LaTeX document foo.tex from anywhere on your hard drive by simply typing latex foo.

I believe that the MikTeX package manager will install its own version of TeX4ht automatically in all three available package sets. The problem is, the install does not edit the batch files (and tex4ht.env) which may (and in some cases will) therefore point to the wrong locations for the files TeX4ht needs. I therefore recommend that you uninstall the version of TeX4ht set up by the package manager, and then re-install using the instructions given below. To uninstall TeX4ht using the package manager do the following:

• Do Start -> Programs -> MikTeX -> MikTeX Package Manager
• In the Name field type tex4ht. The response should list two sets of files: tex4ht and miktex-teX4ht-bin.
• Select each of them in turn and click on the minus sign (for Uninstall) or select and then do Task -> Uninstall.

You can now go ahead and install the present distribution. The MikTeX package management utility puts the binaries and batch files in MikTeX’s bin folder, and the other TeX4ht files in a tex4ht folder under the top-level MikTeX folder: you can mimic this by setting the appropriate variables in the automated install process, as described below. Or you can choose to put them somewhere else. Whatever you choose, all the files should come out correct.

4.2 TeX4ht

• Browse to TeX4ht , then:
  • Under “Installation” click on “MS Windows” (second paragraph).
  • Under item b. retrieve tex4ht.zip.
• Optional: get any current TeX4ht updates. To do this:
  • If you’re not on the “Bug Fixes ” page, return to the main TeX4ht page; click on “Bug Fixes”.
  • If there are any updates described there (there may not be), click on “Alternative zipped” in the second bulleted item. This retrieves newt4ht.zip containing all updates.
• Optional: you may also retrieve any updates to the hypertext fonts, by retrieving the file htf.zip if present.

Note: the Bug Fixes page of TeX4ht contains a reference to the basic files, in an archive whose name incorporates the issue date (eg tex4ht-20040211.zip). This is the same as tex4ht.zip referred to above: if you get this one, just rename it to tex4ht.zip before running the installation routine.

4.3 GhostScript

If you have GhostScript 5.50 or later, you don’t absolutely need to upgrade, but since we are now at version 8, it is probably a good idea to do so.

• Browse to GhostScript . Click on the link to “Obtaining AFPL GhostScript”, then find the section for MS-Windows, and download the self-extracting executable, gsmnnw32.exe.

4.4 ImageMagick

Unless you’re sure that no-one reading your HTML will ever do so with a Mozilla-based browser you should upgrade ImageMagick to version 6.0 or later. This version appears to have fixed the problem with GIFs not displaying in these browsers, and makes it unnecessary to worry about the distinction between GIF and GIF87 files.

• Browse to  ImageMagick. At the top of the page, click on Download then, in the left frame, Binary Releases, then, in the top-most descriptive paragraph, Windows Executable. No reason not to get the Q16-windows-dll release.

5 Set Up GhostScript

5.1 Install the distribution

Run the executable for the distribution gsmnnw32.exe. You are asked where to install: I recommend that you accept the defaults, which will put the executables in c:\gs\gsm.nn\bin. Do not uncheck the box for GhostScript’s fonts: you may need them. Do not install GhostScript to a directory whose path contains a space character — TeX4ht will be unable to utilize it.

6 Set up ImageMagick

6.1 Install the distribution

ImageMagick’s installation routine offers to install to c:\Program Files. You should not do this: because we will be using IM in batch files, the included space will cause problems (for the same reason as with GhostScript). Instead, install to a folder whose name (path) does not contain spaces. See above under “MiKTeX” for some suggestions.

7 Set up TeX4ht

Note that we automatically place the TeX4ht executables (tex4ht.exe and t4ht.exe) in MiKTeX’s bin folder with the other executables. If you don’t like this, it is easy to move them after the install has done its job. Remember, they must be in your path.

Here’s what you need to do to set up TeX4ht.

• Find or create an empty folder on your hard drive, for the temporary installation files.
• Place the TeX4ht distribution files (tex4ht.zip and possibly newt4ht.zip and htf.zip) there.
• Retrieve tex4ht-miktex-install.zip and unzip it to this location.
• You must now make a few decisions.
  • Where do you want to put the TeX4ht files? I recommend that you put them in c:\tex4ht, but you can change this (eg, by putting them onto drive D). Your choice must not contain spaces, though.
  • Where do you want to put the batch files? Your choice must be in your path. One suggestion is to put them with MiKTeX’s (and TeX4ht’s) binaries, which by assumption is a folder already in your path. A second possibility is to put them in a folder in your path which contains other batch files, something like c:\utility, if you’ve set up such a folder. See section A.2 for how to add such a folder to your path.
  • Do you want to use a cache system for GIF files? See section 7.1 for more information on this. If you’re unsure, then you should probably decide “no”: with today’s faster computers, this is less important than it once was.
  • Do you want the batch files to run “invisibly”? As distributed, they consist of a series of commands, all of which will be displayed on your screen. This display can be can avoided by inserting an @echo off command at the top of each file, and the install routine can do that for you. My advice is to let us do it: if you need to see what’s going on, you can always change the off to on.
  • Do you want to use htrun with two different TeX setups, say MiKTeX and Scientific WorkPlace? htrun is a little utility I wrote which tries to distinguish whether your source file is TeX or LaTeX, which type of conversion you wish to perform, and it will call the appropriate batch file for you. If you are using only one TeX system, there’s no issue. But if you have two or more TeX’s, then you have the opportunity of renaming the batch files, by adding a suffix to their names. That is, you can change, say, htlatex.bat (a standard file) to a MikTeX specific file, say htlatexm.bat. For most users this will not be necessary. In addition, it is only available under Windows NT4/2k/XP.

    Note that if you take this option, then, as an added precaution, we add the full paths to the MiKTeX executables to the batch files. That is, instead of simply latex we construct something like c:\texmf\miktex\bin\latex, where of course the path is the path to the MiKTeX executables, which you provide for us.

  • Do you need MikTeX support for Mackichan Software’s Scientific Word, Scientific Workplace or Scientific NoteBook? These require special attention, see section B.2. Most users will not need this.
• Open miktex-install.bat in a text editor like NotePad. You must now supply values for a series of environment variables at the top of the file. These are all of the form set xxx=yyy , where xxx is the name of the environment variable, and you need to supply the yyy. In the following table we also show that some of these are checked, and show what we look for. Here’s what’s needed:

  Variable	Points to	Checked?
  t4htdir	Top-level TeX4ht directory	N (created if needed)
  miktexdir	Top-level MiKTeX directory (eg c:\texmf)	Y (latex.exe)
  locdir	Top-level local MiKTeX directory (eg c:\localtexmf)	N
  gsdir	Location of gswin32c.exe	Y (gswin32c.exe)
  imdir	Location of convert.exe	Y (convert.exe)
  batdir	Location for the batch files; must be in your path	N

  (In the case of miktexdir we automatically append the necessary subdirectories to arrive at MiKTeX’s bin directory). Note that none of these should end with a \ or with a space.

  There are a few other variables that you may need to change. These are of the form set xxx=N and if you want special handling, you must replace the N with something to indicate your choice.

  • For silent batch files (recommended) replace the N in myecho . So this could read, eg, set myecho=y
  • If you want to enable the cache system (see section 7.1), replace the N in myglyph.
  • If you want to install the support for Scientific WorkPlace (etc) replace the N in swp.
  • Finally, if you want to rename the batch files, you must replace the 2 in set mysuff=2 by the suffix you wish to add. (Why 2? Because any single-letter could be a choice for appending). If, for example, you say set mysuff=mik then a batch file like htlatex.bat would be renamed to htlatexmik.bat. Remember, this is probably useful only if you are running TeX4ht in connection with two different TeX systems, and it is only available on Win NT4/2k/XP.
• Save miktex-install.bat
• Now run miktex-install.bat. This should install all files. We also create a folder <tex4ht>/miktex_doc and copy this file there, for future reference.

  That’s it.

7.1 Speeding up image generation

This section describes an optional feature of the TeX4ht support.

If, when creating HTML or XHTML, TeX4ht needs to represent a single character not present in the default font, it produces a GIF image using GhostScript and ImageMagick. These single-character images — call them “glyph-gifs” — never change, and TeX4ht is intelligent enough to know that if they are present in the current directory, there’s no reason to re-generate them. But if they’re not in the current directory then they normally would be regenerated, even if some other document had already produced the necessary files. But because TeX4ht distinguishes between the job of generating a glyph-gif and that of creating other GIFs (used, eg, for entire equations, or tables), this opens up the possibility of more sophisticated handling of glyph-gifs.

What we want to do is specify special handling just when we are generating glyph-gifs. We do this by setting up an F script — this is just a command, or sequence of commands, which contain the letter F in the first column — in tex4ht.env, in which case those entries will control glyph-gifs, while the G script (entries beginning with G) will control other GIFs

The automatic install includes just such a script, and we activate it if you ask us to. It consists of a single line in tex4ht.env: FCall glyphgif.bat %%1 %%2 %%3 which calls the batch file glyphgif to process glyph-gifs. If you did not ask that it be activated, the line is still there, but there is a space in the first column, which de-activates it. If you want to activate it later, just open tex4ht.env in a text editor and remove the space before the F. (Of course, you can design your own script if you want to).

How glyphgif.bat works: suppose you need a glyph-gif for character 1A hex from font cmmi10. You will be asking the system to generate cmmi10-1A.gif. Then glyphgif.bat works as follows:

• Does cmmi10-1A.gif already exist in the current directory? If so, no further action is taken.
• If not, does cmmi10-1A.gif already exist in the cache? If so, it is copied into the current directory, and no further action is taken.
• Otherwise, use dvips, GhostScript and ImageMagick to generate cmmi10-1A.gif and then put a copy of the newly-created GIF to the cache for future use.

Warning There is one down-side to using the cache setup. Suppose you need to generate a glyph-gif, but for some reason the GIF generation fails. You now have an incorrect — typically empty — glyph-gif file in your cache and in the current document’s directory; and TeX4ht will continue to use it until you delete it. In this case you must delete the bad files from both the current directory and from the cache, and then re-process your document. This can be confusing unless you’re alert to what can happen. You can (temporarily) stop the F script from running by opening tex4ht.env and putting a space before the character F on the line in tex4ht.env calling the F script. This forces all glyph-gifs to be made in the normal way, and the cache is not consulted or updated.

7.2 Other utilities

Section 14 explains how to obtain and use some utilities which may simplify your use of TeX4ht. You may want to glance at that now. In addition, you might want to take a look at Steve Mayer’s TeXConverter, a GUI interface to TeX4ht and other conversion programs. It is available from here . The TeXConverter assumes you have a working MiKTeX+TeX4ht setup, so you should check out the installation as described below, before getting it.

If you are going to try OpenOffice conversions (batch files oo*.bat) you should know that OpenOffice expects its XML files to be stored in a particular structure inside a .zip file. TeX4ht will create the correct file, but you will need to have a command-line version of a zip creation utility available. Here are two possibilities:

• If you use WinZip, there is available from the WinZip website ( here) a pair of command-line add-ons, wzunzip.exe and wzzip.exe. To get them, click on WinZip add-ons under Downloads on the menu on the left. To use the command-line support, place the files with the other WinZip files, and then modify tex4ht.env and replace the call to zip by a call to wzzip, preceeded by the full path to the file. If that path includes a space, the entire command should be in double-quotes, for example "c:\Program Files\winzip\wzzip.exe" .
• You can get a free command-line zip utility from InfoZip here . Place it in your path: a reasonable place is with the TeX4ht batch files. This is a companion to the unzip.exe supplied as part of the present Tex4ht-MikTeX distribution, and if you find yourself using command-line utilities, you may wish to copy our unzip.exe there too.

Part III
Testing and Troubleshooting

8 Testing the Installation

The TeX4ht distribution contains two test files. Each creates an HTML file containing a single line of text, one single-character GIF (a “glyph-gif”), and one multi-character GIF To run these tests, assuming that you’ve set up all environment and path variables correctly:

• Start a DOS session and change to c:\tex4ht\test
• First, test the new interface, which doesn’t require an explicit LaTeX package: issue the command

  htlatex testb

  Note that if you asked the automatic installation to add a suffix to the batch files, you’ll need to call htlatexsuff testb, where suff is the suffix you selected (htlatex.bat will not be present). Either way, the TeX compiler will run, and there will be two calls to ImageMagick/GhostScript to generate GIFs. Load testb.html into your browser to make sure it looks right. If you have multiple browsers, it may be good idea to try them all.

• Next, test the older interface in which you explicitly load the TeX4ht package in your source. Issue the command

  ht latex testa

  (Or htsuff latex testa if you added a suffix). The TeX compiler will run three times, but because the glyph-gif will already be present, there will be only one call to ImageMagick/GhostScript. View testa.html in your browser(s).

If all the tests work, then you can delete any remaining files in the temporary installation folder. If something goes wrong, see the next section.

9 Troubleshooting

9.1 First steps

If you can’t process the test files properly, begin with some easy checks.

• Make sure that MikTeX is working properly, especially if you’ve just installed it. If you take testa.tex and comment out (put a % at the beginning of) the line \usepackage{tex4ht}, this file should be processable without errors by MiKTeX, and viewable through yap. Remember to remove the comment when it is working properly.
• If you see empty spaces where the GIFs should be, then if you are using a pre-version-6.0 ImageMagick, you should upgrade. If you are already using IM 6.0+, please let me know: it means that I was wrong about the GIF problem being fixed, and we’ll need to take steps.
• Otherwise watch the screen carefully. The image-generation part of the translation process should write a series of lines saying System return: 0 on your screen. A non-zero value indicates that that part is going wrong.
• If convert reports UnrecognizedColor (’#FFFFFF’) then you need to open tex4ht.env in a text editor, find the G script line calling convert.exe and remove the single quotes around the #FFFFFF.
• If you get an error beginning Error: /invalidfont in findfont this means that GhostScript isn’t finding a font it needs. Make sure that all dvips command lines (in tex4ht.env and glyphgif.bat) contain -Ppdf
• If you want to re-run the installation, you must first re-unzip the distribution archive (tex4ht-miktex-install.zip): because we try to clean up a bit as we go along, some files are no longer present when the installation batch file ends. If miktex-install.bat is OK, re-name it before unzipping, or else it will be over-ridden.

If you think that the post-processing (GhostScript + ImageMagick) isn’t getting the right parameters, you can check this by adding lines to the G script, something like the following:

(This also illustrates that you can make these scripts do almost anything you like).

10 Getting Help

If all else fails, I’m willing to try to help get the TeX4ht system set up. (This is distinct from general TeX4ht support: for that you should contact Eitan Gurari). Here’s what you need to do.

1. Make up a short source (.tex) file exhibiting the essential problem. For example, if some glyph doesn’t generate the right GIF file, the source should contain a line or so of text, plus the offending character. If the problem is an included graphic, make sure your document has just the one graphic.
2. Copy the source file (and any needed graphic file) to an empty directory.
3. Copy redir.zip from c:\tex4ht\updatem to this directory, and unzip it.
4. Copy the batch file that you use to run TeX4ht to this directory. If it begins with @echo off change this to @echo on.
5. Type the following command: set kpathsea_debug=-1 (no spaces)
6. Now run the following command:

   redir -o viton.txt -eo command

   where command is the full TeX4ht command, beginning with the name of the appropriate batch file. You should not see any output. If you get a message saying The VDM redirector is already loaded then repeat the command including the full path to redir (eg c:\mydir\redir -o viton.txt -eo command )

   This creates the file viton.txt which contains (most of) the output generated by TeX4ht and its helper applications.

7. Type the following command (which undoes the previous one): set kpathsea_debug=
8. Copy tex4ht.env (from c:\tex4ht\texmf\tex4ht\base\win32\tex4ht\base\win32) into the directory.
9. Make a zip archive of all the files in this directory, and send it along to me, together with a brief description of what’s going wrong. Be sure to mention (a) which MiKTeX version and (b) which operating system you are using.

Part IV
Upgrading

This section contains details of what needs to be changed if you upgrade parts of the system.

11 Upgrading GhostScript

The following files contain references to GhostScript’s location and will need to be edited if you upgrade GhostScript and place its files in a new folder:

• c:\tex4ht\texmf\tex4ht\base\win32\tex4ht\base\win32\tex4ht.env (in the section setting up the G scripts)
• glyphgif.bat if you elect to use it (see section 7.1)

12 Upgrading ImageMagick

If you upgrade ImageMagick, the following files contain references ImageMagick’s location, and will need to be edited:

• c:\tex4ht\texmf\tex4ht\base\win32\tex4ht\base\win32\tex4ht.env (in the section setting up the G scripts)
• glyphgif.bat if you elect to use it (see section 7.1);

13 Updating TeX4ht

At present, updates (bug fixes) for TeX4ht are distributed in two forms: one, usually called newt4ht.zip, contains updates to the TeX4ht system (batch files, executables) itself, while htf.zip contains updated ht-font files. It is relatively unlikely that you will need to update the ht-font files; but either or both will be handled by the following procedure:

• Retrieve either or both update files from Eitan Gurari’s web site and copy the files to <tex4ht>\updatem where <tex4ht> is your top-level TeX4ht directory
• Start a DOS session and change directory to <tex4ht>\updatem
• Run the file update.bat. This will install any new files it finds, and update MikTeX’s filename database if necessary.

Part V
The Supplemental Utilities

14 Supplemental Utilities for TeX4ht+MiKTeX

There are several supplemental utilities which are automatically installed by this procedure.

14.1 htrun.exe

htrun is a little utility which attempt ti simplify running TeX4ht. It will be useful if:

• You have a mixture of LaTeX files, some of which explicitly load the TeX4ht package, and some of which don’t, and you don’t want to check each time you run TeX4ht which it is.
• You have a mixture of TeX files (LaTeX, plain TeX,texinfo, etc) which you need to run through TeX4ht, and you don’t want to check each time what kind of file it is, in order to call the right batch file.

htrun quickly scans your source (.tex) file and attempts to deduce what type it is; and then calls the appropriate batch file automatically. The htrun setup consists of two files, htrun.exe and htrun.ini

14.1.1 Setting up htrun

htrun is installed automatically to the folder containing the TeX4ht batch files. But you need to configure a few items, in htrun.ini.

• Open htrun.ini and make sure that you see debflag = 0 and rdebflag = 0. If you are running under Windows NT4/Win2k/Win XP, make sure that you also have packquote = 1.

If you need to process Scientific Word/WorkPlace/Notebook documents, go to Appendix B.2. Once this is done, you can use it in exactly the same way you’d use any of the batch files, namely

htrun myfile [options1 [options2 [options3]]]

where the [optionsn] are as described on the TeX4ht web site, and may be omitted if you want standard processing. You can get some information on what the program’s doing by running htrun with no arguments. See also Appendix B.3.

14.1.2 Testing htrun

Once htrun and all batch files are in your path you can repeat the tests: start a DOS session, switch to c:\tex4ht\test and run

htrun testb

htrun testa

These should give the same results as before, and you should see a message on your screen telling you which batch file is being run, based on what htrun has decided about your source. You can set up the htrun to pause after displaying this information — see Appendix B for details.

Part VI
Appendices

Appendix A The Environment

This appendix explains two aspects of dealing with the Windows environment: how to set environment variables, and how to increase the size of the environment.

A.1 Setting environment variables

For purposes of illustration, we assume that you want to set the environment variable delegate_path to the value c:\ImageMagick\ImageMagick

• Under Windows NT/2k/XP: open the Control Panel, choose System, then Environment. At the bottom of the dialog under Variable: enter
  delegate_path
  and under Value: enter
  c:\ImageMagick\ImageMagickClick OK. This will take effect the next time you start a DOS session.
• Under Windows95/98: edit autoexec.bat; add the line
  set delegate_path=c:\ImageMagick\ImageMagick.You need to re-boot for the changes to take effect.

A.2 Adding a directory to your path

Your path is an environment variable like any other, so you’ll just follow the procedure for adding an environment variable, except this time you’ll edit an existing variable. To do this:

• Under Windows NT4/2k/XP : open the Control Panel, choose System, then Environment. Choose the Path variable and elect to edit it. What you need to do is type in the full path to the new folder, separated by what’s there by a semi-colon (;). Then click Set and back out of the Control Panel.
• Under Windows 95/98/ME : open autoexec.bat and add the new folder to the end of the line path= , separated by what’s already there by a semi-colon (;).

A.3 Increasing the environment size

If you run out of environment space (the symptom is the message Out of Environment Space) you will need to increase the environment size. Note that this happens only with Windows 95/98/ME: it will never happen under Windows NT/Win2K/XP. Here’s how to fix the problem.

• Start a windowed DOS session, click the icon at the top-left of the session window, and select Properties.
• Under Memory, change the entry under Environment Size from Auto to (say) 1024. If it is already set to something other than Auto, select the next larger setting. Click Apply.
• Close the window. When you next open it, the Environment size will be larger, and your problems should be gone.
  Note that this is specific to the icon you have just invoked. If you start a DOS session using a different icon, the larger environment size will not be present.

Appendix B More on htrun

B.1 htrun and other hypertext translations

TeX4ht is an extremely flexible system, and supports translation of TeX and LaTeX to a variety of other output formats beyond HTML. htrun can support these, too. The basic idea is that you call htrun with a Translation Prefix, indicating they type of hypertext you want. The translation prefix is indicated on the command line before any other parameters, and is of the form -xxx where xxx indicates the output you want. Presently we have:

(Note that not all of these are supported with all input variants; however, all are available for LaTeX).

The effect of the Translation Prefix is that we run the batch file listed in htrun.ini, but with the file name prefixed by the Prefix. For example, if the .ini file contains an entry to run latex.bat, and your Prefix was -mz, we would actually run mzlatex.bat. If you do not provide a Prefix, we default to ht, which translates to HTML.

There is one last consideration to bear in mind. Suppose you’re using the package form of TeX4ht with the html option specified — that is, your source file contains a line like

\usepackage[html,3.2]{tex4ht}

You can certainly run this file through the version of htrun configured for one of the alternative output translators but you will still get HTML output (because that’s what the package options request). If you are seriously interested in alternative formats, clearly the no-package form of your source document is the one to use. Steve Mayer’s TeXConverter provides an nice alternative solution: if you request an output format with the “wrong” package options, the Converter will offer to (temporarily) remove the entire package line for you. Your file will then be processed by a batch file which does not expect an explicit package, and all will be well.

B.2 SWP support in htrun

Mackichan Software’s programs Scientific Word, Scientific WorkPlace or Scientific Notebook (all referred to here as SWP) produce two kinds of output files:

• Portable LaTeX: these load no special packages, and should be processable by TeX4ht as plain LaTeX sources. One thing to be aware of is that SWP supports many more graphics types than MikTeX, and you will probably have to add TeX4ht support for them. This is relatively easy via a \Configure{graphics} command
• SWP latex: this is the standard output form from the program. There are two difficulties for TeX4ht. One is that all such documents load a special file, tcilatex.tex. This will be missing from your MiKTeX installation, and you will need to obtain it, in order to process the source. The second is that these documents handle graphics via a non-standard macro, \FRAME. This needs to be translated into something that TeX4ht can understand.

  When you install TeX4ht, you have the option of installing the SWP support. This adds about a dozen additional batch files (two for each of the hypertext outputs formats supported by TeX4ht), and a couple of special packages. However, we do not install the basic SWP support file tcilatex.tex: you will need to obtain a copy yourself. If you do not install the support and you try to process an SWP file via htrun, then the system will fail because a non-existent batch file.

  If someone sends you an SWP file, it’s probably simplest to ask them to send you a copy of all special files needed in the document. Alternatively, you may obtain a copy of tcilatex.tex from the Mackichan Software FTP site here Currently, tcilatex.tex is buried deep in the directory tree at this location: swandswp3 -> updates -> tcitex -> tex -> latex -> tci. This file is not proprietary, and may be freely used and distributed.

B.3 Advanced configuration of htrun

htrun needs two kinds of information in order to do its work: a set of document recognition strings, which it uses to determine the source type, and a list of batch files to run. Many of the strings, and all the batch files, are set up in the file htrun.ini and may be configured by the user. As distributed, htrun is set up as follows:

(where “SWP” refers to Scientific Word and Scientific WorkPlace) and where in each case the named batch file will have its name prefixed by ht. (So if the batch file names latex.bat we will actually run htlatex.bat). The Prefix setup is described in more detail in section B.1).

Note that as distributed, the system assumes that you will be using the “replacement” batch files (names end in “m”).You can change any of these by editing the .ini file and altering the text to the right of the equal signs. Before running the selected batch file, htrun looks for it in your path, and will refuse to run if the file isn’t found.

The following options are supported in the [integers] section of htrun.ini (any omitted statement in this series is taken to be “off”, equivalent to =0):

• DEBFLAG=1 : additional information is sent to your DOS session console.
• RDEBFLAG=1 : the system will not actually run the selected batch file, so you can see what would be done with your source file.
• PAUSE=1 : htrun will pause and wait for you to press a key before executing the batch file, and you’ll see what’s about to happen. If the key you press is n or N, then htrun stops (and your source file is not processed).
• LATEX209=1 : this allows you to use separate batch files for processing LaTeX2e and LaTeX 2.09 files.
• PACKQUOTE=1 : The TeX compiler may balk if you try to pass it an empty (ie two consecutive double-quotes,  " "   ) argument for the TeX4ht package (This is the first sort of TeX4ht command-line options). The solution is to pass a space instead (ie two double-quotes separated by a space,  "  "   ). If PACKQUOTE=1, then htrun will expand  " "   in the TeX4ht package position only and insert the needed blank space. This appears necessary for MiKTeX under Win NT4 — but not under Win 98.

Finally, note that htrun’s document-recognition strategy isn’t foolproof. Consider a plain-TeX file containing \input texinfo in a verbatim-like environment (for example, describing how to use TexInfo). This will be — mistakenly — recognized as a TeX4ht-processable TeXInfo file, instead of a plain-TeX file requiring some additional code (the string in CSNAME) before being processed by TeX4ht. Short of building a mini TeX parser, I don’t see how I can cope with this. Of course, LaTeX files, with their well-defined notion of a preamble, are much less susceptible to this sort of thing.