1 Introduction
Luc Maranget's Hevea is a LATEX-to-HTML translator written in the
Objective Caml programming language. It is small, fast, and features support
for basic mathematics without using inline images; but its most important
feature is that it is built around a sophisticated parsing engine that
understands LATEX. This means that you can take a complicated LATEX
macro and re-define it to do only the much simpler things available
to you in HTML. Of course, you will need to understand how to write simple LATEX macros, but as I show in Part V, this is often simple.
I was recently able to “persuade” Luc to
provide direct parser support for SWP's graphics (the \FRAME macro) and Unicode, and this makes Hevea viable for SWP
users.1 An
additional advantage is that, unlike some other translators, Hevea does not
require a TEX/LATEX system, and it can therefore be used off-the-shelf
with Scientific Notebook documents.2
(But see below: even Scientific Notebook now contains its own built-in HTML
generator).
Copies of this document in html and dvi formats are included in the
SWP distribution, as heveasw.html and heveasw.dvi.
2 Availability
Hevea is available only for Windows 95/98/NT/2000/XP, and not for Windows
3.1 systems.3 If you're running on one of those
operating systems, Hevea should support SWP 3 and 2.5; probably 2.0 also.
3 Help me decide!
SWP users now have three or more alternatives for HTML generation: Luc
Maranget's Hevea, and Eitan Gurari's TeX4ht (not for AScientific Notebook),
or (SWP4+ only) built-in HTML generation. Which is best for you? Bearing in
mind that you may have to work with the systems to get them to work for you,
here are some considerations.
-
Machichan Software
- All the Mackichan Software products after verion 4
(including Scientific NoteBook) come with a built-in HMTL generator.
One advantage of this over Hevea is that it will automatically generate
graphics images for your math, so you are not limited to HTML entities.
However, there are some appearance problems with this native HTML
generation: see the discussion in
swpht.html
on this website. If this is a problem for you, you may wish to stick with
either Hevea or TeX4ht, depending on your needs.
- Setup
- Hevea takes only a few minutes to set up, and requires no
helper applications to run. By contrast, TeX4ht is more complicated to
install, and requires both Ghostscript and ImageMagick to run properly. Of
course, SWP native support is available as soon as you've installed the
system.
- Basic Text Handling
- If your document consists largely of text (as
opposed to mathematics) and uses only standard LATEX constructs, all
translators produce good HTML. But Hevea has a noticeable speed advantage
over TeX4ht, and a small advantage over native SWP, since images do need to
be generated. However, with reaonably fast computers, the difference between
Hevea and SWP's native HTML generation is pretty small, and may not even be
noticeable.
- Real-time support
- As of Hevea version 1.07+ you get a compiled
native-code version of Hevea: previous versions used an interpreted bytecode
system. The native-code version is much faster: one result is that
Hevea is now suitable for real-time on-demand translations of LaTeX
documents. Neither TeX4ht nor the SWP built-in support can do this.
- Internationalization
- As of Hevea version 1.08, all systems support
Babel. (Hevea's -francais option is still available, but
deprecated).
- Simple Math
- Hevea now (version 1.08) uses HTML entities to represent
math symbols: previous versions, like the well-known TtH translator,
represented mathematical symbols using the symbol font that is
present on almost all computers. Either way, you get HTML which is fast to
generate and fast to load. The downside is that it works only for
“simple” math — math which uses only
the available symbols; and even when it can display the content of
your math, the display may not be optimal. TeX4ht and SWP native support, on
the other hand, use images to represent math, and thus can represent exactly
what you'd see on the printed page. But these images need to be generated,
and documents containing them take longer to load. There's an obvious
trade-off involved here: how you resolve it is up to you.
- Complicated Math
- For math which uses symbols not present in the
symbol font, or math where accuracy of placement is important,
Hevea cannot cope well. On the other hand, the image-based solution offered
by both TeX4ht and SWP's built-in support will accurately reproduce both the
symbolism and the layout of your formulas. So for complicated math, either
of these is preferred over Hevea.
- Translation to plain text
- Hevea does an excellent job of converting
your non-mathematical LATEX to plain text: numbered lists get the
correct numbers, sectioning is nicely set off from the main text, etc. By
contrast, TeX4ht can do a traditional “detex” translation, just stripping off the LATEX
commands. SWP cannot do this at all. Hevea is probably what you want for
text production.
- User Effort
- Unless you use only standard LATEX, you will probably
need to tell Hevea how to deal with at least a few of the macros in your
document; and this means being able to write a few simple LATEX macros.
This is not difficult but goes against SWP's philosophy of shielding the
user from LATEX. As for TeX4ht, my experience has been that once the
system is installed and working properly, user intervention is rarely
required. (You can tweak TeX4ht, but you usually don't have to).
- Graphics
- By construction, both Hevea and TeX4ht handle SWP graphics
in much the same way: they write HTML IMG tags and leave it up to
you as author to produce versions of the graphics that will be understood by
browsers. TeX4ht will usually do this authomatically, while Hevea needs some
assistance: see section 11. SWP's native support geenrates its
graphics automatically, which is a considerable advantage.
4 Call for assistance
I've developed the SWP support in swp.hva based on my own
experience with Hevea and SWP, and I'm adding material as necessary. User
contributions are welcome. This applies especially to the Scientific
Notebook support: I don't use SN myself, so I've got only a rudimentary
idea of what needs to be dealt with.
There is no SWP support for Info translation; if anyone wants to supply a
swp.hva file for Info, I'd be glad to include it.
5 Updates
This section lists updates to the SWP-Hevea system and documentation, for
easy reference.
-
May 14, 2005: Hevea 1.08 released. Major changes: (1) the Symbol font
usages is now abandoned in favor of HMTL entities, which provides more
robust support for representing math. (2) Support for CSS stylesheets is now
implemented (see the online Hevea manual). Important: Luc found a
bug in the original release of version 1.08: this has now been corrected. If
your hevea executables are dated before May 14 2005, please refresh them
with the versions in the updated archive.
- October 2, 2003: Hevea 1.07 released. This version includes only
(faster) native-code versions of Hevea and friends: the old bytecode system
( and ocamlrun.exe) are no longer needed.
- May 19, 2002:
-
Hevea version 1.06 is released. See
winport.html
for details.
- An experimental native-Windows-code version of Hevea and Hacha (and a
new program, Esponja, an HTML optimizer) is available. This version does not
use the bytecode interpreter. It can run significantly faster, especially
for long documents on slower machines. But it is experimental. If you
try this version and you use Steve Mayer's TeXConverter, you should probably
upgrade that, too. Details in
native.html.
- If you use Hevea 1.05 in connection with version 4 of the SWP family
of products you need to make a couple of simple changes. (These are included
in the Hevea 1.06 distribution; if you want to use SWP4 with Hevea you must
be using Hevea 1.05 or later).
-
Open swp.hva in Hevea's html directory.
- Find the line TCI's hyperref
- On the next line, change \def\hyperref to \def\msihyperref
- Below this definition, add the following line:
- \AtBeginDocument{\@ifundefined{hyperref}{\let\hyperref=\msihyperref}{}}
- Make the same change in the version of swp.hva in Hevea's
text subdirectory.
- February 5, 2001: added a warning against putting the files in
directory whose names (and/or paths) contain spaces.
- July 14, 2000: Unicode support may require that you change the META
information to use the UTF-8 character set. Added a note in section 12 explaining how to do this.
- June 4, 2000: added a note on some inconsistencies between the SWP use
of the HyperLink dialog and the code generated by Hevea. See section 18.
- May 5, 2000:
-
Hevea 1.05 is officially released. The SWP support is no longer based
on the beta version.
- The latest version of Steve Mayer's TeXConverter (see Appendix G) now supports Hacha.
- December 30, 1999: Initial release, based on the “unstable” Hevea 1.05–6 of December 22, 1999.