TTH(1)

NAME
tth, ps2gif - TeX and LaTeX to HTML translator and its auxiliary program

SYNOPSIS
tth [ -c ] [ -e? ] [ -f? ] [ -g ] [ -h ] [ -i ] [ -Lfile ] [ -n ] [ -pdirectory ] [ -r ] [ -v ]

ps2gif postscript-file gif-file

DESCRIPTION

tth translates TeX source that uses the plain macro package or LaTeX, including most mathematics, into a near equivalent in HTML. The output conforms to HTML3.2 except for the use of the <font face="symbol"> tag, which is a common extension and part of the HTML4.0 draft.

The program is a filter, i.e. it reads from standard input and writes to standard output. In addition, diagnostic messages concerning its detection of unknown or untranslated constructs are sent to standard error.

In handling embedded graphical files tth can make use of an auxiliary program, ps2gif, which in turn makes use of the ghostscript interpreter gs(1) and the Portable Bitmap Graphics suite of commands, see pbm(1).

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; (standard error may then need to be redirected.)

tth handles TeX things like:
Almost all mathematics, including symbols, fractions, delimiters.
{} \begingroup\endgroup  grouping.
\it \bf \sl etc  styles.
\beginsection.
\centerline{}.
\item{...} \itemitem{...} {\obeylines  ...}.
Almost all accented latin characters written like \"o, or \"{e}.
\hang \hangindent \narrower for entire paragraphs
  (\hangafter ignored).
\headline is made into a title.
% Comments. Simply removed.
\halign tables, checks template for the presence of \vrule,
  to decide if the table is to be border style.
\settabs \+ style tables.
\input: But, of course, not from the implicit texinputs path.
\newcount, \number, \advance and counter setting.
\def, \edef, \xdef but no delimited arguments.
  All definitions are global.
\matrix, \pmatrix but not \bordermatrix. \cases.

LaTeX support includes essentially all mathematics plus the following environments:
em, verbatim, center, flushright [one paragraph only], verse, quotation, quote, itemize, enumerate, description, list [treated as if description], figure, table, tabular[*,x], equation, displaymath, eqnarray [only one equation number], math, array, thebibliography, [raw]html, index [as description].
and Latex commands:
[re]newcommand, newenvironment [optional arg not permitted], chapter, section, subsection, subsubsection, caption, label, ref, pageref [no number], emph, textit, texttt, textbf, centering, raggedleft, includegraphics, [e]psfig, title, author, date [not automatic], lefteqn, frac, tableofcontents, input, include [as input], textcolor, color [8 standard colors], footnote [ignoring optional arg], cite, bibitem, bibliography, tiny ... normalsize ... Huge, newcounter [no ``within'' support], 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.

Hypertext cross-references within the document are automatically generated by (e.g.) ref, and tableofcontents.

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. Untranslatable TeX math tokens are inserted verbatim.

Independence of [La]TeX installation

A major difference between tth and latex2html(1) is that tth does not call the latex(1) or tex(1) programs, and is not dependent upon these, or indeed any other 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) which 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 quietly omit the construct. Forward references via ref will not work if the .aux file is unavailable, but backward references will.

epsfbox/includegraphics PostScript graphics inclusion

The standard way in plain TeX to include a graphic is using the epsf macros. The work is done by \epsfbox{file.ps} which tth can parse. By default tth produces a simple link to such a postscript file. Optionally it can call a user-supplied (script or) program called ps2gif to convert the postscript file to a gif file, "file.gif" (unless "file.gif" already exists in the same directory as "file.ps" in which case it is simply referenced). The program must have permission to write the outputfile (file.gif) in the directory in which the file.ps resides. That gif is then automatically either linked or inlined in the document.
 The Latex command \includegraphics{...} does exactly the same thing. Its optional arguments are ignored. \[e]psfig{file=...} is also treated the same.

OPTIONS

-c  prefix header "Content-type: text/HTML" (for direct web serving).

-d  disable definitions with delimited arguments. Default enable.

-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 f3 (default) allows three levels built-up, f0 none, f9 lots.

-g  remove, don't guess intent of, \font commands. Default guess font/size.

-h  print some help.

-i  use italic font for equations (like TeX). Default roman.

-Lfile
    tells tth the base file (no extension) for LaTeX auxiliary input.

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

-v  give verbose commentary.

-V  even more verbose, and border equations for debugging

SEE ALSO
The tth manual http://venus.pfc.mit.edu/tth/manual.cgi (or preferably your local copy), latex(1), latex2html(1), tex(1)

BUGS

Apple Macintosh browser font problems

For reasons described in the tth manual, correct viewing of tth documents requires Mac Netscape to be set to View Encoding MacRoman, and Edit Preferences Fonts Use-document-fonts (NS 4.0).

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. See http://venus.pfc.mit.edu/tth/Xfonts.notes. You might want to put these notes on your site for people viewing your documents.

Other browser bugs

Under Windows, both Netscape (3.0) and Internet Explorer (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 visual quality.

Both Netscape and IE fail (although somewhat differently) to carry font changing commands from cell to cell of HTML3.2 tables. This means that for example boldface in equations will be lost after the first fraction or built-up construct. The tth -i switch mostly circumvents this problem but the browsers ought to fix it.

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!

tth bugs

See the manual for TtH limitations.

The code has been compiled and run on Linux 2.0, MSDOS, and Open VMS.

AUTHOR

tth is copyright (c) 1997 Ian Hutchinson (hutch@pfc.mit.edu).

LICENSE

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.

ACKNOWLEDGEMENTS

Many thanks for useful discussions and input to Robert Curtis, Ken Yap, Paul Gomme, Bruce Lipschultz, Mike Fridberg, Michael Sanders, Michael Patra, Bryan Anderson, Wolfram Gloger, Ray Mines, John Murdie, David Johnson, Jonathan Barron, Michael Hirsch, Jon Nimmo, Alan Flavell, Ron Kumon.