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.
       http://hutchinson.belmont.ma.us/ttm/manual.cgi  (or  preferably  your  local   copy).   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://hutchinson.belmont.ma.us/ttm/.

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.