NAME
tth, latex2gif, ps2gif, ps2png - TeX and LaTeX to HTML translator and
its auxiliary program
SYNOPSIS
tth [options] [<file.tex] [>file.html] [2>err]
tth [options] file.tex [2>err]
latex2gif file (no extension)
ps2gif file.ps file.gif [icon.gif]
ps2png file.ps file.gif [icon.gif]
DESCRIPTION
tth translates TeX source that uses the plain macro package or LaTeX,
including most mathematics, into a near equivalent in HTML. The formal
standard that TTH-translated documents follow is strictly HTML4.0
Transitional.
The complete documentation is contained in "tth_manual.html"
distributed with the program. This man page is an incomplete summary
and updated on an irregular basis. [Last updated 1 May 2002 by Hans
Fredrik Nordhaug.]
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 auxiliary
programs, ps2gif or ps2png, which in turn make 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.)
To discuss how to get the best from tth, you can subscribe to a mailing
list by sending an email containing the message subscribe
tth_mailing_list to "majordomo@hutchinson.belmont.ma.us". Then you can
send messages to "tth_mailing_list@hutchinson.belmont.ma.us".
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.
Independence of [La]TeX installation and the -L switch
A major difference between tth and latex2html is that tth does not call
the latex or tex programs at all by default, 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.
Alternatively, the tth switch -a causes tth automatically to attempt to
run latex on the file, if no auxiliary file .aux exists.
When run specifying a filename on the command line as a non-switch
argument, x tth constructs the name of the expected auxiliary LaTeX
files in the usual way and looks for them in the same directory as the
file. If you are using tth as a filter, you must 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.
BibTeX bibliographies
tth supports bibliographies that are created by hand using
\begin{thebibliography} etc. Such bibliographies do not require
anything beyond the .aux file. tth also supports bibliographies created
using BibTeX from a biblography database. The filename.bbl file is
input at the correct place in the document. However, this filename.bbl
is not created automatically by latex. In addition to running latex on
the source file to create the auxiliary file, you must also execute
bibtex filename in the same directory, to create the filename.bbl file,
and then run latex again to get the references right. (This is, of
course, no more than the standard procedure for using bibtex with latex
but it must be done if you want tth to get your bibliography right). If
you don’t create the
.bbl file, or if you create it somewhere else that tth does not
search, then naturally tth won’t find it. Since the BibTeX process is
relatively tortuous, tth offers an alternative. Using the -a switch
with tth will cause it to attempt to generate the required .bbl file
automatically using bibtex and latex.
There are many different styles for bibliographies and a large number
of different LaTeX extension packages has grown up to implement them,
which tth does not support. More recently, a significant
rationalization of the situation has been achieved by the package
natbib. tth has rudimentary support built in for its commands \citep
and citet in the default author-date form without a second optional
argument. A style file for natbib is distributed with TTHgold which
makes it possible to accommodate most of its more useful styles and
commands and easily switch from author-date citation to numeric
citation.
Indexing
tth can make an extremely useful hyperlinked index using LaTeX
automatic indexing entries. But 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.
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.
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.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 a more appropriate graphics format, by using
ps2gif or ps2png to convert the postscript file to a png or gif file,
"file.png" or file.gif" When the switch -e1 or -e2 is specified, if
‘‘file.png’’, ‘‘file.gif’’ or ‘‘file.jpg’’ already exists in the same
directory as implied by the reference to ‘‘file.ps’’ then no conversion
is done and the file found is used instead. That graphics file is then
automatically either linked (-e1) or inlined (-e2) in the document. If
no such file is found, TTH tries to find a postscript file with
extension that starts either .ps or .eps and convert it, first using
ps2png then, if unsuccessful, ps2gif. By popular request, a third
graphics option -e3 for generating icons is now available.
The LaTeX command \includegraphics{...} and the older
\[e]psfig{file=...} are treated the same as \epsfbox. Their optional
arguments are ignored.
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 or png, and then included using \includegraphics. The switch
-a, causes tth to attempt automatic picture conversion using latex2gif.
OPTIONS
-a attempt automatic conversion of picture environments. Default
omit.
-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 png/gif using user-
supplied ps2png/ps2gif. -e2 convert and include inline. -e2 as
e2 but with icon. -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 some help. -? print usage
-i use italic font for equations (like TeX). Default roman.
-j? use index page length ?. Default 20 lines. -j single column.
-Lfile tells tth the base file (no extension) for LaTeX auxiliary
input.
-n? HTML title format control. 0 raw. 1 expand macros. 2 expand
eqns.
-ppath specify additional directories (path) to search for input files.
-r output raw HTML (no preamble or postlude) for inclusion in other
HTML.
-t permit built-up items in textstyle equations. Default in-line
items only.
-u unicode character encoding. (Default iso-8859-1).
-v give verbose commentary.
-V even more verbose (for debugging).
-w? HTML writing style. Default no head/body tags. -w -w0 no title.
-w1 single title only, head/body tags. -w2 XHTML.
-xmakindxcmd
specify a non-standard makeindex command line.
-y? equation style: bit 1 compress vertically; bit 2 inline
overaccents.
SEE ALSO
The tth manual which is more likely to be up-to-date.
http://hutchinson.belmont.ma.us/tth/manual.cgi (or preferably your
local copy). In addition reading the man pages for latex, latex2html,
tex and makeindex might be useful.
Browser Problems
tth translates (La)TeX into standard HTML and takes account as far as
possible of the idiosyncrasies of the major browsers. Nevertheless,
there are several problems that are associated with the browsers.
Authors and publishers should recognize that these are not tth bugs.
Many of the most serious difficulties of Mathematics rendering in HTML
are associated with the need for extra symbols. In addition to various
Greek letters and mathematical operators, one needs access to the
glyphs used to build up from parts the large brackets matching the
height of built-up fractions. These symbols are almost universally
present on systems with graphical browsers, which all have a ‘‘Symbol’’
font, generally based on that made freely available by Adobe. The
problem lies in accessing the font because of shortcomings in the
browsers and the HTML standards that relate to font use.
For more information please read the section "Browser Problems" in the
manual.
AUTHOR
tth is copyright (c) 1997-2002 Ian Hutchinson (hutch@psfc.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.
For details see http://hutchinson.belmont.ma.us/tth/.
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.