T_TH: a "T_EX to HTML" translator.

Version 4.04

Abstract

T_TH translates T_EX documents that use the Plain macro package or L^AT_EX, into 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.

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

1 Capabilities

1.1 Plain T_EX

1.1.1 Mathematics

Almost all of T_EX'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 ¹.
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 9.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] ², 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 L^AT_EX

L^AT_EX 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 7.3].

1.2.2 L^AT_EX 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 L^AT_EX constructs. Internal hypertext cross-references are automatically generated (e.g. by ref and tableofcontents) provided L^AT_EX has previously been run on the document and the appropriate command-line switch is used.

1.3 Special T_EX usage for T_TH

A few non-standard T_EX commands are supported as follows ³. See also 6.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.
\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.
%%tth:... The rest of the comment line is passed to tth (not TeX) for parsing.

1.4 Unsupported Commands

When T_TH encounters T_EX 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 T_TH is flex code which is processed to produce a C program tth.c which comprises the distribution. This file is compiled by

	gcc -o tth tth.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):
  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.

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".

T_TH is extremely fast in default mode on any reasonable hardware. Conversion of even large T_EX files should be a matter of a second or two. This makes it possible to use T_TH in a CGI script to output HTML directly from T_EX source if desired; (stderr may then need to be redirected.)

4 Messages

Messages about T_TH's state and its assessment of the T_EX 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 T_TH or in the T_EX of the file being translated. Some errors are fatal and cause T_TH to stop. On others it will continue, but the T_EX file probably should be corrected in order to get correct output.

Warnings

These start **** but without reporting Error. They are messages by which T_TH 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 T_EX 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 T_TH 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 T_TH and will rarely be comprehensible!

The presumption that lies behind T_TH message design is that the file being translated has been debugged using T_EX or L^AT_EX to remove syntax errors. T_TH is not good at understanding or reporting T_EX syntax errors and counts only the lines in the main T_EX file, not those in files read by \input. Therefore error reporting by T_TH does not reach even the low standard of clarity set by T_EX and L^AT_EX error messages. Although T_EX files can be debugged using T_TH alone, since it is very fast, the process is not recommended for inexpert T_EX users. Moreover, since T_TH understands both T_EX and L^AT_EX simultaneously, it can parse some files that T_EX or L^AT_EX separately cannot.

5 Mathematics

5.1 Equations

Equations are translated internally into HTML. T_TH 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 T_EX math tokens are inserted verbatim.

The internal approach to equation translation is a major area where T_TH departs from the philosophy of L^AT_EX2html and its derivatives. T_TH 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 L^AT_EX2html'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).

The option [-i] to T_TH makes italic the default font within equations, and thus the style more T_EX-like. The italic font appearance in browsers is not as satisfactory as T_EX's math italic, so for many documents roman looks better.

Spacing in equations is handled slightly differently by T_TH than by T_EX. The reason is that most browsers use fonts that will crowd the characters horizontally too close for comfort in many cases (for example: M_||/2). Also, built-up HTML equations are more spread out vertically than in T_EX. Therefore T_TH equations look better if spaces are added between some characters. So T_TH does not remove spaces in the original T_EX file between characters in equations. The author is thus able to control this detail of layout in the HTML without messing up their T_EX file - since T_EX will ignore any spaces inserted. Legacy T_EX code that contains a lot of spurious whitespace (ignored by T_EX) may, as a result, occasionally become too spread-out when translated.

5.2 In-line Equation Limitations

Some T_EX 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 in-line equations cannot be properly supported because tables cannot be placed in-line in HTML. T_TH output often will be strangely disjointed. As an option, T_TH provides switch -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 [ $ ... $ or $ ... $] 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

2 + n

This option gives a slightly strange layout for simple equations but is a big improvement for some situations, e.g. in-line matrices.

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 T_TH will render them well in displaystyle. These latter constructs are nevertheless commonly used in in-line T_EX. By default T_TH renders these constructs in a relatively intuitive way. For example $\hat{a}$ is rendered ∧a. The result is rarely elegant but it is unambiguous.

5.3 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 T_TH 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 T_TH 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.

6 Features dependent on external programs.

6.1 Independence of [La]T_EX installation and the -L switch.

A major difference between T_TH and LaTeX2HTML is that T_TH does not call the L^AT_EX 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 L^AT_EX are handled by multiple passes that write auxiliary files. T_TH does only a single pass through the source. If you want T_TH to use L^AT_EX constructs (e.g. tableofcontents, bibliographic commands, etc.) that depend on auxiliary files, then you do need to run L^AT_EX on the code so that these files are generated. Alternatively, the T_TH switch -a causes T_TH 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, T_TH constructs the name of the expected auxiliary L^AT_EX files in the usual way and looks for them in the same directory as the file. If you are using T_TH as a filter, you must tell T_TH, using the switch -Lfilename, the base file name of these auxiliary files (which is the name of the original file omitting the extension). If T_TH cannot find the relevant auxiliary file because you didn't run L^AT_EX 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 T_TH that the document being translated is to be interpreted as a L^AT_EX file even though it lacks the usual L^AT_EXheader commands. This may be useful for translating single equations that (unwisely) use the \frac command.

6.2 BibTeX bibliographies

T_TH supports bibliographies that are created by hand using \begin{thebibliography} etc. Such bibliographies do not require anything beyond the .aux file. T_TH also supports bibliographies created using BibT_EX 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 L^AT_EX. In addition to running L^AT_EX 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 L^AT_EX again to get the references right. (This is, of course, no more than the standard procedure for using BibT_EX with L^AT_EX but it must be done if you want T_TH to get your bibliography right). If you don't create the .bbl file, or if you create it somewhere else that T_TH does not search, then naturally T_TH won't find it. Since the BibT_EX process is relatively tortuous, T_TH offers an alternative. Using the -a switch with T_TH will cause it to attempt to generate the required .bbl file automatically using BibT_EX and L^AT_EX.

There are many different styles for bibliographies and a large number of different L^AT_EX extension packages has grown up to implement them, which T_TH does not support. More recently, a significant rationalization of the situation has been achieved by the package natbib. T_TH 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 T_THgold which makes it possible to accommodate most of its more useful styles and commands and easily switch from author-date citation to numeric citation.

6.3 Indexing

T_TH can make an extremely useful hyperlinked index using L^AT_EX 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. T_TH indexes L^AT_EXdocuments by section number rather than by page; assuming, of course, that they have been prepared with index entries in the standard L^AT_EX fashion.

When processing a L^AT_EX file that contains the \makeindex command in its preamble, T_TH 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. T_TH does this independently of L^A

TTH: a "TEX to HTML" translator.