NAME¶

ttm, latex2gif, ps2gif, ps2png - TeX and LaTeX to MathML translatorand its auxiliary programs

SYNOPSIS¶

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

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

latex2giffile(no extension)

ps2giffile.ps file.gif[icon.gif]

ps2pngfile.ps file.png[icon.png]

DESCRIPTION¶

The scriptslatex2gif, ps2giforps2pngare in therecommended packagetth-common.

ttmtranslates TeX source that uses the plain macro package or LaTeX,including most mathematics, into a near equivalent in MathML. The formalstandard that TTM-translated documents follow is strictly HTML4.0Transitional.

The complete documentation is contained in "ttm_manual.html" distributedwith the program. This man page is an incomplete summary and updated on anirregular basis. [Last updated 1 May 2002 by Hans Fredrik Nordhaug.]

The program is a filter, i.e. it reads from standard input andwrites to standard output. In addition, diagnostic messages concerningits detection of unknownor untranslated constructs are sent to standard error.

In 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).

ttmis extremely fast in default mode on any reasonable hardware.Conversion of even large TeX files should be a matter of a second ortwo. 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.)

ttm 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 includes essentially all mathematics plus the followingenvironments:
em, verbatim, center, flushright [one paragraph only], verse,quotation, quote, itemize, enumerate, description, list [treatedas 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 [nonumber], 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 oraddto 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 automaticallygenerated by (e.g.) ref, and tableofcontents.

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.

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 writeauxiliary 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,x 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, 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 numberof different LaTeX extension packages has grown up to implementthem, 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.

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.

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 -xswitch. For a file without the "\makeindex" command, ttm will write noindex 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 epsfmacros. The work is done by \epsfbox{file.ps} whichttmcan parse. Bydefaultttmproduces a simple link to such a postscript file, or indeed any format file.

Optionally TTM can use a more appropriate graphics format, by usingps2giforps2pngto 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 samedirectory as implied by the reference to ``file.ps'' then noconversion is done and the file found is used instead. That graphicsfile is then automatically either linked (-e1) or inlined (-e2) in thedocument. If no such file is found, TTM tries to find a postscriptfile 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 MathML. Pictures usingthe built-in LaTeX commands must be converted to a graphics file suchas a gif or png, and then included using \includegraphics. The switch -a,causes ttm to attempt automatic picture conversion using latex2gif.

OPTIONS¶

-a

attempt automatic conversion of picture environments. Default omit.

-c

prefix header "Content-type: text/MathML" (for direct web serving).

-d

disable definitions with delimited arguments. Default enable.

-e?

epsfbox handling:-e1convert figure to png/gif using user-supplied ps2png/ps2gif.-e2convert and include inline.-e3as e2 but with icon.-e0(default) no conversion, just ref.

-f?

sets the depth of grouping to which fractions are constructed built-upf5(default) allows five levels built-up,f0none,f9lots.

-g

don't guess an MathML equivalent for font definitions, just remove.

-h

print some help.-?print usage

-i

use italic font for equations (like TeX). Default roman.

-j?

use index page length ?. Default 20 lines. -j 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) for inclusion in other MathML.

-t

permit built-up items in textstyle equations. Default in-line items only.

-u

unicode character encoding. (Default iso-8859-1).

-v

give verbose commentary.

-V

even more verbose (for debugging).

-w?

MathML writing style. Default no head/body tags. -w -w0 no title.-w1 single title only, head/body tags. -w2 XMathML.

-xmakindxcmd

specify a non-standard makeindex command line.

-y?

equation style: bit 1 compress vertically; bit 2 inline overaccents.

SEE ALSO¶

The ttm manual which is more likely to be up-to-date. A local copy should bein the Debian package. In addition reading the man pages forlatex, latex2html, tex and makeindex might be useful.

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.

Many of the most serious difficulties of Mathematics rendering in MathMLare associated with the need for extra symbols. In addition to variousGreek letters and mathematical operators, one needs access to theglyphs used to build up from parts the large brackets matching theheight of built-up fractions. These symbols are almost universallypresent on systems with graphical browsers, which all have a``Symbol'' font, generally based on that made freely available byAdobe. The problem lies in accessing the font because ofshortcomings in the browsers and the MathML standards that relate to font use.

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

AUTHOR¶

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

CopyrightLicense¶

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

The software comes WITHOUT ANY WARRANTY; without even the impliedwarranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

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

ACKNOWLEDGEMENTS¶

Many thanks for useful discussions and input toRobert 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, MichaelHirsch, Jon Nimmo, Alan Flavell, Ron Kumon.