TTH(1)

📦 version 4.16, in fedora 43, fedora 44

✨ tth(1) ✨

okay so bestie, this is the manual page for tth — section 1 of the manual, the TeX to HTML translator 💖. It comes with a whole little squad of auxiliary programs, and we're gonna go through all of it. Grab a snack 🍓, this one's a chonker.

🌸 NAME 🌸

tth, latex2gif, ps2gif, ps2png — a TeX and LaTeX to HTML translator, plus its auxiliary programs 🫶

💅 SYNOPSIS 💅

tth [options] [<file.tex] [>file.html] [2>err]

tth [options] file.tex [2>err]

latex2gif file (no extension)

ps2gif file.ps file.gif [icon.gif]

ps2png file.ps file.gif [icon.gif]

🦋 DESCRIPTION 🦋

tth translates TeX source that uses the plain macro package or LaTeX — including most mathematics — into a near-equivalent in HTML ✨. The formal standard that TTH-translated documents follow is strictly HTML4.0 Transitional. Periodt.

The complete documentation lives in tth_manual.html, distributed with the program. This man page is, and I quote, an incomplete summary updated on an irregular basis 🙈. [Last updated 1 May 2002 by Hans Fredrik Nordhaug.]

The program is a filter — meaning it reads from standard input and writes to standard output. On top of that, diagnostic messages about its detection of unknown or untranslated constructs get sent to standard error. So like, three streams, all doing their own thing 💅

When it's handling embedded graphical files, tth can make use of auxiliary programs — ps2gif or ps2png — which in turn make use of the ghostscript interpreter gs(1) and the Portable Bitmap Graphics suite of commands, see pbm(1).

tth is extremely fast in default mode on any reasonable hardware, no cap. Conversion of even large TeX files should be a matter of a second or two ⚡. This makes it possible to use tth in a CGI script to output HTML directly from TeX source if desired — standard error may then need to be redirected, bestie, don't forget 🔥

💖 what tth handles (TeX edition) 💖

tth handles TeX things like:

  • Almost all mathematics, including symbols, fractions, delimiters 🧮
  • {} \begingroup \endgroup — grouping
  • \it \bf \sl etc — styles
  • \beginsection
  • \centerline{}
  • \item{...} \itemitem{...} {\obeylines ...}
  • Almost all accented latin characters written like \"o, or \"{e} 🌸
  • \hang \hangindent \narrower for entire paragraphs (\hangafter ignored)
  • \headline is made into a title
  • % Comments. Simply removed.
  • \halign tables — checks template for the presence of \vrule, to decide if the table is to be border style
  • \settabs \+ style tables
  • \input: But, of course, not from the implicit texinputs path 🙈
  • \newcount, \number, \advance and counter setting
  • \def, \edef, \xdef but no delimited arguments. All definitions are global.
  • \matrix, \pmatrix but not \bordermatrix. \cases.

💜 LaTeX support 💜

LaTeX support includes essentially all mathematics plus the following environments:

  • em, verbatim, center, flushright [one paragraph only], verse, quotation, quote, itemize, enumerate, description, list [treated as if description], figure, table, tabular[*,x], equation, displaymath, eqnarray [only one equation number], math, array, thebibliography, [raw]html, index [as description]

and Latex commands:

  • [re]newcommand, newenvironment [optional arg not permitted], chapter, section, subsection, subsubsection, caption, label, ref, pageref [no number], emph, textit, texttt, textbf, centering, raggedleft, includegraphics, [e]psfig, title, author, date [not automatic], lefteqn, frac, tableofcontents, input, include [as input], textcolor, color [8 standard colors], footnote [ignoring optional arg], cite, bibitem, bibliography, tiny ... normalsize ... Huge, newcounter [no ``within'' support], setcounter, addtocounter, value [inside set or addto counter], arabic, the, stepcounter, newline, verb[*], bfseries, itshape, ttfamily, textsc, ensuremath, listoftables, listoffigures, newtheorem [no optional arguments permitted], today, printindex, boldmath, unboldmath, newfont, thanks, makeindex, index.

Hypertext cross-references within the document are automatically generated by (e.g.) ref, and tableofcontents ✨ iconic behavior honestly.

When tth encounters TeX constructs that it cannot handle — either because there is no HTML equivalent, or because it is not clever enough — it tries to remove the mess they would otherwise cause in the HTML code, generally giving a warning of the action if it is not sure what it is doing. Untranslatable TeX math tokens are inserted verbatim 💀

🧚 Independence of [La]TeX installation and the -L switch 🧚

A major difference between tth and latex2html is that tth does not call the latex or tex programs at all by default, and is not specifically dependent upon these, or indeed any other (e.g. perl) programs being installed on the translating system. Its portability is therefore virtually universal 🌈 slay.

Forward references in LaTeX are handled by multiple passes that write auxiliary files. tth does only a single pass through the source. If you want tth to use LaTeX constructs (e.g. tableofcontents, bibliographic commands, etc.) that depend on auxiliary files, then you do need to run LaTeX on the code so that these files are generated. Alternatively, the tth switch -a causes tth automatically to attempt to run latex on the file, if no auxiliary file .aux exists 👑

When run specifying a filename on the command line as a non-switch argument, tth constructs the name of the expected auxiliary LaTeX files in the usual way and looks for them in the same directory as the file. If you are using tth as a filter, you must tell tth, using the switch -Lfilename, the base file name of these auxiliary files — which is the name of the original file omitting the extension. If tth cannot find the relevant auxiliary file because you didn't run LaTeX and generate the files, or didn't include the switch, then it will omit the construct and warn you ⚠️ Forward references via ref will not work if the .aux file is unavailable, but backward references will. The -L switch with no filename may be used to tell tth that the document being translated is to be interpreted as a LaTeX file even though it lacks the usual LaTeX header commands. This may be useful for translating single equations that (unwisely) use the \frac command 🙈

📚 BibTeX bibliographies 📚

tth supports bibliographies that are created by hand using \begin{thebibliography} etc. Such bibliographies do not require anything beyond the .aux file. tth also supports bibliographies created using BibTeX from a biblography database. The filename.bbl file is input at the correct place in the document. However, this filename.bbl is not created automatically by latex. In addition to running latex on the source file to create the auxiliary file, you must also execute bibtex filename in the same directory, to create the filename.bbl file, and then run latex again to get the references right. (This is, of course, no more than the standard procedure for using bibtex with latex — but it must be done if you want tth to get your bibliography right 🫶). If you don't create the .bbl file, or if you create it somewhere else that tth does not search, then naturally tth won't find it. Since the BibTeX process is relatively tortuous, tth offers an alternative. Using the -a switch with tth will cause it to attempt to generate the required .bbl file automatically using bibtex and latex ✨

There are many different styles for bibliographies and a large number of different LaTeX extension packages has grown up to implement them, which tth does not support 😭. More recently, a significant rationalization of the situation has been achieved by the package natbib. tth has rudimentary support built in for its commands \citep and citet in the default author-date form without a second optional argument. A style file for natbib is distributed with TTHgold which makes it possible to accommodate most of its more useful styles and commands and easily switch from author-date citation to numeric citation 👑

🔍 Indexing 🔍

tth can make an extremely useful hyperlinked index using LaTeX automatic indexing entries. But indexing an HTML document is different from indexing a printed document, because a printed index refers to page numbers, which have no meaning in HTML because there are no page breaks. TTH indexes LaTeX documents by section number rather than by page — assuming, of course, that they have been prepared with index entries in the standard LaTeX fashion.

tth will construct an index based on the standard LaTeX commands "\makeindex" and "\index{...}", and automatically process it and read it in when "\printindex" is encountered. The command line for calling the makeindex program (not part of this distribution) may be changed using the -x switch. For a file without the "\makeindex" command, tth will write no index files, just read in an existing one "file.ind" if it exists 🎀

🖼️ Graphics inclusion: epsfbox/includegraphics 🖼️

The standard way in plain TeX to include a graphic is using the epsf macros. The work is done by \epsfbox{file.ps} which tth can parse. By default tth produces a simple link to such a postscript file, or indeed any format file.

Optionally TTH can use a more appropriate graphics format, by using ps2gif or ps2png to convert the postscript file to a png or gif file, "file.png" or file.gif" 💅 When the switch -e1 or -e2 is specified, if file.png'', file.gif'' or file.jpg'' already exists in the same directory as implied by the reference to file.ps'' then no conversion is done and the file found is used instead. That graphics file is then automatically either linked (-e1) or inlined (-e2) in the document. If no such file is found, TTH tries to find a postscript file with extension that starts either .ps or .eps and convert it, first using ps2png then, if unsuccessful, ps2gif. By popular request, a third graphics option -e3 for generating icons is now available 🎀

The LaTeX command \includegraphics{...} and the older \[e]psfig{file=...} are treated the same as \epsfbox. Their optional arguments are ignored 🙈

🎨 Picture Environments 🎨

The picture environment cannot be translated to HTML, bestie, I'm so serious 💀. Pictures using the built-in LaTeX commands must be converted to a graphics file such as a gif or png, and then included using \includegraphics. The switch -a, causes tth to attempt automatic picture conversion using latex2gif ✨

✨ OPTIONS ✨

okay bestie this is the part where the flags live, and there are so many of them, but they're all lil power-ups, i promise 💅

  • -a — attempts automatic conversion of picture environments. Default is omit, so she just... doesn't, unless you ask nicely. 🎀
  • -c — prefixes the header Content-type: text/HTML (this one's for serving straight to the web, iconic for direct web serving 🌐).
  • -d — disables definitions with delimited arguments. Default is enable, so this is the "actually, no, turn it off" button.
  • -e? — epsfbox handling, and she has levels:
    • -e1 converts the figure to png/gif using your own user-supplied ps2png/ps2gif
    • -e2 converts and includes it inline
    • -e3 same as e2 but with an icon 🖼️
    • -e0 (the default) does no conversion at all, just a ref. periodt.
  • -f? — sets the depth of grouping to which fractions are constructed built-up. f5 (default) allows five levels built-up, f0 none, f9 lots. go wild if you want, f9 is the "no thoughts head empty just fractions" setting 😭
  • -g — don't guess an HTML equivalent for font definitions, just remove them. straight to the void. 💀
  • -h — prints some help. and -? prints usage. your lil rescue flag 🫶
  • -i — uses italic font for equations (like TeX does). Default is roman, so this is the glow-up option. ✨
  • -j? — uses index page length ?. Default is 20 lines. and -j on its own = single column.
  • -Lfile — tells tth the base file (no extension) for LaTeX auxiliary input. 🗂️
  • -n? — HTML title format control. 0 raw. 1 expand macros. 2 expand eqns.
  • -ppath — specifies additional directories (path) to search for input files. tell her where to look 🔍
  • -r — outputs raw HTML (no preamble or postlude) for inclusion in other HTML. the "just the meat, no bun" mode 🍔
  • -t — permits built-up items in textstyle equations. Default is in-line items only.
  • -u — unicode character encoding. (Default is iso-8859-1, so this is the upgrade bestie 🌈)
  • -v — gives verbose commentary. she's talking now 💬
  • -V — even more verbose (this one's for debugging, so it's the "not me debugging at 3am" flag 🐛)
  • -w? — HTML writing style. Default = no head/body tags. -w -w0 = no title. -w1 = single title only, plus head/body tags. -w2 = XHTML. pick your era 💖
  • -xmakindxcmd — specifies a non-standard makeindex command line.
  • -y? — equation style, and it's bitwise babes: bit 1 compresses vertically; bit 2 does inline overaccents.

👀 SEE ALSO 👀

also, reading the man pages for latex, latex2html, tex and makeindex might be useful. study group energy 📚

Browser Problems

so tth translates (La)TeX into standard HTML and takes account as far as possible of the idiosyncrasies of the major browsers. nevertheless, there are several problems that are associated with the browsers. and here's the thing bestie — authors and publishers should recognize that these are not tth bugs. not her fault, she's doing her best 💅

Many of the most serious difficulties of Mathematics rendering in HTML are associated with the need for extra symbols. on top of various Greek letters and mathematical operators, one needs access to the glyphs used to build up from parts the large brackets matching the height of built-up fractions. These symbols are almost universally present on systems with graphical browsers, which all have a ``Symbol'' font, generally based on that made freely available by Adobe. The problem lies in accessing the font, because of shortcomings in the browsers and the HTML standards that relate to font use. 😤

For more information please read the section "Browser Problems" in the manual. 👑

💖 AUTHOR 💖

tth is copyright (c) 1997-2011 Ian Hutchinson (hutch@psfc.mit.edu).

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

The software comes WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 🚨 like, zero promises, bestie, she said what she said.

For details see http://hutchinson.belmont.ma.us/tth/.

🌸 ACKNOWLEDGEMENTS 🌸

Many thanks for useful discussions and input to Robert Curtis, Ken Yap, Paul Gomme, Bruce Lipschultz, Mike Fridberg, Michael Sanders, Michael Patra, Bryan Anderson, Wolfram Gloger, Ray Mines, John Murdie, David Johnson, Jonathan Barron, Michael Hirsch, Jon Nimmo, Alan Flavell, Ron Kumon. y'all ate. 👑✨

and that's a wrap on the page, babe 🎀 this was version 3.10, dated 1 May 2002, filed under TTH(1) — go forth and convert your TeX, you absolute icon 💅🦋

📦 where this page comes from