tex4ht for DEBIAN - packaging notes - revised for v.20070821
------------------------------------------------------------

Each file in the tex4ht system has a version date recorded within it.  The
version of this Debian package is 20070821, based on the upstream 
authors numbering scheme---suitably Debian-ized.
The version dates of the main source and style files are as follows:

	tex4ht.c	2007-04-21-21:07
	t4ht.c		2007-01-05-03:17
	tex4ht.sty	2007-08-19-01:12

The author has responded to comments on the Debian bugs archive regarding
the availability of the literate programming source. Please see
README.Debian-source in this directory for details.

In addition to the substantial work (see below) done by the previous maintainer
Andrew Gray (many, many thanks to him wherever he is now), the following features
in the new source were exploited. 

	(1) The LGTYP variable was defined in Andrew's Makefile 
	    so that PNG is the default graphic format instead of GIF.
	(2) The new tex4ht.env allows for multiple tagged sections of
	    possible ways to create graphics. The default one
	    creates PNG's using dvipng.
	(3) Sample file in /usr/share/doc/tex4ht/html also provides
	    some rudimentary documentation. You can process this with
	    "htlatex tex4ht_doc.tex" or "htlatex tex4ht_doc.tex bg".
	(4) The package has been split for the convenience of the
	    mirrors into "tex4ht" and "tex4ht-common" but it is
	    unlikely that you can use one package without the other.
	(5) The package "tex4ht" now includes "xtpipes.jar" which is
	    a java program that is used for some of the conversions.
	    Its use requires a java runtime supporting version at least
	    1.5 to work.

On configuration (tex4ht.env)
=============================

The configuration file for tex4ht is searched for by kpathsearch library
routines. You can put this file in the following places (see
README.kpathsea for details).

	$PWD/tex4ht.env, $PWD/.tex4ht, $HOME/tex4ht.env, $HOME/.tex4ht
	/usr/share/texmf/tex4ht/tex4ht.env

The last file is provided by the package as a symlink to
/etc/tex4ht/tex4ht.env in keeping with the Debian convention on
configuration files. This file differs from the upstream version only in
the graphics conversion section. It is somewhat self documenting.

On graphics conversion
======================

As explained at the top of /etc/tex4ht/tex4ht.env, suitable tags
can be used select the named sections of the graphics conversion process.
Please examine the top of that file to understand its format.

The graphics sections provided are default, upstream and netpbm.

The default scripts (htlatex and friends) for converting TeX/LaTeX to
HTML only convert graphics to PNG.

If you explicitly ask for non-PNG graphics then the configuration file
always depends on the imagemagick suite to perform conversion.

The default conversion method uses only dvipng for conversion to PNG.

The upstream conversion method uses the imagemagick suite. If you wish
to use many different types of graphics outputs this may be your best
choice. Note that convert also depends on a suitable ghostscript for the
initial conversion from postscript to bitmap. This method also offers
a way to convert figures to SVG using pstoedit.

The upstream conversion method also has a commented out (with
spaces!) a method that uses the "pngalpha" driver which is available
with ghostscript 8.14 and higher; if you wish to use this then remove
the spaces in front of it. A further commented out section (tagged
KHP) uses "pnggray" which does not have transparency. If you only have
access to gs 8.01 then use this instead of the line on top. Note that
gs-esp version 7.xx does not currently crop images correctly and results
in awful HTML pages.

There is another commented out method which is an older version of
the imagmagick method. If you have an older imagemagick you may want
to use this.

The netpbm conversion method uses the netpbm suite.

Kapil Hari Paranjape <kapil@imsc.res.in>
Wed, 22 Aug 2007 12:09:22 +0530

Original Maintainer's notes
===========================

<KHP's note: What follows below is a major portion of the original
README.Debian. The "I" in the sentences below refers to Andrew Gray>

There are no original manual pages for tex4ht, but I wrote a page based
on the HTML documentation.  The user-guide consists of HTML documentation
which is available in /usr/share/doc/texmf/tex4ht.  Start with file mn.html
(or index.html) in your web browser.

The original source did not include a Makefile, so I have written one (with
the program sources, in the temp/ subdirectory of the source package).  This
has been simplified in v.20030426, partly because the source tex4ht files are
organised in a directory structure closer to the typical web2c structure.

The Debian versions of tex4ht and t4ht are built with the 'kpathsea'
file-search library, as used by tex and other programs in the package
tetex-bin.  See the file README.kpathsea in this directory for notes on how
tex4ht can be configured using the global kpathsea configuration file.  Note
that because the programs are built with kpathsea, the path-searching and
bookkeeping file options within the tex4ht.env configuration file ('t', 'i'
and 'l' lines) are redundant and/or will be interpreted in special ways (see
README.kpathsea for details).

The 'bug-fix' files (in newt4ht.zip) and new htf fonts (in htf.zip) have
overwritten the equivalent files from tex4ht.zip.

In keeping with Debian's free software philosophy, I have altered the
configuration file and scripts to generate PNG rather than GIF files by
default.  The alterations are as follows:

 - in tex4ht.env config file:  altered 'g' line to 'g.png', to generate PNG
   files for any symbol characters that are used in your document

 - in the htlatex-like scripts (httex, httexi and htlatex in /usr/bin/httex, 
   and scripts in /usr/share/tex4ht), add 'png' option to the
   tex/latex commands, to generate PNG files for any pictures specifically
   requested in your document

Note that, if you do not have the imagemagick package installed, you will have
to adjust the 'G' lines towards the end of the configuration file
/etc/tex4ht/tex4ht.env.  See the HTML documentation for more details, or the
comments within tex4ht.env:  the version of tex4ht.env currently shipped with
the package includes (commented out) versions of these lines for netpbm-users.

For more details on the configuration of tex4ht, see the HTML documentation.
Note that the HTML documentation and the test files are placed under
/usr/share/doc/texmf/tex4ht.

If you are upgrading from a Debian tex4ht package earlier than v.20000703, you
may want to read the notes in file NEWS.Debian.

Andrew Gray <ajpg@debian.org>, 
Fri,  2 May 2003 22:22:03 +0100
--
