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 ---