1TTH(1)                      TeX to HTML translator                      TTH(1)
2
3
4

NAME

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

SYNOPSIS

10       tth [options] [<file.tex] [>file.html] [2>err]
11
12       tth [options] file.tex [2>err]
13
14       latex2gif file (no extension)
15
16       ps2gif file.ps file.gif [icon.gif]
17
18       ps2png file.ps file.gif [icon.gif]
19

DESCRIPTION

21       tth translates TeX source that uses the plain macro package  or  LaTeX,
22       including  most mathematics, into a near equivalent in HTML. The formal
23       standard that TTH-translated documents follow is strictly HTML4.0 Tran‐
24       sitional.
25
26       The  complete  documentation is contained in "tth_manual.html" distrib‐
27       uted with the program. This man  page  is  an  incomplete  summary  and
28       updated on an irregular basis. [Last updated 1 May 2002 by Hans Fredrik
29       Nordhaug.]
30
31       The program is a filter, i.e. it reads from standard input  and  writes
32       to  standard  output.  In  addition, diagnostic messages concerning its
33       detection of unknown or untranslated constructs are  sent  to  standard
34       error.
35
36       In handling embedded graphical files tth can make use of auxiliary pro‐
37       grams,  ps2gif or ps2png, which in turn make  use  of  the  ghostscript
38       interpreter  gs (1) and the Portable Bitmap Graphics suite of commands,
39       see pbm (1).
40
41       tth is extremely fast in default mode on any reasonable hardware.  Con‐
42       version  of even large TeX files should be a matter of a second or two.
43       This makes it possible to use tth  in  a  CGI  script  to  output  HTML
44       directly  from  TeX source if desired; (standard error may then need to
45       be redirected.)
46
47       tth handles TeX things like:
48          Almost all mathematics, including symbols, fractions, delimiters.
49          {} \begingroup\endgroup  grouping.
50          \it \bf \sl etc  styles.
51          \beginsection.
52          \centerline{}.
53          \item{...} \itemitem{...} {\obeylines  ...}.
54          Almost all accented latin characters written like \"o, or \"{e}.
55          \hang \hangindent \narrower for entire paragraphs
56            (\hangafter ignored).
57          \headline is made into a title.
58          % Comments. Simply removed.
59          \halign tables, checks template for the presence of \vrule,
60            to decide if the table is to be border style.
61          \settabs \+ style tables.
62          \input: But, of course, not from the implicit texinputs path.
63          \newcount, \number, \advance and counter setting.
64          \def, \edef, \xdef but no delimited arguments.
65            All definitions are global.
66          \matrix, \pmatrix but not \bordermatrix. \cases.
67
68       LaTeX support includes essentially all mathematics plus  the  following
69       environments:
70          em, verbatim, center, flushright [one paragraph only], verse, quota‐
71          tion, quote, itemize, enumerate, description, list  [treated  as  if
72          description],  figure,  table,  tabular[*,x], equation, displaymath,
73          eqnarray [only one equation number], math,  array,  thebibliography,
74          [raw]html, index [as description].
75       and Latex commands:
76          [re]newcommand,  newenvironment  [optional arg not permitted], chap‐
77          ter,  section,  subsection,  subsubsection,  caption,  label,   ref,
78          pageref  [no  number],  emph,  textit,  texttt,  textbf,  centering,
79          raggedleft, includegraphics,  [e]psfig,  title,  author,  date  [not
80          automatic],  lefteqn,  frac,  tableofcontents,  input,  include  [as
81          input], textcolor, color [8  standard  colors],  footnote  [ignoring
82          optional  arg], cite, bibitem, bibliography, tiny ... normalsize ...
83          Huge, newcounter [no ``within'' support], setcounter,  addtocounter,
84          value  [inside set or addto counter], arabic, the, stepcounter, new‐
85          line, verb[*],  bfseries,  itshape,  ttfamily,  textsc,  ensuremath,
86          listoftables,  listoffigures, newtheorem [no optional arguments per‐
87          mitted], today, printindex, boldmath, unboldmath,  newfont,  thanks,
88          makeindex, index.
89
90       Hypertext cross-references within the document are automatically gener‐
91       ated by (e.g.) ref, and tableofcontents.
92
93       When tth encounters TeX constructs that it cannot handle either because
94       there  is  no  HTML  equivalent, or because it is not clever enough, it
95       tries to remove the mess they would otherwise cause in the  HTML  code,
96       generally  giving  a warning of the action if it is not sure what it is
97       doing.  Untranslatable TeX math tokens are inserted verbatim.
98

Independence of [La]TeX installation and the -L switch

100       A major difference between tth and latex2html is that tth does not call
101       the  latex  or  tex programs at all by default, and is not specifically
102       dependent upon these, or indeed any other (e.g. perl),  programs  being
103       installed on the translating system.  Its portability is therefore vir‐
104       tually universal.
105
106       Forward references in LaTeX are handled by multiple passes  that  write
107       auxiliary  files.  tth  does only a single pass through the source.  If
108       you want tth to use LaTeX  constructs  (e.g.  tableofcontents,  biblio‐
109       graphic  commands,  etc.)  that  depend on auxiliary files, then you do
110       need to run LaTeX on the code so that these files are generated. Alter‐
111       natively,  the tth switch -a causes tth automatically to attempt to run
112       latex on the file, if no auxiliary file .aux exists.
113
114       When run specifying a filename on the  command  line  as  a  non-switch
115       argument,  x  tth  constructs  the name of the expected auxiliary LaTeX
116       files in the usual way and looks for them in the same directory as  the
117       file.  If you are using tth  as a filter, you must tell tth , using the
118       switch -Lfilename, the base file name of these auxiliary  files  (which
119       is  the name of the original file omitting the extension). If tth  can‐
120       not find the relevant auxiliary file because you didn't run  LaTeX  and
121       generate  the files or didn't include the switch, then it will omit the
122       construct and warn you.  Forward references via ref will  not  work  if
123       the  .aux  file  is  unavailable,  but backward references will. The -L
124       switch with no filename may be used to  tell  tth   that  the  document
125       being  translated  is  to be interpreted as a LaTeX file even though it
126       lacks the usual LaTeX header commands. This may be useful for translat‐
127       ing single equations that (unwisely) use the \frac command.
128

BibTeX bibliographies

130       tth  supports bibliographies that are created by hand using \begin{the‐
131       bibliography} etc. Such bibliographies do not require  anything  beyond
132       the  .aux  file.  tth also supports bibliographies created using BibTeX
133       from a biblography database. The filename.bbl file is input at the cor‐
134       rect  place in the document.  However, this filename.bbl is not created
135       automatically by latex. In addition to running latex on the source file
136       to  create the auxiliary file, you must also execute bibtex filename in
137       the same directory, to create the filename.bbl file, and then run latex
138       again  to  get  the references right. (This is, of course, no more than
139       the standard procedure for using bibtex with latex but it must be  done
140       if  you  want  tth to get your bibliography right). If you don't create
141       the
142        .bbl file, or if you create it  somewhere  else  that   tth  does  not
143       search,  then naturally  tth won't find it. Since the BibTeX process is
144       relatively tortuous,  tth offers an alternative. Using  the  -a  switch
145       with   tth  will cause it to attempt to generate the required .bbl file
146       automatically using bibtex and latex.
147
148       There are many different styles for bibliographies and a  large  number
149       of  different  LaTeX extension packages has grown up to implement them,
150       which tth does not support. More recently, a  significant  rationaliza‐
151       tion of the situation has been achieved by the package natbib.  tth has
152       rudimentary support built in for its commands \citep and citet  in  the
153       default  author-date  form without a second optional argument.  A style
154       file for natbib is distributed with TTHgold which makes it possible  to
155       accommodate  most  of  its  more  useful styles and commands and easily
156       switch from author-date citation to numeric citation.
157

Indexing

159       tth can make an extremely useful hyperlinked index  using  LaTeX  auto‐
160       matic  indexing  entries.   But  indexing an HTML document is different
161       from indexing a printed document, because a  printed  index  refers  to
162       page  numbers,  which have no meaning in HTML because there are no page
163       breaks. TTH indexes LaTeX documents by section number  rather  than  by
164       page;  assuming,  of  course,  that  they have been prepared with index
165       entries in the standard LaTeX fashion.
166
167       tth will construct an  index  based  on  the  standard  LaTeX  commands
168       "\makeindex"  and  "\index{...}", and automatically process it and read
169       it in when "\printindex" is encountered. The command line  for  calling
170       the  makeindex  program  (not part of this distribution) may be changed
171       using the -x switch. For a file without the "\makeindex"  command,  tth
172       will  write  no index files, just read in an existing one "file.ind" if
173       it exists.
174

Graphics inclusion: epsfbox/includegraphics

176       The standard way in plain TeX to include a graphic is  using  the  epsf
177       macros.  The  work is done by \epsfbox{file.ps} which tth can parse. By
178       default tth produces a simple link to such a postscript file, or indeed
179       any format file.
180
181       Optionally  TTH  can  use  a more appropriate graphics format, by using
182       ps2gif or ps2png to convert the postscript file to a png or  gif  file,
183       "file.png"  or  file.gif"  When  the switch -e1 or -e2 is specified, if
184       ``file.png'', ``file.gif'' or ``file.jpg'' already exists in  the  same
185       directory as implied by the reference to ``file.ps'' then no conversion
186       is done and the file found is used instead.  That graphics file is then
187       automatically  either linked (-e1) or inlined (-e2) in the document. If
188       no such file is found, TTH tries to find a postscript file with  exten‐
189       sion  that starts either .ps or .eps and convert it, first using ps2png
190       then, if unsuccessful, ps2gif. By popular  request,  a  third  graphics
191       option -e3 for generating icons is now available.
192
193       The    LaTeX    command    \includegraphics{...}    and    the    older
194       \[e]psfig{file=...} are treated the same as \epsfbox.   Their  optional
195       arguments are ignored.
196

Picture Environments

198       The  picture  environment  cannot be translated to HTML. Pictures using
199       the built-in LaTeX commands must be converted to a graphics  file  such
200       as  a  gif or png, and then included using \includegraphics. The switch
201       -a, causes tth to attempt automatic picture conversion using latex2gif.
202

OPTIONS

204       -a     attempt automatic conversion of  picture  environments.  Default
205              omit.
206
207       -c     prefix  header  "Content-type:  text/HTML" (for direct web serv‐
208              ing).
209
210       -d     disable definitions with delimited arguments. Default enable.
211
212       -e?    epsfbox handling: -e1 convert figure to png/gif using  user-sup‐
213              plied ps2png/ps2gif.  -e2 convert and include inline.  -e3 as e2
214              but with icon.  -e0 (default) no conversion, just ref.
215
216       -f?    sets the depth of grouping to which  fractions  are  constructed
217              built-up  f5  (default) allows five levels built-up, f0 none, f9
218              lots.
219
220       -g     don't guess  an  HTML  equivalent  for  font  definitions,  just
221              remove.
222
223       -h     print some help.  -?  print usage
224
225       -i     use italic font for equations (like TeX). Default roman.
226
227       -j?    use index page length ?. Default 20 lines. -j single column.
228
229       -Lfile tells  tth  the  base  file  (no  extension) for LaTeX auxiliary
230              input.
231
232       -n?    HTML title format control. 0 raw.  1  expand  macros.  2  expand
233              eqns.
234
235       -ppath specify additional directories (path) to search for input files.
236
237       -r     output raw HTML (no preamble or postlude) for inclusion in other
238              HTML.
239
240       -t     permit built-up items in textstyle  equations.  Default  in-line
241              items only.
242
243       -u     unicode character encoding. (Default iso-8859-1).
244
245       -v     give verbose commentary.
246
247       -V     even more verbose (for debugging).
248
249       -w?    HTML  writing style. Default no head/body tags. -w -w0 no title.
250              -w1 single title only, head/body tags. -w2 XHTML.
251
252       -xmakindxcmd
253              specify a non-standard makeindex command line.
254
255       -y?    equation style: bit 1 compress vertically; bit 2 inline  overac‐
256              cents.
257
258

SEE ALSO

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

Browser Problems

266       tth translates (La)TeX into standard HTML and takes account as  far  as
267       possible  of  the  idiosyncrasies  of the major browsers. Nevertheless,
268       there are several problems  that  are  associated  with  the  browsers.
269       Authors and publishers should recognize that these are not tth bugs.
270
271       Many  of the most serious difficulties of Mathematics rendering in HTML
272       are associated with the need for extra symbols. In addition to  various
273       Greek  letters  and  mathematical  operators,  one  needs access to the
274       glyphs used to build up from parts  the  large  brackets  matching  the
275       height  of  built-up  fractions.  These  symbols are almost universally
276       present on systems with graphical browsers, which all have a ``Symbol''
277       font, generally based on that made freely available by Adobe. The prob‐
278       lem lies in accessing the font because of shortcomings in the  browsers
279       and the HTML standards that relate to font use.
280
281       For  more information please read the section "Browser Problems" in the
282       manual.
283

AUTHOR

285       tth is copyright (c) 1997-2011 Ian Hutchinson (hutch@psfc.mit.edu).
286
288       You are hereby freely licensed to use this software under the terms  of
289       the  GNU General Public License, version 2, published by the Free Soft‐
290       ware Foundation, a copy of which is enclosed in the file license.txt.
291
292       The software comes WITHOUT ANY WARRANTY; without even the implied  war‐
293       ranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
294
295
296        For details see http://hutchinson.belmont.ma.us/tth/.
297

ACKNOWLEDGEMENTS

299       Many thanks for useful discussions and input to Robert Curtis, Ken Yap,
300       Paul Gomme, Bruce Lipschultz, Mike Fridberg, Michael  Sanders,  Michael
301       Patra,  Bryan  Anderson,  Wolfram Gloger, Ray Mines, John Murdie, David
302       Johnson, Jonathan Barron, Michael Hirsch, Jon Nimmo, Alan Flavell,  Ron
303       Kumon.
304
305
306
307
308
309
310
3113.10                              1 May 2002                            TTH(1)
Impressum