This file is part of CWEB version x3.04, and explains briefly what CWEB is, and how to set it up, and what the various files are for. Here is a listing of the other files constituting the release with a brief indication of their purpose. common.w % CWEB source for routines common to CTANGLE and CWEAVE ctangle.w % CWEB source for CTANGLE cweave.w % CWEB source for bulk of CWEAVE parser.w % CWEB source for parser of CWEAVE rules.w % CWEB source for grammar rules of CWEAVE common.inc % CWEB source included by common.w, ctangle.w, and cweave.w intro.inc % CWEB source included by ctangle.w and cweave.w common.c % C file produced (by CTANGLE) from common.w; for bootstrap common.h % C file produced (by CTANGLE) from common.w; for bootstrap ctangle.c % C file produced (by CTANGLE) from ctangle.w; for bootstrap cwebxmac.tex % TeX macro file needed to process files produced by CWEAVE cwebcmac.tex % TeX macro file needed in addition for compatibility mode cwebhmac.tex % optional TeX macro file creating hyperlinks for xhdvi (e.g.) manual.tex % master file for the CWEB manual compare.tex % file \input by manual.tex (present to facilitate bootstrap) Makefile % control file for UNIX make facility to build CWEB man1 % directory with UNIX manpage man1/cweb.1 % UNIX manpage for CTANGLE and CWEAVE examples % directory with sample CWEB programs examples/compare.w % Compare files; source for compare.tex above examples/treeprint.w % Convert sorted file listings to a tree diagram examples/wc.w % Count characters, words and lines in text files examples/wmerge.w % Perform preprocessing of change files as filter examples/Makefile cweb.el % EMACS file that might facilitate editing CWEB files The CWEB system allows you to write C programs and their documentation at the same time, in a way that optimises human readability. This version fully supports ANSI/ISO C, and indeed requires such a compiler for its own compilation. Like other WEB systems, CWEB allows you to decompose your programs into small, logically related portions, to add any desired amount of documentation to each of them, and to present them in any order that help understanding. As TeX is used to obtain the printed source document, a high typographic quality can be obtained while allowing for formatting of complicated formulae and tables; formatting of C program fragments is simple however, since it is done fully automatically. When used properly, CWEB can be used to produce documents that combine the qualities of a scientific publication about algorithms and of a well documented source listing for an implementation of those algorithms. The CWEB system consists of two programs, CTANGLE and CWEAVE, that are to be used in combination with a C compiler and TeX; both transform text files, while they share the same input language. CWEB source files, that typically have suffix `.w', can be converted by CTANGLE to C files (suffix `.c') that can be compiled, and alternatively can be converted by CWEAVE to TeX files (suffix `.tex') from which the typeset source listing can be produced by TeX. More details can be found in the manual, which you obtain by running TeX on the file manual.tex. Here the main interest is that since CWEB is written using CWEB you need a bootstrap procedure to get things going. For this purpose the derived files common.c, common.h and ctangle.c are supplied. If you have the UNIX make facility, all you have to do is check that these files are newer than the sources common.w and ctangle.w (they should be when the archive is unpacked, but you can use "touch" to make them newer in case this should be necessary), and that the Makefile macro CC refers to an ANSI compiler (it is set to "cc"; you may need to select "gcc" instead or to supply additional flags in CFLAGS) and then invoke "make all". Otherwise here is the required sequence of commands. $ cc -c ctangle.c # compile main part of CTANGLE $ cc -c common.c # compile common code $ cc -o ctangle ctangle.o common.o # link CTANGLE together $ ./ctangle cweave # create cweave.c from cweave.w $ cc -DDEBUG -DSTAT -g -c cweave.c # compile main part of CWEAVE $ cc -DDEBUG -DSTAT -g -o cweave cweave.o common.o # link CWEAVE together $ tex manual.tex # typeset the manual $ # the rest is only needed to obtain source listings for the CWEB system $ ./cweave common # produce common.tex $ tex common # typeset listing of common code $ ./cweave ctangle # produce ctangle.tex $ tex ctangle # typeset listing of CTANGLE $ ./cweave cweave # produce cweave.tex $ tex cweave # typeset listing of CWEAVE By the time you have done all this successfully, you have already tested CTANGLE and CWEAVE on a substantial amount of input, and you may be confident that the system is working properly. Should you on the other hand encounter problems during bootstrapping, then things are of course less pleasant, especially because you cannot print the source listings yet. Few problems are expected though, since there are no known system dependencies, and identical source code compiles on several dissimilar systems, one of which is quite non-UNIX. It is expected though that the compiler can handle large arrays (certainly larger than 64 Kb) and programs that used command line arguments; if your compiler does not, you will either have to replace it by a better one or do some tailoring of the programs. If you encounter any other difficulties, please report them to me at . If you do need to make changes to common.c, common.h, or ctangle.c, don't forget to write them down, since they will have to be applied at the proper places in common.w, ctangle.w, or common.inc in order to persist after bootstrapping. Such patches are best incorporated into a change file (e.g., ctangle.ch) as explained in the manual. Marc van Leeuwen Universit\'e de Poitiers http://wallis.univ-poitiers.fr/~maavl/