summaryrefslogtreecommitdiff
path: root/web/c_cpp/c2cweb/c2cweb.txt
blob: 9a7b64eb62181723c8e4b40de69c1ce5a9a9e1f0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479

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