Fresh Fish 2/FFMCD02.bin/new/dev/misc/cweb/readme

Text File | 1993-12-21 | 12.0 KB | 249 lines

                            -*-Text-*-
% This file, README.AMIGA, is part of CWEB-p.
% The CWEB programs by Silvio Levy are based on programs by D. E. Knuth.

% Copyright (C) 1987,1990,1993 Silvio Levy and Donald E. Knuth
% Copyright (C) 1991,1992,1993 Hans-Hermann Bode
% Copyright (C) 1992 Klaus Guntermann
% Copyright (C) 1991,1993 Carsten Steger
% Copyright (C) 1993 Andreas Scherer

% Permission is granted to make and distribute verbatim copies of this
% document provided that the copyright notice and this permission notice
% are preserved on all copies.

% Permission is granted to copy and distribute modified versions of this
% document under the conditions for verbatim copying, provided that the
% entire resulting derived work is distributed under the terms of a
% permission notice identical to this one.

% Please send comments, suggestions, etc. to [e-mail].
% If related to changes specific for MSDOS, however,
% send them to Hans-Hermann Bode,
% hhbode@@dosuni1.rz.uni-osnabrueck.de or HHBODE@@DOSUNI1.BITNET.
% If related to changes specific for AMIGA, however,
% send them to Andreas Scherer,
% Abt-Wolf-Straße 17, 96215 Lichtenfels, Germany.

This is the ANSI-C/C++ implementation of Silvio Levy's and Donald E.
Knuth's CWEB system, compiled and provided with changefiles for ANSI C and
Turbo C++ and a makefile for Turbo Make by Hans-Hermann Bode, including
additional changes to improve support of ANSI-C compilers and a makefile
for c89 by Klaus Guntermann, and including additional changes for full
support of ANSI-C compilers and to support the SAS/C 6.0 compiler on the
AMIGA by Andreas Scherer.

Note that the changes for the Turbo-C++ compiler are made conditional
(they will become effective only if the symbol __TURBOC__ is defined,
which automatically is the case when compiled with Turbo C++), so users
of other systems with ANSI-C compilers might be able to compile the
sources without editing.

Note that the changes for the AMIGA and SAS/C 6.0 compiler support are
made conditional (they will become effective only if the symbol _AMIGA
is defined, which automatically is the case when compiled with the SAS/C
compiler).  AMIGA patch 2.8 [p7] was recently evaluated on a HP Apollo
workstation and absolutely no change to the AMIGA source had to be made,
only the makefile for the C89 compiler proved to include to few dependencies.

This directory contains the following files from the original CWEB
distribution (`.' denotes the local directory):

./makefile.org        makefile from the original distribution
./readme.org        readme file from the original distribution
./common.h        header file to be included in ctangle.w and cweave.w
./common.w        common code for ctangle and cweave
./common-man.ch        change file for the complete documentation
./common-vms.ch        example change file for VAX/VMS (not incorporated)
./ctangle.w        the tangle processor
./ctangle-man.ch    change file for the complete documentation
./ctangle-vms.ch    example change file for VAX/VMS (not icorporated)
./cweave.w        the weave processor
./cweave-man.ch        change file for the complete documentation
./cweave-vms.ch        example change file for VAX/VMS (not incorporated)
./cweb.1        manual page (nroff format)
./cweb.el        elisp file for GNU Emacs
./cwebmac.tex        macros for formatting
./cwebman.tex        the user manual
./prod.w        production rules to be included in cweave.w
./examples        directory containing examples of CWEB programming
./examples/extex.w    - spellchecking filter for TeX and CWEB by Don Knuth
./examples/kspell.el    - Emacs interface to extex/wordtest
./examples/makefile    - generic makefile for CWEB applications
./examples/oemacs.el    - Emacs interface to oemacs
./examples/oemacs.w    - non-portable example program for OpenWindows
./examples/readme    - readme file from the examples directory
./examples/treeprint.w    - tree-structured directory lister by Norman Ramsey
./examples/wc.w        - UNIX word-count utility
./examples/wmerge.w    - WEB-like file merger by Silvio Levy
./examples/wordtest.w    - spellchecker by Don Knuth
./examples/xlib_types.w    - include file for XView programs
./examples/xview_types.w- ditto

The following files are added in this distribution by various contributors:

general:
./cweb.man        manual page (ASCII format)
./common-p.hch        change file for common.h
./common-p.ch        change file for common.w
./ctangle-p.ch        change file for ctangle.w
./cweave-p.ch        change file for cweave.w
./prod-p.ch        change file for prod.w
./cwebmang.ch        change file for cwebman.tex
./macros/ccwebmac.tex    beautifications for cwebmac.tex
./macros/gcwebmac.tex    German version of cwebmac.tex
./common.c        CTANGLEd product of common.w and common-p.ch
./ctangle.c        CTANGLEd product of ctangle.w and ctangl-p.ch
./examples/commonwords.w program to count word frequencies in text files
./examples/extex-p.ch    change file for extex.w
./examples/primes.w     program to print the first 1000 prime numbers
./examples/sample.w     program to produce random numbers
./examples/treeprint-p.ch change file for treeprint.w (doesn't work for Amiga!)
./examples/wc-p.ch    change file for wc.w
./examples/wordtest-p.ch change file for wordtest.w
./examples/wmerge.c    CTANGLEd product of wmerge.w and wmerge-p.ch
./examples/wmerge-p.ch    change file for wmerge.w

special for users of c89 or other ANSI C compilers by Klaus Guntermann:
./makefile.c89        makefile for c89
./readme.c89        this file for users of c89

special for PC users by Hans-Hermann Bode:
./makefile.pc        makefile for Turbo C++
./readme.pc        informations for PC users

special for AMIGA users by Andreas Scherer:
./readme.amiga        informations for AMIGA users (this file)
./makefile.amiga    makefile for SAS/C compiler 6.0 and up
./bin/ctangle        executable tangle processor, Amiga version
./bin/cweave        executable weave processor, Amiga version
./bin/wmerge        executable WEB merge program, Amiga version
./examples/smakefile    MAKEFILE for SAS/C compiler 6.0 and up
./ARexx/Start_Web.ced    ARexx script to start cweave and ctangle from CED
./ARexx/Catalogs/cweb.cd Catalog description for German defaults
./ARexx/Catalogs/cweb.e.ct Catalog translation for English users
./ARexx/Catalogs/english/cweb.catalog Message catalog for English users
./ARexx/Compile.ced    ARexx script to start SAS/C 6.3 from CED (V3.5+)

The additional files with extensions .h, .w, .tex, and .c are
reproducable from the other sources by means of an executable WMERGE,
CTANGLE, CWEAVE, and an ANSI-C compiler.

Before starting, you should run cwebmang.tex (needs ccwebmac.tex and
gcwebmac.tex!) through TeX and print out the manual.  If you are not
going to use this distribution on an AMIGA, you can reclaim some disk
space by removing all AMIGA related files.  You will have to compile
the binaries using your ANSI-C compiler.

Make sure, that the files you got are in proper format (if you took
them from a ZIP archive, line ends might still contain carriage return
and linefeed characters, which may not be appropriate for your
operating system).  Make sure, that you do *not* use one of those stupid
operating systems with only eight+three (ridiculous) significant characters
in file names, because there are several files in this distribution with
longer names (see the list above).  You will have to rename some files,
when you use DOS.

How to create the binaries:

1.  Rename the makefile.amiga to Makefile or SMakefile, for use with
SMake.  Note that makefile.org is lacking some dependencies, so you
better start from makefile.c89 when on a Un*x system.  And even this
proved to be no good: When recompiling the AMIGA source on a HP Apollo
workstation with C89, absolutely *no* change had to be made to the
common.c and ctangle.c source files, but the makefile included to few
dependencies.

2.  If your compiler is not named SC, you have to change the CC
definition to the proper call in the Makefile, e.g., for the ANSI-C
version of gcc use
    CC = gcc -ansi
Check also the other lines in Makefile so that all directory
definitions are set properly for your local system and configuration.

3.  Touch common.c, ctangle.c, and examples/wmerge.c to make them
up-to-date.  To make ctangle, cweave and the wmerge processor say
`make programs'; this should  produce actions similar to the following,
possibly with harmless warning messages from the compiler (there won't
be any if you use SAS/C 6.3!), and e.g. the options and the name of the
compiler may be as modified in Makefile:

sc nolink ctangle.c
sc nolink common.c
slink FROM $(OBJS) ctangle.o TO ctangle LIB $(LIBS)
./ctangle cweave cweave-p.ch
sc code=FAR nolink cweave.c
slink FROM $(OBJS) cweave.o  TO cweave LIB $(LIBS)
(cd examples; sc link wmerge.c)

To get some reassurance that things are OK, you can say `make
cautiously', which ensures that CTANGLE will reproduce itself.
(Otherwise the source files common.w and ctangle.w won't actually
have been used.)

To install cweave, ctangle, wmerge, ccwebmac.tex and gcwebmac.tex,
the manual page, an emacs macro file, and the ARexx script files,
say `make install'.  You may also decide to move the files manually
to their proper places.  See the Makefile for details, what to move,
and for suggestions, where to move it.

Incidentally, if you try the recompilation with another compiler, you
may have no luck without changing the sources.  In this case, it is
necessary to do all the required changes in the .c file first, until
you can compile ctangle.c and common.c.  But it is necessary then, to
add the same modifications to the change file (never make any changes
to the .w files!).  Finally processing ctangle.w and the extended
change file for ctangle with the modified ctangle will create the same
contents as the manual modifications.  If such changes are needed for
a common compiler, please notify the authors about this and send the
extended changes.

4.  Do not edit one of the .w files under any circumstances.  Do all
modifications in the associated .ch files, but keep in mind that
you'll need a working ctangle processor to generate the updated .c
files.  And beware:  CWEB version 3.0 needs a CTANGLE and CWEAVE with
`longest_name==1000', so any older version with `longest_name==400' will
fail!  Furthermore, do not edit common.h, prod.w, or cwebmac.tex.
Make your modifications to common-p.hch or prod-p.ch.  To incorporate the
changes you will need a working wmerge program.  This will be prepared
when ctangle and cweave are created.  There is a tangled wmerge.c also
in case you don't have a working ctangle processor so far.  However, you
are allowed to make changes to ccwebmac.tex and gcwebmac.tex in the
./macros subdirectory.

5.  If you want a full documentation of the tangle and weave programs,
type `make docs'.  The documentation created will include the changes
needed for the ANSI-C/C++ and the AMIGA extensions.

6.  To delete all intermediate files created in the make processes say
`make clean'.  You will be left with the files in this distribution.

7.  The weave and tangle processors as well as wmerge in the example
directory now recognize a CWEBINPUTS environment variable.  When an
include file name (argument to the @i command) can not be found in the
current directory or in the absolute path, a multi-path search is
performed.  CWEBINPUTS---if not empty---may contain a list of search
path names, delimited by PATH_SEPARATORs.  The current directory is
represented by an empty path entry, but it is search first anyway.
Device names must end in an DEVICE_SEPARATOR.  Example for AmigaOS:

    setenv CWEBINPUTS "RAM:,CWEB:includes"

If CWEBINPUTS is not set, some sensible defaults are searched (honest!).

8.  The tangle and weave processors of this implementation are able to
process traditional C, ANSI C, and C++.  Note that CTANGLE always uses
a default extension .c for its output file; this may not be appropriate
for C++ compilers, but you can work around this by supplying a third
argument in the command line (see cwebman).

9.  You can define a font for comments in the C part of the modules by means
of the \cmntfont macro.  It defaults to \tenrm, i.e., ten-point roman;
if you don't like this, say, e.g.,

  \let\cmntfont=\tenss

to get a ten-point sans-serif comment font or whatever.  This command
should be placed in the limbo section of your sources or in your own
version of cwebmac.tex, e.g., like in ccwebmac.tex.