This is the c2cweb package Version 1.5 (10-Nov-1996) ===================================================== Copyright (C) 1996 Werner Lemberg [see below for a German introduction] c2cweb will transform plain C or C++ code into a CWEB file to get a pretty formatted output. A modified CWEAVE (which transforms the CWEB file into a TeX file, see below) is included also. Some c2cweb highlights: variables and function names in italics reserved words (int, char, return etc.) in bold face strings in typewriter type comments in typwriter type or roman an index(!) of all variables, constants, function names etc. each function gets a section and more The c2cweb package contains the following files: c2cweb.txt this file history.txt the history file Makefile a makefile to compile c2cweb for UNIX, OS/2, and DOS c2cweb.def definition file (needed for compiling under OS/2 only) COPYING the GNU Copying License c2cweb.w a CWEB file of the program you should say make documentation (using this package's CWEAVE) to produce a TeX-output c2cweb.c extracted with CTANGLE from c2cweb.w c2cweb.dvi the final .dvi-file c2cweb.exe an executable for DOS and OS/2 compiler.w compiler dependent formatting commands (an output of c2cweb reads this file) c2cweb.ger a small german `package' to demonstrate national language support example.h example.c a C code example with inserted c2cweb control commands cweb/cweave.exe a modified executable (for DOS and OS/2) of CWEAVE Ver. 3.2 with three important new features: o the switch +a causes CWEAVE to produce a different output format, basically if(a) {bla bla bla... } instead of if(a) { bla bla bla... } o the switch +i causes CWEAVE to append () after a function name in the index (this makes only sense if all names are unique) o the #define statement handling was basically enhanced to allow macros with parameters cweb/cweave.w this is the original CWEAVE source file of Levy's CWEB package ver 3.2 (July 1994) cweb/cweave.ch the change file for cweave.w cweb/cweave.c extracted with CTANGLE from cweave.{w,ch} cweb/common.h this is needed to build CWEAVE (slightly different from the original) cweb/common.w taken unaltered from CWEB 3.2 cweb/common.ch change file for common.w cweb/common.c extracted with CTANGLE from common.{w,ch} cweb/Makefile Makefile for CWEAVE (UNIX, OS/2, and DOS) cweb/cweave.def definition file (needed for compiling under OS/2 only) cweb/cwebmac.ori the standard cwebmac.tex file (slightly modified) cweb/cwebmac.tex alternative format file cweb/cwebmaca.tex this alternative format file is read by TeX if you use the +a switch; similar to cwebmac.tex cweb/prod-alt.w this file is an include file of cweave.ch; it contains the alternative syntax rules of CWEAVE if the switch a is on You should get the original CWEB package for further documentation; it contains change files for different operating systems also. Copying ------- This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. Installation ------------ The c2cweb executable should be in the path. The CWEAVE executable should also be in the path; it needs the file compiler.w (use the environment variable CWEBINPUTS to set the path). c2cweb.ger, cwebmac.tex and cwebmaca.tex must be found by TeX (the path is usually controlled by the TEXINPUT environment variable). DOS and WINDOWS users must assure that emx.exe and rsx.exe can be found (either in the path or set with the EMX and RSX environment variables). OS/2 users must assure that emx.dll and rsx.exe can be found (either in the path or set with the EMX and RSX environment variables). [emx.exe, emx.dll, and rsx.exe can be found in the the emxrsx.zip package of the emTeX distribution.] Remarks for UNIX systems users ------------------------------ Because of the many different UNIX implementations, no executables are included. The programs should compile without great problems if you use the gcc compiler, the GNU C library and gnumake; you should say make all OS=unix in the c2cweb directory to build the binaries. Included in the package you will already find .c files extracted with CTANGLE which can be directly used to compile. How to use ---------- The only change the user has to do normally is to insert /*@@*/, starting an empty line outside of a comment or string before the first function block (normally main(){ ... }) in the C code. After this command c2cweb writes each function block into a section. Before /*@@*/ all stuff is written into a (possibly large) section. If you want to structure this further or if you have structure definitions between functions, use /*@*/ to start a new section without starting the function block algorithm (and of course /*@@*/ before the next function). The function algorithm simply counts paired braces; if none are open, a new section will begin. The file example.c has these control codes inserted already. The syntax is c2cweb [switches] csourcefile(s) | @responsefile(s) The possible switches are: -v: all comments are written in typewriter type. You will need this if you have already formatted your comments, for example /********************/ /* example.c */ /********************/. -t value: all tabs will be expanded, and the -t switch defines the tab length (default value is 4). -l: causes all linefeeds inside of C text to be output explicitly by inserting @/ (a CWEB control code) at the end of each code line. -o directory: sets the output directory which must exist already. -f format_file: include a format file (additionally to compiler.w). -b "titlestring": defines a title with the titlestring enclosed in double quotes. This string will be passed directly to \TeX. -1: one-sided output (i.e. left header is the same as right header). The last steps are calling CWEAVE with the transformed master file and then calling TeX to get a printable .dvi-file. An example: your input files are header1.h, header2.h, file1.c, file2.c, file3.c you must call then c2cweb [options] header*.h file*.c to get the *.*w files. c2cweb will now process your files and tells you which file is the input file for CWEAVE (we'll assume file3.cw). After calling cweave [options] file3.cw you get a .tex file (and some additional auxiliary files) which should be processed further by PLAIN TeX (LaTeX is not supported): tex file3[.tex] Please read the `Hints and Tricks' section about enhancements and limitations of c2cweb in the file c2cweb.w (say `make documentation' to build the .dvi file). Author ------ Werner Lemberg (a7971428@unet.univie.ac.at) Please report any errors, comments or suggestions to this email-address. Werner Lemberg Goldschlagstr. 52/14 A-1150 Vienna/Austria -------------------------------------------------------------------------------- c2cweb Paket Version 1.5 (10-Nov-1996) ======================================= Copyright (C) 1996 Werner Lemberg c2cweb verwandelt gewoehnlichen C - oder C++ - Quellcode in eine CWEB-Datei, um einen gut formatierten Ausdruck zu erhalten. Dieses Paket enthaelt ausserdem eine modifizierte Version von CWEAVE (welche die CWEB-Datei in eine TeX-Datei transformiert). Besonderheiten u.a.: Variablen und Funktionsnamen in Kursivschrift reservierte Woerter (int, char, return etc.) in Fettschrift Strings in Schreibmaschinenschrift Kommentare in Normal- oder Schreibmaschinenschrift ein Index(!) aller Variablen, Konstanten, Funktionsnamen etc. jede Funktion fuellt einen eigenen Abschnitt Das c2cweb-Paket enthaelt folgende Dateien: c2cweb.txt diese Datei history.txt Entstehungsgeschichte von c2cweb Makefile ein Makefile fuer c2cweb (UNIX, OS/2 und DOS) c2cweb.def Definitionsdatei (wird nur fuer die Kompilation unter OS/2 gebraucht) COPYING GNU Kopierlizenz c2cweb.w die CWEB-Realisation dieses Programms Um eine TeX .dvi-Datei zu erhalten sollte man make documentation eingeben (mit der CWEAVE-Version dieses Pakets) c2cweb.c extrahiert mittels CTANGLE aus c2cweb.w c2cweb.dvi die finale .dvi-Datei c2cweb.exe ausfuehrbares Programm fuer DOS und OS/2 compiler.w Compiler-abhaengige Formatierbefehle (von c2cweb erzeugte Dateien inkludieren diese Datei) c2cweb.ger ein kleines Deutsch-`Paket', um die Unterstuetzung von nichtenglischen Sprachen zu demonstrieren. example.h example.c ein C-Code-Beispiel mit bereits eingefuegten c2cweb-Kontrollbefehlen cweb/cweave.exe eine modifizierte Version von CWEAVE Version 3.2 (fuer DOS und OS/2) mit drei wichtigen neuen Eigenschaften: o mit der Option +a formatiert CWEAVE den Quellcode anders, und zwar im Prinzip if(a) {bla bla bla... } anstelle von if(a) { bla bla bla... } o die Option +i veranlasst CWEAVE, jedem Funktionsnamen () im Index anzuhaengen (nur sinnvoll, wenn alle Namen eindeutig sind) o die Behandlung von Praeprozessorbefehlen (#define etc.) wurde entscheidend verbessert, um Makros mit Parametern zu ermoeglichen cweb/cweave.w die originale CWEAVE Quelldatei aus Levy's CWEB-Paket Version 3.2 (Juli 1994) cweb/cweave.ch Change-Datei fuer cweave.w cweb/cweave.c extrahiert aus cweave.{w,ch} mittels CTANGLE cweb/common.h wird benoetigt fuer die Kompilation von cweave.exe (Original wurde etwas modifiziert) cweb/common.w unveraendert von CWEB 3.2 uebernommen cweb/common.ch Change-Datei fuer common.w cweb/common.c extrahiert aus common.{w,ch} mittels CTANGLE cweb/Makefile Make-Datei fuer CWEAVE (UNIX, OS/2 und DOS) cweb/cweave.def Definitionsfile (wird nur fuer die Kompilation unter OS/2 gebraucht) cweb/cwebmac.ori urspruengliche cwebmac.tex-Datei (leicht veraendert) cweb/cwebmac.tex alternative Formatdatei cweb/cwebmaca.tex diese alternative Formatdatei wird von TeX gelesen, wenn die +a-Option angegeben ist; sonst gleich zu cwebmac.tex cweb/prod-alt.w diese Datei ist eine Include-Datei von cweave.ch; sie enthaelt die alternativen Syntaxregeln, falls Option +a verwendet wird Es ist empfehlenswert, sich das originale CWEB-Paket zu besorgen, welches weitere Dokumentation enthaelt. Ausserdem sind Change-Dateien fuer andere Betriebssysteme enthalten. Installation ------------ c2cweb (c2cweb.exe fuer DOS und OS/2 Benutzer) sollte im Pfad sein. CWEAVE (cweave.exe fuer DOS und OS/2 Benutzer) sollte auch im Pfad sein; es braucht die Datei compiler.w (die Umgebungsvariable CWEBINPUTS setzt den Pfad). TeX muss die Dateien c2cweb.ger, cwebmac.tex und cwebmaca.tex finden koennen (der Pfad wird normalerweise von der TEXINPUT-Umgebungsvariablen kontrolliert). DOS und WINDOWS Benuetzer muessen sicherstellen, dass emx.exe und rsx.exe gefunden werden koennen (entweder im Pfad oder durch die Umgebungsvariablen EMX und RSX bestimmt). OS/2 Benuetzer muessen sicherstellen, dass emx.dll und rsx.exe gefunden werden koennen (entweder im Pfad oder durch die Umgebungsvariablen EMX und RSX bestimmt). [emx.dll, emx.exe und rsx.exe koennen im Paket exmrsx.zip gefunden werden, das Bestandteil von emTeX ist.] Bemerkungen fuer UNIX Benutzer ------------------------------ Aufgrund der vielen verschiedenen UNIX-Systeme sind keine ausfuehrbaren Dateien inkludiert. Die Programme sollten ohne groessere Probleme kompilierbar sein, wenn gcc, die GNU C-Bibliothek und gnumake verwendet wird. make all OS=unix im c2cweb- und cweb-Verzeichnis erstellt die ausfuehrbaren Dateien. In diesem Paket befinden sich bereits mittels CTANGLE extrahiert .c Dateien, die man direkt kompilieren kann. Verwendung ---------- Die einzige Veraenderung, die der Anwender normalerweise machen muss, ist das Einfuegen von /*@@*/ am Anfang einer leeren Zeile ausserhalb eines Kommentars oder Strings vor dem ersten Funktionsblock (das ist in der Regel main(){ ...}) im C-Quellcode. Nach diesem Befehl erzeugt c2cweb fuer jede Funktion einen eigenen Abschnitt. Vor /*@@*/ wird alles in eine einzige (u.U. grosse) Sektion geschrieben. Will man solche Abschnitte zusaetzlich strukturieren oder hat man Struktur-Definitionen zwischen Funktionen, sollte man /*@*/ verwenden, um einen neuen Abschnitt zu beginnen, ohne den Funktionsalgorithmus einzuschalten (und natuerlich /*@@*/ vor der naechsten Funktion einfuegen). Der Funktionsalgorithmus zaehlt einfach paarweise geschwungene Klammern; falls keine mehr offen, wird ein neuer Abschnitt begonnen. In der Beispieldatei example.c sind diese Kontrollcodes bereits enthalten. Aufruf: c2cweb [Optionen] C-Quelldatei(en) | @Response-Datei(en) Folgende Optionen sind moeglich: -v: alle Kommentare werden in Schreibmaschinenschrift ausgegeben. Dieser Schalter ist notwendig, falls die Kommentare bereits formatiert sind, zum Beispiel /********************/ /* example.c */ /********************/. -t Wert: all Tabulator-Stopps werden expandiert; -t Wert definiert die Tabulatorweite (Grundeinstellung: Wert=4). -l: Zeilenumbrueche in der Eingabe innerhalb von C-Text bleiben in der Ausgabe erhalten durch explizites Anhaengen von @/ (einem CWEB Kontrollcode) an jede Code-Zeile. -o Verzeichnis definiert das Ausgabeverzeichis (muss bereits existieren). -o Format-Datei Inkludiert (zusaetzlich zu compiler.w) eine Format-Datei -b "Titel": definiert einen Titel (in doppelten Anfuehrungszeichen). Dieser String wird direkt an TeX weitergegeben. -1: einseitige Ausgabe (d.h., linker Seitenkopf wird dem rechten Seitenkopf gleichgesetzt). Die letzten Schritte sind das Aufrufen von CWEAVE mit der transformierten Hauptdatei und danach der Aufruf von TeX, um eine druckfaehige .dvi-Datei zu erhalten. Ein Beispiel: die Eingabedateien: header1.h, header2.h, file1.c, file2.c, file3.c Man muss jetzt c2cweb [Optionen] header*.h file*.c aufrufen, um die *.*w-Dateien zu erhalten. c2cweb bearbeitet jetzt alle Eingabedateien und teilt mit, welche Datei die Eingabedatei fuer CWEAVE ist (hier im Beispiel sei es file3.cw). Nach dem Aufruf cweave [Optionen] file3.cw erhaelt man eine .tex-Datei (und einige zusaetzliche Hilfsdateien), die mit PLAIN TeX weiterverarbeitet werden muss (LaTeX wird nicht unterstuetzt): tex file3[.tex] Im Abschnitt `Hints and Tricks' in der Datei c2cweb.w werden weitere Verbesserungen und Beschraenkungen von c2cweb beschrieben (der Aufruf `make documentation' erzeugt die .dvi-Datei). Autor ----- Werner Lemberg (a7971428@unet.univie.ac.at) Bitte alle Fehler, Kommentare oder Bemerkungen an obige email-Adresse schicken. Werner Lemberg Goldschlagstr. 52/14 A-1150 Vienna/Austria --- end of c2cweb.txt ---