manpagez: man pages & more
man tth(1)
Home | html | info | man
tth(1)                      TeX to HTML translator                      tth(1)




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

       The  complete  documentation is contained in "tth_manual.html" distrib-
       uted 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 pro-
       grams,  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.  Con-
       version  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.)

       To discuss how to get the best from tth, you can subscribe to a mailing
       list  by  sending  an  email containing the message subscribe tth_mail-
       ing_list to "majordomo@hutchinson.belmont.ma.us".  Then  you  can  send
       messages to "tth_mailing_list@hutchinson.belmont.ma.us".

       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, quota-
          tion,  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],  chap-
          ter,   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,  new-
          line,  verb[*],  bfseries,  itshape,  ttfamily,  textsc, ensuremath,
          listoftables, listoffigures, newtheorem [no optional arguments  per-
          mitted],  today,  printindex, boldmath, unboldmath, newfont, thanks,
          makeindex, index.

       Hypertext cross-references within the document are automatically gener-
       ated 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 vir-
       tually 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, biblio-
       graphic commands, etc.) that depend on auxiliary  files,  then  you  do
       need to run LaTeX on the code so that these files are generated. Alter-
       natively, 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   can-
       not  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 translat-
       ing single equations that (unwisely) use the \frac command.


BibTeX bibliographies

       tth supports bibliographies that are created by hand using  \begin{the-
       bibliography}  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 cor-
       rect 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 rationaliza-
       tion 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 auto-
       matic 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 exten-
       sion 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 serv-
              ing).

       -d     disable definitions with delimited arguments. Default enable.

       -e?    epsfbox handling: -e1 convert figure to png/gif using  user-sup-
              plied ps2png/ps2gif.  -e2 convert and include inline.  -e2 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 overac-
              cents.



SEE ALSO

       The tth manual which is more likely to be up-to-date.   http://hutchin-
       son.belmont.ma.us/tth/manual.cgi  (or  preferably  your local copy). In
       addition reading the man pages for latex, latex2html, tex and makeindex
       might be useful.


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 prob-
       lem  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-2002 Ian Hutchinson (hutch@psfc.mit.edu).


LICENSE

       You  may  freely use this software for non-commercial purposes.  It may
       not be used for commercial purposes without an additional license.   If
       you  distribute any copies, you must include this file and these condi-
       tions must apply to the recipient.  No warranty of fitness for any pur-
       pose  whatever  is  given, intended, or implied.  You use this software
       entirely at your own risk.  If you choose to use tth, by  your  actions
       you  acknowledge  that  any  direct or consequential damage whatever is
       your responsibility, not mine.

        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)

tth 4.09 - Generated Mon May 15 15:40:44 CDT 2017
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.