TtHgold Special Features

1 Installation
2 Features
    2.1 Additional Capabilities
    2.2 Windows Graphical User Interface
3 Producing output split into different files.
    3.1 Overview
    3.2 Navigation Controls at File Top and Tail
    3.3 Special Precautions when Splitting Output
        3.3.1 Floats such as figures or tables
        3.3.2 Multiple Bibliographies
4 Style-Sheet Compact Layout
5 Other Files
    5.1 Babel Language Support
    5.2 AMSL^AT_EX Support
    5.3 Natbib Support

Abstract

Use of the additional features included in T_THgold is described.

1 Installation

Unpack the distribution for Windows by the command
```
tthgoldW.exe
```
which uses the self-unzipping capability of the distributed file or use some other archive unzipper such as "winzip".
or for the C distribution
```
tar xzvf tthgoldC.tgz
```
or for Linux
```
tar xzvf tthgoldL.tar.gz
```
depending on the distribution you obtained.
For the Windows executable distribution (tthgoldW.exe) you may install simply by executing the install.bat file by the command
```
install 
```
(in your unzipped directory) or double-clicking on the install program. This will put the tth graphical user interface, tth-gui, on your desktop.
If you are using the C distribution (for systems other than Linux or DOS/Windows), then assuming your compiler is called cc, compile the code, for example by the commands:
```
cc -o tth tth.c
cc -o tthsplit tthsplit.c
```
For the C distribution, copy the executable tth or (under Windows etc) tth.exe to a directory that is on your path, e.g. /usr/local/bin. Copy to the same place the additional executable tthsplit. Your installation is complete!

2 Features

2.1 Additional Capabilities

T_THgold possesses all the capabilities of the standard T_TH. For details of these standard features, see the T_TH manual. The additional capabilities of T_THgold lie primarily in its ability to produce from L^AT_EX source a set of correctly cross-hyperlinked HTML files: one file for each section for the "article" style (or any style that does not have chapters) or one for each chapter for "book" (or other relevant) style. Splitting the output to lower levels of sectioning is not recommended or supported.

An alternate rendering of equations is available by using the -y switch. This tells T_THgold to use cascading style sheets (CSS1) to compress the height of fractions and other built-up concepts in equations. The resulting HTML has improved, more compact, vertical layout rivalling any existing mathmatics screen renderer for aesthetic quality.

2.2 Windows Graphical User Interface

The tth-gui enables translation to be done by simply dragging a TeX file and dropping it on the tth icon. When that is done, a window pops up, offering optional buttons for fine tuning the output. Hit the button "run" to do the translation, and "quit" when you are satisfied. The executable may also be run from the command line by giving the command tth [switches] filename and the graphical user interface by be run with the command tth-gui. However, the tth-gui is better at managing long file names than the command line executable under the most common Windows operating system versions.

3 Producing output split into different files.

3.1 Overview

Because the T_TH program itself always produces just one output file, the division of the output into different files takes place in two steps. First, T_TH is run on the L^AT_EX file with the switch -s (for "split"). This switch tells T_TH 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 T_TH 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 L^AT_EX file called texdocument.tex. The switch -L tells T_TH to use auxiliary files that were produced when L^AT_EX 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 is a more specific program that will unpack MIME files produced by T_TH. (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 L^AT_EX 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.

3.2 Navigation Controls at File Top and Tail

By default T_TH 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 T_TH 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.

3.3 Special Precautions when Splitting Output

3.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 L^AT_EX beyond the end of their corresponding section. This is a familiar problem with L^AT_EX. The result of this float misplacement is that T_TH 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 T_TH 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 L^AT_EX source file, in the preamble between the documentclass and the begin{document} commands, the extra command:

\input /usr/share/tth/tthprep.sty

where the path should be to wherever you unpacked or are keeping the tth distribution file tthprep.sty. Then L^AT_EX 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 L^AT_EX 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 L^AT_EX file in its original condition, but the auxiliary files in appropriate form for T_TH.

3.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.

4 Style-Sheet Compact Layout

When using the switch -y1 to produce vertically more compact fractions, no additional precautions are needed. T_THgold should perform this optimization completely transparently.

The publisher should nevertheless bear in mind that not all browsers support CSS1 style sheets. The subset of CSS1 used by T_THgold is fully supported by Netsc*pe 4+ and IE 4+. Earlier versions of Netsc*pe do not support style sheets at all. Some users switch off the style-sheet capability of their browsers to avoid difficulties with poorly designed pages using style sheets. The HTML output is designed to be rendered by such a browser exactly as it would be if the -y1 switch had not been used, which means that no loss of quality will occur.

The switch -y2 produces "inline overaccents": things like hats and tildes inside of paragraphs, based on CSS2 style sheet capability. It is impossible to do so while preserving the ability to fall back gracefully when a browser does not use CSS2 support. Therefore, while the accents may look better to you, be careful. Realize that they may not look better to someone else.

5 Other Files

The T_THgold distribution also includes some other definition files that are specifically tuned for use with T_TH. They provide support for several desirable features that in normal L^AT_EX are implemented by style files that use unsupported features, for example category codes.

5.1 Babel Language Support

Rudimentary support for different languages, normally part of the "Babel" package, is obtained by adding into the L^AT_EX preamble the line, for example

%%tth: \input /usr/share/tth/babel/swedish.bab

This redefines the titles of chapters, table of contents, index, and so on according to the Babel scheme for the language specified. This line is ignored by L^AT_EX since it is a comment.

5.2 AMSL^AT_EX Support

Some of the additional equation and array environments of AMSL^AT_EX are supported by the simplified TtH style file input via:

%%tth:\input /usr/share/tth/amslatex.sty

The layout subtleties of these environments are inappropriate for an HTML file, so they are simply translated into corresponding L^AT_EX eqnarray or array environments. In addition some of the AMS-specific commands are defined,

\text, \dfrac, \cfrac, \tfrac, \binom, \boldsymbol, \iint etc,
\overset, \underset, \intertext

but are treated similarly by simple translation.

The many additional symbols that AMSL^AT_EX makes available to TeX are, of course, not available for most browsers - they do not have the fonts. Therefore, TtH is likewise unable to support them.

5.3 Natbib Support

Natbib extended citation commands are supported through an external style file. TtH will try to input the file tthntbib.sty (abbreviated to stay within the 8.3 name limit of some file systems) if it finds a \usepackage{natbib} command in the LaTeX file. If that file is not in your current path, an error message will occur, and the Natbib support will be less extensive. Either set the environment variable TTHINPUTS to include the directory where tthntbib.sty lives, or use the -p switch. If, for some reason, the \usepackage{natbib} is not explicitly in your LaTeX file, you can add the following line in the preamble.

%%tth: \input /usr/share/tth/tthntbib.sty

Your file might already contain, or you might want also to add lines like:

%%tth: \NAT@numberstrue % or not, as the case may be.

The default is that ifNAT@numbers is false so one obtains author-date style citations and references. It is also possible to use the natbib bibpunct command to define the spacing and labeling style explicitly, for example,
%%tth: \bibpunct{\{}{\}}{:}{n}{}{}
(The %%tth is only needed if you want to hide the command from LaTeX.)

The starred and alternative versions of commands are not supported, nor are citetext or multiple bibliographies.

File translated from T_EX by T_TH, version 4.03.
On 30 May 2013, 11:28.