tex4ht for DEBIAN - source package notes - revised for v.20070821
-----------------------------------------------------------------

The sources can be updated by running the script "debian/update_src.sh"
in the source package. There is also a target "get-orig-source" for
"debian/rules" that does this.

The sources for this package are organised as follows:

	bin/,
	temp/,
	src/,
	texmf/:	These directories were created by unpacking the archive
		http://www.cse.ohio-state.edu/~gurari/TeX4ht/fix/tex4ht.tar.gz.

	lit/:	This directory was created by unpacking the archive
		http://www.cse.ohio-state.edu/~gurari/TeX4ht/fix/tex4ht-lit.zip
		and adding the style files found under
		http://www.cse.ohio-state.edu/~gurari/systems

Upstream's instructions for building the package are found at
http://www.cse.ohio-state.edu/~gurari/TeX4ht/mn-unix.html.

Based on these documents the previous maintainer Andrew Gray created
the following files in the src/ directory:
	90tex4ht.cnf (now renamed to 80tex4ht.cnf)
	htcmd.c
	Makefile
	scripts.sh
	tex4ht.man
The build procedure for the package currently only makes use
of the directories src/, bin/ and texmf/ --- the latter two are
arch-independent. Why is lit/ not used? Read on.

The non-use of "lit/"
-----------------
As has been remarked in bug #244276, the upstream author generates the
distributed archive using his own literate programming system that is
found in the various style files in lit/. In response to this bug the
upstream author has created the tex4ht-lit.zip archive as explained in
the following link.

	http://www.cse.ohio-state.edu/~gurari/Tex4ht/bugfixes.html
	or 
	file:///usr/share/doc/tex4ht/html/bugfixes.html

Each .tex file in lit/ is the literate source for one of the files in one
of the three directories bin/ src/ texmf/. The instruction for 
compilation is to be found at the top of each .tex file.

This source is *not* currently used in the Debian build process for the
following reasons (the point 2 is the more serious one):

	1. The upstream author has already provided the output files
           of the result of applying tex/latex to these literate
           sources. The main purpose of providing the lit/ source is
           to allow others to read/modify this source. To facilitate
           this use of lit/ there is now a target "litbuild" for
           debian/rules that re-creates the top-level tree in the
           directory dest/ by using the lit/ source.

	2. As a result of the way dates are used to create version
	   information, the version strings of the created
           files will not match that of the sources used for the
           build. The consequence for bug reports would be quite
           difficult to handle.

This has the unfortunate side effect of increasing (to almost double)
the size of the source package but that is (in my opinion) a small price
to pay for providing the complete source.

The use of "lit/"
-----------------
The DFSG requires that the source be in a form that is suitable for
modification---which is naturally interpreted as the form in which
the upstream author actually incorporates modification. The source is
also a source(!) of information on how the system works.

Thus, the primary use of "lit/" is to re-build the distributed files
in case someone wants to produce (for whatever reason) a modified
version of "tex4ht" after changing one of the files in "lit/". Towards
this end a new target "litbuild" has been provided for the makefile
"debian/rules".

Thanks to work done by Patrice Dumas, there are two ways to invoke
the "litbuild" target. If invoked with "LITK" defined this target
depends on an installed "tex4ht" package and uses that to rebuild the
distribution. The version without options rebuild everything using TeX
and the C compiler.

Both versions need "texlive-latex-recommended" and all dependencies of
that installed. In addition, the bootstrap version needs "libkpathsea-dev"
in order to compile the "tex4ht" and "t4ht" binaries that are used
during the bootstrap.

The "litbuild" target rebuilds the "bin/", "src/" and "texmf/" directories
as subdirectories of "dest/". Additional documentation generated as a
consequence of literate programming can be found in "dest/litdoc/".
The log of this process is kept in "debian/lit/litbuild.log". The
".diff"s of the differences between the generate directories and those
distributed can be found in the files "debian/lit/*diff.log".

Some of the differences are "expected" due to the folllowing reasons
(some of these were provided by the upstream author):

	1. Sometimes the *.4ht files are not re-compiled following
	   a bug fix. Instead the bug fix is "back-ported" to the
	   literate program. This causes some minor differences 
	   which do not affect the functioning of the system.

	2. Some of the literate files are more up-to-date than the
	   texmf tree since the former are still being worked on.
	   In particular, the "jsmath" and "emacspeak" part of
	   the system is currently being worked on.

	3. In some places 8-bit characters come out as (say) 
	   the 0xE5 character in the generated file whereas it is
	   "^^e5" in the distributed file. TeX treats these similarly
	   so it should not cause a problem. Handling this is part
	   of upstream's new approach to accents which is still being
	   worked on.

Kapil Hari Paranjape <kapil@imsc.res.in>
Sun, 06 Apr 2008 04:24:42 +0000
--
