HEAD PREVIOUS

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.

HEAD NEXT