ps2gif postscript-file gif-file
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 complete documentation is contained in tth_manual.html distributed with the program. This man page is an incomplete summary.
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, makeindex, index.
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.
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.
tth will construct an index based on the standard LaTeX commands "\makeindex" and "\index{...}", and automatically process it and read it in when "\printindex" is encountered. The command line for calling the makeindex program (not part of this distribution) may be changed using the -x switch. For a file without the "\makeindex" command, tth will write no index files, just read in an existing one "file.ind" if it exists.
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" or "file.jpg" 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.
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).
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.html. You might want to put these notes on your site for people viewing your documents.
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!
See the manual for TtH limitations.
The code has been compiled and run on Linux 2.0, MSDOS, and Open VMS.
tth is copyright (c) 1997-8 Ian Hutchinson (hutch@psfc.mit.edu).
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. For details see http://hutchinson.belmont.ma.us/tth/.
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.