TTM: a "TEX to HTML" translator.

TtM icon
Version 4.04

Abstract

TTM translates TEX documents that use the Plain macro package or LATEX, into HTML. TTM is based on the highly successful translator TTH, but translates the equations into MathML instead of HTML. It is extremely fast and completely portable. It produces web documents that are more compact and managable, and faster-viewing, than those from other converters, because it really translates the equations, instead of converting them into images.

Contents

1  Capabilities
    1.1  Plain TEX
        1.1.1  Mathematics
        1.1.2  Formatting and Macro Support
    1.2  LATEX
        1.2.1  Environments:
        1.2.2  LATEX Commands:
    1.3  Special TEX usage for TTM
    1.4  Unsupported Commands
2  Installation
3  Usage
4  Messages
    4.1  Mathematics Layout Style Improvement using CSS
5  Features dependent on external programs.
    5.1  Independence of [La]TEX installation and the -L switch.
    5.2  BibTeX bibliographies
    5.3  Indexing
        5.3.1  Glossaries.
    5.4  Graphics Inclusion: epsfbox/includegraphics
    5.5  Picture Environments
6  Tabular Environment or Halign for Tables
    6.1  Tabular
    6.2  Halign
    6.3  Longtables
7  Boxes, Dimensions, and fills
8  TEX command definitions and other extensions
    8.1  Delimited-parameter macros and Conditionals
    8.2  Macro- and Style-file inclusion
    8.3  Layout to include arguments of unknown commands
    8.4  Restrictions on redefinition of internal commands
        8.4.1  Footnotes
9  Color
    9.1  LATEX Color
    9.2  Plain Color
    9.3  Limitations
10  Producing output split into different files.
    10.1  Overview
    10.2  Navigation Controls at File Top and Tail
    10.3  Special Precautions when Splitting Output
        10.3.1  Floats such as figures or tables
        10.3.2  Multiple Bibliographies
11  HTML and output
    11.1  Formal HTML validation
    11.2  HTML Styles
12  Browser and Server Problems
    12.1  Accessing Symbol Fonts: Overview
    12.2  Accessing Symbol Fonts: Details
    12.3  Printing
    12.4  Netscape/Mozilla Composer
    12.5  Other Browser Bugs
    12.6  Web server problems
13  Code Critique
14  License
15  Acknowledgements
A  Appendix: Non-Standard TEX Macros
B  Appendix: Frequently Asked Questions
    B.1  Building and Running TTM
    B.2  [La]TeX constructs TTM does not seem to recognize
    B.3  HTML output that does not satisfy
    B.4  How to write TEX designed for Web publishing
    B.5  Formerly Frequently Asked Now Rarely Asked
Index

1  Capabilities

1.1  Plain TEX

1.1.1  Mathematics

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

1.1.2  Formatting and Macro Support

1.2  LATEX

LATEX support includes essentially all mathematics plus the following

1.2.1  Environments:

em, verbatim, center, flushright, verse, quotation, quote, itemize, enumerate, description, list [treated as if description], figure, table, tabular[*,x], equation, displaymath, eqnarray, math, array [not generally in in-line equations], thebibliography, [raw]html, index [as description], minipage [ignoring optional argument], longtable [but see 6.3].

1.2.2  LATEX Commands:

[re]newcommand, newenvironment, chapter, section, subsection, subsubsection, caption, label, ref, pageref [no number], emph, textit, texttt, textbf, centering, raggedleft, includegraphics, [e]psfig, title, author, date [maketitle ignored: title etc inserted when defined], lefteqn, frac, tableofcontents, input, include [as input, 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.

1.3  Special TEX usage for TTM

A few non-standard TEX commands are supported as follows 3. See also 5.4. 
\epsfbox{file.[e]ps} Puts in an anchor called "Figure" linked to 
    file.[e]ps (default), or alternatively calls user-supplied script 
    to convert the [e]ps file to a gif image and optionally inline it.  
\special{html:"tags"} inserts ``tags'' into the HTML e.g. for images etc.  
\href{reference}{anchor} highlights ``anchor'' with href=``reference''.
\url{URL} like \href but with URL providing both reference and anchor.
\begin{[raw]html} ... \end{[raw]html} environment passed direct to output.
\ttmtensor Subscripts and superscripts immediately following, on simple
    characters, are stacked up in displaystyle equations, not staggered. 
\ttmdump{...} The group is omitted by ttm. Define \ttmdump as a nop for TeX.
%%ttm:... The rest of the comment line is passed to ttm (not TeX) for parsing.

1.4  Unsupported Commands

When TTM encounters TEX constructs that it cannot handle either because there is no HTML equivalent, or because it is not clever enough, it tries to remove the mess they would otherwise cause in the HTML code, generally giving a warning of the action if it is not sure what it is doing. The following are not translated. 
 \magnification \magstep etc : Removes the whole construct.
 Some boxes in equations.
 \raisebox, \lowerbox and similar usages.
 \accent, \mathaccent. 

2  Installation

The source for TTM is flex code which is processed to produce a C program ttm.c which comprises the distribution. This file is compiled by 
	gcc -o ttm ttm.c
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".

3  Usage

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. 
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 ttm 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. 
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 < and >, 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".
TTM is extremely fast in default mode on any reasonable hardware. Conversion of even large TEX files should be a matter of a second or two. This makes it possible to use TTM in a CGI script to output HTML directly from TEX source if desired; (stderr may then need to be redirected.)

4  Messages

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

Error Messages

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

Warnings

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

Informational and external

Lines with no **** are either informational, meaning the state of the translation is not considered abnormal, or else they may come from external programs (e.g. makeindex), over which TTM has no control.
The switch -v causes more verbose messages to be output, which may be helpful for understanding why errors are reported. A higher level of verbosity -V can be invoked, but is intended primarily for internal debugging of TTM and will rarely be comprehensible!
The presumption that lies behind TTM message design is that the file being translated has been debugged using TEX or LATEX to remove syntax errors. TTM 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 \input. Therefore error reporting by TTM does not reach even the low standard of clarity set by TEX and LATEX error messages. Although TEX files can be debugged using TTM alone, since it is very fast, the process is not recommended for inexpert TEX users. Moreover, since TTM understands both TEX and LATEX simultaneously, it can parse some files that TEX or LATEX  separately cannot.
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 in-line in plain HTML, although TTM will render them well in displaystyle. These latter constructs are nevertheless commonly used in in-line TEX. By default TTM renders these constructs in a relatively intuitive way. For example $\hat{a}$ is rendered ∧a. The result is rarely elegant but it is unambiguous.

4.1  Mathematics Layout Style Improvement using 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.
Vertical Compression   of the otherwise sometimes rather spread-out mathematics is implemented on TTM 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 -y, which permits a numeric argument, e.g. -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 -y with an even numeric argument (or none at all), e.g. -y2 or -y.
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 TTM version 3.87 it is used as default. It can be turned off using the -y switch with the second bit (2) zeroed in the numeric argument. For example -y1 or -y0 turns it off.

5  Features dependent on external programs.

5.1  Independence of [La]TEX installation and the -L switch.

A major difference between TTM and LaTeX2HTML is that TTM does not call the LATEX or tex programs at all by default, and is not specifically dependent upon these, or indeed any other (e.g. PERL), programs being installed on the translating system. Its portability is therefore virtually universal.
Forward references in LATEX are handled by multiple passes that write auxiliary files. TTM does only a single pass through the source. If you want TTM to use LATEX constructs (e.g. tableofcontents, bibliographic commands, etc.) that depend on auxiliary files, then you do need to run LATEX on the code so that these files are generated. Alternatively, the TTM switch -a causes TTM 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, TTM 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 TTM as a filter, you must tell TTM, using the switch -Lfilename, the base file name of these auxiliary files (which is the name of the original file omitting the extension). If TTM cannot find the relevant auxiliary file because you didn't run LATEX and generate the files or didn't include the switch, then it will omit the construct and warn you. Forward references via ref will not work if the .aux file is unavailable, but backward references will. The -L switch with no filename may be used to tell TTM that the document being translated is to be interpreted as a LATEX file even though it lacks the usual LATEXheader commands. This may be useful for translating single equations that (unwisely) use the \frac command.

5.2  BibTeX bibliographies

TTM supports bibliographies that are created by hand using \begin{thebibliography} etc. Such bibliographies do not require anything beyond the .aux file. TTM also supports bibliographies created using BibTEX from a biblography database. The filename.bbl file is input at the correct place in the document. However, this filename.bbl is not created automatically by LATEX. In addition to running LATEX on the source file to create the auxiliary file, you must also execute bibtex filename in the same directory, to create the filename.bbl file, and then run LATEX again to get the references right. (This is, of course, no more than the standard procedure for using BibTEX with LATEX but it must be done if you want TTM to get your bibliography right). If you don't create the .bbl file, or if you create it somewhere else that TTM does not search, then naturally TTM won't find it. Since the BibTEX process is relatively tortuous, TTM offers an alternative. Using the -a switch with TTM will cause it to attempt to generate the required .bbl file automatically using BibTEX and LATEX.
There are many different styles for bibliographies and a large number of different LATEX extension packages has grown up to implement them, which TTM does not support. More recently, a significant rationalization of the situation has been achieved by the package natbib. TTM has rudimentary support built in for its commands \citep and citet in the default author-date form without a second optional argument. A style file for natbib is distributed with TTMgold which makes it possible to accommodate most of its more useful styles and commands and easily switch from author-date citation to numeric citation.

5.3  Indexing

TTM 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. TTM indexes LATEXdocuments by section number rather than by page; assuming, of course, that they have been prepared with index entries in the standard LATEX fashion.
When processing a LATEX file that contains the \makeindex command in its preamble, TTM will construct an appropriately cross-hyperlinked index that will be input when the command \printindex is encountered, which must be after all the index references \index{ ... } in the document. TTM does this independently of LATEX, but not of the subsidiary program makeindex that is normally used with LATEX to produce the final index. TTM creates its index entries in a file with extension .tid (Tth InDex). Unfortunately the standard form that makeindex expects for compound numbering of its sections or pages is "1-2", separated by a dash. TtM changes that to "1.2" using a point, and has to output a style file filename.mst , where filename is the base filename of the latex file being processed, to enable makeindex to handle this form. When the \printindex command is encountered, TTM closes the .tid file and runs the command 
makeindex -o filename.tin filename.tid
on it. This creates an output file filename.tin, and then TTM reads that file in as its index. If, instead of creating an index file during TTM processing, one wants to use with TTM an index file already created, all that is needed is to remove the \makeindex command from the top of the LATEX source and copy the existing .ind file to a .tin file that will be input by \printindex. No indexing files will be written or deleted without a \makeindex command in the document.
The \makeindex command, if present, will also cause TTM to add a linked entry called "Index" to the end of any table of contents. This entry is a highly desirable feature for an HTML file, but if there is no \printindex command at the end of the document, the index will not exist, so the reference will be non-existent.
On some operating systems with file name length restrictions, the makeindex program is called makeindx. Therefore a TTM switch is provided: -xcommandline, which substitutes commandline for the default call makeindex. Therefore, -xmakeindx will switch to the correct program name on one of these limited operating systems. This switch also allows additional parameters or switches to be passed to makeindex. If the -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 -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 TTM or LATEX, except by hand.
All of the index file processing naturally requires that TTM have write permission for the directory in which the original LATEX file (specified by the -L switch) resides.
Layout of the index   can be controlled with the switch -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. TTM 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 -j20. A switch -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 -j1 will cause the columns to break at every indexspace, that is generally at every new letter, so letter lists will alternate between columns.

5.3.1  Glossaries.

LATEX has a parallel set of commands for glossary construction, replacing "index" with "glossary". However, there is no \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. TTM does not support a glossary separate from the index. Instead it simply defines the command as \def\glossary{\index} with the result that glossary entries are placed in the index. It may be necessary to add \makeindex and \printindex commands to make TTM handle the glossary entries for a file that has only a \makeglossary command.

5.4  Graphics Inclusion: epsfbox/includegraphics

The standard way in plain TEX to include a graphic is using the epsf macros. The work is done by \epsfbox{file.[e]ps} which TTM can parse. By default TTM produces a simple link to such a postscript file, or indeed any format file.
Optionally TTM can use a more appropriate graphics format, possibly using a user-supplied (script or) program called ps2png or ps2gif to convert the postscript file to a png4 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, TTM tries to find a postscript file with extension that starts either .ps or .eps and convert it, first using ps2png then, if unsuccessful, ps2gif. Linux (un*x) ps2png and 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 5 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 ps2png (or gif) is supplied must be of the form: 
ps2png inputfile.ext outputfile.ext
The program must have permission to write the outputfile (file.png) in the directory in which the file.ps resides.
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, TTM passes to ps2gif (or png) a third argument consisting of the name, "file_icon.gif", of an icon file. ps2gif is expected to create it from the same postscript file. In other words the call becomes 
ps2gif file.eps file.gif file_icon.gif
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 ps2gif will not then be called.
The LATEX2e command \includegraphics{...} and the older \[e]psfig{file=...} are treated the same as \epsfbox. Their optional arguments are ignored.
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, TTM supports postscript, encapsulated postscript, gif, and jpeg, plus any future formats that become supported by common browsers. However, LATEX does not support these other formats, so it will give an error message if it can't find a postscript file, unless you specify the bounding box, thus preventing LATEX interrogating the file.

5.5  Picture Environments

The picture environment cannot be translated to HTML. Pictures using the built-in LATEX commands must be converted to a graphics file such as a gif, and then included using \includegraphics, see 5.4. The switch -a, causes TTM to attempt automatic picture conversion using a user-supplied routine latex2gif. When this switch is used, TTM outputs the picture to a file picn.tex, where n is the number of the picture (if there does not already exist a file picn.gif). It then calls the command latex2gif picn which must be a command (e.g. a script using LATEX, dvips, etc.) on the system, which converts the file picn.tex to a file picn.gif. An example linux script is included in the distribution but this conversion script is dependent on the system and so is entirely the user's responsibility. For viewing the results, the files picn.gif must be accessible to the browser in the same directory as the HTML files, then they will be included in-line. It is impossible for a picture environment to be converted in this automatic fashion if it contains macros defined somewhere else in the original LATEX file, because the macros will then be undefined in the picture file that is extracted, and LATEX will be stumped. In that case, manual intervention is necessary.

6  Tabular Environment or Halign for Tables

The tabular environment is the recommended way to construct tables in LATEX. In plain TEX, although \settabs etc. is supported, the \halign{ ... } command is recommended. (The LATEX tabbing environment is not supported by TTM because it is antithetical to the spirit of HTML document description, and because it is an extremely complicated construct. If you are lucky, TTM 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 achievable6. However, the limitations of HTML tables impose the following limitations on the translation.

6.1  Tabular

6.2  Halign

6.3  Longtables

7  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 
\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}
are on a line by themselves. You get:
The left the Right

Matter to be set in horizontal mode to a limited hsize
Stuff to the right of the makebox.

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 12.5] 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 \mbox which is often used in LATEX for introducing text inside equations.
Negative skips are not supported at all.
The only important dimension parameter that is currently interpreted is \hsize. It is what controls the width of a vbox. It can be reset using the plain TEX format e.g. \hsize = 3in or scaled or advanced e.g. \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 \hsize.
TTM trys valiantly to mimic the sort of text alignment that is obtained using glue such as \hfil and \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, TTM will completely ignore the glue outside an hbox, and it doesn't know the difference between \hfil and \hfill, etc.

8  TEX command definitions and other extensions

8.1  Delimited-parameter macros and Conditionals

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 TTM. In such cases it is all too possible for the delimited parameter not to be matched, resulting in a runaway argument situation. Thus, delimited parameter macros are especially dangerous when using TTM, or indeed any process other than TEX itself. (And they are never exactly "safe TEX"). The recognition of these definitions can be disabled using the -d switch, in which case the definitions are simply discarded.
Conditionals such as \if, \ifnum and so on are supported, as listed above (1.1.2). In TTM they have one syntax limitation. Further `if' commands are not permitted in, or as part of a command expanded in, the tokens, characters, or numbers being tested. Thus, an example of truly perverse usage such as
\ifnum 1=\if ab 1\else 2\fi  True \else False \fi
will likely break. Nested `if' constructs are permitted in the conditional text, however, so
\ifnum 1=1 True\if ab -true\else -false\fi \else False \fi
is fine. Because TTM does not internally resemble TEX, whereas the result of conditionals such as \if and \ifx may depend on internal representations, there cannot be 100% compatibility of such tests at the lowest level. Still, tests on externally defined commands ought generally to give correct results. When authoring documents in TEX one is generally well advised to avoid conditionals.
Although TTM supports a remarkably complete subset of LATEX, it does not support all of the complicated primitive details of TEX, partly because that would be unnecessary. For example, practically any TEX that redefines category codes (other than @ which TTM treats universally as a letter) will break because TTM 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 TTM expects only letters or @ in user-defined command names, not punctuation characters etc.

8.2  Macro- and Style-file inclusion

Macro definitions are fully supported by TTM. 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. TTM does not recognize the \usepackage command by default because the LATEX macros that are input by this command almost always contain catcode changes or other usages incompatible with TTM. That is another reason why TTM 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 TTM. Thus, the macro definitions are included when "TEX"ing the file, but not when "TTM"ing it. It should be clear from this discussion, however, that TTM 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 TTM.
TTM will find an input file if
  1. the full path is specified relative to the directory from which TTM is run, e.g.
    \input /home/myhome/mytexdir/mymacro.tex
  2. the -p switch specifies a path on which the file is found, or
  3. the TTHINPUTS environment variable is defined to be a path on which the file is found.
Paths are searched in this order until an appropriate file is found or all directory options are exhausted
This policy provides a mechanism for making available the alternative package for TTM, without alteration of the original TEX files, by placing the (simplified) version of the macro package on the path TTM searches. An example using the -p switch might be 
ttm >file.html <file.tex -p/usr/local/ttminputs:~/myttminputs
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, TTM-compatible, TEX macros.
When TTM 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 \inputing them. Therefore a special switch -pNULL is provided that disables all \input or \include files.

8.3  Layout to include arguments of unknown commands

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

8.4  Restrictions on redefinition of internal commands

In TTM (unlike TEX) most internal commands can not normally be redefined; any redefinition will simply be ignored (except inside edef and a few other places). This prevents TTM from safely allowing use of major packages that redefine standard TEX commands. For example amsTEX redefines footnote to have just one argument, which will cause problems. This particular example is potentially a problem with LATEX too, which also redefines footnote. TTM 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 TTM explicitly which type the file is. (Besides, a mixed file will play havoc with TEX itself.)

8.4.1  Footnotes

Footnotes are placed together at the end of the document, or, in the case of TTMgold splitting files, in a separate file called footnote.html. The title of this end section is determined by the macro \tthfootnotes. By default this is "Footnotes", but can be redefined by the user at will, e.g. by \def\tthfootnotes{Tailnotes}.

9  Color

TTM supports the coloring of text using the color package macros for LATEX, supported by dvips (but not xdvi). TTM also supports the Plain TEX colordvi macros contained in the package colordvi.tex that do the same thing.

9.1  LATEX Color

The LATEX syntax is recommended because the 68 standard named colors7 are directly supported internally by TTM 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}{...}, \textcolor[rgb]{0.,.5,0.}{...}, \textcolor[cmyk]{0.,.5,0.,0.3}{...}. You can define custom colors in the usual way using, for example 
{\definecolor{Puce}{rgb}{1.,.5,.8}
\color{Puce} This is my own Puce.}
Which gives " This is my own Puce."
The command \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 <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. \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 \colorbox and \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. "This sentence" is the result of the command \colorbox{green}{``This sentence''}. If it is colored, then your browser supports style sheets to this extent. If not, check your preferences settings.

9.2  Plain Color

The Plain TEX syntax using commands such as \Red{red text} requires the file colordvi.tex to be input prior to their use. But because TTM does not search the standard TEX paths, that file will not usually be found unless the full path is explicitly specified. If the file is not found, only the 8 standard colors 
\Red, \Green, \Blue, \Cyan, \Magenta, \Yellow, \Black, and \White
are recognized internally by TTM. You can use the user-defined CMYK numeric style 
\Color{0. .5 .5 0.}{pale red}
without the colordvi file. It gives the result "pale red" but the notation becomes cumbersome unless you define your color e.g. like 
\def\redcolor{0. .5 .5 0.}
\Color{\redcolor}{The stuff that is red.}
Another difficulty with the colordvi command \textColor (which is the color 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 \textColor often gives HTML files that won't pass HTML validation.

9.3  Limitations

Color commands do not propagate into different cells of HTML tables because of what may be regarded as a browser bug [12.5]. 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.

10  Producing output split into different files.

10.1  Overview

Because the TTM program itself always produces just one output file, the division of the output into different files takes place in two steps. First, TTM is run on the LATEX file with the switch -s (for "split"). This switch tells TTM to produce output that is in 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 TTM 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 
ttm -s -Ltexdocument <texdocument.tex >mimedocument.html
would produce such a file called mimedocument.html from a LATEX file called texdocument.tex. The switch -L tells TTM 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 html, you can use just 
ttm -s texdocument
There are available standard tools for unpacking multipart mime files into their individual files, notably the mpack tools available from the "Andrew" distribution, which may be available on some systems. However the executable ttmsplit (whose source is in the ttmgold directory) is a more specific program that will unpack MIME files produced by TTM. (ttmsplit will not handle general MIME files.) To unpack the multipart file into its individual files requires the simple command: 
ttmsplit <mimedocument.html
This will inform the user of the files produced, for example 
index.html
chap1.html
chap2.html
refs.html
footnote.html
the file 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 ttm can be piped to ttmsplit to produce the split files directly by the command line: 
ttm -s -Ltexdocument <texdocument.tex | ttmsplit
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 ttm-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.

10.2  Navigation Controls at File Top and Tail

By default TTM 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 TTM 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 
\def\ttmsplittail{
 \special{html:\n<hr><table width=\"100\%\"><tr><td>
 <a href=\"}\ttmfilenext\special{html:\">}NEXT
 \special{html:</a></td><td align=\"right\">
 <a href=\"index.html\">HEAD</a></td></tr></table>\n</html>}}
\def\ttmsplittop{
 \special{html:<table width=\"100\%\"><tr><td>
 <a href=\"}\ttmfilechar\special{html:\">}PREVIOUS
 \special{html:</a></td><td align=\"right\">
 <a href=\"index.html\">HEAD</a></td></tr></table>}}
The macro \ttmsplittail 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, \ttmsplittop is called. Note that these macros use the builtins \ttmfilenext and \ttmfilechar 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.

10.3  Special Precautions when Splitting Output

10.3.1  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 TTM 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 TTM 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: 
\input /usr/local/ttm/ttmprep.sty
where the path should be to wherever you unpacked or are keeping the ttm distribution file ttmprep.sty. Then LATEX should be run twice on the file to create the auxiliary files that ttm will use in its translation. Because of the extra definitions in ttmprep.sty, the auxiliary files so produced can be interpreted by ttm to give correctly linked split files. If you want to produce dvi output from your LATEX then you should remove this extra input command. None of this is needed unless splitting by sections (not chapters) is to be performed or floats are problematic.
To make it easier for the user, a script is provided called ttmprep which automates the process of producing satisfactory auxiliary files through the single command 
ttmprep texdocument.tex
The script will leave the LATEX file in its original condition, but the auxiliary files in appropriate form for TTM.

10.3.2  Multiple Bibliographies

Multiple bibliographies in split files are a problem. All the citations in the rest of the text link to a single file refs.html because there is no way for TtMgold know the name of other files to refer to. However, each time a bibliography is started, when splitting, TtMgold starts a new file. TtMgold numbers reference files after the first as refs1.html refs2.html etc.
After splitting the output using ttmsplit, 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 ttmrfcat will do this if run in the directory where the split files reside. It destroys all the refsx.html files. But since those were generated by TtMgold, they can always be generated again. Some spurious file navigation buttons will remain in the resulting 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.

11  HTML and output

11.1  Formal HTML validation

TTM 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 TTM-translated documents follow is strictly HTML4.0[1]8 Transitional. However, TTM does not formally validate its documents, and can be made to violate the standard by some TEX usage.
One reason for violation arises because HTML4.0 requires a <title>...</title> for every document. A title is constructed from LATEX files that contain the \title{...} command, in which case HTML conformance is ensured by putting the \title command before any text (i.e. in the preamble, where it belongs). If the \title command is not desired in the TEX file, for example because it is a plain TEX document, a title can be provided by the author for the HTML document by putting a line like this at the top of the TEX file. 
%%ttm:\begin{html}<title>Put the title here</title>\end{html}
This line will be ignored by TEX. Actually, any raw HTML output at the start of the file is assumed by TTM to indicate that the author has explicitly output a title. If no title indication of any of the above types is present, TTM 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 \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.

11.2  HTML Styles

There are good reasons why the <head> and <body> tags are by default omitted by TTM. See the FAQ [B.3] 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 requires that containers have both opening and closing tags. Therefore TTM has a switch -w? (where the question mark denotes an optional integer) that controls its writing style as follows.
Default
Construct title. Do not enter head and body tags.
-w -w0
Do not construct title or enter head/body tags.
-w1
Enter head and body tags assuming that the title is the dividing point.
-w2
Use XHTML syntax.
-w4bove). The foing tags. Vp con>Tviolatinp;-s nbsman">vlution onter head s have both ob> tT-w1
Er the outpasly a conveconstruct pan clai>
If thisdoth s EX Commands: tTss="roman Nested `if'n>,( TeX__sui 412">,( TeX_nd body commands in by hand, u 6 u œ 6 aeill continue,\but t&ºDH‹=* &¾1Àè¦èüÿƒ;&맾 H‰ßè`æüÿH…Àgs. Vp cconvecontricteand will‹Œ$De>