TTM: a "TEX to HTML" translator.
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 HTML and output
10.1 Formal HTML validation
10.2 HTML Styles
11 Browser and Server Problems
11.1 Accessing Symbol Fonts: Overview
11.2 Accessing Symbol Fonts: Details
11.3 Printing
11.4 Netscape/Mozilla Composer
11.5 Other Browser Bugs
11.6 Web server problems
12 Code Critique
13 License
14 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
- Font styles: \it, \bf, \sl, \uppercase, everywhere,
\rm in most situations
1.
- Accented characters written like \"o or \'{e}.
- Guess the intent of font definitions, i.e. \font commands
[optionally, remove contruct].
- Macro definitions that are global: \gdef, \xdef,
\global\def, \global\edef; or local to the
current group: \def, \edef.
- Definitions with delimited arguments.
- Input of files [see 8.2].
- Newcount, number, advance and counter setting [global counter setting
only].
- Conditionals: iftrue,
iffalse,
ifnum,
ifodd,
ifcase,
if [for defined commands and plain characters, not some internals]
2, ifx [only for
defined commands and counters; internals appear undefined], ifvmode,
ifmmode, newif.
- Centerline, beginsection, item, itemitem, obeylines; hang, hangindent,
narrower [for entire paragraphs, hangafter ignored].
Headline is made
into a title, footnote{}{}. Comments: removed.
- Tables: halign [uses border style if the template contains
vrule.]. Settabs, \+.
- Simple uses of \hbox,\vbox and \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.
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 ernalt.
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 pro