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
-
You need a version of zip/unzip which handles long file names.
- 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.
- Move the LATEX style file Hevea.sty to some place in your LATEX tree.
- 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.
- 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.
- 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:
-
Change to the \test subdirectory of the
main Hevea directory.
- 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.
- 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:
-
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.
- Copy hevea.bat to this directory. Edit hevea.bat and
make the following changes:
-
change @echo off to @echo on
- immediately below the line set path = add the line dir %heveadir%\*.exe
- Save the file.
- Unzip redir.exe from redir.zip to your directory.
- 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.