Hevea: the Win-32 port ********************** Philip A. Viton =============== The Ohio State University ========================= March 29, 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 Windows NT 4 and Windows 95/98/2000/XP. Starting with 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 #4 or you can download the SWP supplementary distribution (which also contains the documentation) #4. 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 #4. 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 #4. 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 #4. 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. 3 Update News *=*=*=*=*=*=*= - March 29, 2013: Hevea 2.06 released. This corrects a general bug, not confined to Windows. - March 26, 2013: Hevea 2.05 released. This corrects a problem with the Windows implementation of Esponja: we recommend that Hevea-2.00 users upgrade to 2.05. - September 10, 2012: Hevea 2.00 (and 1.99) released. - September 12, 2007: Hevea 1.10 released. - October 29, 2006: As luck would have it, Internet Explorer 7 was released just as Hevea 1.09 was; and contrary to all hopes, there's a regression in the browser's ability to display some math symbols. You can take a look at #4 to see some symbols which were displayed in IE6, but no longer show up in IE7. (FireFox 2.0 was released a few days later, but, as one might expect, I've not noticed any regressions here). The problem has been reported, and we can always hope that Miscrosoft will it, but meanwhile, with some help from Luc, I've come up with a temporary hack. It relies on defining a Javascript function in the HTML document: the function decides whether the browser being used to view the page is Internet Explorer or not, and if it is, displays symbols using the Windows Symbol font; otherwise it uses standard entities. This appears to solve the problem, but of course there's a downside: these symbols won't be displayed at all --- IE or not --- unless scripts are allowed to run. In IE, whether scripts are blocked is fairly obvious; but in Firefox, if you're running the NoScript extension, you may want to set it up to Enable Message About Blocked Scripts (NoScript setup, bottom of the Appearance tab). My solution uses a special version of winfonts.hva called winfonts2.hva. As of today, the file is included in the Windows distribution: if you've already set up Hevea, you can get it separately #4: unzip it to Hevea's HTML folder. I have not made it the default in the Hevea batch file: if you want to use it, just edit the file, and replace winfonts.hve by winfonts2.hva. Note that you don't want to use it for text translation, since Javascript has no meaning there. Note that winfonts2.hva is an unofficial fix, and is not included in Luc's distribution. If Unix users want it, they can download it from the stand-alone link given above. Please let me know of any problems (symbols that don't display correctly): there may be typos. It may also be possible, using another Javascript function, to provide a better solution for the delimiters problem: I'm currently thinking about how this could be done. Watch this space. - October 17, 2006: Hevea-1.09 released. Among other things, this fixes two problems with version 1.08. First, if you put the front-matter commands \author (etc) into the body of the document (ie, not in the preamble), Hevea didn't process them. Second, there is a problem with viewing math expressions surrounded by large delimiters in certain browsers, notably those running under Windows. The problem arises because in Hevea 1.08 these delimiters were constructed with HTML entities; and in most of the fonts provided to Windows users, those particular entities are not defined. Resolving this is more difficult than one might suspect, because the obvious fall-back --- use the symbol font --- is officially unsupported in Mozilla-based browsers. - 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). 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, 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. - Start a 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% 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 #4 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 #4 and ImageMagick from #4 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 (1). ----------------------------------------------------------------------- (1) http://hevea.inria.fr/index.html