NAME

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

SYNOPSIS

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

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

       latex2gif file (no extension)

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

       ps2png file.ps file.png [icon.png]

DESCRIPTION

       The scripts latex2gif, ps2gif or ps2png are in the recommended package tth-common.

       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.

       The  complete documentation is contained in "ttm_manual.html" distributed with the program. This man page
       is an incomplete summary and 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. In addition,
       diagnostic messages concerning its detection of unknown or 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).

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

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

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

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

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

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: -e1 convert figure to png/gif using user-supplied  ps2png/ps2gif.   -e2  convert
              and include inline.  -e3 as e2 but with icon.  -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 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 be in the Debian package. In
       addition reading the man pages for latex, 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 MathML are associated with the need for
       extra  symbols.  In addition to 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 MathML standards that relate to font use.

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

AUTHOR

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

Copyright License

       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.

        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.

3.10                                               1 May 2002                                             TTM(1)