sec6.html

6.1 Independence of [La]T_EX installation and the -L switch.

A major difference between T_TH and LaTeX2HTML is that T_TH does not call the L^AT_EX or tex programs at all by default, and is not specifically dependent upon these, or indeed any other (e.g. PERL), programs being installed on the translating system. Its portability is therefore virtually universal.

Forward references in L^AT_EX are handled by multiple passes that write auxiliary files. T_TH does only a single pass through the source. If you want T_TH to use L^AT_EX constructs (e.g. tableofcontents, bibliographic commands, etc.) that depend on auxiliary files, then you do need to run L^AT_EX on the code so that these files are generated. Alternatively, the T_TH switch -a causes T_TH automatically to attempt to run latex on the file, if no auxiliary file .aux exists.

When run specifying a filename on the command line as a non-switch argument, T_TH constructs the name of the expected auxiliary L^AT_EX files in the usual way and looks for them in the same directory as the file. If you are using T_TH as a filter, you must tell T_TH, using the switch -Lfilename, the base file name of these auxiliary files (which is the name of the original file omitting the extension). If T_TH cannot find the relevant auxiliary file because you didn't run L^AT_EX and generate the files or didn't include the switch, then it will omit the construct and warn you. Forward references via ref will not work if the .aux file is unavailable, but backward references will. The -L switch with no filename may be used to tell T_TH that the document being translated is to be interpreted as a L^AT_EX file even though it lacks the usual L^AT_EXheader commands. This may be useful for translating single equations that (unwisely) use the \frac command.

6.2 BibTeX bibliographies

T_TH supports bibliographies that are created by hand using \begin{thebibliography} etc. Such bibliographies do not require anything beyond the .aux file. T_TH also supports bibliographies created using BibT_EX from a biblography database. The filename.bbl file is input at the correct place in the document. However, this filename.bbl is not created automatically by L^AT_EX. In addition to running L^AT_EX on the source file to create the auxiliary file, you must also execute bibtex filename in the same directory, to create the filename.bbl file, and then run L^AT_EX again to get the references right. (This is, of course, no more than the standard procedure for using BibT_EX with L^AT_EX but it must be done if you want T_TH to get your bibliography right). If you don't create the .bbl file, or if you create it somewhere else that T_TH does not search, then naturally T_TH won't find it. Since the BibT_EX process is relatively tortuous, T_TH offers an alternative. Using the -a switch with T_TH will cause it to attempt to generate the required .bbl file automatically using BibT_EX and L^AT_EX.

There are many different styles for bibliographies and a large number of different L^AT_EX extension packages has grown up to implement them, which T_TH does not support. More recently, a significant rationalization of the situation has been achieved by the package natbib. T_TH has rudimentary support built in for its commands \citep and citet in the default author-date form without a second optional argument. A style file for natbib is distributed with T_THgold which makes it possible to accommodate most of its more useful styles and commands and easily switch from author-date citation to numeric citation.

6.3 Indexing

T_TH can make an extremely useful hyperlinked index using L^AT_EX automatic indexing entries. But indexing an HTML document is different from indexing a printed document, because a printed index refers to page numbers, which have no meaning in HTML because there are no page breaks. T_TH indexes L^AT_EXdocuments by section number rather than by page; assuming, of course, that they have been prepared with index entries in the standard L^AT_EX fashion.

When processing a L^AT_EX file that contains the \makeindex command in its preamble, T_TH will construct an appropriately cross-hyperlinked index that will be input when the command \printindex is encountered, which must be after all the index references \index{ ... } in the document. T_TH does this independently of L^AT_EX, but not of the subsidiary program makeindex that is normally used with L^AT_EX to produce the final index. T_TH creates its index entries in a file with extension .tid (Tth InDex). Unfortunately the standard form that makeindex expects for compound numbering of its sections or pages is "1-2", separated by a dash. TtH changes that to "1.2" using a point, and has to output a style file filename.mst , where filename is the base filename of the latex file being processed, to enable makeindex to handle this form. When the \printindex command is encountered, T_TH closes the .tid file and runs the command

makeindex -o filename.tin filename.tid

on it. This creates an output file filename.tin, and then T_TH reads that file in as its index. If, instead of creating an index file during T_TH processing, one wants to use with T_TH an index file already created, all that is needed is to remove the \makeindex command from the top of the L^AT_EX source and copy the existing .ind file to a .tin file that will be input by \printindex. No indexing files will be written or deleted without a \makeindex command in the document.

The \makeindex command, if present, will also cause T_TH to add a linked entry called "Index" to the end of any table of contents. This entry is a highly desirable feature for an HTML file, but if there is no \printindex command at the end of the document, the index will not exist, so the reference will be non-existent.

On some operating systems with file name length restrictions, the makeindex program is called makeindx. Therefore a T_TH switch is provided: -xcommandline, which substitutes commandline for the default call makeindex. Therefore, -xmakeindx will switch to the correct program name on one of these limited operating systems. This switch also allows additional parameters or switches to be passed to makeindex. If the -xcommandline contains any spaces, then it is interpreted as the complete command-line (not just the first word of the command-line), in which the base filename may be referenced up to 3 times as "%s". For example -x"makeindex -s style.sty -o %s.tin %s.tid" will handle the index using a different style file "style.sty". If you don't have the makeindex program, you can't create indexes with T_TH or L^AT_EX, except by hand.

All of the index file processing naturally requires that T_TH have write permission for the directory in which the original L^AT_EX file (specified by the -L switch) resides.

Layout of the index can be controlled with the switch -j with an immediately following argument that specifies the minimum number of lines in a column before the column will be terminated. Because index entries are usually short, books almost always adopt a two-column format for the index. T_TH will also do so by default, but since an HTML document has no page breaks, the question arises how long the individual columns are allowed to be. The default (no switch) is equivalent to -j20. A switch -j with no argument is equivalent to specifying a very large number of lines, with the result that only one column is used. A switch -j1 will cause the columns to break at every indexspace, that is generally at every new letter, so letter lists will alternate between columns.

6.3.1 Glossaries.

L^AT_EX has a parallel set of commands for glossary construction, replacing "index" with "glossary". However, there is no \printglossary command and the .glo file that L^AT_EX produces cannot be handled by the makeindex program without a specific style file being defined. Therefore glossary entries are highly specialized and rarely used. T_TH does not support a glossary separate from the index. Instead it simply defines the command as \def\glossary{\index} with the result that glossary entries are placed in the index. It may be necessary to add \makeindex and \printindex commands to make T_TH handle the glossary entries for a file that has only a \makeglossary command.

6.4 Graphics Inclusion: epsfbox/includegraphics

The standard way in plain T_EX to include a graphic is using the epsf macros. The work is done by \epsfbox{file.[e]ps} which T_TH can parse. By default T_TH produces a simple link to such a postscript file, or indeed any format file.

Optionally T_TH can use a more appropriate graphics format, possibly using a user-supplied (script or) program called ps2png or ps2gif to convert the postscript file to a png⁴ or gif file, "file.png" or "file.gif". ["file" is the name of the original postscript file without the extension and png or gif are interchangeable as far as matters for this description]. When the switch -e1 or -e2 is specified, if "file.png", "file.gif" or "file.jpg" already exists in the same directory as implied by the reference to "file.ps" then no conversion is done and the file found is used instead. That graphics file is then automatically either linked (-e1) or inlined (-e2) in the document. If no such file is found, T_TH tries to find a postscript file with extension that starts either .ps or .eps and convert it, first using ps2png then, if unsuccessful, ps2gif. Linux (un*x) ps2png and ps2gif scripts using Ghostscript and the netpbm utilities for this purpose are included with the distribution. A comparable batch program can be constructed to work under other operating systems ⁵ or else the conversion can be done by hand. Naturally you need these utility programs or their equivalent on your system to do the conversion. The calling command-line for whatever ps2png (or gif) is supplied must be of the form:

ps2png inputfile.ext outputfile.ext

The program must have permission to write the outputfile (file.png) in the directory in which the file.ps resides.

By popular request, a third graphics option -e3 for generating icons is now available. If no previously translated graphics file, e.g. "file.png" exists, T_TH passes to ps2gif (or png) a third argument consisting of the name, "file_icon.gif", of an icon file. ps2gif is expected to create it from the same postscript file. In other words the call becomes

ps2gif file.eps file.gif file_icon.gif

This third argument is then the file that is inlined, while the larger gif file named "file.gif" is linked such that clicking on the icon displays the full-size gif file. The icon will not be created if "file.gif" already exists, because ps2gif will not then be called.

The L^AT_EX2e command \includegraphics{...} and the older \[e]psfig{file=...} are treated the same as \epsfbox. Their optional arguments are ignored.

If the extension is omitted for the graphics file specification, then .ps or .eps is tried. If the extension of the file specified is non-null and not .ps or .eps, no conversion is done but the file is referenced or in-lined as an image. In effect, then, T_TH supports postscript, encapsulated postscript, gif, and jpeg, plus any future formats that become supported by common browsers. However, L^AT_EX does not support these other formats, so it will give an error message if it can't find a postscript file, unless you specify the bounding box, thus preventing L^AT_EX interrogating the file.

6.5 Picture Environments

The picture environment cannot be translated to HTML. Pictures using the built-in L^AT_EX commands must be converted to a graphics file such as a gif, and then included using \includegraphics, see 6.4. The switch -a, causes T_TH to attempt automatic picture conversion using a user-supplied routine latex2gif. When this switch is used, T_TH outputs the picture to a file picn.tex, where n is the number of the picture (if there does not already exist a file picn.gif). It then calls the command latex2gif picn which must be a command (e.g. a script using L^AT_EX, dvips, etc.) on the system, which converts the file picn.tex to a file picn.gif. An example linux script is included in the distribution but this conversion script is dependent on the system and so is entirely the user's responsibility. For viewing the results, the files picn.gif must be accessible to the browser in the same directory as the HTML files, then they will be included in-line. It is impossible for a picture environment to be converted in this automatic fashion if it contains macros defined somewhere else in the original L^AT_EX file, because the macros will then be undefined in the picture file that is extracted, and L^AT_EX will be stumped. In that case, manual intervention is necessary.

HEAD