Ubuntu Manpage: tth, latex2gif, ps2gif, ps2png - TeX and LaTeX to HTML translator and its auxiliary program

NAME

       tth, latex2gif, ps2gif, ps2png - TeX and LaTeX to HTML translator and its auxiliary program

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.

       The  complete documentation is contained in "tth_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 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.  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.)

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

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

       -a     attempt automatic conversion of picture environments. Default omit.

       -c     prefix header "Content-type: text/HTML" (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 HTML 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 tth the base file (no extension) for LaTeX auxiliary input.

       -n?    HTML title format control. 0 raw. 1 expand macros. 2 expand eqns.

       -ppath specify additional directories (path) to search for input files.

       -r     output raw HTML (no preamble or postlude) for inclusion in other HTML.

       -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?    HTML  writing style. Default no head/body tags. -w -w0 no title.  -w1 single title only, head/body
              tags. -w2 XHTML.

       -xmakindxcmd
              specify a non-standard makeindex command line.

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

Browser Problems

       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.
       Authors and publishers should recognize that these are not tth bugs.

       Many  of  the most serious difficulties of Mathematics rendering in HTML 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 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).

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

3.10                                               1 May 2002                                             TTH(1)