11 Producing output split into different files.
11.1 Overview
Because the TTH program itself always produces just one output file,
the division of the output into different files takes place in two
steps. First, TTH is run on the LATEX file with the switch
-s (for "split"). This switch tells TTH to produce output
that is in multipart MIME format. Incidentally, this format is
used for sending multipart mail messages with attachments over the
internet. For present purposes it is simply a convenient standard for
TTH to use to show how to split the output and what the names of the
final files should be. If we wanted to keep this MIME file, then for
example the command
tth -s -Ltexdocument <texdocument.tex >mimedocument.html
would produce such a file called mimedocument.html from a
LATEX file called texdocument.tex. The switch -L
tells TTH to use auxiliary files that were produced when LATEX
was previously run on it. Alternatively if you want the output file to
have the same name as the texdocument but with the extension
html, you can use just
tth -s texdocument
There are available standard tools for unpacking multipart mime files
into their individual files, notably the mpack tools available from
the "Andrew" distribution, which may be available on some
systems. However the executable tthsplit (whose source is in
the tthgold directory) is a more specific
program that will unpack MIME files produced by TTH. (tthsplit
will not handle general MIME files.) To unpack the multipart
file into its individual files requires the simple command:
tthsplit <mimedocument.html
This will inform the user of the files produced, for
example
index.html
chap1.html
chap2.html
refs.html
footnote.html
the file index.html is always the topmost file with
links to succeeding files, and cross-links from any table of contents
or list of figures, etc.
It is unnecessary to save the intermediate file. Instead, the output
of tth can be piped to tthsplit to produce the split
files directly by the command line:
tth -s -Ltexdocument <texdocument.tex | tthsplit
Since the names of the split parts of the document are predetermined,
it is strongly advisable to make a separate directory for each
different LATEX document to keep the parts of the document in. The
conversion and splitting must then be performed in that directory to
ensure the files end up there. This task is left to the user.
The Windows graphical user interface tth-gui offers an option for
the translated file to "split it here". If this button is checked,
the file will be split in the same folder as the tex file, producing
the HTML files as above.
11.2 Navigation Controls at File Top and Tail
By default TTH places navigation links labelled "PREVIOUS" and
"NEXT" at the top and tail of the split pages, and a link "HEAD"
to the first section of the file at both places. These do not use cute
little images because images have to be in separate files, which would
defeat the principle of TTH always outputing just one file. However,
authors might want their own images or indeed far more elaborate
navigation links. The links can be customized straightforwardly by
redefining two special macros that are used for the navigation
section. By default these macros are defined as
\def\tthsplittail{
\special{html:\n<hr><table width=\"100\%\"><tr><td>
<a href=\"}\tthfilenext\special{html:\">}NEXT
\special{html:</a></td><td align=\"right\">
<a href=\"index.html\">HEAD</a></td></tr></table>\n</html>}}
\def\tthsplittop{
\special{html:<table width=\"100\%\"><tr><td>
<a href=\"}\tthfilechar\special{html:\">}PREVIOUS
\special{html:</a></td><td align=\"right\">
<a href=\"index.html\">HEAD</a></td></tr></table>}}
The macro \tthsplittail is called when splitting, as soon as a
chapter or section command is detected. Then after the split is
completed and the HTML header has been inserted for the next file,
\tthsplittop is called. Note that these macros use the
builtins \tthfilenext and \tthfilechar to access the
names of the next and the previous HTML files respectively.
These splitting macros can be redefined to whatever style of
navigation the author prefers. But careful attention should be paid to
the use of raw HTML output, for example using the HTML special.
11.3 Special Precautions when Splitting Output
11.3.1 Floats such as figures or tables
If you are splitting an article-style file that has a lot of
floating bodies (i.e. figures or tables) in it, these may be moved by
LATEX beyond the end of their corresponding section. This is a
familiar problem with LATEX. The result of this float misplacement
is that TTH may become confused and generate incorrect
cross-references to these floats in the list of figures and or list of
tables, because the only way that TTH can tell the section of float
placement is by the order of lines in the auxiliary files. If this
happens, some special precautions will prevent it.
All that is required is to add to the LATEX source file, in the
preamble between the documentclass and the begin{document} commands,
the extra command:
\input /usr/local/tth/tthprep.sty
where the path should be to wherever you unpacked or are
keeping the tth distribution file tthprep.sty. Then LATEX should
be run twice on the file to create the auxiliary files that tth will
use in its translation. Because of the extra definitions in
tthprep.sty, the auxiliary files so produced can be interpreted by
tth to give correctly linked split files. If you want to produce
dvi output from your LATEX then you should remove this extra
input command. None of this is needed unless splitting by
sections (not chapters) is to be performed or floats are
problematic.
To make it easier for the user, a script is provided called
tthprep which automates the process of producing satisfactory
auxiliary files through the single command
tthprep texdocument.tex
The script will leave the LATEX file in its original condition,
but the auxiliary files in appropriate form for TTH.
11.3.2 Multiple Bibliographies
Multiple bibliographies in split files are a problem. All the
citations in the rest of the text link to a single file
refs.html because there is no way for TtHgold know the name of other
files to refer to. However, each time a bibliography is started,
when splitting, TtHgold starts a new file. TtHgold numbers reference
files after the first as refs1.html refs2.html
etc.
After splitting the output using tthsplit, the user has then to
concatenate the reference files into a single html file if the
cross-references are all to be correct. The utility program
tthrfcat will do this if run in the directory where the split
files reside. It destroys all the refsx.html files. But since those
were generated by TtHgold, they can always be generated again. Some
spurious file navigation buttons will remain in the resulting
refs.html file. They can be removed by hand if desired.
Things go much more smoothly if there is only one bibliography per TeX
document and it is at the end of the TeX file.