\documentclass[12pt]{article}
% 
%\def\href#1#2{\special{html:<a href="#1">}{#2}\special{html:</a>}}
\def\tthdump{}
\newif\iftth 
\def\TtH{$\rm{}T_TH$}
\def\TtM{$\rm{}T_TM$}% For the translated documentation.
\let\thisTeX=\TeX
\iftth\else\def\TeX{\protect\thisTeX}\fi
\def\TtHgold{\TtH{}gold}
%
\setcounter{tocdepth}{5}
\usepackage{fullpage}
\usepackage{makeidx}
\usepackage{color}
%\usepackage{url}
\usepackage{hyperref}
\makeindex

\begin{document}
\title{\TtH: a ``\TeX\ to HTML'' translator.}
\special{html:<center><img src="tth.gif" alt="TtH icon" /></center>}
\centerline{Version 4.04}
\author{}\date{}
\maketitle

\begin{abstract}
\TtH\ translates \TeX\ documents that use the Plain macro package or
\LaTeX, into HTML\ifx\TtMgold\undefined\else.
\TtH\ is based on the highly successful translator 
T$_{\rm T}$H, but translates the equations into MathML instead of HTML\fi.
 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.
\end{abstract}

\tableofcontents

\section{Capabilities}

\subsection{Plain \TeX}


\subsubsection{Mathematics\index{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].

\subsubsection{Formatting and Macro Support}

\begin{itemize}

\item\index{fonts}
\index{roman@\verb+\rm+}
Font styles: \verb|\it, \bf, \sl, \uppercase|, everywhere,
\verb|\rm| in most situations
\footnote{The problem with {\tt$\backslash$rm} in text is that HTML
has no {$\tt <rm>$} tag, and relies on cancelling all previous (e.g.)
{$\tt <i>$} or {$\tt <b>$} tags. By default (using style -y1)
\TtH\ uses Cascading Style Sheets to solve this problem. However not
all older browsers support CSS and even in those that do, the user can
turn off the CSS support. The best solution is to avoid
{\tt$\backslash$rm} by using proper grouping of non-roman text. (In
equations {\tt$\backslash$rm} is essential, but \TtH\ has a
work-around in equations.)}.

\item Accented characters written like \verb|\"o| or \verb|\'{e}|. 

\item Guess the intent of font definitions, i.e. \verb|\font| commands
[optionally, remove contruct].

\item Macro definitions that are global: \verb|\gdef|, \verb|\xdef|,
\verb|\global\def|, \verb|\global\edef|; or local to the
current group: \verb|\def|, \verb|\edef|.
 
\item Definitions with delimited arguments.

\item Input of files [see \ref{texins}].

\item Newcount, number, advance and counter setting [global counter setting
only].
\index{if@\verb+\if+}\index{conditionals|see{{$\tt\backslash$\tt{}if}}}
\label{ifs}

\item Conditionals: iftrue,
iffalse,
ifnum,
ifodd,
ifcase,
if   [for defined commands and plain characters, not some internals]
\footnote{Conditionals {$\tt\backslash$\tt{}if}
 and {$\tt\backslash$\tt{}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.}, ifx [only for
defined commands and counters; internals appear undefined], ifvmode,
ifmmode, newif.

\item Centerline, beginsection, item, itemitem, obeylines; hang, hangindent,
narrower [for entire paragraphs, hangafter ignored].
\index{headline@\verb+\headline+} Headline is made
into a title, footnote\{\}\{\}. Comments: removed.

\item Tables: halign [uses border style if the template contains
vrule.]. Settabs, \verb|\+|.

\item Simple uses of \verb!\hbox,\vbox! and \verb!\hsize! to align text and
make boxes with restricted widths, but these are discouraged. In
setting the width of a vbox, the value of hsize should be once only,
immediately at the beginning of the vbox.

\end{itemize}


\subsection{\LaTeX}
\LaTeX\ support includes essentially all mathematics plus the following 

\subsubsection{Environments:}\index{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
generally in in-line equations], thebibliography, [raw]html,
index [as description], minipage [ignoring optional argument],
longtable [but see \ref{longtab}].

\subsubsection{\LaTeX\ Commands:\index{commands!\LaTeX\ supported}}
 [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,
includeonly ignored], textcolor, color, footnote
[ignoring optional arg], cite, bibitem, bibliography, tiny
... normalsize ... Huge, newcounter, setcounter, addtocounter, value
[inside set or addto counter], arabic, the, stepcounter, newline,
verb[*] [can't use @ as separator], bfseries, itshape, ttfamily,
textsc, ensuremath, listoftables, listoffigures, newtheorem [no
optional arguments permitted], today, printindex, boldmath,
unboldmath, newfont, thanks, makeindex, index, @addtoreset,
verbatiminput, paragraph, subparagraph, url, makebox, framebox, mbox,
fbox, parbox [ignoring optional argument], definecolor, colorbox,
fcolorbox [not in equations], pagecolor [discouraged], savebox, sbox,
usebox.


 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.

\subsection{Special \TeX\ usage for \TtH}
 A few non-standard \TeX\ commands are supported as follows
\footnote{See appendix for \TeX\ macros supporting these commands}. See
also \ref{epsf}.\index{HTML!insertion}
 {\begin{verbatim}
\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''.
\url{URL} like \href but with URL providing both reference and anchor.
\begin{[raw]html} ... \end{[raw]html} environment passed direct to output.
\tthtensor Subscripts and superscripts immediately following, on simple
    characters, are stacked up in displaystyle equations, not staggered. 
\tthdump{...} The group is omitted by tth. Define \tthdump as a nop for TeX.
\tthverbatim{thename} "thename" (or whatever is the group) is taken as the
    name of a verbatim environment that must be ended by \end{thename}.
%%tth:... The rest of the comment line is passed to tth (not TeX) for parsing.
\end{verbatim} }


\subsection{Unsupported Commands\index{commands!handling unsupported}}

 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. \index{commands!unsupported}The following are
not translated.

%\verb is not allowed inside an argument in \LaTeX\ (it is in tth).
{\begin{verbatim}
 \magnification \magstep etc : Removes the whole construct.
 Some boxes in equations.
 \raisebox, \lowerbox and similar usages.
 \accent, \mathaccent. 
\end{verbatim} }

\section{Installation}

\index{flex}\index{compile}
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
{\begin{verbatim}
	gcc -o tth tth.c
\end{verbatim} }
\noindent or whatever C compiler you are using. Compilation takes
typically less than a minute on a modern PC. 

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

Alternatively you may be able to obtain a precompiled executable from
wherever you accessed this file. The Wind@ws executable comes with a
batch file for installation. Just run it by the command ``install''.

\section{Usage}

\index{switches!\TtH}\index{switches!-L} Command line is as
follows. The order of the parts is irrelevant. Switches (preceded by a
minus sign --) can appear anywhere on the line. Square brackets should
not be entered, they simply indicate optional parts of the command
line.\label{n-switch}
 { \tthdump{\small}
\ifx\TtMgold\undefined
\begin{verbatim}
Either filter style (the < and > are file redirection operators):
  tth [-a -c -d ... ] <file.tex [>file.html] [2>err]

Or, specifying the input file as an argument (output is then implied):
  tth [-a -c -d ... ] file[.tex] [2>err]

Switches:
   -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? HTML title format control. 0 raw. 1 expand macros. 2 expand equations.
   -ppath specify additional directories (path) to search for input files.
      -pNULL is a special switch that disables all \input or \includes.
   -r output raw HTML (no preamble or postlude) for inclusion in other HTML.
	-r2 omit just the time stamp. -r1 is equivalent to -r.
   -t display built-up items in textstyle equations (default in-line).
   -u? unicode character encoding. Default 2 (unicode 3.2). 0 (iso8859-1)
   -v give verbose commentary. 
   -w? html writing style: 0 no title construction. 1 use head/body. 2 XHTML.
   -y? equation style: bit 1 compress vertically; bit 2 inline overaccents.
   -xmakeindx  specify a non-standard makeindex command line.
\end{verbatim}
\else
\begin{verbatim}
Either filter style (the < and > are file redirection operators):
  ttm [-a -c -d ... ] <file.tex [>file.html] [2>err]

Or, specifying the input file as an argument (output is then implied):
  ttm [-a -c -d ... ] file[.tex] [2>err]

Switches:
   -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.
   -Lfile  tells tth the base file (no extension) for LaTeX auxiliary input, 
      enables LaTeX commands (e.g. \frac) without a \documentclass line.
   -n? HTML title format control. 0 raw. 1 expand macros. 2 expand equations.
   -ppath specify additional directories (path) to search for input files.
      -pNULL is a special switch that disables all \input or \includes.
   -r output raw HTML (no preamble or postlude) for inclusion in other HTML.
	-r2 omit just the time stamp. -r1 is equivalent to -r.
   -w? html writing style: 0 no title construction. 1 insert head/body.
   -xmakeindx  specify a non-standard makeindex command line.
   -v give verbose commentary. 
\end{verbatim}
\fi
 }
\index{stdin}\index{stdout}\index{stderr}
With no arguments other than switches starting with a ``-'', 
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. If these standard
channels are not redirected using \verb!<! and \verb!>!, then the
input is read from the command line, and both output and error
messages are printed on the screen.

If a non-switch argument is present, it is assumed to be the name of
the input file. The file must have extension ``.tex'' but the extension
may be omitted. The output file is then constructed from the argument
by removing the extension ``.tex'' if specified, and adding ``.html''.

\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.\index{CGI script}
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.)


\section{Messages\index{messages}\index{Error}\index{warning}}


Messages about \TtH's state and its assessment of the \TeX\ it is
translating are output always to the \verb!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:

\subsubsection*{Error Messages} 
These start \verb!**** 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.

\subsubsection*{Warnings}
These start \verb!****! but without reporting \verb!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 {\em necessarily} require
intervention. Examples include the use of some dimensions, glue, or similar
\TeX\ commands that have no HTML equivalent. 

\subsubsection*{Informational and external}
Lines with no \verb!****! 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 \verb!-v! causes more verbose messages to be output, which
may be helpful for understanding why errors are reported. A higher
level of verbosity \verb!-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 counts only the lines in the main \TeX\ file, not
those in files read by \verb!\input!. Therefore error reporting by
\TtH\ does not reach even the low standard of clarity set by \TeX\ and
\LaTeX\ error messages. Although \TeX\ files {\em 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.



\ifx\TtMgold\undefined
\section{Mathematics}

\subsection{Equations}

\index{HTML!3.2}\index{HTML!4.0}\index{font!face@\verb+face=""symbol""+}
 Equations are translated internally into HTML. \TtH\ uses HTML tables
 for layout of built-up fractions in display equations. It also uses
 the HTML tag $<$font face=``symbol''$>$ to render Greek and large
 delimiters etc. Untranslatable \TeX\ math tokens are inserted
 verbatim.

\index{LaTeX2HTML!differences}
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).

\index{italic!equation style}
\paragraph{The option [-i]} to \TtH\ {\bf 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.

\index{spacing}
\paragraph{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_\parallel/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\ {\em
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.

\subsection{In-line Equation Limitations\index{limitations}}

\index{in-line equations!arrays} \index{in-line equations!fractions}
\index{in-line equations!overaccents} 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 or built-up fractions in {\bf in-line equations} cannot be
properly supported because tables cannot be placed in-line in HTML.
\TtH\ output often will be strangely disjointed.
\label{inline}
\index{in-line equations!built-up display}
\index{equations!textstyle|see{in-line equations, overaccents}}
 As an option, \TtH\ provides switch \verb+-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
[\verb+$ ... $+ or \verb+\( ... \)+] 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
%%tth:\begin{html}<br /><table border="0" align="left"><tr><td nowrap="nowrap"></td><td nowrap="nowrap" align="center">1<hr noshade="noshade" />2 + n<br /></td><td nowrap="nowrap" align="center"></td></tr></table><br />\end{html}
This option gives a slightly strange layout for simple equations
but is a big improvement for some situations, e.g. in-line matrices.
\fi

Likewise 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 \emph{in-line} in plain
HTML, although \TtH\ will render them well in
\emph{displaystyle}. These latter constructs are nevertheless commonly
used in in-line \TeX. By default \TtH\ renders these constructs in a
relatively intuitive way. For example \verb|$\hat{a}$| is rendered
$\hat{a}$. The result is rarely elegant but it is
unambiguous. 

\subsection{Mathematics Layout Style Improvement using CSS}\label{yswitch}
\index{mathematics!layout style}
\index{Style Sheets}\index{CSS}

Some of the mathematics rendering limitations just mentioned can be
 overcome using Cascading Style Sheets. These are an extension of HTML
 that allows finer control over the layout. Most modern browsers
 support some fraction of the CSS specification, but historically its
 implementation has been slow and buggy. So it used to be awkward and
 dangerous to adopt CSS for authoring because of never knowing whether
 one was producing HTML that would simply be broken on a particular
 browser. Moreover using style sheets slows down the browser's
 rendering.

 \index{switches!-y1}\index{compression!vertical}
\paragraph{Vertical Compression} of the otherwise sometimes rather
spread-out mathematics is implemented on \TtH\ using a simple built-in
style sheet to reduce unwanted vertical space. The implementation
works around the different idiosyncrasies of the browsers'
implementations as well as it can, and is designed to degrade
gracefully in browsers without CSS support or with the support
switched off. This compression can be controlled by the switch \verb!-y!,
which permits a numeric argument, e.g. \verb!-y1!.  Compression is on
by default, which corresponds to the first bit of the -y switch value
being 1 (in other words the value is odd).  It may be switched off by
using the switch \verb!-y! with an even numeric argument (or none at
all), e.g. \verb!-y2! or \verb!-y!.

\index{switches!-y2}
\paragraph{In-line over-accents} can be rendered explicitly using the
relative positioning available in CSS2. The result is visually
 preferable to the the indicative base rendering. However, it does not
 fall-back gracefully, and the application of over accents to
 multiple-character groups produces a poorly aligned result.
  Nevertheless, since \TtH\ version 3.87 it is used as default. It can
 be turned off using the \verb!-y!  switch with the second bit (2) zeroed
 in the numeric argument. For example \verb!-y1! or \verb!-y0! turns
 it off.


\section{Features dependent on external programs.}

\subsection{Independence of [La]\TeX\ installation and the -L switch.}
\label{LaTeXfiles}
\index{LaTeX2HTML!differences}\index{portability} 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.

\index{auxiliary files}\index{switches!-L}
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 {\em do} need to run \LaTeX\ on the code so that these files are
generated. Alternatively, the \TtH\ switch
\verb+-a+\index{a@-a switch}\index{switches!-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, \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 \verb!-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.\index{references!forward}
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 \verb|\frac| command.


\subsection{BibTeX bibliographies\index{Bib\TeX}\label{bibtex}}

\TtH\ supports bibliographies that are created by hand using
\verb!\begin{thebibliography}! etc. Such bibliographies do not require
anything beyond the .aux file. \TtH\ \emph{also} supports
bibliographies created using Bib\TeX\ from a biblography database. The
\verb!filename.bbl! file is input at the correct place in the
document. However, this \verb!filename.bbl!  is \emph{not} created
automatically by \LaTeX. In addition to running \LaTeX\ on the source
file to create the auxiliary file, you must also execute
\verb!bibtex filename! in the same directory, to create the
\verb!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 Bib\TeX\ 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 Bib\TeX\ process
is relatively tortuous, \TtH\ offers an alternative. Using the -a
switch\index{a@-a switch}\index{switches|-a} with \TtH\ will cause it
to attempt to generate the required .bbl file automatically using
Bib\TeX\ 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
\verb|natbib|.  \TtH\ has rudimentary support built in for its
commands \verb|\citep| and \verb|citet| in the default author-date
form without a second optional argument.  A style file for
\verb|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.

\subsection{Indexing\index{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 {\em by section number} rather
than by page; assuming, of course, that they have been prepared with
index entries in the standard \LaTeX\ fashion.

\index{makeindex} When processing a \LaTeX\ file that contains the
\verb+\makeindex+ command in its preamble, \TtH\ will construct an
appropriately cross-hyperlinked index that will be input when the
command \verb+\printindex+ is encountered, which {\em must be after}
all the index references \verb+\index{ ... }+ in the document. \TtH\
does this independently of \LaTeX, but not of the subsidiary program
\verb+makeindex+ that is normally used with \LaTeX\ to produce the
final index. \TtH\ creates its index entries in a file with extension
.tid (Tth InDex). Unfortunately the standard form that
\verb+makeindex+ expects for compound numbering of its sections or
pages is ``1-2'', separated by a dash. TtH changes that to ``1.2''
using a point, and has to output a style file \verb+filename.mst+ ,
where \verb+filename+ is the base filename of the latex file being
processed, to enable makeindex to handle this form.  When the
\verb+\printindex+ command is encountered, \TtH\ closes the .tid file and
runs the command
\begin{verbatim}
makeindex -o filename.tin filename.tid
\end{verbatim}
on it.  This creates an output file \verb+filename.tin+, and
then \TtH\ reads that file in as its index.  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 {\em remove} the
\verb+\makeindex+ command from the top of the \LaTeX\ source and copy
the existing .ind file to a .tin file that will be input by
\verb+\printindex+. No indexing files will be written or deleted
without a \verb+\makeindex+ command in the document.

The \verb+\makeindex+ command, if present, will also cause \TtH\ to add
\index{Table of Contents!Index entry}
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 \verb+\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: \verb+-xcommandline+, which substitutes \verb+commandline+
for the default call \verb+makeindex+. Therefore, \verb+-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. If the \verb+-xcommandline+
contains any spaces, then it is interpreted as the complete
command-line (not just the first word of the command-line), in which
the base filename may be referenced up to 3 times as ``\%s''. For
example
\verb+-x"makeindex -s style.sty -o %s.tin %s.tid"+ will handle the
index using a different style file ``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.

\index{switches!-j}
\index{index!layout in one or two columns and the equivalent page length}
\paragraph{Layout of the index} can be controlled with the switch
\verb!-j! with an immediately following argument that specifies the
minimum number of lines in a column before the column will be
terminated. Because index entries are usually short, books almost
always adopt a two-column format for the index. \TtH\ will also do so
by default, but since an HTML document has no page breaks, the question
arises how long the individual columns are allowed to be. The default
(no switch) is equivalent to \verb!-j20!. A switch \verb!-j! with no
argument is equivalent to specifying a very large number of lines,
with the result that only one column is used.  A switch \verb!-j1!
will cause the columns to break at every indexspace, that is generally
at every new letter, so letter lists will alternate between columns.


\index{glossary} 
\subsubsection{Glossaries.} \LaTeX\ has a parallel set of commands for
glossary construction, replacing ``index'' with ``glossary''.
However, there is no \verb+\printglossary+ command and the .glo file
that \LaTeX\ produces cannot be handled by the makeindex program
without a specific style file being defined. Therefore glossary
entries are highly specialized and rarely used. \TtH\ does not support
a glossary separate from the index. Instead it simply defines the
command as \verb+\def\glossary{\index}+ with the result that glossary
entries are placed in the index. It may be necessary to add
\verb+\makeindex+ and \verb+\printindex+ commands to make \TtH\ handle
the glossary entries for a file that has only a \verb+\makeglossary+
command.

\subsection{Graphics Inclusion: epsfbox/includegraphics\index{graphics files}}
\label{epsf}
The standard way in plain \TeX\ to include a graphic is using the epsf
macros. The work is done by $\backslash$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.

\index{ps2gif}\index{ps2png} Optionally \TtH\ can use a more appropriate
graphics format, possibly using a user-supplied (script or) program
called \verb|ps2png| or \verb|ps2gif| to convert the postscript file
to a png\footnote{The PNG graphics file format is an improved
replacement for the GIF standard. Netscape has built in rendering for
PNG. The GIF standard is plagued with legal problems related to a
ridiculous patent on the type of file compression it uses.}  or gif
file, ``file.png'' or ``file.gif''. [``file'' is the name of the
original postscript file without the extension and png or gif are
interchangeable as far as matters for this
description]. 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 \verb|ps2png| then, if unsuccessful, \verb|ps2gif|.  Linux
(un*x) \verb|ps2png| and \verb|ps2gif| scripts using Ghostscript and
the netpbm utilities for this purpose are included with the
distribution.  A comparable batch program can be constructed to work
under other operating systems
\footnote{\label{ps2gifprob}May 1999 reports indicated that there is a
batch program in circulation bearing the comment ``:\#batchified by
cschenk@snafu.de'' that tries to implement the functionality of ps2gif
and gives errors on WinNT when called by \TtH\ but not when called from
the command line. I have not had recent reports of problems, so I
think this problem has been fixed.}  or else the conversion 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 \verb|ps2png| (or gif) is supplied must be of the form:
\begin{verbatim}ps2png inputfile.ext outputfile.ext\end{verbatim}
 The program must
have permission to write the outputfile (file.png) in the directory in
which the file.ps resides. 


\index{icons}
By popular request, a third graphics option -e3 for generating icons is
now available. If no previously translated graphics file,
e.g.~``file.png''  exists, \TtH\ passes to \verb|ps2gif| (or png) a third
argument consisting of the name, ``file\_icon.gif'', of an icon file.
\verb|ps2gif| is expected to create it from the same postscript file. In
other words the call becomes
\begin{verbatim}ps2gif file.eps file.gif file_icon.gif\end{verbatim}
 This third argument is then the file that is
inlined, while the larger gif file named ``file.gif'' is linked such
that clicking on the icon displays the full-size gif file. The icon
will not be created if ``file.gif'' already exists, because
\verb|ps2gif| will not then be called.



\index{includegraphics@\verb+\includegraphics+}
The \LaTeX2e command $\backslash$includegraphics\{...\} and the older
$\backslash$[e]psfig\{file=...\} are treated the same as $\backslash$epsfbox.
Their optional arguments are ignored.

\index{postscript}\index{jpeg}\index{gif}
If the extension is omitted for the graphics file specification, then
.ps or .eps is tried.  If the extension of the file specified is
non-null and 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.

\subsection{Picture Environments\index{picture environment}}
\label{pict}
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 \verb+\includegraphics+, see
\ref{epsf}. The switch \verb+-a+\index{a@-a switch}\index{switches!-a},
 causes \TtH\ to attempt automatic 
picture conversion using a user-supplied routine \verb+latex2gif+.
When this switch is used, \TtH\ outputs the picture to a file pic\textit{n}.tex,
where \textit n is the number of the picture (if there does not already exist
a file pic\textit{n}.gif). It then calls the command \verb+latex2gif picn+
which must be a command (e.g. a script using \LaTeX, dvips, etc.) on
the system, which converts the file pic\textit{n}.tex to a file pic\textit{n}.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 pic\textit{n}.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.

\section{Tabular Environment or Halign for Tables} 
\label{tabhal}
The tabular environment is the recommended way to construct tables in
\LaTeX. In plain \TeX, although \verb|\settabs| etc.~is supported, the
\verb|\halign{ ... }| command is recommended.  (The \LaTeX\ tabbing
environment is \emph{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 achievable\footnote{The alignment argument of the
math array environment was ignored in \TtH\ versions earlier than 2.20
but is now honored.}. However, the limitations of HTML tables impose
the following limitations on the translation.

\subsection{Tabular}
\begin{itemize}

\item HTML tables have either all cells bordered with rules or
none. \TtH\ therefore decides whether to use a bordered table by
examining the first character of the alignment argument. If is it
\verb!|!, then the table is bordered, otherwise not.

\item HTML tables are not capable of simultaneously aligning part of a
cell's contents to the right and part to the left, which is
automatically done by \LaTeX\ on some occasions when @-strings are used.
For example if the alignment argument is \verb!|l@{~units}|r|!, \LaTeX
will align ``units'' to the right of the first cell. \TtH\ can't. In
some unbordered cases \TtH\ will try for the same effect by putting the
closing @-string in the following cell. This won't always give a good
result.

\item @-strings and \verb!*{num}! code repetition are not permitted in the
alignment argument to \verb|\multicolumn|, but they are in the main
tabular alignment argument.
\end{itemize}

\subsection{Halign}

\index{halign@\verb+\halign+}
\begin{itemize}

\item \TtH\ decides whether to use a bordered table in Plain \TeX
 by examining the entire halign template (i.e.~the material up to the
first \verb|\cr| of the halign). If it contains the command
\verb|\vrule| \TtH\ makes the table bordered, otherwise not.


\item \TtH\ decides on the alignment of the cell contents by looking for
\verb|\hfill| or \verb|\hss| commands in the cell template. The
default is to left-align the cell. If one of these spacing commands is present
in the template prior to the \verb|#| for this cell, then the cell
will be right-aligned unless such a command also appears after the
\verb|#|, in which case the cell is centered. Again HTML is not capable of
applying different alignments to different parts of a cell. So results may
sometimes be different from \TeX. However, if most of this paragraph
sounds totally obscure to you, don't worry; \TtH\ will probably do the
right thing.

\item The \verb|\multispan| command is supported, giving a centered
multicolumn cell, and \verb|\omit| is treated as \verb|\multispan1|.
However, \verb|\span| is currently not supported.

\item In \TeX\ each cell of an halign table resides within its own
  implied brace group. Because \TtH\ does not implement this implied
  group, errors can arise. Even HTML table errors that lead to parse
  errors with XML parsers can arise when the cells have boxes in them.
  If this happens, the fix is to put an explicit brace group round the
  offending cell in the template line like this example:
\begin{verbatim}
  \halign{#\quad\hfil &{\vbox{\hsize\0.5\hsize #}}\cr
    1 & V-box material\cr
    }
\end{verbatim}

\end{itemize}


\subsection{Longtables}
\index{longtable}\label{longtab}

\begin{itemize}

\item
The longtable environment is supported, but it is always centered. It
is converted into a standard tabular inside a table environment
because there is no need to accommodate page breaks (the main point of
longtable) in HTML. 

\item The caption (including caption*) command is
translated correctly but set as part of the HTML table; so, if the
caption is longer than the longest row of the table, it will cause the
whole table width to expand, possibly up to 100\% of the
line-width. 

\item The commands endhead, endfirsthead, endfoot, endlastfoot,
are ignored, but their immediately preceding commands are therefore
inserted into the table. That is probably not desirable for the foot
commands.  Longtable footers are not translated into footers. 

\item The \verb!\kill!  command is ignored. Its text is spuriously inserted.
\end{itemize}



\section{Boxes, Dimensions, and fills}

Boxes, dimensions, and fills are rarely appropriate for web documents
because they imply an attempt to control the fine details of
layout. Browsers make their own choices about layout of a document in
HTML. For example they make the lines fit whatever size of window
happens to be present. This dynamic formatting makes mincemeat of most
detailed \TeX\ layout. In fact, if you want your readers to see
exactly what you see, that is impossible with HTML, and you should use
some other representation of your document.

There are nevertheless many cases when a \TeX\ document containing
boxes, dimensions, and fills needs to be translated.  Limited
translation of these constructs is supported. They are translated,
where appropriate and possible, into HTML tables with widths and
vertical skips estimated to give a reasonable result on a browser. It
must be stressed that accurate translation is inherently impossible
because browsers deal in pixel sizes and default font sizes that vary
and are out of the control of the publisher.

The types of box usage that translate quite well are when things like
\begin{verbatim}
\hbox to \hsize{The left \hfil the Right}
\vbox{\hsize=2in Matter to be set in horizontal mode to a 
  limited hsize}
\makebox[0.6\hsize][r]{Stuff to the right of the makebox.}
\framebox{check}
\end{verbatim}
are on a line by themselves.
You get:

\hbox to \hsize{The left \hfil the Right}

\vbox{\hsize=2in Matter to be set in horizontal mode to a limited hsize}

\makebox[0.6\hsize][r]{Stuff to the right of the makebox.}

\framebox{check}

Usages that translate poorly tend to be boxes within a line of
text. That is because current HTML table implementations have to start
a new line unless they happen to be adjacent to a table already. Thus
an hbox in a line will give a line break that you might not have
wanted. This behaviour is really a bug in the browsers, but we are
currently stuck with it. The behaviour of HTML tables is buggy
[see \ref{tablebug}] when their alignment is specified, which means that
strange results are likely if more than one box on a line is being
set. Boxes in equations are troublesome. The only type that is
reasonably supported is \verb!\mbox! which is often used in \LaTeX\ for
introducing text inside equations.

Negative skips are \emph{not supported at all}.

The only important dimension parameter that is currently interpreted
is \verb!\hsize!. It is what controls the width of a vbox.  It can be
reset using the plain \TeX\ format e.g.~\verb!\hsize = 3in! or scaled
or advanced e.g.~\verb!\hsize=0.6\hsize!  but only within a group. It
makes no sense for the HTML file to try to specify the width of the
line at the outermost level. That is the browser's business.

New dimensions can be defined, set, advanced, scaled and used to set
other dimensions including \verb!\hsize!. 

\TtH\ trys valiantly to mimic the sort of text alignment that is
obtained using glue such as \verb!\hfil! and \verb!\hss!, provided it
is inside a box. However, the alignment algorithm of HTML tables makes
it impossible to obtain fills with exactly equal sizes. So don't be
surprised if some results looks disagreeable. Moreover, \TtH\ will
completely ignore the glue outside an hbox, and it doesn't know
the difference between \verb!\hfil! and \verb!\hfill!, etc.

\section{\TeX\ command definitions and other extensions}

\subsection{Delimited-parameter macros and
Conditionals\index{definitions!delimited}}

Delimited parameter definitions are fully supported. 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 or handled differently by
\TtH. In such cases it is all too possible for the delimited parameter
\emph{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.

\index{if@\verb+\if+}
Conditionals such as \verb|\if|, \verb|\ifnum| and so on are
supported, as listed above (\ref{ifs}). 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\\
\verb|\ifnum 1=\if ab 1\else 2\fi  True \else False \fi|\\ will likely
break. Nested `if' constructs \emph{are} permitted in the conditional
text, however, so\\ 
\verb|\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 \verb|\if| and \verb|\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.


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.\index{catcodes} 
For example, practically any \TeX\ that redefines {\bf 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 {\bf
only letters or @ in user-defined command names}, not punctuation
characters etc.

\subsection{Macro- and Style-file 
inclusion\index{macro files}\index{texinputs path} }
\index{input@\verb+\input+!TEXINPUTS}%this index entry won't work
				     %inside the subsection argument.
\label{texins}
Macro definitions are fully supported by \TtH. However, special macro
packages designed for a specific layout of journal or conference, for
example, often use unsupported constructs such as catcode changes. It
may then be inadvisable to use the macro package.  \TtH\ does not
recognize the \verb!\usepackage! command by default because the
\LaTeX\ macros that are input by this command almost always contain
catcode changes or other usages incompatible with \TtH. That is
another reason why \TtH\ does not normally have directory paths
defined the same as \TeX. If a macro package is on the TEXINPUTS path
it will be found by \TeX\ but not by \TtH.  Thus, the macro
definitions are included when ``\TeX''ing the file, but not when
``\TtH''ing it.  It should be clear from this discussion, however,
that \TtH\ generally does not support any of the enormous number of
extensions to \LaTeX\ unless they are mentioned in this manual,
because most extension packages are incompatible with \TtH.

\index{input@\verb+\input+!TTHINPUTS}
\TtH\ \emph{will} find an input file if 
\begin{enumerate}
\item the full path is
 specified relative to the directory from which \TtH\ is run, e.g.  \\
 \verb|\input /home/myhome/mytexdir/mymacro.tex| \\ 
\item the \verb!-p! switch specifies a path on which the file is
found, or
\item the TTHINPUTS environment variable is defined to be a path on
which the file is found.
\end{enumerate}
Paths are searched in this order until an appropriate file is
found or all directory options are exhausted

\index{commands!alternative files} This policy provides a mechanism
for making available the alternative package for \TtH,
without alteration of the original \TeX\ files, by placing the
(simplified) version of the macro package on the path \TtH\ searches.
 An example using the \verb!-p! switch might be
\begin{verbatim}
tth >file.html <file.tex -p/usr/local/tthinputs:~/mytthinputs
\end{verbatim}

\index{macros!alternate}
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.

\index{input@\verb+\input+!disabling}
When \TtH\ is used within a CGI script accepting arbitrary \TeX\ for
translation, its ability to input any file on the system is a serious
security hole. It can be used to view all sorts of files on the system
by \verb!\input!ing them. Therefore a special switch \verb!-pNULL! is
provided that disables all \verb!\input! or \verb!\include! files.

\subsection{Layout to include arguments of unknown
commands\index{commands!unknown}
\index{unknown commands|see{commands, unknown}}}

Unrecognized or undefined commands of the form
$\backslash$dothis\{one\}\{two\}\{three\}, are treated by discarding
all the following {\it 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
``$\backslash$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.

\subsection{Restrictions on redefinition of internal
commands\index{commands!renaming}\index{commands!redefining}
}

In \TtH\ (unlike \TeX) most internal commands can {\it 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 ams\TeX\
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.)
 
\subsubsection{Footnotes}\index{footnotes}
Footnotes are placed together at the end of the document, or, in the
case of \TtH gold splitting files, in a separate file called
footnote.html. The title of this end section is determined by the
macro \verb!\tthfootnotes!. By default this is ``Footnotes'', but can
be redefined by the user at will, e.g. by
\verb!\def\tthfootnotes{Tailnotes}!.


\section{Color\index{color}}
\index{colordvi}
\TtH\ supports the coloring of text using the color package macros for
\LaTeX, supported by dvips (but not xdvi).  \TtH\ also supports the Plain
\TeX\ colordvi macros contained in the package colordvi.tex that do the
same thing. 

\subsection{\LaTeX\ Color}

The \LaTeX\ syntax is recommended because the 68 standard
named colors\footnote{See the file colordvi.tex for a list of
the named colors.} are directly supported internally by \TtH\ using the named
model. Any numerical CMYK, RGB and Gray color can also be prescribed. For
example the following commands are enclosed in themselves:
\textcolor[named]{BrickRed}{$\backslash$textcolor[named]\{BrickRed\}\{...\}},
\textcolor[rgb]{0.,.5,0.}{$\backslash$textcolor[rgb]\{0.,.5,0.\}\{...\}},
\textcolor[cmyk]{0.,.5,0.,.3}{$\backslash$textcolor[cmyk]\{0.,.5,0.,0.3\}\{...\}}.
You can define custom colors in the usual way using, for example
\begin{verbatim}
{\definecolor{Puce}{rgb}{1.,.5,.8}
\color{Puce} This is my own Puce.}
\end{verbatim}
Which gives ``{\definecolor{Puce}{rgb}{1.,.5,.8}
\color{Puce}This is my own Puce.}''

The command \verb!\pagecolor! is supported but discouraged. It
is highly likely to give rise to an HTML file that will fail
validation because it inserts an HTML tag \verb!<body bgcolor=...>!
which will not be in its correct position (immediately following the
title). The only way to be certain to produce an HTML file that passes
validation is to put the title and body commands in by hand, using
e.g.  \verb!\special{html:<title>...</title><body ...>}!  Netscape
seems not to mind a body tag out of order, but only the first one is
able to set the page background color.

The commands \verb!\colorbox! and \verb!\fcolorbox! are supported via
CSS style sheet commands. They will only work to set the background
color of included text if the browser is set to use style sheets. 
\colorbox{green}{``This sentence''} is the result of the command
\verb!\colorbox{green}{``This sentence''}!. If it is colored, then
your browser supports style sheets to this extent. If not, check your
preferences settings.

\subsection{Plain Color}

The Plain \TeX\ syntax using commands such as \verb!\Red{red text}! requires
the file \verb!colordvi.tex! to be input prior to their use. But
because \TtH\ does not search the standard \TeX\ paths, that file will
\emph{not} usually be found unless the full path is explicitly
specified. If the file is not found, only the 8 standard colors
\begin{verbatim}
\Red, \Green, \Blue, \Cyan, \Magenta, \Yellow, \Black, and \White
\end{verbatim}
 are
recognized internally by \TtH. You can use the user-defined CMYK numeric
style 
\begin{verbatim}
\Color{0. .5 .5 0.}{pale red}
\end{verbatim}
without the colordvi
file. It gives the result ``\iftth\Color{0. .5 .5 0.}{pale red}\else
\textcolor[cmyk]{0.,.5,.5,0.}{pale red}\fi'' but the
notation becomes cumbersome unless you define your color
e.g. like
\begin{verbatim}
\def\redcolor{0. .5 .5 0.}
\Color{\redcolor}{The stuff that is red.}
\end{verbatim}

Another difficulty with the colordvi
command \verb!\textColor! (which is the color \emph{switch} --- \LaTeX
syntax reversed that usage and changed to comma-delimited arguments
just to confuse us) is that it is a global setting. It then
becomes almost impossible to maintain proper nesting of the closure of
the font commands used for colors in HTML. As a result, use of
\verb!\textColor! often gives HTML files that won't pass HTML validation.

\subsection{Limitations}
Color commands do not propagate into different cells of HTML tables
because of what may be regarded as a browser bug
[\ref{cellbug}]. For that reason, tables and equations will not color
correctly if the color commands enclose more than one cell (for
tables) or equation element. Remember also that some computers may be
limited in their color display capability, so the subtleties of colors
will be lost in some circumstances. 

% TtH Gold documentation.

\section{Producing output split into different files.}

\subsection{Overview}

Because the \TtH\ program itself always produces just one output file,
the division of the output into different files takes place in two
steps. First, \TtH\ is run on the \LaTeX\ file with the switch
\verb!-s! (for ``split''). This switch tells \TtH\ to produce output
that is in {\bf 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
\TtH\ 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
\begin{verbatim}
tth -s -Ltexdocument <texdocument.tex >mimedocument.html
\end{verbatim}

\noindent would produce such a file called \verb!mimedocument.html! from a
\LaTeX\ file called \verb!texdocument.tex!. The switch \verb!-L!
tells \TtH\ to use auxiliary files that were produced when \LaTeX\ 
was previously run on it. Alternatively if you want the output file to
have the same name as the texdocument but with the extension
\verb!html!, you can use just
\begin{verbatim}
tth -s texdocument
\end{verbatim}

There are available standard tools for unpacking multipart mime files
into their individual files, notably the \verb!mpack! tools available from
the ``Andrew'' distribution, which may be available on some
systems. However the executable \verb!tthsplit!  (whose source is in
the tthgold directory) is a more specific 
program that will unpack MIME files produced by \TtH. (\verb!tthsplit!
will {\em not} handle general MIME files.) To unpack the multipart
file into its individual files requires the simple command:

\begin{verbatim}
tthsplit <mimedocument.html
\end{verbatim}

\noindent This will inform the user of the files produced, for
example

\begin{verbatim}
index.html
chap1.html
chap2.html
refs.html
footnote.html
\end{verbatim}

\noindent the file \verb!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 \verb!tth! can be piped to \verb!tthsplit! to produce the split
files directly by the command line:

\begin{verbatim}
tth -s -Ltexdocument <texdocument.tex | tthsplit
\end{verbatim}

Since the names of the split parts of the document are predetermined,
it is strongly advisable to make a separate directory for each
different \LaTeX\ 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.

\subsection{Navigation Controls at File Top and Tail}

By default \TtH\ 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 \TtH\ 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
\begin{verbatim}
\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>}}
\end{verbatim}

The macro \verb!\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,
\verb!\tthsplittop! is called. Note that these macros use the
builtins \verb!\tthfilenext! and \verb!\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.


\subsection{Special Precautions when Splitting Output}

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

\begin{verbatim}
\input /usr/local/tth/tthprep.sty
\end{verbatim}

\noindent where the path should be to wherever you unpacked or are
keeping the tth distribution file \verb!tthprep.sty!. Then \LaTeX\ 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
\verb!tthprep.sty!, the auxiliary files so produced can be interpreted by
tth to give correctly linked split files. If you want to produce
\verb!dvi! output from your \LaTeX\ then you should remove this extra
input command.  None of this is needed unless splitting by {\em
sections\/} (not chapters) is to be performed or floats are
problematic.

To make it easier for the user, a script is provided called
\verb!tthprep! which automates the process of producing satisfactory
auxiliary files through the single command

\begin{verbatim}
tthprep texdocument.tex
\end{verbatim}

\noindent The script will leave the \LaTeX\ file in its original condition,
but the auxiliary files in appropriate form for \TtH.

\subsubsection{Multiple Bibliographies}
Multiple bibliographies in split files are a problem. All the
citations in the rest of the text link to a single file
\verb!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 \verb!refs1.html! \verb!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
\verb!tthrfcat! will do this if run in the directory where the split
files reside. It destroys all the \verb!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
\verb!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.



\section{HTML and output}
\subsection{Formal HTML validation}
\index{title!HTML construction} \TtH\ takes as its standard HTML that
can be rendered by Netscape and IE browsers versions 4 and higher
(with the caveats above).  The formal standard that \TtH-translated
documents follow is strictly HTML4.0[1]\footnote{It proves to be
  better to specify 4.0 as the HTML Doctype because on some operating
  systems symbol font rendering is not honored for 4.01 documents.}
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 {\it requires} a
\verb+<title>...</title>+ for every document.
A title is constructed from \LaTeX\ files that contain the \verb+\title{...}+
command, in which case HTML conformance is ensured by putting the
\verb+\title+ command before any text (i.e.~in the preamble, where it
belongs).  If the \verb+\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.
\begin{verbatim}
%%tth:\begin{html}<title>Put the title here</title>\end{html}
\end{verbatim}
This line will be ignored by \TeX. Actually, any raw HTML output at the
start of the file is assumed by \TtH\ to indicate that the author has
explicitly output a title. 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.  

If commands like
\verb|\item|, that output material to the HTML file occur
before the title has been constructed, the HTML title command will be
out of order and the formal standard will be violated. 

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.

\subsection{HTML Styles}
\label{htmlstyle}
There are good reasons why the \verb!<head>! and \verb!<body>! tags
are by default omitted by \TtH.  See the FAQ [\ref{headbody}] for a
brief discussion. However, the evolution of HTML standards (not yet
browsers) is towards imposing more restrictions on the freedom to omit
tags. For example XHTML \emph{requires} that containers have both
opening and closing tags. Therefore \TtH\ has a switch \verb|-w?|
(where the question mark denotes an optional integer) that controls
its writing style as follows.
\begin{description}
\item[Default] Construct title. Do not enter head and body tags.
\item[-w -w0] Do not construct title or enter head/body tags.
\item[-w1] Enter head and body tags assuming that the title is the
dividing point.
\item[-w2] Use XHTML syntax.
\item[-w4] Don't use block level font size commands between paragraphs.
\end{description}
At present, in addition to the default style that
attempts to construct a title but does not enter head and body tags,
-w or equivalently -w0 prevents \TtH\ from attempting to construct a
title or anything else in the way of head/body divisions. This style
is best used for documents where the author has explicitly entered the
required HTML tags. The switch -w1 invokes pedantic HTML style which
enters head and body tags under the assumption that the title
(possibly constructed automatically) is the last thing in the head
section. A style -w2 produces XHTML documents but \emph{requires}
cascading style sheet (CSS) support in the browser otherwise the
rendering will not be as satisfactory as the default. 

Addition of four to the writing style index (e.g. -w4) prevents
 \TtH\ employing block-level font size commands if the size is changed
 immediately after a \verb!\par! or implied paragraph. The additional
 CSS style sheet is not inserted and, of course, the browser need not
 support CSS. The (now) default writing style is to accommodate tables
 and equations inside sections of larger or smaller text in a manner
 that will pass standards validation. According to the standard, HTML
 font changing commands like most others, are either of
 inline\index{inline elements} type, in which case they are forbidden
 to contain block\index{block level elements} level constructs like
 tables, or block type, in which case they force a new line and so
 can't be used within a paragraph. The default can't universally fix
 this unnecessarily restrictive requirement of the standard (which
 most browsers wisely do not honor). There are situations where
 \TeX\ usage is simply impossible to express in HTML. However, it does
 fix the vast majority of sensible usages. The switch -w4 turns off
 this approach, reverting to less standards-compatible style.

\section{Browser and Server Problems}

\TtH\ translates \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, and
a few that are associated with web servers. Authors and publishers
should recognize that these are \emph{not} \TtH\ bugs. Font-related
problems are complicated. If you don't need all the gory details, you
might want to read section \ref{fontoverview} and then skip to
\ref{exploder}.

\index{fonts!accessing}
\index{symbol font!accessing}
\subsection{Accessing Symbol Fonts: Overview}\label{fontoverview}

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 \emph{accessing} the font because of
shortcomings in the browsers and the HTML standards that relate to
font use.

\index{switches!-y1}
\index{switches!-y2}
\index{switches!-u}
In brief, there are three ways to access the symbol fonts; these will
be described in more detail below. The following table indicates which of
these approaches to accessing the symbol fonts works with which
browser. It also outlines which of the mathematics rendering
improvements via CSS positioning are satisfactory.
\begin{center}
\begin{tabular}{|l|ccc|cc|}\hline
 & \multicolumn{3}{c|} { Symbol Encoding } &
\multicolumn{2}{c|}{CSS Positioning} \\
& 8-bit numeric & Adobe Private & Unicode 3.2 &  relative & height
compress \\\hline
\TtH\ switch &-u0&-u1&-u2 &-y2& -y1\\ 
Browser:& & & & &\\
MSIE 5.0    & Yes & No & No & Yes & Buggy\\
Mozilla 1.x X & Alias/Font & Buggy & Buggy & Yes & Yes\\
Firefox 1.x X & Alias/Font & Buggy & Buggy & Yes & Yes\\
Firefox 1.x Win & Yes  & Buggy & Buggy & Yes & Yes\\
Konqueror 1.9.8& Alias & No & No & Yes & Yes \\\hline
Firefox 3.5 X & No & Buggy & Ugly & Yes & Yes \\
Chrome 4.0 X & No & Buggy & Ugly & Yes & Yes \\
Firefox 3.5 Win & Yes & No & Buggy & Yes & Yes \\
MSIE 8.0 Win & Yes & No & Ugly & Yes & Yes \\
\hline
\end{tabular}
\end{center}

This situation is painful. The 8-bit numeric style symbol access
 method, which was the approach originally pioneered by \TtH, used to
 work with a significant number of browsers but needed additional font
 settings for X-window systems.  This is the approach that \TtH\ used
to use
 by default. However Mozilla and Firefox have systematically moved
 towards disabling this method under linux and OSX, presumably because
 they consider it not standards-compliant. They have not properly
 implemented the unicode 3.2 alternative, because the glyphs they use
 for built-up delimiters are incorrectly sized and leave ugly gaps. In
 some cases the spacing is completely erroneous. One is left with the
 choice between the traditional 8-bit approach, which works well with all
 MSWindows systems up to Vista, but does not work with most recent
 X-based operating systems; or Unicode 3.2 which works with most
 browsers, but is badly buggy in Windows Firefox and ugly everywhere.

In the interests of an eventual rationalization of this situation, TtH
 has changed to make the Unicode 3.2 coding its default from the 2010
 version 3.87 on, but this by no means universally satisfactory.

\subsection{Accessing Symbol Fonts: Details\index{fonts!details}}

\index{character set}\index{encoding}
Prior to HTML4.0, that is, during the major phase of the evolution of
HTML, the default encoding for HTML documents was ISO-8859-1
(sometimes called ISO Latin-1). The document encoding defines a
mapping between the bytes of the file itself and characters. The
HTML4.0 standard draws a strict (but often confused) distinction
between the document ``character set'', sometimes referred to more
recently as the character ``repertoire''(which refers to all the
characters that might be used in it) and the ``document encoding''
(which encodes a subset of the character set by mapping them to
bytes). The confusion is compounded by the entrenched usage of the term
``charset'' to refer to the ``document encoding'' (not the character
set). This usage is presumably a reflection of the prior lack of any
significant distinction between the two. 

Purists since the adoption of HMTL4.0 regard the selection of a glyph
as governed by the process: $\mbox{(byte) code} \rightarrow
\mbox{glyph-name} \rightarrow \mbox{font-glyph}$. In this view, even
though the font contains the glyphs in a well defined order, the
glyph is accessed not by its position in the font but by its name. For
example, in a document with ISO-8859-1 encoding, the byte with decimal
value 97 maps to the ``latin small letter a'' which is accessed from
the font on that basis.  On this view, it is not possible, or rather
ought not to be possible, to access the Greek letter alpha by
specifying that the font is Symbol and the byte coding decimal value
is 97, despite the fact that the Greek alpha is indeed in the same
position in the Symbol font as the lower case a in its font. This is
because (the story goes) 97 means ``latin small letter a'' and the
Symbol font simply does not contain the latin small letter a.

In practice, of course, most browsers, including Internet Explorer (to
8.x), have not taken so pedantic an approach. In a document that is
encoded in the same order as the fonts on the system, as is the case
for ISO-8859 on systems other than the (old) MacIntosh, the browser maps
code to glyph directly on the basis of numeric position in the
font. Therefore it is perfectly sensible to specify eight-bit code 97
and Symbol font to obtain alpha. In other words, the browsers treat
the Symbol font as if it were an ISO-8859 font even though, as far as
the glyph names are concerned, it is not. It can be argued, even
within the world-view of standards lawyers, that a document that does
not explicitly specify its encoding (and \TtH\ documents do not) could
be considered to obey its own font encoding or some unspecified
encoding, in which case, bytes ought to be permitted to refer directly
to numeric font positions, in just this fashion, regardless of whether
the font is identified as ISO 8859. But such arguments are usually a
waste of breath. In any case, recent versions of Mozilla and its
derivatives on the Windows operating system will properly render
symbols provided they are told that the DOCTYPE is HTML 4.0, not HTML
4.01. This is the reason why \TtH\ has reverted to giving its
documents this rather out of date DOCTYPE.

On the X-windows system, a distinction between fonts is provided
directly in the system via the font naming conventions. Mozilla takes
notice of this font allocation by permitting access only to fonts
whose names end 8859-1, for default encoded documents. The symbol font
is not one of those fonts unless additional steps are taken. The
enabling of the symbol font requires specification of some system font
aliases, or installation of a specially encoded Symbol font, which
then ensures that the Symbol font is treated as if it were ISO-8859-1
encoded. Notice that this type of problem arises for any document that
wants to access more than one language of font. Thus, any document
desiring a mixture of, for example, western and cyrilic characters
would face the same problem.

To summarise, the symbol font is present on practically every computer
on the planet that runs a graphical browser. Under the MSWindows
operating system, IE to version 8.x, and Mozilla (gecko)-based
browsers treat the symbol font as if it were a numerically encoded
font and compatible with ISO 8859-1 encoding, provided the DOCTYPE is
HTML 4.0 Transitional.  Treating the font as such enables the glyphs to be
accessed using either eight-bit codes in just the same way as standard
ASCII characters. This is the way that documents have accessed these
glyphs for years.

The HTML4.01 standard says that unicode (ISO 10646, also called UCS) is
the character set of HTML, and that the way characters outside the
current document encoding should be accessed is through unicode
points. Unicode is backwardly compatible with ISO 8859-1 in a way that
we need not dwell on. Unicode is supposed to fix all the font problems
that are described here, and with luck eventually it will indeed
help. The problem is that (1) Unicode is enormous, so only a tiny
fraction of it is so far supported, and (2) in its original incarnation
unicode does not even assign points to the parts of large delimiters
that are needed for mathematics. They \emph{are} present in the new
version of unicode, 3.2, becoming current. However, as the
table above shows, no browser cleanly supports the new unicode
assignments. Mozilla used to support some assignments of points in
unicode's designated ``private usage area'' to the glyphs we
need. Apparently these assignments have become de-facto standards for
the Adobe Symbol font in typographic circles. No other browser
supports them. They are not and, according to unicode principles,
never will be part of the unicode standard, and appear to be on the
way out.

The option that mathematics web publishing currently has, then, is
 either an approach that works with Windows browsers but which purists
 say is not consistent with latest standards, or a representation that
 is consistent with the standard but useless with some browsers. It
would be really nice if the browsers would get their act together on
mathematical symbols.

\subsection{Printing\index{printing}}
\label{exploder}

In many browsers, 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 {\it browse}, but not
necessarily the best medium for paper production.

\subsection{Netscape/Mozilla Composer\index{Netscape/Mozilla Composer}}
\label{nscomp}
Netscape Composer and Mozilla Composer 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.\index{publish!through composer disallowed}
  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.


\subsection{Other Browser Bugs}

\label{cellbug}

Font changing commands do not propagate from cell to cell of HTML
tables. In rendering equations (using tables) \TtH\ circumvents this
bug (excuse me, \emph{feature}) at the cost of significant extra effort and
slightly verbose HTML.  However, for tables generated by
\verb+\halign+ or \verb+\begin{tabular}+ \TtH\ takes no special steps
to avoid this problem. A change of font face in a cell, for example by
\verb+\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.

\label{tablebug}
Tables are incapable of being properly embedded within a line of text.
They generally force a new line. This is quite a significant handicap
when translating in-line material that could use a table. It can be
argued that this behaviour is required by the HTML
standard. Specifically, the \verb!<p>! element is defined as having
in-line attributes which prevent it from containing any elements
defined as being \verb!block! type, of which \verb!<table>! or
actually strictly \verb!<td>! is one. However, even if you ensure that
text is not inside a \verb!<p>!, most browsers force a new line.


\subsection{Web server problems}
\index{UTF-8}\index{web-server}

The HTML files that \TtH\ produces are encoded using the charset
ISO-8859-1, like most web files. In newer linux systems the default
file encoding on the computer is in many cases now UTF-8. For the
characters with codes above 128, this can cause problems with the web
server. The web server may wrongly assume that the HTML file is a
UTF-8-encoded file, and declare this assumption in the http content-type
header that it sends to browsers when they access the file. For
gecko-based browsers, the http content-type declaration overrides any
internal file declaration of the encoding of the file. Consequently,
the browser treats this file as if it is UTF-8 encoded, with the
result that codes higher than 128 are misinterpreted. This is an
inadequacy in the web server (apache is known to behave this way in
some situations).

There are several options to work around this problem.

It is possible to convert all files from ISO-8859-1 to UTF-8 encoding,
using a utility called \verb!iconv!, present on most modern linux
installations. This is not an attractive solution because then when
the files are browsed locally (via file://...) they will display
incorrectly. Locally, the browser does not have the http content-type
declaration to guide (or misguide) it, and it thinks the files are
ISO-8859-1 encoded. But if they've been converted, they are not.

The better approach seems to be to fix the web server so that it gets
the file content-type right. This can be done on a per-directory basis
by creating a file called \verb!.htaccess! in the directory. This file
should contain the line:
\begin{verbatim}
  AddType text/html;charset=ISO-8859-1 html
\end{verbatim}
This tells the server that all files in this directory and its
subdirectories that have extension \verb!html! are to be considered of
type HTML and encoded with the ISO-8859-1 charset.

Unfortunately some web servers are configured not to pay attention to
the \verb!.htaccess! file. If yours is one, you have to get the web
master to edit the server configuration file
(\verb!/etc/httpd/conf/httpd.conf!). The lines that read
\verb!AllowOverride None! must read instead
\verb!AllowOverride FileInfo!. Alternatively, get the webmaster to
change the line in that configuration file that reads
\verb!AddDefaultCharset UTF-8! to read instead
\begin{verbatim}
AddDefaultCharset ISO-8859-1
\end{verbatim}
 and once the server is restarted all your troubles will be over
without any of those pesky \verb!.htaccess! files.
 
There are other ways of accomplishing the same thing in the web
server, if you are a guru. Information is available at 
\href{http://www.w3.org/International/questions/qa-htaccess-charset}{the
  W3C FAQ}.


\section{Code Critique\index{bugs}}

If you think you have found a bug, you can report it to
\verb!tth(at)hutchinson.belmont.ma.us! (with the usual character
substituted in the email address).  You are most likely to get help if
your report is accompanied by the brief section of \TeX\ code that
causes the problem. Let me repeat, in addition to a brief description
of the problem, send the \TeX\ code, preferably a short
section isolating the problem, in a document that can be processed
by \TeX. It is the only way for me to establish
what the problem is. But please don't send \LaTeX2.09 files or files
that do not conform to the (1994) \LaTeX\ users' guide. And
please check this \TtH\ manual and especially the FAQ (\ref{FAQ}) first.

The code has been compiled and run on Linux, MSDOS, Wind*ws, Open VMS,
and sundry other operating systems. See 
\href{http://hutchinson.belmont.ma.us/tth/platform.html}
{http://hutchinson.belmont.ma.us/tth/platform.html}.

\section{License}

\index{license}
\TtH\ is copyright \copyright\ Ian Hutchinson, 1997-2011.

You are hereby freely licensed to use this software under the terms of
the GNU General Public License, version 2, published by the Free
Software Foundation, a copy of which is enclosed in the file
license.txt.

The software comes WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

%\setcounter{section}{23}
\section{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, Rick Mabry, Andrew Trevorrow, Guy Albertelli II, Steve
Schaefer and for bug
reports from others too numerous to mention.

\appendix
\section{Appendix: Non-Standard \TeX\ Macros}

\index{macros!special use}
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.

{\begin{verbatim}
\def\hyperlink#1#2{\special{html:<a href="\##1">}#2\special{html:</a>}}
  % Incorrect link name in \TeX\ because # can't be passed properly to a special.
\def\hypertarget#1#2{\special{html:<a name="#1">}#2\special{html:</a>}}
\long\def\tthdump#1{#1} % Do nothing. The following are not done for TtH.
\tthdump{%
\def\title#1{\bgroup\leftskip 0 pt plus1fill \rightskip 0 pt plus1fill
\pretolerance=100000 \lefthyphenmin=20 \righthyphenmin=20
\noindent #1 \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
  % Macro for http reference inclusion, per hypertex.
 \def\href#1#2{\special{html:<a href="#1">}#2\special{html:</a>}}
 \def\urlend#1{#1\endgroup}
 \def\url{\begingroup \tt 
  \catcode`\_=13 % Don't know why this works.
  \catcode`\~=11 \catcode`\#=11 \catcode`\^=11 
  \catcode`\$=11 \catcode`\&=11 \catcode`\%=11
\urlend}% \url for plain \TeX.
}
\end{verbatim} }


\section{Appendix: Frequently Asked Questions}
\label{FAQ}

\subsection{Building and Running \TtH}

\paragraph{Why does my compiler crash when compiling \TtH?}
\leavevmode\\ \TtH\ comes in the form of a single C source file
because it is mostly one very large function which is produced by
flex. It is completely standard C code but the size challenges
compilers' capabilities, especially if you try to optimize using the
-O switch. With gcc under linux it is possible to compile an optimized
version, but optimization hardly affects the speed and reduces the
disk size of the already modest executable only by about
20\%. Therefore it is no significant loss to compile without
optimization. Under DOS, even unoptimized compilation can cause DJGPP
to crash if its stack size is less than about 1024k. The fix (using
stubedit on cc1.exe) for this DJGPP bug is described in its FAQ.

\paragraph{Why does my \TtH\ executable, which I compiled myself, crash?}
\leavevmode\\ Assuming that this is not a problem caused by invalid
\TeX, or by you poking around inside the C code, it is probably a
compiler shortcoming.  Some default settings of some compilers give
\TtH\ too little stack space and cause it to crash. Most
self-respecting compilers have switches or settings to increase that
space. Try increasing it, or get one of the binary distributions.

\paragraph{Why won't \TtH\ run from Program Manager in Wind*ws?}\leavevmode\\
You need a command line. Call up the DOS prompt. If you feel the need
for a drag and drop facility, get \TtHgold.


\subsection{[La]TeX constructs \TtH\ does not seem to recognize}

\paragraph{\TtH\ does not recognize tableofcontents, backward
references, listoffigures, ...}\leavevmode\\
Yes it does, see section \ref{LaTeXfiles}, and use the \verb+-L+ switch.

\paragraph{\TtH\ does not insert my picture environments.}\leavevmode\\
If picture environment pictures are to be included, conversion to a gif file
is needed. See \ref{pict}.

\paragraph{\TtH\ messes up my tabbing environment.}\leavevmode\\
Tabbing is not currently supported. It is alien to the HTML document
mark-up approach. See section \ref{tabhal}.

\index{switches!-L}\index{frac command!see switch -L}
\paragraph{Why doesn't $\tt\backslash$frac work in equations?}\leavevmode\\
It does, but only in \LaTeX\ documents because \verb|\frac| is not a
plain \TeX\ command. The document you are presenting to \TtH\ doubtless
has no \verb|\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 \verb|-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.


\index{extensions to \LaTeX}\index{Latex@\LaTeX\ extension packages}
\index{usepackage@\verb+\usepackage+}
\paragraph{Why does \TtH\ not recognize ... command from ... style
package?}\leavevmode\\
Let's be perfectly clear here. \TtH\ does not currently recognize 
\verb|\usepackage| and, with the exception of commands explicitly
mentioned in this manual, does not support \emph{any} of the zillions
of extensions to \LaTeX\ that exist, even if they are part of the
``standard distribution''. \TtH\ does support macro definitions, see
section \ref{texins}, and
you might find that if you explicitly \verb!\input! the style file
that you need it will recognize the macro. However, many \LaTeX\
extension packages are written in a complicated manner such that they
depend on changes in catcodes, which \TtH\ does not
support. Therefore no guarantee can be given. This is one reason why
\TtH\ deliberately does not recognize \verb|\usepackage|.

\index{line-ends}
\paragraph{Why does \TtH\ not recognize my ends of lines properly?}\leavevmode\\
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.

\index{skip space and dimension commands}
\paragraph{Why does \TtH\ complain about my skip, space, ... command?}\leavevmode\\ 
Dimensions are often inappropriate for HTML. \TtH
tries do something sensible with dimension, space, and glue
commands. 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.

\index{bibtex}
\paragraph{Can \TtH\ be made to support Bib\TeX\ bibliographies?}\leavevmode\\
It already does; see \ref{bibtex}. If \TtH\ is not finding the .bbl file
even though you used the -L switch, then you probably forgot to
generate it using \LaTeX\ \emph{and} Bib\TeX, or perhaps it is in the
wrong place. Try using the \TtH\ switch -a.\index{a@-a switch}\index{switches|-a}  

\index{support}
\paragraph{Does \TtH\ support ...?}\leavevmode\\ Probably yes if it is part
of \LaTeX. But if you want a specific additional capability, and find
that it is not supported, why not write a TeX macro to support it and
translate it into suitable HTML using the functions described in this
manual. Then you will have your support and if you send it to
\verb!tth(at)hutchinson.belmont.ma.us! (with the usual character
substituted in the email address), it may be possible to include it
into the standard \TtH\ executable and you'll have helped all the
other users of \TtH.

\subsection{HTML output that does not satisfy}

\label{headbody}\index{head@\verb+<head>+}\index{body@\verb+<body>+}
\paragraph{Why doesn't \TtH\ automatically generate} \verb!<head>!
and \verb!<body>! \textbf{HTML tags?}\leavevmode\\
 First, the \verb!<head>! and
\verb!<body>! tags are \emph{optional} in the HTML specification. There is
no need for \TtH\ to generate them to statisfy the standard. Second, \TeX
and \LaTeX\ files do not have a corresponding structural division into
separate head and body sections. It might seem as if \LaTeX\ does, with
\verb!\begin{document}!  being the divider, but there are many cases
where this mapping is incorrect. For example title may not be defined
until after \verb!\begin{document}!, corresponding to the HTML body
section, whereas it must be in the head section. Finally, if \TtH
automatically entered \verb!<head>! and \verb!<body>! tags, then the
thoughtful author would not be able to enter them where they ought to
be by using, for example:\leavevmode\\
\verb!%%tth: \begin{html} <head> \end{html}!\leavevmode\\
Therefore, the choice \emph{not} to produce these tags automatically
is a deliberate one based on a careful consideration of the advantages
and disadvantages. An author can always adjust their \TeX\ code to
include them, if they wish to be pedantic about the division. See also
the section on HTML style [\ref{htmlstyle}].

\index{title!TeX commands not expanded in}
\paragraph{Why don't \TeX\ commands get expanded in the HTML title?}\leavevmode\\
In HTML, the stuff that goes in the \verb|<title>...</title>| of a
page is not permitted by the specification to contain HTML tags -
things in angle brackets - and tags are not interpreted. If an
equation or some other command that \TtH\ translates into HTML
formatting is in the title, then the title will break when
expanded. Therefore \TtH\ deals with commands differently in the
title.  By default it leaves them in the \TeX\ form that they started
as, since that is about as easy to read as any unformatted
mathematics. Using the -n? switch enables control of the precise
behaviour. See \ref{n-switch}.

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

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

\ifx\TtMgold\undefined
\paragraph{What is this strange result using $\tt\backslash$dot
$\tt\backslash$hat $\tt\backslash$tilde $\tt\backslash$frac
$\tt\backslash$vec ... in in-line equations?}\leavevmode\\
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\ \emph{will} render all these built-up constructs
correctly in a \emph{display} equation. See also \ref{inline} and
\ref{yswitch} for alternatives.
\fi

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

\index{dagger}
\paragraph{Why does a dagger sign come out strange?}\leavevmode\\
Browsers don't generally have a dagger sign in their fonts. \TtH\ uses a
kludge.

\index{Composer}
\paragraph{The file I ``published'' using Netscape Composer looks
messed up when viewed on a Mac.}\leavevmode\\
Don't use Composer on \TtH\ documents. See section \ref{nscomp}.

\index{fbox}
\paragraph{Why does \TtH\ mess up my $\tt\backslash$fbox,
minipage, etc?}\leavevmode\\ The whole concept of a ``box'' is not really
translatable into HTML. \TtH\ tries to mimic the box using tables. But
in some cases, especially in equations, it can't cope.

\index{calligraphic}
\paragraph{How do I get caligraphic fonts, \{$\tt\backslash$cal E\}, AMS
fonts,  etc?}\leavevmode\\
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 \verb|\cal| to be
something different, such as \verb|%%tth:\def\cal{\it\color{red}}|.

\index{double-quotes}
\paragraph{Why does \TtH\ turn double-quotes into an accent
instead of quotes?}\leavevmode\\ In basic \TeX\ the double quotes character
\verb+"+ 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 provide the umlaut over accent
and for some other special needs. \TtH\ supports these German uses in
some appropriate contexts. English speakers should adopt proper \TeX
quote usage.  There is essentially never a situation in \LaTeX\ where
it is advisable to use a double quote to represent itself outside of a
verbatim section (where it will naturally be treated literally). In
Plain \TeX\ you might need it. If so, \verb!\char`"! is an
absolutely fool-proof way to insert it. Here it is:\char`". 
You can also just enclose it in braces thus:\{{"}\}. 

\index{p@\verb+<p>+}
\paragraph{Why doesn't TtH output use $\rm <p>$ for paragraphs?}\leavevmode\\
 For the first years of its existence it
did. However, standards of HTML interpretation have grown tighter to
the point where \verb!<p>! is a great liability. In XHTML (the latest
HTML standard) \verb!<p>! is a container element. It must have a
closing \verb!</p>!; so that every paragraph must be its own
group. This compulsion is contrary to \TeX\ usage. Therefore TtH
changed to dispense completely with any use of \verb!<p>!, using an
empty \verb!<div>! with an associated CSS style instead. This has the
significant benefit of ensuring that for standards-compliant browsers,
font changes propagate even into the cells of tables. (NS4 is not
compliant, Mozilla, NS7 etc are, in this respect.)

\subsection{How to write \TeX\ designed for Web publishing}

\index{Tth@\TtH-only code}\index{iftth}
\paragraph{How do I insert code that is used only by \TtH, not \TeX?}\leavevmode\\
Use \verb+%%tth:+ followed by the material you wish to pass to \TtH.
\TeX\ omits this line as a comment. Alternatively, insert \verb|\newif\iftth|
at the top of your document, then use a conditional:
\verb|\iftth \TtH\ material \fi|. TtH recognizes \verb|\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.

\index{HTML!tags}
\paragraph{How do I insert HTML tags into my file without \TeX\ knowing?}\leavevmode\\
Use \verb+%%tth:+ then on this line put 
\verb+\begin{html} tags \end{html}+. Do not try to continue this
html onto a second line with a second \verb+%%tth:+ before the
\verb+\end{html}+ because the html environment will output the
\verb+%%tth:+, which it probably not what you want. Another way to
pass codes directly to the output is the \verb+\special{html: ... }+
command. Do
\emph{not} use \verb+\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.

\index{Tex@\TeX-only code}
\paragraph{How do I insert code that is used only by \TeX, not \TtH?}\leavevmode\\
Insert \verb|\newif\iftth| at the top of the file and then use
the conditional constr
uction:
\begin{verbatim}\iftth\beginsection{The \TtH\ Header}\par\else\beginsection{The \TeX\ Header}\fi
\end{verbatim}
The `else' clause may also be used with a blank first clause, of
course: \verb|\iftth\else ... \fi|.
Alternatively, insert the definition \verb+\def\tthdump#1{#1}+ at the
top of the file and then use \verb+\tthdump{\TeX\ material}+ to pass
stuff only to \TeX. The command \verb+\tthdump+ is an internal command
for \TtH\ (which cannot be redefined) that simply discards its argument.
Thus, for example, the following will output
alternate versions from \TeX\ and \TtH.\begin{verbatim}
\def\tthdump#1{#1}
%%tth:\begin{html}<H1>The HTML Header</H1>\end{html}
\tthdump{\beginsection{The \TeX\ Header}\par}
\end{verbatim}

\index{styles}
\paragraph{How do I include the style file ...sty for the \TeX\ paper I prepared for... journal?}\leavevmode\\ 
 If you must, put it in the same directory as your .tex file and see
 if it works. If it crashes, you may have to write a simpler one.
 Remove the old style file. 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.

\index{tables!bordered cells filled in}
\paragraph{In bordered tables I want an empty cell to look
empty. How do I make \TtH\ do that?}\leavevmode\\
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 \verb+&~&+ in the \TeX.

\index{hash sign}
\paragraph{How do I include into a macro I am defining a \# sign
for an HTML reference?}\leavevmode\\
When you do \verb!\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
\verb|\def\localhref{\special{html:<a href="#reference">}}| then \TeX
will complain as follows:\begin{verbatim}
! Illegal parameter number in definition of \localref.
<to be read again> 
                   r
l.3 \def\localref{\special{html:<a href="#r
                                            eference">}}
?\end{verbatim} This problem is caused by \TeX's syntax analysis of
the contents of the definition. One solution is to {\it hide} the
definition from \TeX\ using \verb|%%tth:|. An alternative definition
that avoids this problem must also be included for \TeX's benefit, for
example thus:\begin{verbatim}
\def\tthdump#1{#1}
\tthdump{\edef\localref{[a hyperreference]}}
%%tth:\def\localhref{\special{html:<a href="#reference">}}
\end{verbatim}
Alternatively, use \verb+\#+ in place of \verb+#+ in the hypertex
reference. \TtH\ specifically recognizes this as a literal and does
appropriate translation. For example
\begin{verbatim}
\def\localhref#1#2{\special{html:<a href="\##1">}#2\special{html:</a>}}
\end{verbatim}
will use its first parameter as a local anchor reference, preceded by \verb|#|,
and its second as the text of the anchor. The sequences \verb!\%! and
\verb!\\! are also treated as escaped literals, inserting their second
character, inside a raw html section.

\index{URL}
\paragraph{How do I construct a macro to take as a single
argument a URL, which may contain special \TeX\ characters like} 
\verb|_ ~ @ &| 
\textbf{etc, that makes \TtH\ construct a hyperreference but \TeX\ just enter it in the
text?}\leavevmode\\ Use the built-in command \verb!\url{...}!. This behaves in
essentially the same way as the command defined in \LaTeX's
url.sty. The reference will appear verbatim in the text (in teletype
font).

\subsection{Formerly Frequently Asked Now Rarely Asked}

\index{FILES}
\index{file not found}
\index{input@\verb+\input+!``file not found'' error}
\paragraph{Why does \TtH\ only manage to input a limited number
of files, perhaps 15 or so, then report ``file not found'' after
that?}\leavevmode\\
This is a limitation of the operating system. It has only a limited
number of file handles available. In MSDOS this number is set by a command 
\verb!FILES=...! in the operating system configuration file
\verb|config.sys|. It needs to be set to a number large enough to
accommodate all the input or include files that your \TeX\ document
uses, plus whatever other file overhead the operating system is
using. Under OS/2 a similar limitation exists and is avoided by 
increasing the number of allowable file handles in the emx run-time
system (e.g.~SET EMXOPT=-c -h400 in config.sys). 

\index{WinNT}
\paragraph{\TtH\ seems not to work on WinNT when converting
included PostScript} files, even though my ps2gif program works fine
from the command line. What is the problem?\leavevmode\\
The problem is not \TtH. It appears to be an operating system
problem. The batch program ps2gif is breaking for some strange reason
when called from \TtH. See footnote \ref{ps2gifprob}.

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

\printindex

\end{document}


