TTM(1)

📦
version 4.16 · 3 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 TTM(1) — TeX to MathML translator 💖

okay bestie, grab a boba, because this whole page is about ttm — the TeX/LaTeX → MathML translator — plus its little helper squad. it's giving academic but make it slay ✨

🌸 NAME 🌸

not one icon, not two, but four of them, bestie:

  • ttm, latex2gif, ps2gif, ps2png — TeX and LaTeX to MathML translator and its auxiliary programs 🫶

✨ SYNOPSIS ✨

here's how you summon them, exactly as written:

ttm [options] [<file.tex] [>file.xml] [2>err]

filter mode, feed it stdin, catch stdout, dump the drama on stderr 💅

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

or just hand it a file, queen 👑

latex2gif file (no extension)
ps2gif file.ps file.gif [icon.gif]
ps2png file.ps file.png [icon.png]

💜 DESCRIPTION 💜

first things first: the scripts latex2gif, ps2gif and ps2png live in the recommended package tth-common. noted, bestie 📝

ttm translates TeX source that uses the plain macro package or LaTeX — including most mathematics — into a near equivalent in MathML. the formal standard that TTM-translated documents follow is strictly HTML4.0 Transitional. periodt.

real talk: the complete documentation lives in ttm_manual.html, which is distributed with the program. this man page is an incomplete summary and gets updated on an irregular basis. [Last updated 1 May 2002 by Hans Fredrik Nordhaug.] 😭

the program is a filter, i.e. it reads from standard input and writes to standard output. and also, diagnostic messages about its detection of unknown or untranslated constructs get sent to standard error. so keep an eye on that stderr, diva 👀

when it's handling embedded graphical files, ttm 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). it's a whole little ecosystem fr fr 🦋

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 MathML directly from TeX source if desired; (standard error may then need to be redirected.) main character energy, truly 💅

🎀 TeX things ttm handles 🎀

okay here's the roster, no skips:

  • 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. cute, right? 🎀

when ttm encounters TeX constructs that it cannot handle — either because there is no MathML equivalent, or because it is not clever enough — it tries to remove the mess they would otherwise cause in the MathML code, generally giving a warning of the action if it is not sure what it is doing. Untranslatable TeX math tokens are inserted verbatim. so, like, don't be shocked when weird stuff shows up raw 🙈

🦋 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. self-sufficient queen 👑

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 LaTeX header commands. this may be useful for translating single equations that (unwisely) use the \frac command. 🙈

📚 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 — and this is the part nobody warns you about — 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. slay, automation 💅

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. iconic, honestly 💖

🔎 Indexing 🔎

ttm can make an extremely useful hyperlinked index using LaTeX automatic indexing entries. but indexing an MathML document is different from indexing a printed document, because a printed index refers to page numbers, which have no meaning in MathML because there are no page breaks. TTM 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. adaptation, she ate 🍓

ttm 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, ttm 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 ttm can parse. by default ttm produces a simple link to such a postscript file, or indeed any format file. lowkey minimal, love that for her ✨

optionally TTM 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, 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. by popular request, a third graphics option -e3 for generating icons is now available. the people asked, and she delivered 👑

the LaTeX command \includegraphics{...} and the older \[e]psfig{file=...} are treated the same as \epsfbox. their optional arguments are ignored. no notes. 💅

🎨 Picture Environments 🎨

the picture environment cannot be translated to MathML. 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 ttm to attempt automatic picture conversion using latex2gif. workaround queen 🫶

✨ OPTIONS ✨

okay bestie here's the whole menu, buckle up 💅 every single flag, no skips, no cap:

  • -a — tries to auto-convert picture environments for u. default is omit (so like, off).
  • -c — slaps the header "Content-type: text/MathML" at the top, for when you're serving it straight to the web 🌐.
  • -d — disables definitions with delimited arguments. default is enable, so they're on unless you say otherwise.
  • -e? — the epsfbox handling squad 🖼️: -e1 converts the figure to png/gif using your user-supplied ps2png/ps2gif. -e2 converts it and includes it inline. -e3 is like e2 but with an icon. -e0 (the default) does no conversion at all, just a ref. pick ur fighter.
  • -f? — sets the depth of grouping to which fractions are constructed built-up. f5 (default) allows five levels built-up, f0 is none, f9 is lots.
  • -g — don't even try to guess an MathML equivalent for font definitions, just remove them. bye 👋
  • -h — prints some help. and -? prints usage. besties helping besties 🫶
  • -i — use an italic font for equations (like TeX does). default is roman.
  • -j? — use index page length ?. default is 20 lines. -j on its own means single column.
  • -Lfile — tells ttm the base file (no extension) for LaTeX auxiliary input.
  • -n? — MathML title format control. 0 raw, 1 expand macros, 2 expand eqns.
  • -ppath — specify additional directories (path) to search for input files.
  • -r — output raw MathML (no preamble or postlude) so u can drop it into other MathML.
  • -t — permits built-up items in textstyle equations. default is in-line items only.
  • -u — unicode character encoding. (default is iso-8859-1.)
  • -v — gives verbose commentary, spill the tea ☕
  • -V — even MORE verbose (for debugging, iykyk).
  • -w? — MathML writing style. default has no head/body tags. -w -w0 means no title. -w1 means a single title only, with head/body tags. -w2 means XMathML.
  • -xmakindxcmd — specify a non-standard makeindex command line.
  • -y? — equation style: bit 1 compresses vertically; bit 2 does inline overaccents.

💖 SEE ALSO 💖

the ttm manual, which is more likely to be up-to-date fr. a local copy should be chillin' in the Debian package. also, reading the man pages for latex, latex2html, tex and makeindex might be useful if u wanna go deeper 🔥

🦋 Browser Problems 🦋

ttm translates (La)TeX into standard MathML 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. authors and publishers should recognize that these are not ttm bugs, okay? not our girl's fault, periodt.

many of the most serious difficulties of Mathematics rendering in MathML are associated with the need for extra symbols. in addition to various Greek letters and mathematical operators, u need access to the glyphs used to build up, from parts, the large brackets that match 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 the one Adobe made freely available. the problem lies in accessing the font, because of shortcomings in the browsers and the MathML standards that relate to font use 😭

for more info please read the section "Browser Problems" in the manual.

👑 AUTHOR 👑

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

u 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. 🫣 so like, no take-backs, bestie.

for details see http://silas.psfc.mit.edu/tth/mml/.

🌈 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 ttm page, bestie!! this was version 3.10 of TTM(1), dated 1 May 2002 🎀 go forth and convert ur math, u got this 🧚💜

📦 where this page comes from