4 A recipe for TEX4ht conversion of TEX documents

Now we have come to the point of stating a working recipe for creating HTML versions of LATEX documents with TEX4ht. We will first summarize the needed programs and files, and then state a development procedure. The recipe should be more than adequate for most projects, but when converting huge projects such as books with hundreds of pages, one might encounter bugs in TEX4ht. If this is the case, report the bug to the author of TEX4ht and/or work around the problem.5

4.1 Step 0: Prerequisites

Besides LATEX with TEX4ht installed you will also need:

Locate the tex4ht.env configuration file and store it in a convenient place for editing as explained below. You can also use the one supplied in the file package mentioned in section 5.

Also locate your default texmf.cnf file and copy it into a convenient place, e.g. your working directory. During large projects TEX will almost certainly run out of capacity. When this happens, locate the appropriate variable in the configuration file and modify it.

4.2 Step 1: Creating the scripts

Fetch the TEX4ht configuration file tex4ht.env. Edit the lines starting with a G. They should look like this:

G./cscript.sh %%1 %%2 %%3 2

You will need the aforementioned cscript.h, of course. Either get it from [6] or copy the listing at the end of this guide. (Note that you may need to change the location of the bash binary at the beginning.)

4.3 Step 2: Preparing your LATEX source

Most of the time, TEX4ht will accept every bit of LATEX code you have written. This is because TEX4ht works on a level just between TEX and LATEX, so that every macro gets special treatment.

There is one difference, however, and it is an important one: Always place your macro definitions after the \begin{document}-command. This has subtle reasons, and I recommend that you look it up in [1] if you are curious.

It might happen that one or two of your macros won’t compile. In that case, it is a bug in TEX4ht. Either find a workaround or report the bug if it is serious, although it is unlikely.6

You might also get strange errors seemingly not related to a macro, but it probably is. Let’s say you have encountered an error at line 2651 in your document. It still might be your macro that isn’t working correctly; just pay attention to exactly where in the line the error occurs.

Now I have said a lot about errors, and you might get the impression that errors is something you’ll have to deal with a lot. This is not so, but it is good to be prepared and not to have to spend hours at errors with an easy solution.

Now for the preamble: You’ll need to invoke the TEX4ht package. Use this snippet:

\usepackage[html,png]{tex4ht}

If you want to split your document into several HTML files, add an integral parameter after png and a comma. (See the above part on parameters to TEX4ht.) For a big book project, 3 is typically a good value.

This is probably everything that is needed: One line of code in addition to moving your macros to after \begin{document}.

You may also want to set an option that forces every tiny inline equation to become a bitmap. By default TEX4ht creates HTML code for as many inline equations as possible, with varying degree of success. This option is described in [2] in detail:

\Configure{$}{\PicMath}{\EndPicMath}{}
Place the option after \begin{document}. Similar settings exist also for other math environments.

4.4 Step 3: Compiling and error checking

You are now ready to compile. You can for example run the command

ht latex basefilename
as described previously. You may also compose your own arrangement of latex, tex4ht and t4ht commands if the previous doesn’t fix all the tables et.c. (This is typical in a big project.)

Note that in csript.sh you specify the bitmap quality. Due to the long conversion times for included PostScript figures, I reccomend that you start with a quality setting of 0 until you are happy with the look of the rest of the HTML document. The quality setting will not affect the rest of the HTML generating process.

You can of course preview your HTML pages in a web browser. The base file has the same name as your document.

4.5 Step 4: The web page

After you are satisfied with the results, copy all the .html and .png files to your published web area.

Note:
When the surfer enters your directory, and if you do not have an index.html, he/she will see all the files in the directory. If you don’t want that, create an index.html to prevent this.
Note:
Also note that all the files created resides in your working directory and should be placed in the same published directory. You can specify options to place the .html-files in a special place, but you must modify csript.sh yourself to place the images there as well.