Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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  up-
       dated  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 de-
       tection of unknown or untranslated constructs are sent to standard  er-
       ror.

       In handling embedded graphical files tth	can make use of	auxiliary pro-
       grams,  ps2gif or ps2png, which in turn make use	of the ghostscript in-
       terpreter  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  di-
       rectly  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 au-
	  tomatic], 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, listofta-
	  bles,	listoffigures, newtheorem [no optional	arguments  permitted],
	  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 ar-
       gument, 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 La-
       TeX  header  commands.  This may	be useful for translating single equa-
       tions 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  en-
       tries 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 op-
       tion -e3	for generating icons is	now available.

       The  LaTeX  command  \includegraphics{...}  and	 the   older   \[e]ps-
       fig{file=...}  are  treated the same as \epsfbox.  Their	optional argu-
       ments 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 re-
	      move.

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

       -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. Au-
       thors 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)

NAME | SYNOPSIS | DESCRIPTION | Independence of [La]TeX installation and the -L switch | BibTeX bibliographies | Indexing | Graphics inclusion: epsfbox/includegraphics | Picture Environments | OPTIONS | SEE ALSO | Browser Problems | AUTHOR | LICENSE | ACKNOWLEDGEMENTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tth&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help