File: tth.1

package info (click to toggle)
tth 4.08%2Bds-2
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 1,376 kB
  • ctags: 124
  • sloc: xml: 291; makefile: 174; sh: 168; ansic: 131
file content (354 lines) | stat: -rw-r--r-- 14,237 bytes parent folder | download | duplicates (6)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
.TH TTH 1 "1 May 2002" 3.10 "TeX to HTML translator"
.SH NAME
tth, latex2gif, ps2gif, ps2png \- TeX and LaTeX to HTML translator 
and its auxiliary program
.SH SYNOPSIS
.B tth
[\fIoptions\fP] [\fI<file.tex\fP] [\fI>file.html\fP] [\fI2>err\fP]
.sp
.B tth
[\fIoptions\fP] \fIfile.tex\fP [\fI2>err\fP]
.sp
.B latex2gif
.I file
(no extension)
.sp
.B ps2gif
.I file.ps file.gif
[\fIicon.gif\fP] 
.sp
.B ps2png
.I file.ps file.gif
[\fIicon.gif\fP] 
.SH DESCRIPTION
.PP
.I 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. 
.PP
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.]
.PP
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.
.PP
In handling embedded graphical files \fItth\fP
can make use of auxiliary programs, \fI ps2gif\fP or \fIps2png\fP,
which in turn make use of the ghostscript interpreter \fIgs\fP (1)
and the Portable Bitmap Graphics suite of commands, see \fIpbm\fP (1).
.PP
.I 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 \fItth\fP in a CGI script to output 
HTML directly from TeX source if desired; (standard error may then 
need to be redirected.)
.PP
\fItth\fP handles TeX things like:
.nf
.in 1i
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.
.in
.fi
.PP
LaTeX support includes essentially all mathematics plus the following 
environments:
.in 1i
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].
.in
.fi
and LaTeX commands:
.in 1i
[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.
.in
.fi
.PP 
Hypertext cross-references within the document are automatically
generated by (e.g.) ref, and tableofcontents.
.PP
When \fItth\fP 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.
.SH "Independence of [La]TeX installation and the -L switch"
A major difference between \fItth\fP and \fIlatex2html\fP is that \fItth\fP 
does not call the \fIlatex\fP or \fItex\fP programs at all by default, 
and is not specifically dependent upon these, or indeed any other 
(e.g. \fIperl\fP), programs being installed on the translating system. 
Its portability is therefore virtually universal.
.PP
Forward references in LaTeX are handled by multiple passes that write
auxiliary files. \fItth\fP does only a single pass through the source.
If you want \fItth\fP 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 \fItth\fP switch \-a
causes \fItth\fP automatically to attempt to run \fIlatex\fP on the file,
if no auxiliary file .aux exists.
.PP
When run specifying a filename on the command line as a non-switch argument,
x \fItth\fP 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 \fItth\fP  as a filter, you must tell \fItth\fP , using the
switch \-Lfilename, the base file name of these auxiliary files
(which is the name of the original file omitting the extension). If
\fItth\fP  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 \fItth\fP  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.
.SH "BibTeX bibliographies"
\fItth\fP supports bibliographies that are created by hand using
\\begin{thebibliography} etc. Such bibliographies do not require
anything beyond the .aux file. \fItth\fP 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 \fIlatex\fP. In addition to running \fIlatex\fP 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 \fIlatex\fP again to get the
references right. (This is, of course, no more than the standard
procedure for using \fIbibtex\fP with \fIlatex\fP but it must be done if you
want \fItth\fP to get your bibliography right). If you don't create the
 .bbl file, or if you create it somewhere else that  \fItth\fP does not
search, then naturally  \fItth\fP won't find it. Since the BibTeX process
is relatively tortuous,  \fItth\fP offers an alternative. Using the \-a
switch with  \fItth\fP will cause it to attempt to generate the required .bbl 
file automatically using \fIbibtex\fP and \fIlatex\fP.
.PP
There are many different styles for bibliographies and a large number
of different LaTeX extension packages has grown up to implement
them, which \fItth\fP does not support. More recently, a significant
rationalization of the situation has been achieved by the package
natbib.  \fItth\fP 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.
.SH "Indexing"
\fItth\fP 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.
.PP
\fItth\fP 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 
.I -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.
.SH "Graphics inclusion: epsfbox/includegraphics"
.PP
The standard way in plain TeX to include a graphic is using the epsf
macros. The work is done by \\epsfbox{file.ps} which
.I tth
can parse. By
default
.I tth
produces a simple link to such a postscript file, or indeed any format file.
.PP
Optionally TTH can use a more appropriate graphics format, by using 
.I ps2gif
or
.I 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.
.PP
The LaTeX command \\includegraphics{...} and the older
\\[e]psfig{file=...} are treated the same as \\epsfbox.
Their optional arguments are ignored.
.SH "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 \fItth\fP to attempt automatic picture conversion using 
\fIlatex2gif\fP.
.SH OPTIONS
.TP
.B -a
attempt automatic conversion of picture environments. Default omit.
.TP
.B -c 
prefix header "Content-type: text/HTML" (for direct web serving).
.TP
.B -d 
disable definitions with delimited arguments. Default enable.
.TP
.BR -e ?
epsfbox handling:
.B -e1
convert figure to png/gif using user-supplied ps2png/ps2gif.
.B -e2
convert and include inline.
.B -e3
as e2 but with icon. 
.B -e0
(default) no conversion, just ref.
.TP
.BR -f ?
sets the depth of grouping to which fractions are constructed built-up
.B f5
(default) allows five levels built-up,
.B f0
none,
.B f9
lots.
.TP
.B -g 
don't guess an HTML equivalent for font definitions, just remove.
.TP
.B -h
print some help.
.B -?
print usage
.TP
.B -i 
use italic font for equations (like TeX). Default roman.
.TP
.B -j?
use index page length ?. Default 20 lines. \-j single column.
.TP
.B -Lfile
tells \fItth\fP the base file (no extension) for LaTeX auxiliary input.
.TP
.B -n? 
HTML title format control. 0 raw. 1 expand macros. 2 expand eqns.
.TP
.B  -ppath
specify additional directories (path) to search for input files.
.TP
.B -r
output raw HTML (no preamble or postlude) for inclusion in other HTML.
.TP
.B -t
permit built-up items in textstyle equations. Default in-line items only.
.TP
.B -u
unicode character encoding. (Default iso-8859-1).
.TP
.B -v
give verbose commentary. 
.TP
.B -V
even more verbose (for debugging).
.TP
.B -w?
HTML writing style. Default no head/body tags. \-w \-w0 no title.
\-w1 single title only, head/body tags. \-w2 XHTML.
.TP
.B -xmakindxcmd
specify a non-standard makeindex command line.
.TP
.B -y?
equation style: bit 1 compress vertically; bit 2 inline overaccents.

.SH "SEE ALSO"
The tth manual which is more likely to be up-to-date.
.B http://hutchinson.belmont.ma.us/tth/manual.cgi
(or preferably your local copy). In addition reading the man pages for
\fIlatex\fP, \fIlatex2html\fP, \fItex\fP and \fImakeindex\fP
might be useful.
.SH "Browser Problems"
\fitth\fP 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 \fitth\fP bugs.
.PP
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.
.PP 
For more information please read the section "Browser Problems" in the 
manual.
.SH AUTHOR
.PP
.I tth
is copyright (c) 1997-2011 Ian Hutchinson (hutch@psfc.mit.edu).
.SH Copyright License
.PP
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/.
.SH ACKNOWLEDGEMENTS
.PP
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.