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

After installation you are able to process 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
  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?''
I think most of the readers interested in this converter are already
familiar with the Literate Programming concept.
For interested readers who are not familiar with these terms I suggest to
browse
 http://www.desy.de/user/projects/LitProg/Start.html
for a fine introduction into the matter.

CWEB (ftp://ftp.tu-darmstadt.de/pub/programming/literate-programming/c.c++/cweb-3.4.tar.gz),
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.
E.g. Klaus Guntermann (guntermann@iti.informatik.tu-darmstadt.de) and
Joachim Schrod (schrod@iti.informatik.th-darmstadt.de, jschrod@acm.org)
devised a TeX package that allows you to document directly in LaTeX.
This package is named cweb-sty-1.1.1 and is available from TU Darmstadt.
(ftp://ftp.tu-darmstadt.de/pub/programming/literate-programming/c.c++/cweb-sty-1.1.1.tar.gz)


Now we reached the point where CWEB2HTML plays its role. A TeX document
that can be understood by LaTeX could of course be parsed by LaTeX2HTML.
(ftp://www-dsed.llnl.gov/files/programs/unix/latex2html/sources/)
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 coming with the converter allows you to
link several stand-alone cweb documents together in that they point to each
other, and these links are of course clickable in your HTML browser.
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.
This approach also underlines the literate programming philosophy.



REQUIREMENTS:

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

 o LaTeX2HTML 96.1 or later, and the tools required for this.
   Use the URL of the introduction to get LaTeX2HTML if you don't have it.

 o cweb-3.4, that is cweave, ctangle, cwebmac.tex, etc.
   Use the URL of the introduction to get it.
   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
   Use the URL of the introduction to get it.
   Copy cweb.cls, cwebbase.tex, keyvald.sty and examples/rcs.sty
   into a directory that is known to LaTeX.



INSTALLATION:

This package combines various sources that first have to find their way to
the appropriate places.
You might first want to test the converter prior to installing anything.
You can do this as follows:
Add this directory to the TEXINPUTS shell variable. Do it in a colon
separated way, i.e.
if you are tcsh or csh user, type:
    setenv TEXINPUTS $PWD\::$TEXINPUTS
and if you are sh, bash, ksh, etc. user, type:
    TEXINPUTS=$PWD\::$TEXINPUTS; export TEXINPUTS

Then either configure the Makefile, telling it the right paths to perl,
latex2html, cweb2html (this converter) and some other executables.

Or, opposed to this, make sure every of that programs is found.
Do this by adding this directory to the PATH shell variable the way stated
above. You might want to check whether an executable will be found with
    which <program>
You might also want to have a glance over the Makefile in this case.

Test the package by running ``make wcltx.html''.
Everything should run smoothly.
The only warning you should see are about the unknown commands
copy, cweb_at_chunk, and RCSdate with 98.1.
With 97.1, you should only get RCSdate as unknown command.

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>