WEB++

Writing a single CWEB document and utilizing the `@(filename@>' feature of CTANGLE is one way to deal with large software systems consisting of multiple source files and associated header files. I personally like this approach and both CTANGLE and CWEAVE are large enough even in their standard flavor.

The other way is to write a CWEB document for each of the C(++) modules. An extensive example for this approach is the C(--) implementation of `The Stanford GraphBase' by Donald Knuth. He wrote more than 30 CWEB modules for the associated C modules. He used the `multiple output' mechanism for header files in case that external declarations had to be exported from a C module. The documentation for this collection of literate programs comes as a book of the name `The Stanford GraphBase', where each software module forms a major part or chapter of the printed documentation. The `local' indexes created by CWEAVE were collected in a single index for the whole book, so inter-module references are possible.

In connection with a well-written `Makefile' the second approach can save a lot of time in the development phase, because neither the whole CWEB source has to be processed by CTANGLE (or CWEAVE) nor have all the C modules created automatically to be recompiled after each modification.

The library I am working on is small enough that I would like to document the entire thing in one CWEB file. I know I can use the "@(" control sequence to output to different files, but what should the main file be? I am thinking of having the unnamed code section go to the header file and using @( to produce the several implementation files. Is this the right way? Does anybody have experience doing this type of thing?

It's too early in the lifetime of literate programming for any Right Way to have surfaces. We all argue about techniques, but I think we all realize that we're all still working in the dark. On the other hand, CWEB is set up to generate a .c file as the main file by default. so your technique is certainly something Knuth didn't really consider (of course, that in itself may be a Good Thing).

I sometimes use @( to mimic noweb's multiple-root-chunk facility, and don't even bother to have an unnamed chunk at all. My personal preference, when confronted with multiple outputs (more than just a .h and .c with the same name) is to name all the chunks to be extracted with their file names. In CWEB, this would mean no @c chunks, in noweb, no <<*>> chunk. I think CWEB produces a zero-length .c file, with perhaps, a warning message, but that's only a minor irritant.

Not long ago I finished writing a program in C++ in which I used FWEB. I developed completely different strategy of splitting code into header and code files. I used two types of web files: *.hw and *.w. The first one was literate header file and it was tangled into *.h file by ftangle and *.w was literate code file and was tangled into *.cc. The makefile I used was constructed to recompile parts of the program only if the real source (*.w, *.hw) was changed.

To get woven output of my work I wrote another file, let's say "documentation.w" which contained the introductory part of the documentation, general information about program and several @i"..." statements which included all files, which actually contained the code. After this there was also a "REFERENCES" part. To get the documentation I had something like this in the makefile:

fweave documentation.w
latex2e documentation
latex2e documentation
latex2e documentation
xdvi documentation