
This is the CWEB to HTML converter package for LaTeX2HTML 97.1,
98.1, 99.1, 99.2 by
    Jens Lippmann <lippmann@rbg.informatik.tu-darmstadt.de>
 

After installation you are able to process a CWEB document with this
converter and translate it into HTML via LaTeX2HTML.


MANIFEST:
Part of this package is
  Makefile    -- Makefile to generate objects with make
  makemake.pl -- Perl script to remake the Makefile
  cweb.perl   -- LaTeX2HTML style file
  cweb.cls    -- Patched cweb.cls for LaTeX 2e
  htcweb.perl -- LaTeX2HTML style file
  htcweb.sty  -- LaTeX style file
  htcweb.tex  -- LaTeX input file
  wcltx.w     -- The example from LaTeX CWEB
  wcltx.bib   -- above's bibliography
  linkex1.w   -- Example for linked documents
  linkex2.w   -- above's counterpart




INTRODUCTION TO THE CONVERTER:

First, you might ask yourself ``What is CWEB?''

And, nevertheless, ``What is Literate Programming?''

Most of the readers interested in this converter will most probably be
familiar with the Literate Programming concept.
Readers who are not familiar with these terms are suggested to browse
 http://www.desy.de/user/projects/LitProg/Start.html
for a fine introduction into the matter.

CWEB, by Donald Knuth and Silvio Levy, enables you to combine raw TeX
and C or C++ code within one document.  It is nothing entirely new for
a programmer who is used to C or TeX, there is just one more pass to
get the program resp. the documentation out of your cweb file.  Use
ctangle to produce the program file containing the code, and cweave to
produce a pretty looking TeX document which contains both your
documentation and the listing of your code.

However, typesetting the program documentation in TeX caused many
developers to refrain from such a technique, which is not necessary
because several approaches exist to use CWEB with LaTeX.
Klaus Guntermann (guntermann@iti.informatik.tu-darmstadt.de) and
Joachim Schrod (schrod@iti.informatik.th-darmstadt.de) implemented a
LaTeX document class for CWEB that allows you to document it in LaTeX.
This package is named cweb-sty-1.1.1 and is available at TU Darmstadt.


Now this is exactly the background needed for CWEB2HTML: A CWEB document
that can be translated by LaTeX should also be parseable by LaTeX2HTML.
The idea behind CWEB2HTML is to process the LaTeX file (generated by cweave)
such that it is translated with LaTeX2HTML.
So you can generate both HTML and DVI output from your cweb file with no
visible loss in quality.

Furthermore, the htcweb package that is part of this converter allows you to
link several stand-alone cweb documents together using a rather simple and
automated referencing mechanism.
This so-called inter-refinement linking feature (in contrast to the linking
between the refinements of one cweb file, which I call intra-refinement links)
make it possible to present your project sources as a full-meshed hypertext
document, both visible in DVI and HTML, whereby the HTML presentation will
come out best.
IMO this approach strongly emphasizes the literate programming concept.



INSTALLATION and TEST:

In order to run, you will need to install the following tools prior to this
converter:

 o LaTeX2HTML 96.1, 97.1, 98.1, 99.1, or 99.2
   ftp://www-dsed.llnl.gov/files/programs/unix/latex2html/sources/

 o cweb-3.4 (cweave, ctangle, cwebmac.tex, etc.)
   ftp://ftp.tu-darmstadt.de/pub/programming/literate-programming/c.c++/cweb-3.4.tar.gz
   Copy cwebmac.tex into a directory that is known to LaTeX.
   If you are using bash, tcsh or any other Unix shell, you
   should check your TEXINPUTS variable if it is defined.

 o cweb-sty-1.1.1
   ftp://ftp.tu-darmstadt.de/pub/programming/literate-programming/c.c++/cweb-sty-1.1.1.tar.gz
   Copy only cwebbase.tex, keyvald.sty and examples/rcs.sty into a
   directory that is known to LaTeX, you do not need the rest.
   If you use LaTeX 2e (what is most probably the case), take care that
   LaTeX inputs the patched cweb.cls of this package and not the one of
   cweb-sty-1.1.1!

Then simply configure the Makefile, telling it the right paths to Perl,
latex2html, cweb2html and some other executables.
Run the Makefile of this package by typing ``make''.
This Makefile only works under Unix-like operating systems!

Everything should translate smoothly. There are a few warning generated
by LaTeX2HTML about unknown commands RCSdate and copy. Ignore them.
Browse the example by clicking on the refinement labels.
You are also able to visit the Indentifiers index and the Refinements index.
Alternatively, use the Next tag of the navigation panel to sweep over the
document.

After the test showed to be successful, you might want install the following
things permanently.
Here is a proposal:
 o htcweb.sty, htcweb.tex into the texinputs/ directory of LaTeX2HTML
 o htcweb.perl, cweb.perl into the styles/ directory of LaTeX2HTML

Finally you might want to create icons for the two missing navigations
bar items 'Identifiers' and 'Refinements' (this release does not offer them).
Place that icons into the icon directory of LaTeX2HTML, either icons.gif/
or icons.png/.
That should it be.



MAKEFILE DESCRIPTION:

The Makefile offers various targets such as dvi or html.
Type ``make help'' to get a list of them.
You might want to extend the Makefile by adding new files on your own.
This is done very easily, simply add your file name to the FILES macro
near line 59 of the Makefile and rebuild it with ``make Makefile''.



DESCRIPTION OF HTCWEB:

It is perhaps best advised to find out the capabilities of the htcweb style by
experimenting with the example first.

To run the linked documents example, type
make linkex1.html linkex2.html
touch linkex1.w linkex2.w
make linkex1.html linkex2.html

You notice the double invocation of make.
This is necessary because each document imports labels from the other one
and exports its own ones to a so-called label file.
During compilation to DVI this file is name linkex1.lbl resp. linkex2.lbl.
During HTML compilation these are linkex1/labels.pl and linkex2/labels.pl.
In order to present the full-fledged document, sane label files are required
from each document it is importing from.

Note that there is no trivial way to implement dependencies of such linked
documents within a Makefile. All approaches will leed to circular dependencies
because one document depends on the labels to be exported by the other one,
and recompilation of one documents triggers recompilation of every other one
depending on that labels.
A smarter approach (i.e. smarter than make is) must base on some comparison
done on the actual and the former version of a label file.


During document conversion, you should notice lines of the form
- @<...@>
during the first runs of LaTeX resp. LaTeX2HTML.
This message indicates that an inter-refinement failed to get resolved,
that is the node ... as referenced by the actual document could not be
found among the imported labels.
As we are in the first run, this is ok because not all of the label files
do yet exist.

In the subsequent runs, you should notice
+ @<...@>
indicating that the inter-refinement has been resolved.
The only unresolved thing left over finally should be
- @<somewhere@>
then. This is intended behaviour.

Browse the examples like the wcltx one, by starting with linkex1.html.

That's all.
If you want to extend the example with further documents, simply add the lines
\HTCweblabels{
    dvi.obj/linkex1,
    dvi.obj/linkex2,
    dvi.obj/newfile}{
    html.obj/linkex1,
    html.obj/linkex2,
    html.obj/newfile}
to each involved document.
Extend the two lists by each file you want to import labels from. The labels
of the new document are automatically written to the output directory of the
DVI file (newfile.lbl) resp. the HTML document (newfile/labels.pl).
Don't forget to extend your Makefile.

If you get messages of the form

No labels from ....lbl, ignored

during the LaTeX run, or

No such label file <...> in TEXINPUTS or absolute

during the LaTeX2HTML run, make sure the apropriate document has been
translated before.
If you still get such messages, make sure that label file can be found,
by either stating an absolute file name, or stating a relative file name
which points to the label file via TEXINPUTS.
E.g. for building the examples in this package, you defined TEXINPUTS to
contain this directory, and this enables the tools to find linkex1.lbl
by concatenating <this dir> / <dvi.obj/linkex1> .lbl.



SUPPORT:

This package is fully supported by the author, and has been in use since
1996 in the LiPS project (http://www.cdc.informatik.tu-darmstadt.de/LiPS).
The converter is known to work very stable and to be able to cope with
CWEB documents restricted to refinement names with simple syntax.
As soon as you try to use more complicated expressions within refinement
names, the chance to get the translation broken by either CWEB2HTML or
LaTeX2HTML raises significantly.
At this place I want to apologize to the LaTeX3 team for the intensive
catcode switching. I will try hard to reduce them. :)

Before alerting the mailing list or the author because your document fails
to translate, I ask you to make sure you did not screw up CWEB itself.
(talking about our own experiences in the project here)
Proof this by defining the shell variable CWEB2HTMLOFF to 1 or some other
non-zero value,
    setenv CWEB2HTMLOFF 1
or
    CWEB2HTMLOFF=1; export CWEB2HTMLOFF
Then touch the CWEB document (``touch file.w'') and re-initiate the
translation with ``make file.dvi''.
View the results and make sure your document looks as expected!
Note that you will not get sensible results when you try to translate
this LaTeX document to HTML.

If for some reason the LaTeX2HTML translation failed, check your document
for unknown LaTeX styles that could cause the translation to break.
Refer to the LaTeX2HTML manual of how to treat special LaTeX constructs
such as self-defined commands, unusual style files or raw TeX commands
within the source. You could use the &ignore_commands list at the top of
htcweb.perl to help LaTeX2HTML cope with TeX expressions.

You might also want to try a different LaTeX2HTML release.
The converter has mostly been run with LaTeX2HTML 96.1 to 97.1 versions.
Perhaps an older release still is installed at your site?
This will often help a lot to isolate the root cause.


For any bug report or question, contact the LaTeX2HTML mailing list
(http://www.xray.mpe.mpg.de/mailing-lists/latex2html/)
to get help for problems with LaTeX2HTML,
and e-mail me to get problems solved arising with the converter.



KNOWN BUGS:

 - Confusing refinement names:
   Using certain special LaTeX constructs within the refinement name may
   confuse LaTeX2HTML in that it tries to create gif images out of parts
   of the name, which does not look nice.
 - Illegal refinement names:
   Do not use the colon : within any refinement name if you want to use
   the HTCweb features. HTCweb uses the colon as token separator in
   the label files. Alternatively you might want to replace the colon
   in the package, take care about this in both htcweb.sty and .perl.


--
Jens Lippmann <lippmann@rbg.informatik.tu-darmstadt.de>
