home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 2 / goldfish_vol2_cd1.bin / files / dev / c / cweb / readme < prev    next >
Text File  |  1994-08-12  |  16KB  |  316 lines
  1.                             -*-Text-*-
  2. % This file is part of CWEB.  (Set TAB to 8 spaces.)
  3. % The CWEB programs by Silvio Levy are based on programs by D. E. Knuth.
  4. % They are distributed WITHOUT ANY WARRANTY, express or implied.
  5. % This README file was last updated August 12, 1994 by Andreas Scherer
  6.  
  7. % This is CWEB, Version 3.2 [p10] of August 12, 1994, 17:30:00.
  8. % This package includes CWEB, Version 3.2 of July 1994.
  9.  
  10. % Copyright (C) 1987,1990,1993 Silvio Levy and Donald E. Knuth
  11. % Copyright (C) 1991-1993 Hans-Hermann Bode
  12. % Copyright (C) 1992 Klaus Guntermann
  13. % Copyright (C) 1991,1993 Carsten Steger
  14. % Copyright (C) 1993,1994 Andreas Scherer
  15.  
  16. % Permission is granted to make and distribute verbatim copies of this
  17. % document provided that the copyright notice and this permission notice
  18. % are preserved on all copies.
  19.  
  20. % Permission is granted to copy and distribute modified versions of this
  21. % document under the conditions for verbatim copying, provided that the
  22. % entire resulting derived work is given a different name and distributed
  23. % under the terms of a permission notice identical to this one.
  24.  
  25. % Please send comments, suggestions, etc., concerning the original CWEB
  26. % implementation to levy@geom.umn.edu.
  27. % Please send comments, suggestions, etc., related to changes specific
  28. % for this modified distribution CWEB 3.2 [p10], especially language
  29. % catalog translations to Andreas Scherer,
  30. % Abt-Wolf-Straße 17, 96215 Lichtenfels, Germany, [++49](0)9571/2013.
  31.  
  32. This is the ANSI-C/C++ implementation of Silvio Levy's and Donald E.
  33. Knuth's CWEB system, compiled and provided with changefiles for ANSI-C
  34. and makefiles for Borland C/C++ 3.1, SAS/C++ 6.51, and UNIX-(g)cc.
  35. Additional features differing to the original distribution are described
  36. further below.
  37.  
  38. AMIGA patch 3.1 [p9d] was evaluated on July 1, 1994, by Andreas Scherer
  39. and Burkhard Schmitt of Bayreuth University with CC and GCC on a HP Apollo
  40. workstation and a Sun 4 workstation and a SGI workstation.
  41. AMIGA patch 3.1 [p9d] was evaluated on July 2, 1994, by Andreas Scherer
  42. with Borland C/C++ version 3.1 on a PC without any problems.
  43. There are versions of both MAKEFILE.PC and MAKEFILE.UNIX providing
  44. better support for the internal dependencies.
  45.  
  46. This directory contains the following files from the original CWEB
  47. distribution (`.' denotes the current directory):
  48.  
  49. ./makefile.unix        extended makefile from the original distribution
  50. ./readme        extended readme file from the original distribution
  51. ./common.h        header file to be included in ctangle.w and cweave.w
  52. ./common.w        common code for ctangle and cweave
  53. ./comm-man.ch        change file for the complete documentation
  54. ./comm-vms.ch        example change file for VAX/VMS (not incorporated)
  55. ./ctangle.w        the tangle processor
  56. ./ctang-man.ch        change file for the complete documentation
  57. ./ctang-vms.ch        example change file for VAX/VMS (not incorporated)
  58. ./cweave.w        the weave processor
  59. ./cweav-man.ch        change file for the complete documentation
  60. ./cweav-vms.ch        example change file for VAX/VMS (not incorporated)
  61. ./cweb.1        manual page (nroff format)
  62. ./cweb.el        elisp file for GNU Emacs
  63. ./cwebman.tex        the user manual
  64. ./prod.w        production rules to be included in cweave.w
  65. ./wmerge.w        WEB-like file merger by Silvio Levy
  66. ./examples        directory containing examples of CWEB programming
  67. ./examples/extex.w    - spellchecking filter for TeX and CWEB by Don Knuth
  68. ./examples/kspell.el    - Emacs interface to extex/wordtest
  69. ./examples/makefile.org    - generic makefile for CWEB applications
  70. ./examples/oemacs.el    - Emacs interface to oemacs
  71. ./examples/oemacs.w    - non-portable example program for OpenWindows
  72. ./examples/readme.org    - readme file from the examples directory
  73. ./examples/treeprint.w    - tree-structured directory lister by Norman Ramsey
  74. ./examples/wc.w        - UNIX word-count utility
  75. ./examples/wordtest.w    - spellchecker by Don Knuth
  76. ./examples/xlib_types.w    - include file for XView programs
  77. ./examples/xview_types.w  mega-ditto
  78. ./macros/cwebmac.tex    macros for formatting
  79.  
  80. The following change files for AMIGA and PC provided with the original
  81. distribution are incorporated into the present change files in full (well,
  82. almost full: the memory restrictions for MSDOS had not to be met for UNIX
  83. and AMIGA, so throw them away) detail by preprocessor conditionals and
  84. are no longer present in this distribution:
  85.  
  86. ./comm-amiga.ch
  87. ./comm-bs.ch
  88. ./comm-pc.ch
  89. ./ctang-bs.ch
  90. ./ctang-pc.ch
  91. ./cweav-bs.ch
  92. ./cweav-pc.ch
  93. ./makefile.bs
  94. ./wmerg-pc.ch
  95.  
  96. The following files were added to this distribution by various contributors:
  97.  
  98. general:
  99. ./common.c        ctangled product of common.w and common.ch
  100. ./common.ch        change file for common.w
  101. ./ctangle.c        ctangled product of ctangle.w and ctangle.ch
  102. ./ctangle.ch        change file for ctangle.w
  103. ./cweave.ch        change file for cweave.w
  104. ./cweb.man        manual page (ASCII format)
  105. ./cweb32p10.readme    description file from the InterNet distribution
  106. ./cwebmang.ch        change file for cwebman.tex
  107. ./wmerge.c        ctangled product from wmerge.w and wmerge.ch
  108. ./wmerge.ch        change file for wmerge.w
  109. ./examples/cct.w    program to translate between character code tables
  110. ./examples/commonwords.w program to count word frequencies in text files
  111. ./examples/extex.ch    change file for extex.w
  112. ./examples/matrix.wpp    C++ program to invert complex 4x4 matrices
  113. ./examples/primes.w     program to print the first 1000 prime numbers
  114. ./examples/sample.w     program to produce random numbers
  115. ./examples/treeprint.ch    change file for treeprint.w
  116. ./examples/wc.ch    change file for wc.w
  117. ./examples/wordtest.ch    change file for wordtest.w
  118. ./include/ecma94.w    Transliteration table for Latin-1
  119. ./include/hp8.w        Transliteration table for HP Roman 8
  120. ./include/mac8.w    Transliteration table for Macintosh 8-bit font
  121. ./include/pc850.w    Transliteration table for Codepage 850
  122. ./macros/ccwebmac.tex    beautifications for cwebmac.tex
  123. ./macros/ecma94.tex    Umlauts and special characters for Latin-1
  124. ./macros/gcwebmac.tex    German captions in addition to cwebmac.tex
  125. ./macros/hp8.tex    Umlauts and special characters for HP Roman 8
  126. ./macros/mac8.tex    Umlauts and special characters for Macintosh 8-bit
  127. ./macros/pc850.tex    Umlauts and special characters for Codepage 850
  128.  
  129. special for PC users by Hans-Hermann Bode modified by Andreas Scherer:
  130. ./makefile.pc        makefile for Borland C/C++
  131.  
  132. special for users of cc, c89, gcc or other ANSI C compilers for UNIX
  133. by Klaus Guntermann modified by Andreas Scherer according to the original
  134. makefile from the CWEB distribution:
  135. ./makefile.unix        makefile for cc, c89, gcc, ...
  136.  
  137. special for AMIGA users by Andreas Scherer:
  138. ./makefile.amiga    makefile for SAS/C compiler 6.0 and up
  139. ./arexx/compile.ced    ARexx script to start SAS/C 6.x from CED (V3.5+)
  140. ./arexx/start_web.ced    ARexx script to start cweave and ctangle from CED
  141. ./arexx/catalogs/cweb_arexx.cd Catalog description for German defaults
  142. ./arexx/catalogs/cweb_arexx.e.ct Catalog translation for English users
  143. ./arexx/catalogs/english/cweb_arexx.catalog Message catalog for English users
  144. ./bin/ctangle        executable ctangle processor, Amiga version
  145. ./bin/cweave        executable cweave processor, Amiga version
  146. ./bin/wmerge        executable WEB merge program, Amiga version
  147. ./bin/catalogs/cweb.cd    Catalog description for English defaults
  148. ./bin/catalogs/cweb.d.ct Catalog translation for German users
  149. ./bin/catalogs/cweb.h    header file with the English defaults
  150. ./bin/catalogs/gcweb.h    header file with the German defaults
  151. ./bin/catalogs/deutsch/cweb.catalog Message catalog for German users
  152. ./examples/makefile    makefile for SAS/C compiler 6.0 and up
  153.  
  154. The additional files with extensions .tex and .c are
  155. reproducable from the other sources by means of an executable
  156. wmerge, ctangle, cweave, and an ANSI-C compiler.
  157.  
  158. Before starting, you should run cwebmang.tex (needs cwebmac.tex and
  159. ccwebmac.tex and gcwebmac.tex!) through TeX and print out the manual.
  160.  
  161. Make sure, that the files you got are in proper format (if you took
  162. them from a ZIP archive, line ends might still contain carriage return
  163. and linefeed characters, which may not be appropriate for your operating
  164. system).
  165.  
  166. (If you got cweb by mail, you may have cweave.w.1 and cweave.w.2
  167. instead of cweave.w.  The first thing to say then is
  168.  
  169. cat cweave.w.[12] > cweave.w
  170.  
  171. )
  172.  
  173. How to create the binaries:
  174.  
  175. 1.  Rename `makefile.amiga' to `makefile' or `smakefile', for use with
  176. SMAKE.  If you want to install the package on a UNIX system with CC, C89 or
  177. GCC, use `makefile.unix' instead.  If you want to install the package on
  178. MSDOS with Borland C/C++, use `makefile.pc' instead.
  179.  
  180. 2.  Check the entries in the makefile for local conditions like a different
  181. compiler name or additional compiler options you want to use.  Check also
  182. the other lines in the makefile so that all directory definitions are set
  183. properly for your local system configuration.
  184.  
  185. 3.  Touch common.c, ctangle.c, and wmerge.c to make them up-to-date.
  186. To make ctangle, cweave and the wmerge processor say `make progs'; this
  187. should  produce actions similar to the following, possibly with harmless
  188. warning messages from the compiler (there won't be any if you use the
  189. SAS/C 6.x compiler, except some optimizer messages), and e.g., the options
  190. and the name of the compiler may be as modified in the makefile:
  191.  
  192.     sc $(CFLAGS) ctangle.c
  193.     sc $(CFLAGS) common.c
  194.     slink FROM $(OBJS) ctangle.o TO ctangle LIB $(LIBS)
  195.     ctangle cweave cweave.ch
  196.     sc $(CFLAGS) cweave.c
  197.     slink FROM $(OBJS) cweave.o TO cweave LIB $(LIBS)
  198.     sc $(CFLAGS) link wmerge.c
  199.  
  200. or on UNIX systems
  201.  
  202.     cc -g -w -c ctangle.c
  203.     cc -g -w -DCWEBINPUTS=\"/usr/local/lib/cweb\" -c common.c
  204.     cc -g -o ctangle ctangle.o common.o 
  205.     ./ctangle cweave
  206.     cc -g -w -c cweave.c
  207.     cc -g -w -o cweave cweave.o common.o
  208.     cc -g -w -o wmerge wmerge.c
  209.  
  210. To get some reassurance that things are OK, you can say `make cautiously',
  211. which ensures that ctangle will reproduce itself.  (Otherwise the source
  212. files common.w and ctangle.w won't actually have been used.)
  213.  
  214. To install cweave, ctangle, wmerge, cwebmac.tex, ccwebmac.tex, and
  215. gcwebmac.tex, the manual page, an emacs macro file, and the ARexx script
  216. files and associated language catalogs, say `make install'.  You probably
  217. need to be superuser to do this; but it's wise to `make all' first, BEFORE
  218. becomming superuser and saying `make install'.  You may also decide to move
  219. the files manually to their proper places.  See the Makefile for details,
  220. what to move, and for suggestions, where to move it.
  221. And see the ARexx script itself for details how to make use of it
  222. from the CygnusEd Professional Editor.
  223.  
  224. If you want to recompile the programs for another system, you should take a
  225. look inside the change files common.ch, comm-p.hch, ctangle.ch, and
  226. cweave.ch.  Some of the entries marked with "SYSTEM DEPENDENCIES" may need
  227. modifications appropriate for the target system.  All change files are set
  228. up to work for Amiga, PC, and UNIX identically, so no further changes will
  229. be needed if you use on of these systems.
  230.  
  231. Incidentally, if you try the recompilation with another compiler for
  232. another system, you may have no luck without changing the sources.
  233. In this case, it is necessary to do all the required changes in the
  234. .c file first, until you can compile ctangle.c and common.c.  But it
  235. is necessary then, to add the same modifications to the change file
  236. (never make any changes to the .w files!).  Finally processing ctangle.w
  237. and the extended change file for ctangle with the modified ctangle will
  238. create the same contents as the modifications made by hand.  If such
  239. changes are needed for a common compiler, please notify the authors
  240. about this and send the extended changes.
  241.  
  242. Do not edit one of the .w files under any circumstances.  Do all
  243. modifications in the associated .ch files, but keep in mind that
  244. you'll need a working ctangle processor to generate the updated .c
  245. files.  And beware:  CWEB version 3 needs a ctangle and cweave with
  246. `longest_name==1000', so any older version with `longest_name==400' will
  247. fail!  Furthermore, do not edit common.h, prod.w, or cwebmac.tex.
  248. Make your modifications to comm-p.hch and add change files for the
  249. other two.  To incorporate the changes you will need a working wmerge
  250. program.  This will be prepared when ctangle and cweave are created.
  251. There is a tangled wmerge.c also in case you don't have a working
  252. ctangle processor so far.  However, feel free to make changes to the
  253. macroc files ccwebmac.tex and gcwebmac.tex in the ./macros subdirectory.
  254.  
  255. If you want a full documentation of the tangle and weave programs,
  256. type `make docs'.  The documentation created will include all changes
  257. introduced by the .ch files.  To get a list of all catalog strings, you
  258. should also print the file ./bin/catalogs/cweb.h with the original set
  259. of output strings and possibly ./bin/catalogs/cweb.d.ct for a clue to
  260. translations.  If you want to use CWEB on a system without localization,
  261. there is the file ./bin/catalogs/gcweb.h, so German program versions
  262. can be created easily.
  263.  
  264. To delete all intermediate files created in the make processes say
  265. `make clean'.  You will be left with the files in this distribution.
  266.  
  267. The weave and tangle processors as well as wmerge now recognize a
  268. CWEBINPUTS environment variable.  When an include file name (argument
  269. to the @i command) can not be found in the current directory or in the
  270. absolute path, a multi-path search is performed.  CWEBINPUTS---if not
  271. empty---may contain a list of search path names, delimited by
  272. PATH_SEPARATORs, i.e., commas.  The current directory is represented
  273. by an empty path entry, but it is searched first anyway.  Device names
  274. must end in an DEVICE_SEPARATOR, i.e., colons.  Example for AmigaOS:
  275.  
  276.     setenv CWEBINPUTS "RAM:,CWEB:includes"
  277.  
  278. In the respective makefiles for AMIGA, UNIX and PC some decent defaults
  279. are set in the compile time constant CWEBINPUTS.
  280.  
  281. The tangle and weave processors of this implementation are able to
  282. process traditional C, ANSI C, and C++.  Note that ctangle always uses
  283. a default extension .c for its output file; this may not be appropriate
  284. for some C++ compilers, but you can work around this by supplying a third
  285. argument in the command line (see cwebman).
  286.  
  287. Patch level [p9b] of this implementation introduced localization to other
  288. languages than English.  All output strings of ctangle or cweave were
  289. replaced by variable references to an array AppStrings in cweb.h, set to the
  290. English defaults at startup time.  This works for all systems and compilers
  291. in a compatible way.  However, version 2.1 of the AMIGA operating system
  292. introduced the use of language catalogs, thus enabling programs and
  293. applications to be inherently multilingual without recompilation.  To
  294. activate this feature, you only have to install AmigaOS 2.1/3.0.  A German
  295. catalog is already there at the right place (./bin/catalogs/deutsch), so
  296. ctangle and cweave will great you in German, if you start them from their
  297. home directory ./bin and if your system default language is German.
  298. Catalog translations for other languages can easily be installed.
  299.  
  300. Patch level [p9d] of this implementation introduced dynamic memory allocation
  301. for all internal arrays except for `flags[256]'.  By this method both ctangle
  302. and cweave can be compiled in the `NEAR' data segment, so on the AMIGA they
  303. can be made `resident', i.e., they can reside in RAM and don't have to be
  304. loaded from disk after the first time.
  305.  
  306. Patch level [p9d] of this implementation introduced an ARexx communication
  307. facility between CWEB (i.e., ctangle and cweave) and the `Message Browser'
  308. SCMSG, included in the SAS/C 6.X development system.  If you run CWEB with
  309. the `+m' option, any warnings or error messages will be displayed in the
  310. window of SCMSG.  The default setting is `off'.  You can control the
  311. behaviour of this feature by setting the environment variable SCMSGOPT
  312. to a string with any legal command line options for SCMSG as described
  313. in the documentation provided with the compiler package by SAS Institute.
  314. If the environment variable is not set, the default behaviour of SCMSG
  315. will be used.
  316.