1TTH(1) TeX to HTML translator TTH(1)
2
6 tth, latex2gif, ps2gif, ps2png - TeX and LaTeX to HTML translator and
7 its auxiliary program
8
10 tth [options] [<file.tex] [>file.html] [2>err]
11 tth [options] file.tex [2>err]
13 latex2gif file (no extension)
15 ps2gif file.ps file.gif [icon.gif]
17 ps2png file.ps file.gif [icon.gif]
19
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 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 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 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 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 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 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 Hypertext cross-references within the document are automatically gener‐
91 ated by (e.g.) ref, and tableofcontents.
92 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
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 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 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
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 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
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 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
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 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 The LaTeX command \includegraphics{...} and the older
194 \[e]psfig{file=...} are treated the same as \epsfbox. Their optional
195 arguments are ignored.
196
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
204 -a attempt automatic conversion of picture environments. Default
205 omit.
206 -c prefix header "Content-type: text/HTML" (for direct web serv‐
208 ing).
209 -d disable definitions with delimited arguments. Default enable.
211 -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 -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 -g don't guess an HTML equivalent for font definitions, just
221 remove.
222 -h print some help. -? print usage
224 -i use italic font for equations (like TeX). Default roman.
226 -j? use index page length ?. Default 20 lines. -j single column.
228 -Lfile tells tth the base file (no extension) for LaTeX auxiliary
230 input.
231 -n? HTML title format control. 0 raw. 1 expand macros. 2 expand
233 eqns.
234 -ppath specify additional directories (path) to search for input files.
236 -r output raw HTML (no preamble or postlude) for inclusion in other
238 HTML.
239 -t permit built-up items in textstyle equations. Default in-line
241 items only.
242 -u unicode character encoding. (Default iso-8859-1).
244 -v give verbose commentary.
246 -V even more verbose (for debugging).
248 -w? HTML writing style. Default no head/body tags. -w -w0 no title.
250 -w1 single title only, head/body tags. -w2 XHTML.
251 -xmakindxcmd
253 specify a non-standard makeindex command line.
254 -y? equation style: bit 1 compress vertically; bit 2 inline overac‐
256 cents.
257
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
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 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 For more information please read the section "Browser Problems" in the
282 manual.
283
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 The software comes WITHOUT ANY WARRANTY; without even the implied war‐
293 ranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
294 For details see http://hutchinson.belmont.ma.us/tth/.
297
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.
3043.10 1 May 2002 TTH(1)