Hevea: the Win-32 port

Philip A. Viton
The Ohio State University

September 18, 2013

1  Introduction

This note describes the Win-32 port of Hevea and Hacha, a fast LATEX-to HTML translator, provided by permission of the author, Luc Maranget, INRIA, France. The port runs under all Windows versions from Windows 95.

Starting with Hevea version 1.07 we provide a native-code system. 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 that you have Hevea running correctly as a command-line program before installing the TeXConverter.

2  Current Version

The current official version of the Win-32 port is Hevea version 2.06, compiled March 29, 2013. The distribution is available in a zip file, winport.zip, from here. The archive includes a copy of this note.

There is also available Hevea version 1.99, which is the final version to produce HTML-4 code (Hevea 2.00+ produces HTML-5). You can get the distribution, winport-199.zip from here. Note that unless you have a special reason to use HTML-4, the recommendation is to upgrade to the latest in the Hevea 2.00+ series.

Upgrades: unless there’s a specific Windows issue, I tend to recompile Hevea only when there are major improvements. But if for some reason you need the latest version, please feel free to ask for it: I can usually produce a new distribution in a day or so.

Wrappers: Vincent Belaiche has contributed some wrappers (ie cover scripts) for Hevea being run under MSYS: you can get them here. This is a .tgz archive: among other programs, 7-zip can handle them. (The archive also contains versions of the ordinary windows scripts (.bat files): they should be the same as those supplied in my distributions). If anyone would also like an ordinary zip version, please let me know.

3  Update News

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, mappings and test. Note that the test subdirectory is specific to the Win32 port.

    Note that if you want to try both the current version and the last HTML-4 version (Hevea 1.99), the files in both archives have the same name. This means that you should unzip the two distributions to different directories, and then modify one set of batch files to take account of the two different locations.

  3. Move the LATEX style file Hevea.sty to some place in your LATEX tree. With many TeX distributions you will now need to refresh your filename database in order for the new package to be recognized. This applies, for example, to MikTeX (do Start -> Programs, pick the MikTeX group, select Settings (MikTeX 2.5) or Options (MikTeX 2.4 or earlier). When the applet opens, on the General tab click Refresh FNDB). It does not apply to Scientific WorkPlace, Scientific Woird or TrueTeX.
  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. They should not be placed in the same folder as the Hevea executables because there is a name conflict, and Windows will use the executables in preference to the batch files.

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 only (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.

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%
    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.

Note that xxcharset, described in section B2 of the Hevea manual, is not supported (and xxcharset.exe is not included in the distribution). This program is supposed to deduce the appropriate character set from your locale information, but I don’t know how to find this in Windows. If you need this facility, you can follows Luc’s suggestion: include the command in an .hva file, and load this file; or, more directly, put into your document preamble: \makeatletter \def\@charset{xxx} \makeatother , where xxx is a character set known to Hevea (one of the file names in Hevea’s mappings folder, without a .map extension, eg, ISO-8859-7).

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 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 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.