TtH: a ``TeX to HTML'' translator.

TtH icon
Version 2.0


TTH translates TeX source that uses the Plain macro package, or LaTeX, into a near equivalent in HTML. It is extremely fast and completely portable. It produces web documents that are more compact and managable, and faster-viewing, than those from other converters, because it really translates the equations, instead of converting them into images.


1  Capabilities
    1.1  Plain TeX
        1.1.1  Mathematics
        1.1.2  Formatting and Macro Support
    1.2  LATEX
        1.2.1  Environments:
        1.2.2  LATEX Commands:
    1.3  Special TeX usage for TtH
    1.4  Unsupported Commands
2  Installation
3  Usage
4  Messages
5  More Specific Details
    5.1  Equations
    5.2  Independence of [La]TeX installation and the -L switch.
    5.3  Indexing
    5.4  Graphics Inclusion: epsfbox/includegraphics
    5.5  Picture Environments
    5.6  Various TtH limitations
    5.7  Delimited-parameter macros and Conditionals
    5.8  Tabular Environment for Tables
6  Command Handling Limitations
    6.1  Macro- and Style-file inclusion
    6.2  Layout to include arguments of unknown commands
    6.3  Restrictions on redefinition of internal commands
    6.4  Alternate macro inclusion when translating
7  Browser Problems
    7.1  MacIntosh browser font problems
    7.2  Netscape Composer
    7.3  X font problems
    7.4  Internet Expl*der
    7.5  Printing
    7.6  Other Browser Bugs
    7.7  Formal HTML validation
8  Code Critique
9  License
10  Acknowledgements
A  Appendix: Non-Standard TeX Macros
B  Appendix: Frequently Asked Questions

1  Capabilities

1.1  Plain TeX

1.1.1  Mathematics

Almost all of TeX's mathematics is supported with the exception of a few obscure symbols that are absent from the fonts normally available to browsers. Support includes, for example, in-line equations with subscripts and superscripts, display equations with built-up fractions, over accents, large delimiters, operators with limits; matrix, pmatrix, cases, [but not bordermatrix]; over/underbrace [but using a rule, not a brace].

1.1.2  Formatting and Macro Support

1.2  LATEX

LaTeX support includes essentially all mathematics plus the following

1.2.1  Environments:

em, verbatim, center, flushright, verse, quotation, quote, itemize, enumerate, description, list [treated as if description], figure, table, tabular[*,x], equation, displaymath, eqnarray, math, array [not in-line, alignment argument ignored], thebibliography, [raw]html, index [as description].

1.2.2  LATEX Commands:

[re]newcommand, newenvironment, chapter, section, subsection, subsubsection, caption, label, ref, pageref [no number], emph, textit, texttt, textbf, centering, raggedleft, includegraphics, [e]psfig, title, author, date [maketitle ignored: title etc inserted when defined], lefteqn, frac, tableofcontents, input, include [as input], textcolor, color [8 standard colors], footnote [ignoring optional arg], cite, bibitem, bibliography, tiny ... normalsize ... Huge, newcounter, setcounter, addtocounter, value [inside set or addto counter], arabic, the, stepcounter, newline, verb[*], bfseries, itshape, ttfamily, textsc, ensuremath, listoftables, listoffigures, newtheorem [no optional arguments permitted], today, printindex, boldmath, unboldmath, newfont, thanks, makeindex, index, @addtoreset, verbatiminput, paragraph, subparagraph.

These cover most of the vital LaTeX constructs. Internal hypertext cross-references are automatically generated (e.g. by ref and tableofcontents) provided LaTeX has previously been run on the document and the appropriate command-line switch is used.

1.3  Special TeX usage for TtH

A few non-standard TeX commands are supported as follows 2. See also 5.4.
\epsfbox{file.[e]ps} Puts in an anchor called "Figure" linked to 
    file.[e]ps (default), or alternatively calls user-supplied script 
    to convert the [e]ps file to a gif image and optionally inline it.  
\special{html:"tags"} inserts ``tags'' into the HTML e.g. for images etc.  
\href{reference}{anchor} highlights ``anchor'' with href=``reference''.
\begin{[raw]html} ... \end{[raw]html} environment passed direct to output.
\tthdump{...} The group is omitted by TtH. Define \tthdump as a nop for TeX.
%%tth:... The rest of the comment line is passed to TtH (not TeX) for parsing.

1.4  Unsupported Commands

When TtH encounters TeX constructs that it cannot handle either because there is no HTML equivalent, or because it is not clever enough, it tries to remove the mess they would otherwise cause in the HTML code, generally giving a warning of the action if it is not sure what it is doing. The following are examples of constructs not translated.

 \magnification \magstep etc : Removes the whole construct.
 Any dimension and glue commands: removed.
 Boxes: usually ignored (but this can sometimes cause problems).

2  Installation

The source for TtH is flex code which is processed to produce a C program tth.c which comprises the distribution. This file is compiled by

	gcc -o tth tth.c
or whatever C compiler you are using. Compilation takes a couple of minutes on a fast 486. Alternatively, you may be able to obtain a precompiled executable from wherever you accessed this file.

The executable should then be copied to whatever directory you want (preferably on your path of course). That's all!

3  Usage

Command line (switches can appear anywhere on the line):

 tth [switches -c -d ... ] <file.tex [>file.html] [2>err]

   -a automatic picture environment conversion using latex2gif (default omit). 
   -c prefix header "Content-type: text/HTML" (for direct web serving).
   -d disable delimited definitions.
   -e? epsfbox handling: -e1 convert figure to gif using user-supplied ps2gif.
       -e2 convert and include inline. -e0 (default) no conversion, just ref. 
   -f? sets the depth of grouping to which fractions are constructed built-up
    f5 (default) allows five levels built-up, f0 none, f9 lots. 
   -g don't guess an HTML equivalent for font definitions, just remove.
   -h print help. -? print usage.
   -i use italic as default math font.
   -Lfile  tells tth the base file (no extension) for LaTeX auxiliary input, 
      enables LaTeX commands (e.g. \frac) without a \documentclass line.
   -n number eqnarray environments just once (default number each line).
   -pdirectory  designate an additional directory to search for input files.
   -r output raw HTML (no preamble or postlude) for inclusion in other HTML.
   -t display built-up items in textstyle equations (default in-line).
   -w don't attempt HTML title construction or warn on failure. Default warn.
   -xmakeindx  specify a non-standard makeindex command line.
   -v give verbose commentary. 
The program is a filter, i.e. it reads from stdin and writes to stdout. In addition, diagnostic messages concerning its detection of unknown or untranslated constructs are sent to stderr.

TtH is extremely fast in default mode on any reasonable hardware. Conversion of even large TeX files should be a matter of a second or two. This makes it possible to use TtH in a CGI script to output HTML directly from TeX source if desired; (stderr may then need to be redirected.)

4  Messages

Messages about TTH's state and its assessment of the TEX it is translating are output always to the stderr stream, which normally displays on the console, but under Un*x type systems can be redirected to a file if necessary. Normally these messages are one of three types:

Error Messages

These start **** Error: and indicate some improper condition or error either in TTH or in the TEX of the file being translated. Some errors are fatal and cause TTH to stop. On others it will continue, but the TEX file probably should be corrected in order to get correct output.


These start **** but without reporting Error. They are messages by which TTH indicates aspects of the translation process that may not be fully satisfactory, usually because of known limitations, but which quite likely will not prevent the translated file from displaying correctly, and so do not necessarily require intervention. Examples include the use of dimensions, glue, or similar TEX commands that have no HTML equivalent.

Informational and external

Lines with no **** are either informational, meaning the state of the translation is not considered abnormal, or else they may come from external programs (e.g. makeindex), over which TTH has no control.

The switch -v causes more verbose messages to be output, which may be helpful for understanding why errors are reported. A higher level of verbosity -V can be invoked, but is intended primarily for internal debugging of TTH and will rarely be comprehensible!

The presumption that lies behind TTH message design is that the file being translated has been debugged using TEX or LATEX to remove syntax errors. TTH is not good at understanding or reporting TEX syntax errors and does not keep an exact count of line numbers (especially when \input is used). Therefore error reporting by TTH does not reach even the low standard of clarity set by TEX and LATEX error messages. Although TEX files can be debugged using TTH alone, since it is very fast, the process is not recommended for inexpert TEX users. Moreover, since TTH understands both TEX and LATEX simultaneously, it can parse some files that TEX or LATEX separately cannot.

5  More Specific Details

5.1  Equations

Equations are translated internally into HTML3.2 as much as it allows. TtH uses HTML3.2 tables for layout of built-up fractions in display equations. It also uses the extension HTML tag < font face=``symbol'' > , supported by Netscape and other major browsers (and part of the HTML4.0 specification) to render Greek and large delimiters etc. Untranslatable TeX math tokens are inserted verbatim.

The internal approach to equation translation is a major area where TtH departs from the philosophy of Latex2html and its derivatives. TtH does not use any images to try to represent hard-to-translate constructs like equations. Instead it uses the native ability of HTML to the fullest in providing a semantically correct rendering of the equation. The aesthetic qualities obtained are in practice no worse on average than Latex2html's inlined images, which are generally slightly misaligned and of uncertain scaling relative to the text. Some limitations in the HTML code are inevitable, of course, but one ends up with a compact representation that can be rendered directly by the browser without the visitor having to download any additional helper code (e.g. Java equation renderer).

TtH offers an option [-i] which makes italic the default font within equations, and thus the style more TeX-like. The italic font appearance in browsers is not as satisfactory as TeX's math italic, so for many documents roman looks better.

Spacing in equations is handled slightly differently by TtH than by TeX. The reason is that most browsers use fonts that will crowd the characters horizontally too close for comfort in many cases (for example: M||/2). Also, built-up HTML equations are more spread out vertically than in TeX. Therefore TtH equations look better if spaces are added between some characters. So TtH does not remove spaces in the original TeX file between characters in equations. The author is thus able to control this detail of layout in the HTML without messing up their TeX file - since TeX will ignore any spaces inserted. Legacy TeX code that contains a lot of spurious whitespace (ignored by TeX) may, as a result, occasionally become too spread-out when translated.

5.2  In-line Equation Limitations

Some TeX capabilities are extremely difficult or impossible to translate into HTML, because of browser limitations, and are best avoided if possible. Arrays or matrices in in-line equations cannot be properly supported because tables cannot be placed in-line in HTML. TtH output will be strangely disjointed. Likewise built-up fractions, most over- and under-accents, and indeed anything that requires specific placement on the page other than simple subscript or superscript and underline, cannot be rendered in-line in HTML, although TtH will render them well in displaystyle. These latter constructs are nevertheless commonly used in in-line TeX. TtH adopts the default policy of indicating in an unambiguous and relatively intuitive way what construct is being used (as opposed to simply omitting it). For example $\hat{a}$ is rendered [^a]. The result is rarely elegant. Therefore in authoring TeX that is known to be destined for HTML translation, one should bear in mind these limitations, and use an appropriate style.

As an option, TtH provides switch -t to convert inline equations that use built-up constructs into a sort of half display, half in-line equation. Each time a new in-line equation is encountered [$ ... $ or \( ... \)] that needs to be built up, an HTML table that starts a new line is begun, and the text then flows on afterwards. For example
2 + n

This option gives a slightly disjointed layout for simple equations but is a big improvement for some situations, e.g. in-line matrices.

5.3  Independence of [La]TeX installation and the -L switch.

Another major difference between TtH and LaTeX2HTML is that TtH does not call the latex or tex programs at all, 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. You must also 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 LaTeX header commands. This may be useful for translating single equations that (unwisely) use the \frac command.

If you routinely use LaTeX in a way that requires auxiliary files and grow tired of always having to specify the -L switch to TtH, a simple ``l2h'' script may be useful. For example under Linux (Un*x) a script such as

tth <$1.tex >$1.html -L$1 
or the equivalent batch file under DOS/Wind*ws, may save some typing.

5.4  Indexing

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 LaTeX documents 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 ``file.ind''. TtH creates its index entries in a file with extension .tid (Tth InDex). Because of makeindex program limitations, TtH currently removes all the page-number formatting that is present in the index entry (but not the reference formatting). It also uses the section reference style ``1-2'', separated by a dash, because this is the standard form that makeindex expects and it is cumbersome to change it. The actual reference is less important to the reader than the fact that TtH inserts a link to the actual place in the document indexed. When the \printindex command is encountered, TtH closes this file and runs makeindex on it, which creates by default a file with extension .ind, and then TtH reads the .ind file in as its index. Because the .ind file that TtH produces may well be incompatible with running LaTeX itself on the file, TtH deletes the .ind file that it creates (and hence one is left without such a file at the end). 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. Any existing .ind file will still be input by \printindex but no indexing files will be written or deleted.

If you run TtH on a file that contains both a \makeindex command and a \printindex it will overwrite your file.ind. In the unusual situation where your index, file.ind, was created laboriously by hand and cannot be recreated, you should be very careful to remove the \makeindex command from the .tex file. For safety, of course, also save a copy of your file.ind somewhere else.

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 via e.g.  -x"makeindex -s 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.

5.5  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 more appropriate graphics format, possibly using a user-supplied (script or) program called ps2gif to convert the postscript file to a gif file, ``file.gif''. When the switch -e1 or -e2 is specified, if ``file.gif'' or ``file.jpg'' already exists in the same directory as implied by the reference to ``'' then no translation is done and the file found is used instead. That gif (or jpg) is then automatically either linked (-e1) or inlined (-e2) in the document. If no gif or jpg is found, ps2gif is called. A linux (un*x) ps2gif script using Ghostscript and the pbmplus utilities for this purpose is included with the distribution. A comparable batch program can be constructed to work under other operating systems or else the translation 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 ps2gif is supplied must be of the form: ps2gif inputfile.ext outputfile.ext. The program must have permission to write the outputfile (file.gif) in the directory in which the resides.

The Latex command \includegraphics{...} does exactly the same thing. Its optional arguments are ignored. \[e]psfig{file=...} is also treated the same.

If the extension of the file initially specified is 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.

5.6  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 5.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.

5.7  Delimited-parameter macros and Conditionals

Delimited parameter definitions are fully supported. Moreover, in TtH versions 2.0 on, they should be 100% compatible with TeX, even in respect of space compression around commands. However, macros in some style files are written in such a way that the recognition of the delimited parameter depends on other TeX behaviour (e.g. dimensions) that are not supported by TtH. In such cases it is all too possible for the delimited parameter not to be matched, resulting in a runaway argument situation. Thus, delimited parameter macros are especially dangerous when using TtH, or indeed any process other than TeX itself. (And they are never exactly ``safe TeX''). The recognition of these definitions can be disabled using the -d switch, in which case the definitions are simply discarded.

Conditionals such as \if, \ifnum and so on are supported, as listed above (1.1.2). In TtH they have one syntax limitation. Further `if' commands are not permitted in, or as part of a command expanded in, the tokens, characters, or numbers being tested. Thus, an example of truly perverse usage such as
\ifnum 1=\if ab 1\else 2\fi True \else False \fi
will likely break. Nested `if' constructs are permitted in the conditional text, however, so
\ifnum 1=1 True\if ab -true\else -false\fi \else False \fi
is fine. Because TtH does not internally resemble TeX, whereas the result of conditionals such as \if and \ifx may depend on internal representations, there cannot be 100% compatibility of such tests at the lowest level. Still, tests on externally defined commands ought generally to give correct results. When authoring documents in TeX one is generally well advised to avoid conditionals.

5.8  Tabular Environment or Halign for Tables

The tabular environment is the recommended way to construct tables in LaTeX. In plain TeX, although \settabs etc. is supported, the \halign{ ... } command is recommended. (The LaTeX tabbing environment is not supported by TtH because it is antithetical to the spirit of HTML document description, and because it is an extremely complicated construct. If you are lucky, TtH will not mess up your tabbing environment too much, but it makes no attempt to interpret it properly.) Considerable effort has been expended to translate the tabular environment, including interpreting the alignment argument of the environment, into as near an equivalent in HTML as reasonably achievable3. However, the limitations of HTML tables impose the following limitations on the translation.

5.8.1  Tabular

5.8.2  Halign

6  Command Handling Limitations

Although TtH supports a remarkably complete subset of LATEX, it does not support all of the complicated primitive details of TEX, partly because that would be unnecessary. For example, practically any TEX that redefines category codes (other than @ which TtH treats universally as a letter) will break because TtH knows nothing about the concept of category codes. (If you don't know much either, about this unfortunate aspect of TEX, join the vast majority of TEX users!) A related example is that TtH expects only letters or @ in user-defined command names, not punctuation characters etc.

6.1  Macro- and Style-file inclusion

Although macro definitions are supported by TtH, if they contain dimensions or other unsupported constructs, it is often better to leave the definitions in a file on the texinputs path. The file will then not be found by TtH. That provides a mechanism to include the definitions when ``TeX''ing the file, but not when ``TtH''ing it. If the definition is required in TtH, the full path should be specified relative to the directory from which TtH is run, e.g.
\input /home/myhome/mytexdir/mymacro.tex.

6.2  Layout to include arguments of unknown commands

Unrecognized or undefined commands of the form \dothis{one}{two}{three}, are treated by discarding all the following adjacent brace groups. A space between the close and open braces will terminate the discarded arguments and cause the following brace group(s) to be scanned as if just the text. This makes it possible to use formatting to make TeX code come out right in both TeX and HTML. For example if TtH encounters a command written ``\boxthis{width} {boxed material}'' which might be designed in TeX to provide a width to a defined command, written with a space after the first argument, it will ignore the width and scan the boxed material into the text.

6.3  Restrictions on redefinition of internal commands

In TtH (unlike TeX) most internal commands can not normally be redefined; any redefinition will simply be ignored (except inside edef and a few other places). This prevents TtH from safely allowing use of major packages that redefine standard TeX commands. For example amsTeX redefines footnote to have just one argument, which will cause problems. This particular example is potentially a problem with LaTeX too, which also redefines footnote. TtH handles this by keeping track of whether the file is LaTeX or TeX; therefore you should not mix the two dialects in a single file even though there is no need to tell TtH explicitly which type the file is. (Besides, a mixed file will play havoc with TeX itself.)

6.4  Alternate macro inclusion when translating

Sometimes TEX files use special macro packages designed for a specific layout of journal or conference. If such a macro package in its original form uses dimensions or other unsupported constructs, it may be inadvisable to use it. (For example, amsppt.sty which is full of unsupported constructs will certainly cause errors with TtH.) A different, simpler, version of the macro package, designed with the capabilities of TtH in mind, may readily be substituted when using TtH for translation. One way to do this is to leave the original macro or style file on the texinputs path so it is not accessed by TtH, but to prefix the alternative package for TtH. This can be done without alteration of the original TEX files by using, for example, the following command line:

cat alternate.macros file.tex | tth >output.html
Alternatively a line can be added to the top of the TeX file of the form
%%tth:\input /full/path/to/alternate.macros
which will be ignored by TeX.

Since it is impossible to anticipate all style file incompatibilities, it must be the responsibility of the user (or the journal) to decide how to translate the concepts implemented in the original complicated macro package into simpler, TtH-compatible, TEX macros.

7  Browser Problems

7.1  MacIntosh browser font problems

The characters with codes higher than 127 in the Mac fonts are in a different order from the standard ISO-8859-1 (sometimes called ISO Latin-1). If Netscape or IE on Macs have their document encoding set to the standard, then in versions 3 onwards they are programmed to access the glyph where they think the corresponding accented Latin character will be in the Mac font. This is fine if one really wants an accented Latin character. However, for mathematics, using the symbol font (which is ordered the SAME on the Mac as on other platforms) the result is that one gets the wrong symbol glyph. This is a particular problem with large delimiters. The fix is that the Mac browser must be set to use the Options/Document-encoding ``MacRoman". This tells the browser not to do the permutation to access the accented Latin characters in the Mac places; hence, for eight-bit characters, it accesses the symbol font correctly. This would break the Latin accented characters except for the fact that (most current versions of) the browsers still access characters in the Mac order if they are specified numerically using the HTML syntax ``&#???;". So TtH documents will in most cases display both accented characters and symbols correctly on Macs if the document-encoding is set to MacRoman.

In addition, NS4.0 has under Edit Preferences Fonts a choice between ``use document fonts'' and ``use my fonts overriding document''. You need to set ``use document fonts''. This necessity is obvious if you think about it. You can make any document into garbage by specifying your own font (e.g. Greek or Cyrilic) that happens not to be what the document is written in. The same is true for the symbols of mathematics. The reader must permit the document to specify the font. Browsers should always set ``use document fonts'' as the default.

In summary, you might want to tell people viewing your documents to set their browsers to View Encoding MacRoman, and Edit Preferences Fonts Use-document-fonts (NS 4.0).

7.2  Netscape Composer

Netscape Composer (in Netscape Communicator 4.0 on) is too clever for its own good. If you run an HTML document produced by TtH through Netscape Composer, all sorts of internal translations are performed that are detrimental to its eventual display. For example, if you subsequently save the document with the usual encoding set (Western), the eightbit codes that work with Macs are replaced with HTML4.0 entities such as [&]ograve; or [&]pound;. This effectively breaks the document for viewing on Macs because it undoes everything just explained. Even if you use User-Defined encoding, which prevents this particular substitution, Composer will rearrange the document in various ways that it thinks are better, but that make the display of the document worse. The moral is, don't run TtH documents through Netscape Composer. You therefore cannot use the ``publish'' facility of Composer. Transfering the document to the server with plain old ftp will keep it away from Composer's clutches.

7.3  X font problems

Symbol fonts are not normally enabled for Netscape running under X, because of the way Netscape groups its fonts. A fix for this is to install some aliases in the fonts directories or else to add a line to your .Xdefaults file. See You might want to put these notes on your site for people viewing your documents.

A font rendering problem exists for small size single-symbol overbar in the Xfree86 server. The overbar symbol may or may not appear, depending on the direction in which its window uncovered. (Yes, this is a really bizarre bug but can be demonstrated with the xfd program.) It is strictly not a Netscape bug but an X-server, or perhaps font, bug. This symbol is used by TtH only as a fall-back for \bar in situations like in-line equations where it can't render the construct using tables.

7.4  Internet Expl*der

IE 4.0 is reported to render nested sub- and superscripts wrong under Wind*ws 95/8 so that for example the HTML x<sup>n<sub>i</sub></sup> is rendered as if it were x<sup>n</sup><sub>i</sub>. Here is the first form: xni to test your browser. Tests on Win 3.1 with IE 3.01 show no such problem. Obviously, if present, this is a fairly serious bug for mathematics that ought to be fixed by the browser programmers. [Let me know if you can confirm or deny this bug. Also let MS*ft know if you confirm it, so that plenty of people are complaining and they might fix it.]

7.5  Printing

In Netscape 3.0 and 4.0 under X, for example, the printing fonts are hard coded into the browser and the font-changing commands are ignored when printing. For that reason, visitors viewing TtH documents will often not be able to print readable versions of documents with lots of mathematics. This problem could, and should, be fixed in the browsers. However, if you want your readers to be able to print a high-quality paper copy of the file, then you probably want to make available to them either the TeX source or a common page-description format such as Postscript or PDF. Since HTML documents download and display so much faster and better than these other formats on the screen, TtH's translation provides the natural medium for people to browse, but not necessarily the best medium for paper production.

7.6  Other Browser Bugs

Under Wind*ws, both Netscape (3.0) and Internet Expl*rer (3.02) incorrectly size or space vertically the symbol glyphs so that small gaps appear between the parts of large symbols and delimiters. This occurs only at certain font sizes (different between the two browsers!) but causes a slightly annoying degradation of the appearance.

Both Netscape and IE fail (although somewhat differently) to carry font changing commands from cell to cell of HTML3.2 tables. In rendering equations (using tables) TtH circumvents this bug at the cost of significant extra effort and slightly verbose HTML. However, for tables generated by \halign or \begin{tabular} TtH takes no special steps to avoid this bug. Therefore you cannot, for example, increase the font size of an entire table by enclosing it in {\large ... } and indeed the table will revert to the default size even if it is inside a different sized section of text. Moreover, a change of font face in a cell, for example by \it will not carry over to the next cell. A document containing this problem will not pass some HTML validations. It is prevented if every cell of a TeX table is enclosed in braces and the required style applied separately to every cell - a serious annoyance.

IE can become confused about its vertical alignment in tables, with the result that symbols float above or below the horizontal line in built-up equations. This sometimes fixes itself if you simply refresh the page!

7.7  Formal HTML validation

TtH takes as its standard HTML that can be rendered by Netscape and IE browsers versions 3 and higher (with the caveats above). Documents without mathematical symbols, translated by TtH, conform to the HTML3.2 standard. Since the font tag needed for symbols is not part of the HTML3.2 standard, any such symbols compromise that formal standard. Therefore the formal standard that TtH-translated documents follow is strictly HTML4.0 Transitional. However, TtH does not formally validate its documents, and can be made to violate the standard by some TeX usage.

One reason for violation arises because HTML4.0 requires a <title>...</title> for every document. A title is constructed from LaTeX files that contain the \title{...} command, in which case HTML conformance is ensured by putting the \title command before any text (i.e. in the preamble, where it belongs). If the \title command is not desired in the TeX file, for example because it is a plain TeX document, a title can be provided by the author for the HTML document by putting a line like this at the top of the TeX file.

%%tth:\begin{html}<title>Put the title here</title>\end{html}
This line will be ignored by TeX. If no title indication of any of the above types is present, TtH attempts to construct a title from the first few plain words in the document, in much the way that the first line can become the title of a hymn.

In the case where the title construction fails, or if some other TeX usage causes a violation of the formal standard, browsers will still render the output correctly if this manual is followed.

8  Code Critique

Known limitations are significant but mostly covered above. I would be interested to hear about bugs but only if reports are accompanied by the brief section of TeX code that causes the problem. Ungraceful failures to parse straightforward TeX code are of most interest. Aesthetic critiques (with TeX code) will be considered for future improvements. Failures on complicated macros are to be expected. It is now very difficult to crash TtH by exceeding array bounds. I would like to hear about it if you succeed, especially if the code gives no error with TeX. I would be glad to receive LaTeX2e files (emailed to that illustrate LaTeX bugs. But please don't send LaTeX2.09 files or files that do not conform to the latest (1994) LaTeX users' guide. And please check in the FAQ (B) first.

The code has been compiled and run on Linux 2.0, MSDOS, Open VMS and sundry other operating systems. See

9  License

TtH is copyright © Ian Hutchinson, 1997-8 (

You may freely use this software for non-commercial purposes. It may not be used for commercial purposes without an additional license. If you distribute any copies, you must include this file and these conditions must apply to the recipient. No warranty of fitness for any purpose whatever is given, intended, or implied. You use this software entirely at your own risk. If you choose to use TtH, by your actions you acknowledge that any direct or consequential damage whatever is your responsibility, not mine.

10  Acknowledgements

Many thanks for useful discussions and input to Robert Curtis, Ken Yap, Paul Gomme, Michael Sanders, Michael Patra, Bryan Anderson, Wolfram Gloger, Ray Mines, John Murdie, David Johnson, Jonathan Barron, Michael Hirsch, Jon Nimmo, Alan Flavell, Ron Kumon, Magne Rudshaug, and for bug reports from others too numerous to mention.

A  Appendix: Non-Standard TeX Macros

The following macro definitions, although not needed for TtH, will enable a TeX file that uses the non-standard TtH commands to be correctly parsed by Plain TeX.

\def\title#1{\bgroup\leftskip 0 pt plus1fill \rightskip 0 pt plus1fill
\pretolerance=100000 \lefthyphenmin=20 \righthyphenmin=20
\par\egroup}% Centers a possibly multi-line title.
\let\author=\title % Actually smaller font than title in LaTeX.
\input epsf     % PD package defines \epsfbox for figure inclusion
\def\href#1#2{\special{html:<a href="#1">}{#2}\special{html:</a>}}
  % Macro for http reference inclusion, per hypertex.
\def\tthdump#1{#1} % Do nothing. 

B  Appendix: Frequently Asked Questions

Why won't TtH run under DOS? Something about DPMI.
It will, but the distributed DOS executable needs DPMI memory extension support to run. Plain old DOS doesn't have that unless you specifically load it. All Wind*ws versions from 3.1 on support it at the DOS prompt.

Why won't TtH run from Program Manager in Wind*ws?
You need a command line. Call up the DOS prompt.

TtH does not recognize tableofcontents, backward references, listoffigures, ...
Yes it does, see section 5.2, and use the -L switch.

TtH does not insert my picture environments.
If picture environment pictures are to be included, conversion to a gif file is needed. See 5.5.

TtH messes up my tabbing environment.
Tabbing is not currently supported. It is alien to the HTML document mark-up approach. See section 5.8.

How do I make TtH border my tabular table?
TtH looks in the format string argument of the begin{tabular} environment and if it begins with a | (vertical bar) then the HTML table is bordered.

TtH inserts the title and author even without the maketitle command
True, TtH inserts them when you define them. This gives you a chance to fine-tune the presentation if you wish.

Why doesn't \frac work in equations?
It does, but only in LaTeX documents because \frac is not a plain TeX command. The document you are presenting to TtH doubtless has no \documentclass command and other LaTeX blurb at the top. If you insist on having LaTeX commands available in such a document, you can use the -L switch. But note that other changes in interpretation (e.g. in footnotes) are implied by using this switch to tell TtH that this is a LaTeX file.

What is this strange result using \dot \hat \tilde \frac \vec ... in in-line equations?
Neither over and under accents nor built-up constructs such as fractions can be rendered in-line (i.e. in a textstyle equation produced by $ ... $) in HTML. Therefore, TtH outputs something that is not elegant but reasonably indicates the original intention. Additional brackets are inserted to ensure that fractions are unambiguous. TtH will render all these built-up constructs correctly in a display equation. See also 5.6 for an option.

Why does the large square root sign look so ugly?
There are some things that browser symbol fonts can't do well.

Why does a dagger sign come out strange?
Browsers don't generally have a dagger sign in their fonts. TtH uses a kludge.

How do I insert code that is used only by TtH, not TeX?
Use %%tth: followed by the material you wish to pass to TtH. TeX omits this line as a comment. Alternatively, insert \newif\iftth at the top of your document, then use a conditional: \iftth TtH material \fi. TtH recognizes \iftth as a special `if' that is always true, whereas to TeX it is simply a new `if', which by default is false when defined.

How do I insert HTML tags into my file without TeX knowing?
Use %%tth: then on this line put \begin{html} tags \end{html}. Do not try to continue this html onto a second line with a second %%tth: before the \end{HTML} because the html environment will output the %%tth:, which it probably not what you want. Another way to pass codes directly to the output is the \special{html: ... } command. Do not use \begin{verbatim} to pass HTML tags. It will convert the greater than and less than signs to make them appear in the display and not be interpreted as tags.

How do I insert code that is used only by TeX, not TtH?
Insert the definition \def\tthdump#1{#1} at the top of the file and then use \tthdump{TeX material} to pass stuff only to TeX. Thus, for example, the following will output alternate versions from TeX and TtH.

%%tth:\begin{html}<H1>The HTML Header</H1>\end{html}
\tthdump{\beginsection{The TeX Header}\par}
Alternatively, use (after \newif\iftth) the conditional construction.
\iftth \beginsection{The TtH Header}\par \else \beginsection{The TeX Header}\fi
The `else' clause may also be used with a blank first clause, of course: \iftth\else ... \fi.

How do I include the style file ...sty for the TeX paper I prepared for... journal?
If you are wise, you probably don't. TtH often can't handle complicated journal formats for [La]TeX without modification, because they frequently use dimensions, boxes, category code modification or other unsupported constructs. Instead, look at your TeX file, or the TtH messages telling you which commands are unknown. Decide which of the journal's specific commands or environments you used or need. Write a little style file that defines them to do something simple and sensible, or translates them into standard LaTeX commands. Or ask the journal to provide such a style file! If you are a journal publisher, distribute your simplified style file to your authors.

Why does TtH not recognize my ends of lines properly?
If you transfer a file from one operating system to another as a binary file, the line-end codes are likely to be messed up. They use different codes on Un*x, DOS, and Mac. Usually TeX is not bothered by this. TtH is somewhat more sensitive. Use ASCII transfer.

TtH does not recognize evironment ... even though it claims to.
Probably you left a spurious space, e.g. \begin {enumerate} between the \begin and the following brace. TtH won't generally accept that, even though LaTeX does. It is bad style.

Why does not TtH recognize the longtable environment?
It is not part of the standard LaTeX2e.

The file I ``published'' using Netscape Composer looks messed up when viewed on a Mac.
Don't use Composer on TtH documents. See section 7.2.

In bordered tables I want an empty cell to look empty. How do I make TtH do that?
HTML tables by default ``fill in'' an empty cell, so that it gives the visual impression of being absent. This is sometimes useful, so TtH does not prevent it. If you want it to look like an empty cell, put a non-break space in it by &~& in the TeX.

Why does TtH mess up my \fbox, minipage, etc?
The whole concept of a ``box'' is inappropriate for HTML. TtH tries to take reasonable action on encountering one. But in some cases, especially in equations, it can't cope.

Why does TtH complain about my skip, space, ... command?
Dimensions are inappropriate for HTML. TtH tries to remove all dimension, space, and glue commands with the exception of bigskip, medskip and smallskip. Usually it is successful. If so, you need do nothing. In some rare cases, you might see some irrelevant left-over characters from the dimension command that have to be removed by hand.

How do I get caligraphic fonts, {\cal E}, AMS fonts, etc?
You can't because browsers don't have access to them. TtH can only support fonts that are available on the browsers that eventually visit the page. By default TtH tells the browser to render caligraphic as italic helvetica font. You may, if you wish, define \cal to be something different, such as %%tth:\def\cal{\it\color{red}}.

Why does TtH turn double-quotes into an accent instead of quotes?
In basic TeX the double quotes character " is not defined, and hence may do anything that the local installation feels like. Double quotes must be inserted by using two quote '' or back-quote `` characters. In German TeX implementations, the double-quotes character is used to give the umlaut over accent. TtH supports this German use in appropriate contexts. English speakers should adopt proper TeX quote usage.

How do I include into a macro I am defining a # sign for an HTML reference?
When you do \special{html:<a href="#reference">} TtH just puts the html tag in the output verbatim. TeX does essentially the same for its dvi file and the dvi processor later may or may not complain about not understanding it; but generally it is ignored. However if you try to define a macro like \def\localhref{\special{html:<a href="#reference">}} then TeX will complain as follows:

! Illegal parameter number in definition of \localref.
<to be read again> 
l.3 \def\localref{\special{html:<a href="#r
This problem is caused by TeX's syntax analysis of the contents of the definition. One solution is to hide the definition from TeX using %%tth:. An alternative definition that avoids this problem must also be included for TeX's benefit, for example thus:
\tthdump{\edef\localref{[a hyperreference]}}
%%tth:\def\localhref{\special{html:<a href="#reference">}}
Alternatively, use \# in place of # in the hypertex reference. TtH specifically recognizes this as a literal and does appropriate translation. For example
\def\localhref#1#2{\special{html:<a href="\##1">}#2\special{html:</a>}}
will use its first parameter as a local anchor reference, preceded by #, and its second as the text of the anchor.

How do I construct a macro to take as a single argument a URL, which may contain special TeX characters like _ ~ @ & etc, that makes TtH construct a hyperreference but TeX just enter it in the text?
Currently you can't. The problem is that if you give a URL like my_directory, and want it to appear in a TeX (i.e. DVI and printed) version of your document, you need to write: \href{my_directory}{my\_directory} Note the backslash in the second argument, which is the TeX text part of the reference, but not in the first, which is the verbatim URL part. Deciding to add a backslash to a TeX argument or take it away from a verbatim argument is beyond TtH at present, so you will always have to give both forms (if they ever need to be different, which they do if special characters are present in the URL). In short, stick to using the basic \href macro. It must, I suppose, be possible to construct a clever macro to decide to add or subtract a backslash, but I doubt if it is worth the effort. If you feel the urge to try, remember that TtH can't recognize user-defined macro names that include special symbols (e.g. an attempted redefinition of \_ ).

Index (showing section)

auxiliary files, 5-3

bugs, 8-0

CGI script, 3-0

charcodes, 6-0
     alternative files, 6-4
     handling unsupported, 1-3
     LaTeX supported, 1-2
     redefining, 6-3
     renaming, 6-3
     unknown, 6-2
     unsupported, 1-4
compile, 2-0
conditionals, see \if


     delimited, 5-7

environments, 1-2

     textstyle, see in-line equations, overaccents
Error, 4-0

flex, 2-0

     face="symbol", 5-1
fonts, 1-1
frac command
     see switch -L, B-0

gif, 5-5

graphics files, 5-5

\headline, 1-1

     3.2, 5-1
     4.0, 5-1
     insertion, 1-3
HTML tags, B-0

\if, 1-1, 5-7

iftth, B-0
in-line equations
     arrays, 5-2
     built-up display, 5-2
     fractions, 5-2
     overaccents, 5-2
\includegraphics, 5-5
indexing, 5-4
     equation style, 5-1

jpeg, 5-5


     differences, 5-1, 5-3
license, 9-0
limitations, 5-2

Mac browsers, 7-1

macro files, 6-1
     alternate, 6-4
     special use, A-0
makeindex, 5-4
mathematics, 1-1
messages, 4-0

Netscape Composer, 7-2

picture environment, 5-6

portability, 5-3
postscript, 5-5
printing, 7-5
ps2gif, 5-5
     through composer disallowed, 7-2


     forward, 5-3

spacing, 5-1

stderr, 3-0
stdin, 3-0
stdout, 3-0
     -L, B-0
     -L, 3-0, 5-3
     TtH, 3-0
symbols, 7-3

Table of Contents

     Index entry, 5-4
TeX-only code, B-0
texinputs path, 6-1
     HTML construction, 7-7
TtH-only code, B-0

unknown commands, see commands, unknown

vertical alignment, 7-6

warning, 4-0

X fonts, 7-3


1 Conditionals \if and \ifx are not 100% TeX compatible for cases where they refer to internal TeX commands because TtH internals are not identical. Catcodes are also unknown to TtH.

2 See appendix for TeX macros supporting these commands

3 The alignment argument of the math array environment is not interpreted.

File translated from TEX by TTH, version 1.98.
On 23 Jan 1999, 17:56.