HEAD PREVIOUS

6  Features dependent on external programs.

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

A major difference between TTH and LaTeX2HTML is that TTH does not call the LATEX 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 LATEX are handled by multiple passes that write auxiliary files. TTH does only a single pass through the source. If you want TTH to use LATEX constructs (e.g. tableofcontents, bibliographic commands, etc.) that depend on auxiliary files, then you do need to run LATEX on the code so that these files are generated. Alternatively, the TTH switch -a causes TTH 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, TTH constructs the name of the expected auxiliary LATEX files in the usual way and looks for them in the same directory as the file. If you are using TTH as a filter, you must tell TTH, using the switch -Lfilename, the base file name of these auxiliary files (which is the name of the original file omitting the extension). If TTH cannot find the relevant auxiliary file because you didn't run LATEX 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 TTH that the document being translated is to be interpreted as a LATEX file even though it lacks the usual LATEXheader commands. This may be useful for translating single equations that (unwisely) use the \frac command.

6.2  BibTeX bibliographies

TTH supports bibliographies that are created by hand using \begin{thebibliography} etc. Such bibliographies do not require anything beyond the .aux file. TTH also supports bibliographies created using BibTEX 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 LATEX. In addition to running LATEX 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 LATEX again to get the references right. (This is, of course, no more than the standard procedure for using BibTEX with LATEX but it must be done if you want TTH to get your bibliography right). If you don't create the .bbl file, or if you create it somewhere else that TTH does not search, then naturally TTH won't find it. Since the BibTEX process is relatively tortuous, TTH offers an alternative. Using the -a switch with TTH will cause it to attempt to generate the required .bbl file automatically using BibTEX and LATEX.
There are many different styles for bibliographies and a large number of different LATEX extension packages has grown up to implement them, which TTH does not support. More recently, a significant rationalization of the situation has been achieved by the package natbib. TTH 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 TTHgold 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

TTH can make an extremely useful hyperlinked index using LATEX 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. TTH indexes LATEXdocuments by section number rather than by page; assuming, of course, that they have been prepared with index entries in the standard LATEX fashion.
When processing a LATEX file that contains the \makeindex command in its preamble, TTH 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. TTH does this independently of LATEX, but not of the subsidiary program makeindex that is normally used with LATEX to produce the final index. TTH 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, TTH 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 TTH reads that file in as its index. If, instead of creating an index file during TTH processing, one wants to use with TTH an index file already created, all that is needed is to remove the \makeindex command from the top of the LATEX 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 TTH 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 TTH 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 TTH or LATEX, except by hand.
All of the index file processing naturally requires that TTH have write permission for the directory in which the original LATEX 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. TTH 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.

LATEX has a parallel set of commands for glossary construction, replacing "index" with "glossary". However, there is no \printglossary command and the .glo file that LATEX produces cannot be handled by the makeindex program without a specific style file being defined. Therefore glossary entries are highly specialized and rarely used. TTH 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 TTH handle the glossary entries for a file that has only a \makeglossary command.

6.4  Graphics Inclusion: epsfbox/includegraphics

The standard way in plain TEX to include a graphic is using the epsf macros. The work is done by \epsfbox{file.[e]ps} which TTH can parse. By default TTH produces a simple link to such a postscript file, or indeed any format file.
Optionally TTH 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 png4 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, TTH 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 5 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, TTH 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 LATEX2e 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, TTH supports postscript, encapsulated postscript, gif, and jpeg, plus any future formats that become supported by common browsers. However, LATEX 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 LATEX interrogating the file.

6.5  Picture Environments

The picture environment cannot be translated to HTML. Pictures using the built-in LATEX commands must be converted to a graphics file such as a gif, and then included using \includegraphics, see 6.4. The switch -a, causes TTH to attempt automatic picture conversion using a user-supplied routine latex2gif. When this switch is used, TTH 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 LATEX, 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 LATEX file, because the macros will then be undefined in the picture file that is extracted, and LATEX will be stumped. In that case, manual intervention is necessary.

HEAD NEXT