Part I
Overview

1 Introduction

This paper describes Version 2 of the SWP support for TeX4ht, Eitan Gurari’s TeX/LaTeX-to-HTML translator. (Unless otherwise stated, I shall use “SWP” to refer to either Scientific Word or Scientific WorkPlace). TeX4ht allows you to take your SWP document and translate it into accurate HTML: all your mathematics, including characters from the AMS fonts, appear correctly on-screen; alignment in equations is preserved; you can generate tables of contents and break up your document into linked sectional units. TeX4ht supports the new table features introduced with HTML 4.0, cascading style sheets; and the emerging XML standard. Here is a link to the TeX4ht web site, so you can read more about this translator. In this paper, I shall refer to TeX4ht with the SWP support as TeX4ht/SWP.

Note that as of Version 4, all the Mackichan Software products (including Scientific Notebook) allow you to produce HTML directly from the document you’re editing. This is both faster and more convenient than using an external system like TeX4ht. Nontheless, there are some issues about the direct HTML solution that you might want to be aware of. See the discusion in Appendix I for more on this.

A copy of this paper is included as swpht.html (and sub-files) in the swp-ht.zip distribution referred to below. See section 3 and then section 4 for the beginning of the setup instructions.

Note that we support only SWP 2.5+. Scientific NoteBook is not supported. As far as platforms, it is known to work with any version of Windows after Win95.

Installation instructions begin in section 4.

Acknowledgements: This work has benefitted from very substantial assistance from both Eitan Gurari and Steve Mayer. Steve went to an astonishing amount of trouble to test successive versions of the SWP support, and his suggestions led to major improvements. And Eitan was constantly available t when I had questions about TeX4ht itself. If this implementation has any merits, they are due largely to the support I received from them. Of course, remaining problems are my responsibility alone.

The legal conditions underlying this support are contained in Appendix J.

2 Updates

This section notes updates to the SWP/TeX4ht implementation issued since the initial announcement of Version 2. These updates are incorporated, where appropriate, into the main text (and to the distribution).

• Bug fix: January 2006. A user has alterted me to a bug in the batch files: it’s been there (as far as I can tell) forever; and frankly I don’t really understand why the system has worked at all — but it has. The problem is that the top of each batch file sets a path to your SWP system in the variable swppath. As distributed, this was set to something like c:\swp55\tcitex. On its own, this is fine, but then some other entries which reference this variable set the tcitex part again, which will result in a non-existent folder.

  I’ve fixed up the main distribution, and I’m providing a package tex4ht_swp_fixup.zip which will fix an existing distribution: the package is available here . To run the fixup, unzip the zip file to an empty folder, then open fixup.bat in a text editor, and tell us where your swp system is (swppath) and where the batch files are (batloc). Then save and run the fixup file. Note that if you are doing translations to other than html (ie using batch files whose first two letters in the names are other than ht) then you will need to set the prefix variable appropriately, and run the batch file again. In all cases we keep copies of the original batch files in the subdirectory temp of wherevear you run the batch file from, just in case.

  The changes made are as follows: set swppath=c:\swp55\tcitex -> set swppath=c:\swp55; then start /wait %swppath%\truetex -> start /wait %swppath%\tcitex\truetex (3 times). Finally, in the line setting VFFONTS we add // to the end of the line, to enable searching subdirectories. Not strictly needed for SWP as distributed, but it may come in handy if you add other font families, and put their virtual fonts in subdirectories. 

• ImageMagick: the saga continues. Unfortunately, the non-cropping problem noted (and fixed) in IM 6.0.8 has recurred. The new fix (in addition to the old one involving +repage) is to change -crop 0x0 to -trim. This seems to work in all IM version in the 6.x series.

  The current versions of the install routines make the necessary changes, assuming that you’re using IM 6.0.8 or later. Existing users will need to fix their files by hand. Here’s what you need to do: the files concerned are tex4ht.env and glyphgif.bat, tex4ht-im.bat, tex4ht-im1.bat, tex4ht.im2.bat (or as many of these as are present). Fortunately all of these are in the same folder; but note that some of these contain more than one invocation of convert and all need to be changed.

  1. All versions of IM in the 6.x series: change -crop 0x0 to -trim
  2. All versions of IM in the 6.x series: make sure that the name of the input file is the first argument to convert.
  3. IM 6.1.0 or later: add +repage after -trim
  4. ImageMagick 6.0.0 only: if the convert’s command line contains +repage, remove it.

  With these changes, TeX4ht should work with all IM releases from 6.0.0 on. It’s worth watching closely the first time you run TeX4ht to be sure that ImageMagick recognizes all options: the error message for +repage in IM 6.0.0 is convert.exe: unrecognized option ‘+repage’.

  Note that if you are using the image caching F-script (glyphgif.bat) you may have made and cached non-cropped versions of the glyphs. You need to delete them, both in the cache and in the folder containing the original .tex source. These files will have names like cmsy-7e.gif, as opposed to names based on the name of the source document. My suggestion is to delete any of these files whose size is 500 bytes or greater. Nowadays the effort involved to remake glyph-gif files is minimal.

• October 3, 2004: with some help from the ImageMagick bugs people, we have a fix for the Sept 17 problem. Eitan has incorporated the fix into the latest TeX4ht update files, so if you are just now isntalling, the latest ImageMagick programs should be OK.

  If you want to make the fix by hand in an existing TeX4ht installation, this is what’s involved. In tex4htX.env, glyphgif.bat, tex4ht-im.bat, tex4ht-im1.bat, tex4ht.im2.bat (or as many of these as are present): in the lines calling the convert utility (note that there may be more than one such line, and you need to change them all):

  1. After -crop 0x0 add +repage (NB: preceded by a + , not a - , and separated by the surrounding material by at least one space).
  2. Move the name of the source file — which will be a name involving batch parameters, and with extension usually being .ppm) to right after the convert name. For example, in tex4htX.env you’d change the existing call to

     Gc:\ProgramFiles\IM6\convert zz%%4.ppm -crop 0x0 +repage -density 110x110 -transparent #FFFFFF %%3

     (where of course your path may differ from mine: you don’t need to change the path at all).

• September 17, 2004: It looks to me as if ImageMagick 6.0.8 — the current version as of today — does not crop GIF images correctly: the symptom is very large gifs, containing lots of whitespace. I have verified that ImageMagick 6.0.0 does not have this problem, so until the problem is fixed, I recommend that you get 6.0.0. It is available from here .
• May 30 2004: Another set of bug fixes for Win98, found by Carmen Fierro. She has also kindly supplied corrected configuration files for the mz, xh and xhm trenslations. Finally, she has provided a set of replacement configuration files for Seteve Mayer’s TeXConverter (tcconfig.cfg, tcconfig-xh.cfg, tcconfig-mz.cfg and tcconfig-xhm.cfg): these provide support for SWP Portable Graphics. You will need to copy these to the TeXConverter folder by hand if you want to use them. Thanks, Carmen!!

  Good news: the GIF problem noted on Feb 22, 2003 seems to have been solved by ImageMagick 6.0. We are therefore assuming that you will upgrade. See below for details.

• March 24, 2004: Fixed a couple of bugs in the install routine; all of these are fairly easily repairable “by hand” if you get errors. (Thanks to Carmen Fierro for finding these).
  • (SWP5 only): the location of the SWP-specific latex files has changed to SWPmacros (was tci), so the replacement tcilcomm files don’t get put in the right place. Fix: just extract tcilcomm.tex and tcilcomm2.tex from the distribution and copy them to SWP’s SWPmacros folder (in the TCITeX\TeX\LaTeX folder).
  • Typo in tex4ht-im2.bat: the end of the last line says %1%3 %1%3. The first %1%3 should read %1%2.
  • tex4ht-im2.bat wasn’t being copied to the tex4ht folder. Since it was left in the install directory, just copy it yourself (eg to c:\tex4ht if that’s where you put the other tex4ht files). 
• July 25, 2003: Updated and slightly simplified installation procedure, made necessary by the revised TeX4ht archive distributed by Eitan Gurari. Also, this write-up has been to some extent revised and shortened.

  With respect to the GIF problem noted on Feb. 22, I still haven’t seen any notice on the ImageMagick site that it has been fixed. In light of this you have two options: one is to switch to PNG images. On the other hand, if you know that you will be using GIF, you can obtain usable images by forcing ImageMagickk to generate GIF87 versions of the images. You can do this as follows: (note that you’ll need to undo these if you change your preferred image form):

  • Edit c:\tex4ht\tex4htx.env, and in the line calling the ImageMagick convert program, change %%3 to GIF87:%%3
  • Edit c:\tex4ht\glyphgif.bat, and in the line calling the ImageMagick convert program, change %3 to GIF87:%3
  • Edit the following basch files, all in c:\tex4ht: tex4ht-im.bat, tec4ht-im1.bat, tex4ht-im2.bat and in each of them, in the line calling the ImageMagick convert program, change %1%3 to GIF87:%1%3

  If you are already using TeX4ht, and you are saving glyph-gifs in a cache, you should check that your cached images are OK. Probably the simplest way to do this is to check new documents as they’re created, and if you find an unreadable GIF, then delete the relevant image in both the current directory and in the cache. Alternatively, you can start the cache cycle again by deleting all glyph-gifs in the cache and in folders containg converted documents, since the first thing that the cache management batch file does is copy a glyph-gif file from the current directory to the cache: just deleting it from the cache won’t work.

• February 22, 2003: It appears that the current versions of ImageMagick’s convert utility produce gifs which are not readable in (at least) the following browsers: Phoenix 0.4, Mozilla 1.2x, Netscape 4.7x; no error is reported, but the images simply don’t show up. The gifs are readable in (at least) IE 6.0 SP-1, Opera 7.01, and Amaya 7.1 (thanks to Murray Eisenberg for verifying some of these). This has been reported as a bug to ImageMagick. See the Update for July 25 for a solution.
• August 10, 2002: There appears to be an inconsistency between the AMS packages currently supported by TeX4ht and those supplied by SWP30. Of course, SWP30 is very much out-of-date: your best bet may be to upgrade. Alternatively, you might want to try upgrading just the AMS packages; but I have no idea whether this is “safe” from an SWP viewpoint. One known symptom is that the SWP previewer gags on the equation* environment when processing a file for TeX4ht, while “regular” (non-TeX4ht) compilation doesn’t have any problems. If you look carefully at the .log file produced by the TeX4ht compilation, you’ll notice a warning that the AMS package is “too old for TeX4ht”: I take this to mean that Eitan Gurari isn’t about to continue supporting very old versions of the packages (and who can blame him?).

  In an attempt to maintain consistency between the two, I’m making available a set of TeX4ht’s AMS-support files which seem to work with SWP30 — at least for HTML: they do not work for XML. You can get them here, in the file swp30t4ht-ams.zip . (These are actually a subset of the January 2002 TeX4ht files). Note that even if you upgrade TeX4ht you’ll want to keep these files, as long as you’re using SWP30. Here’s my suggestion on how to do so:

  1. Start a DOS session, cd to your SWT/TeX4ht files (typically in c:\swp30\tcitex\tex\latex\tex4ht : it’s where all the.4ht files are).
  2. Make a copy of the current AMS files, just in case: copy ams*.4ht ams*.4ht-sav
  3. Now unzip the archive, over-writing the existing files.
  4. Make the new files read-only, so that you don’t accidentally over-write them if you ever update TeX4ht: attrib +r ams*.4ht

  I have a reasonably complete backlog of TeX4ht files, so if there are still problems, let me know and I’ll see if I can solve it.

• August 1, 2002: There appears to be an incompatibility between the Belleek fonts for mathtime, and GS 7.00. If GhostScript fails to produce correct — or any — images with the “mathtime” option enabled, please upgrade Ghostscript. GS 7.03 and GS 7.04 have no problems. Remember, if you’re using the cache feature, you should also delete all potentially bad glyph-gifs, ie bl*.gif and rb*.gif and remember to do this both in the document directory and in the cache directory (default: c:\tex4ht\cache), or else you’ll never remake them.
• October 10, 2001: there is a problem with documents containing SWP graphics when used with the Babel package (or at least with the francais option of Babel). Babel redefines some characters, including, critically, the semi-colon used to delimit arguments in \FRAME; hence parsing that macro to extract the file name (in swpframe.sty) fails. Because Babel does this at the beginning of the document, you can’t rearrange the swpframe macros to overcome this. Note that this problem arises only with documents with graphics: otherwise, Babel by itself does not appear to lead to problems.

  I have two solutions:

  1. Save your document as Portable LaTeX. This solves everything, since Portable LaTeX documents don’t use the \FRAME macro at all. The only downside that I can see is that this will probably not work with Style Editor documents (which inherently need the tcilatex file).
  2. Otherwise you must arrange to have the swpht package loaded after Babel. You can do this manually in a text editor, or via the Options-and-Packages dialog of SWP. A typical minimalist entry in the latter dialog is [yes,html]{swpht}. Unfortunately, this means that you need to change the yes to no whenever you want to typeset (or prduce PDF) without TeX4ht. You may find it marginally easier to add the swpht package with the RequirePackage loading instruction (eg, \RequirePackage[yes,html]{swpht}, since this is easily accessible from the Typeset -> Preamble dialog.

3 Up and Running

This has turned out to be a fairly long document; but a lot of it consists of technical material which you may not need to successfully convert your SWP document to HTML using TeX4ht. Here’s the shortest path to getting a working TeX4ht system up and running:

• Install TeX4ht/SWP following the instructions in section 4.
• Test the new installation as explained in section 8.
• If something doesn’t work, look at section 19.
• The basic command-line conversion technique is explained in section 10. You may not need to know any more about the system than is explained here.
• Section 11 provides an overview of questions you may have at this point.