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.