## 1 Introduction

This note describes the Win-32 port of Hevea and Hacha, a fast LATEX-toHTML translator, provided by permission of the author, Luc Maranget, INRIA, France. The port runs under Windows NT 4 and Windows 95/98/2000/XP. Due to the unavailability of an Objective Caml compiler, the system is not available for Windows 3.x or plain MS-DOS.
Starting with version 1.07 we provide a native-code system, compiled in conjunction with Microsoft Visual Studio 6. This runs significantly faster than earlier versions, which used a bytecode interpreter (`ocamlrun.exe`). If you really want the old byte-code system (which now involves a dll file for the interpreter), send me an email and I'll be glad to provide it.
If you want to use Hevea in conjunction with Mackichan Software's ScientificWord / Scientific WorkPlace systems, there is a supplementary distribution available. You can read the SWP documentation here or you can download the SWP supplementary distribution (which also contains the documentation) here. Note that you will also need the main Hevea distribution, from this page.
Hevea is a command-line program, intended to be run from a DOS session within Windows. However, Steve Mayer has written a nice GUI interface — called the TeXConverter — to a number of LaTeX conversion programs, including Hevea: with this, you can run Hevea from an icon on your desktop. The TeXConverter also makes it easy to add Hevea style (`.hva`) files. You can get the TeXConverter here. I recommend, though, that you have Hevea running as a command-line program before installing the TeXConverter.

## 2 Current Version

The current version of the Win-32 port is Hevea/Hacha version 1.08, compiled November 22, 2005. This is a bug-fix release; see below. If you currently have a working Hevea 1.08 you need replace only `hevea.exe`, though over-writing the entire distribution should do no harm. The distribution is available in a zip file, `winport.zip,` from here. The archive includes a copy of this note.

## 3 Update News

- November 22, 2005: bugfix release for version 1.08. The problem shows up for example in text translation, where contractions like “it's” gets rendered as “it-s” (the apostrophe is rendered as a dash).
- May 13, 2005: Hevea 1.08 released. Among the new features are: Hevea no longer uses the Symbol font: HTML entities are utilized instead; and there is now support for CSS style sheets (see the Hevea manual). Note that `xxcharset`, described in section B2 of the Hevea manual, is not supported (and `xxcharset.exe` is not included in the distribution). This is supposed to deduce the appropriate character set from your locale information, but I don't know how to find this in Windows (it isn't an environment variable, for example). If someone knows where to find it in the registry, I may be able to provide support: please let me know. Important: Luc found a bug in the original release of version 1.08; this has now been corrected. If your executables are dated before May 14 2005, please refresh them from the new distribution.
- October 2, 2003: Hevea 1.07 released.
- May 17, 2002: Hevea 1.06 is released, including the new HTML optimizer, Esponja`.`
- February 5, 2001: added a warning about installing Hevea to a directory whose name contains spaces.
- August 11, 2000: added note (see section 8) on graphics generation: the image file and the `imagen` script. Also a pointer to the existence of a ScientificWord/WorkPlace setup.
- May 5, 2000: Hevea 1.05 is released. This release includes transparent support for the `\today` macro, plus the support for Scientific Word/WorkPlace, previously available only in an interim “beta” release.
- January 2, 2000: added `redir.zip` to the distributions to help with troubleshooting, and provide some basic instructions.

## 4 Installation Instructions

1. You need a version of `zip/unzip` which handles long file names.
2. Make a directory (the recommended location is `c:\hevea`) and unzip this distribution (`winport.zip`) to that location, preserving subdirectories. Because Hevea is a port of a Unix program, neither the directory nor the path to it should contain spaces, so do not put the files in a subdirectory of `c:\Program Files.`You will see subdirectories `html`, `text`, `info` and `test`. Note that the `test` subdirectory is specific to the Win32 port.
3. Move the LATEX style file `Hevea.sty` to some place in your LATEX tree.``
4. The batch file `hevea.bat` is provided as a cover function for the translator. To customize it, open it in a text editor and ensure that the line beginning `set heveadir=` points to the actual location of the Hevea files (by default `c:\hevea`). This must not end with a backslash.
5. The distribution also contains batch files `htext.bat` and `hinfo.bat` for text and Info translation, respectively; and `hacha.bat` for the Hacha file-chopper. You will need to customize them in the same way you did with `hevea.bat`, above.
6. Move all the batch files to some directory in your path.

The system is now ready to run.

## 5 Testing the Installation

The distribution includes a tiny test file `pavtest.tex` which you can use to test that your installation is running, as follows:

1. Change to the `\test` subdirectory of the main Hevea directory.
2. Assuming that the batch files are in your `PATH` you can do a translation to HTML by running `hevea pavtest.tex`. The result should be `pavtest.html`, which you can compare with my results in `pavtest.htmn`. If you'd prefer a result with extension `.htm` you can do `hevea pavtest -o pavtest.htm` : the `-o` command-line parameter determines the output`name.`
3. You can try a text translation by running `htext pavtest.tex`. The result should be `pavtest.txt`, which you can compare with my results in `pavtest.txs`. Note that since `pavtest.txt` includes a math equation — the choice probabilities for the logit model — the text translation will reveal visual limitations in Hevea's strategy for translating math to text.

## 6 Troubleshooting

The batch files make a copy of your current path before calling Hevea; they add the Hevea directory to your path, call Hevea, and restore the original path when done. Under Windows 95/98 (but not under NT4/Win2k/WinXP) you may run out of the space allocated by the operating system to store these strings. The symptom is a message “Out of Environment Space”. If this happens, you will need to increase the size of your environment area: here are two ways to do this.

- 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 naming the DOS session. If you start a DOS session using a different icon, the larger environment size will not be present. The same applies if you create a shortcut to one of the batch files. See the next item for a more general fix.
- Use a text editor to open up `config.sys` in your root directory. Look for a line beginning `shell=`. If there is an entry on this line of the form `/e:`nnnn where nnnn is some number, add (say) 1024 to nnnn. If there is no `/e:` entry, add at the end of the `shell` line, `/e:1024.` Save the file. Re-boot. You should not have any more problems, but if you do, repeat the procedure, increasing the value of the `/e:` entry. Note that, unlike the last one, this fix will apply to every DOS session you start.

### 6.1 Reporting errors

I'm always glad to try to help when the system doesn't work, and to this end the distribution now includes a copy of `redir.exe` from D.J. Delorie in `redir.zip`. Here's the simplest way to send an error report:

1. Create an empty subdirectory, and copy your `.tex` file to it. (If you can't even run the test document, `pavtest.tex`) you can just use the `\test` subdirectory.
2. Copy `hevea.bat` to this directory. Edit `hevea.bat` and make the following changes:
   1. change `@echo off` to `@echo on`
   2. immediately below the line `set path =` add the line `dir %heveadir%\*.exe`
   3. Save the file.
3. Unzip `redir.exe` from `redir.zip` to your directory.
4. Run the following command
     `redir -o redir.err -eo hevea pavtest.tex`
   this will create `redir.err`. Send it to me.

As you can see from the `redir` documentation, this program may be useful in other instances as well. You can move it to some directory in your path, where it will be generally available. But at least in Windows NT, just calling it may conflict with a built-in function. If you get a message saying `The VDM Redirector is already loaded`, then the operating system is using its internal function in preference to `redir.exe`. You can get round this either by explicitly including a path to `redir.exe` when you call it; or — possibly easier — renaming `redir.exe` to (say) `xredir.exe.`

## 7 Usage notes

This version of Hevea / Hacha requires that the environment variable `HEVEADIR` point to the location of the Hevea executables. The batch file `hevea.bat` sets this up for you, and you should probably use it instead of calling `Hevea.exe` directly.
If you call any of the batch files without an argument, they'll print out a summary of their purpose and syntax.

## 8 Graphics Files

When Hevea see reference to a graphic in your source (typically via an `\includegraphics` macro) it writes some informative material into the “image file”: when you're processing `mydoc.tex` this file will be called `mydoc.image.tex`. This is supported in the Win32 distribution. Under Unix Hevea, the image file is to be processed through a shell script called `imagen`, to actually generate the graphic (typically `.gif`) image. The difficulty here is that Unix shell scripts can do much more than DOS/Windows batch files; in addition, `imagen` assumes that certain supplemental utilities like GhostScript are installed on your computer, as they usually would be under Unix, but not under DOS/Windows.
The bottom line here is that the `imagen` script is not supported under Win32 (even though it is included in the distribution). However, your HTML file includes correct references to all graphics — it's only the graphics files themselves that are missing — so all you need to do is convert your source graphics to web graphics yourself. There are a number of solutions for this: one very capable, small, fast and free system is Irfan-View, obtainable from

  http://softwarecenter.net/irfanview/english.htm

Irfan-View can run either as a command-line utility or as a Windows application. It will convert `.wmf` and `.png` graphics to `.gif`; and I think it will do `.eps` graphics as well. It will not, however, handle the PostScript files produced by `dvips`. If you need to work with PostScript, a solution is ImageMagick plus Ghostscript. This is also free, but is more cumbersome than Irfan View, not to mention much slower. GhostScript is available from

  http://www.cs.wisc.edu/~ghost/index.html

and ImageMagick from

  http://www.imagemagick.org

## 9 Conclusion

Good luck! Hevea is an extremely capable and flexible translator, and I'm glad to be able to make it available to Windows users. All us Win-32 LATEX'ers owe Luc Maranget a real debt for providing it.

  Phil Viton
  Ohio State University
  `viton.1@osu.edu`

> This document was translated from LATEX by HEVEA.