home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 3 / goldfish_volume_3.bin / files / dev / c / cweb / readme < prev    next >
Encoding:
Text File  |  1994-12-14  |  18.8 KB  |  380 lines
  1.                             -*-Text-*-
  2. % This file is part of CWEB (version 3.3 [p11]).
  3. % (Set TAB to 8 spaces to get the indentations right.)
  4. % The CWEB programs by Silvio Levy are based on programs by D. E. Knuth.
  5. % They are distributed WITHOUT ANY WARRANTY, express or implied.
  6. % This README file was last updated December 13, 1994 by Andreas Scherer
  7.  
  8. % This is CWEB, Version 3.3 [p11a] of December 13, 1994, 00:00:00.
  9. % This package includes CWEB, Version 3.3 of December 1994.
  10.  
  11. % Copyright (C) 1987,1990,1993 Silvio Levy and Donald E. Knuth
  12. % Copyright (C) 1991-1993 Hans-Hermann Bode
  13. % Copyright (C) 1992 Klaus Guntermann
  14. % Copyright (C) 1991,1993 Carsten Steger
  15. % Copyright (C) 1993,1994 Andreas Scherer
  16.  
  17. % Permission is granted to make and distribute verbatim copies of this
  18. % document provided that the copyright notice and this permission notice
  19. % are preserved on all copies.
  20.  
  21. % Permission is granted to copy and distribute modified versions of this
  22. % document under the conditions for verbatim copying, provided that the
  23. % entire resulting derived work is given a different name and distributed
  24. % under the terms of a permission notice identical to this one.
  25.  
  26. % Please send comments, suggestions, etc., concerning the original CWEB
  27. % implementation to levy@geom.umn.edu.
  28. % Please send comments, suggestions, etc., related to changes specific
  29. % for this modified distribution CWEB 3.3 [p11], especially language
  30. % catalog translations to scherer@genesis.informatik.rwth-aachen.de.
  31. % Postal address: Roland-Stra{\sse} 16, 52070 Aachen, Germany.
  32.  
  33. This is the ANSI-C/C++ implementation of Silvio Levy's and Donald E.
  34. Knuth's CWEB system, compiled and provided with changefiles for ANSI-C
  35. and makefiles for Borland C/C++ 3.1, SAS/C++ 6.51, and UNIX-(g)cc.
  36. Additional features differing from the original distribution are
  37. described further below.
  38.  
  39. This directory contains the following files from the original CWEB
  40. distribution (`.' denotes the current directory):
  41.  
  42. ./Makefile.unix        extended makefile from the original distribution
  43. ./README        extended readme file from the original distribution
  44. ./common.h        header file to be included in ctangle.w and cweave.w
  45. ./common.w        common code for ctangle and cweave
  46. ./comm-man.ch        change file for the complete documentation
  47. ./comm-vms.ch        example change file for VAX/VMS (not incorporated)
  48. ./ctangle.w        the tangle processor
  49. ./ctang-man.ch        change file for the complete documentation
  50. ./ctang-vms.ch        example change file for VAX/VMS (not incorporated)
  51. ./cweave.w        the weave processor
  52. ./cweav-man.ch        change file for the complete documentation
  53. ./cweav-vms.ch        example change file for VAX/VMS (not incorporated)
  54. ./cweb.1        manual page (nroff format)
  55. ./cweb.el        elisp file for GNU Emacs
  56. ./cwebman.tex        the user manual
  57. ./prod.w        production rules to be included in cweave.w
  58. ./wmerge.w        WEB-like file merger by Silvio Levy
  59. ./examples        directory containing examples of CWEB programming
  60. ./examples/extex.w    - spellchecking filter for TeX and CWEB by Don Knuth
  61. ./examples/kspell.el    - Emacs interface to extex/wordtest
  62. ./examples/Makefile.org    - generic makefile for CWEB applications
  63. ./examples/oemacs.el    - Emacs interface to oemacs
  64. ./examples/oemacs.w    - non-portable example program for OpenWindows
  65. ./examples/README.org    - README file from the examples directory
  66. ./examples/treeprint.w    - tree-structured directory lister by Norman Ramsey
  67. ./examples/wc.w        - UNIX word-count utility
  68. ./examples/wmerge.w~    - older version of Levy's wmerge
  69. ./examples/wordtest.w    - spellchecker by Don Knuth
  70. ./examples/xlib_types.w    - include file for XView programs
  71. ./examples/xview_types.w  mega-ditto
  72. ./macros/cwebmac.tex    macros for formatting
  73.  
  74. The following change files for AMIGA and PC provided with the original
  75. distribution are incorporated into the present change files in full detail
  76. by preprocessor conditionals and are no longer present in this distribution:
  77.  
  78. ./comm-amiga.ch
  79. ./comm-bs.ch
  80. ./comm-pc.ch
  81. ./ctang-bs.ch
  82. ./ctang-pc.ch
  83. ./cweav-bs.ch
  84. ./cweav-pc.ch
  85. ./Makefile.bs
  86. ./examples/wmerg-pc.ch
  87.  
  88. (In fact, I used Barry Schwartz's change files only for MSDOS support;
  89. should you really encounter problems with Big-PC-CWEB use the original
  90. CWEB distribution.)
  91.  
  92. The following files were added to this distribution by various contributors:
  93.  
  94. general:
  95. ./common.c        ctangled product of common.w and common.ch
  96. ./common.ch        change file for common.w
  97. ./ctangle.c        ctangled product of ctangle.w and ctangle.ch
  98. ./ctangle.ch        change file for ctangle.w
  99. ./cweave.ch        change file for cweave.w
  100. ./cweb.man        manual page (ASCII format)
  101. ./cweb32p10b.readme    description file from the AmiNet distribution
  102. ./cwebmana.ch        change file for cwebman.tex
  103. ./wmerge.c        ctangled product from wmerge.w and wmerge.ch
  104. ./wmerge.ch        change file for wmerge.w
  105. ./examples/cct.w    program to translate between character code tables
  106. ./examples/commonwords.w program to count word frequencies in text files
  107. ./examples/extex.ch    change file for extex.w
  108. ./examples/matrix.wpp    C++ program to invert complex 4x4 matrices
  109. ./examples/primes.w     program to print the first 1000 prime numbers
  110. ./examples/primes.ch    changes for the first 1000000 prime numbers
  111. ./examples/sample.w     program to produce random numbers
  112. ./examples/treeprint.ch    change file for treeprint.w
  113. ./examples/wc.ch    change file for wc.w
  114. ./examples/wordtest.ch    change file for wordtest.w
  115. ./include/amiga_types.w    AMIGA specific keywords by Commodore and SAS
  116. ./include/ecma94.w    Transliteration table for Latin-1
  117. ./include/hp8.w        Transliteration table for HP Roman 8
  118. ./include/mac8.w    Transliteration table for Macintosh 8-bit font
  119. ./include/pc850.w    Transliteration table for Codepage 850
  120. ./macros/Xcwebmac.tex    beautifications for cwebmac.tex
  121. ./macros/ecma94.sty    Umlauts and special characters for Latin-1
  122. ./macros/dcwebmac.tex    German captions in addition to cwebmac.tex
  123. ./macros/hp8.sty    Umlauts and special characters for HP Roman 8
  124. ./macros/fcwebmac.tex    French captions in addition to cwebmac.tex
  125. ./macros/icwebmac.tex    Italian captions in addition to cwebmac.tex
  126. ./macros/mac8.sty    Umlauts and special characters for Macintosh 8-bit
  127. ./macros/pc850.sty    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, ... on several machines
  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/cweb_arexx.f.ct catalog translation for French users
  144. ./arexx/catalogs/cweb_arexx.i.ct catalog translation for Italian users
  145. ./arexx/catalogs/english/cweb_arexx.catalog  message catalog for English users
  146. ./arexx/catalogs/francais/cweb_arexx.catalog message catalog for French users
  147.             (for compatibility reasons, the cedilla was replaced
  148.             by an ordinary `c'.  when you use this on the Amiga
  149.             you have to rename it again.)
  150. ./arexx/catalogs/italiano/cweb_arexx.catalog message catalog for Italian users
  151. ./bin/ctangle        executable ctangle processor, Amiga version
  152. ./bin/cweave        executable cweave processor, Amiga version
  153. ./bin/wmerge        executable WEB merge program, Amiga version
  154. ./bin/catalogs/cweb.cd     catalog description for English defaults
  155. ./bin/catalogs/cweb.d.ct catalog translation for German users
  156. ./bin/catalogs/cweb.h    header file with the English defaults
  157. ./bin/catalogs/cweb.i.ct catalog translation for Italian users
  158. ./bin/catalogs/dcweb.h    header file with the German defaults
  159. ./bin/catalogs/icweb.h    header file with the Italian defaults
  160. ./bin/catalogs/deutsch/cweb.catalog  message catalog for German users
  161. ./bin/catalogs/italiano/cweb.catalog message catalog for Italian users
  162. ./examples/Makefile    makefile for SAS/C compiler 6.0 and up
  163.  
  164. The additional files with extensions .tex and .c are reproducable from
  165. the other sources by means of an executable wmerge, ctangle, cweave, and
  166. an ANSI-C compiler.
  167.  
  168. Before starting, you should run cwebmana.tex (needs cwebmac.tex and
  169. (X|d|f|i)cwebmac.tex!) through TeX and print out the manual.
  170.  
  171. Make sure, that the files you got are in proper format (if you took
  172. them from a ZIP archive, line ends might still contain carriage return
  173. and linefeed characters, which may not be appropriate for your operating
  174. system).
  175.  
  176. (If you got cweb by mail, you may have cweave.w.1 and cweave.w.2
  177. instead of cweave.w.  The first thing to say then is
  178.  
  179. cat cweave.w.[12] > cweave.w
  180.  
  181. )
  182.  
  183. How to create the binaries:
  184.  
  185. 1.  Rename `Makefile.amiga' to `Makefile' or `SMakefile', for use with
  186. SMAKE.  If you want to install the package on a UNIX system with CC, C89 or
  187. GCC, use `Makefile.unix' instead.  If you want to install the package on
  188. MSDOS with Borland C/C++, use `Makefile.pc' instead or set up three
  189. projects for CTANGLE, CWEAVE, WMERGE.
  190.  
  191. 2.  Check the entries in the makefile for local conditions like a different
  192. compiler name or additional compiler options you want to use.  Check also
  193. the other lines in the makefile so that all directory definitions are set
  194. properly for your local system configuration.
  195.  
  196. 3.  Touch common.c, ctangle.c, and wmerge.c to make them up-to-date.
  197. To make ctangle, cweave and the wmerge processor say `make progs'; this
  198. should  produce actions similar to the following, possibly with harmless
  199. warning messages from the compiler (there won't be any if you use the
  200. SAS/C 6.x compiler, except some optimizer messages), and e.g., the options
  201. and the name of the compiler may be as modified in the makefile:
  202.  
  203.     sc $(CFLAGS) ctangle.c
  204.     sc $(CFLAGS) common.c
  205.     slink FROM $(OBJS) ctangle.o TO ctangle LIB $(LIBS)
  206.     ctangle cweave cweave
  207.     sc $(CFLAGS) cweave.c
  208.     slink FROM $(OBJS) cweave.o TO cweave LIB $(LIBS)
  209.     sc $(CFLAGS) link wmerge.c
  210.  
  211. or on UNIX systems
  212.  
  213.     cc -g -w -c ctangle.c
  214.     cc -g -w -DCWEBINPUTS=\"/usr/local/lib/cweb\" -c common.c
  215.     cc -g -o ctangle ctangle.o common.o 
  216.     ./ctangle cweave cweave
  217.     cc -g -w -c cweave.c
  218.     cc -g -w -o cweave cweave.o common.o
  219.     cc -g -w -o wmerge wmerge.c
  220.  
  221. To get some reassurance that things are OK, you can say `make cautiously',
  222. which ensures that ctangle will reproduce itself.  (Otherwise the source
  223. files common.w and ctangle.w won't actually have been used.)
  224.  
  225. To install cweave, ctangle, wmerge, cwebmac.tex, and (X|d|f|i)cwebmac.tex,
  226. the manual page, an emacs macro file, and the ARexx script files and
  227. associated language catalogs, say `make install'.  You probably need to
  228. be superuser to do this; but it's wise to `make all' first, BEFORE becoming
  229. superuser and saying `make install'.  You may also decide to move the files
  230. manually to their proper places.  See the makefile for details, what to move,
  231. and for suggestions, where to move it.
  232. And see the ARexx script itself for details how to make use of it
  233. from the CygnusEd Professional Editor.
  234.  
  235. If you want to recompile the programs for another system, you should
  236. take a look inside the change files common.ch, ctangle.ch, and cweave.ch.
  237. Some of the entries marked with "SYSTEM DEPENDENCIES" may need modifications
  238. appropriate for the target system.  All change files are set up to work for
  239. Amiga, PC, and UNIX identically, so no further changes will be needed if
  240. you use one of these systems.
  241.  
  242. Incidentally, if you try the recompilation with another compiler for
  243. another system, you may have no luck without changing the sources.
  244. In this case, it is necessary to do all the required changes in the
  245. .c file first, until you can compile ctangle.c and common.c.  But it
  246. is necessary then, to add the same modifications to the change file
  247. (never make any changes to the .w files!).  Finally processing ctangle.w
  248. and the extended change file for ctangle with the modified ctangle will
  249. create the same contents as the modifications made by hand.  If such
  250. changes are needed for a common compiler, please notify the authors
  251. about this and send the extended changes.
  252.  
  253. Do not edit one of the .w files under any circumstances.  Do all
  254. modifications in the associated .ch files, but keep in mind that
  255. you'll need a working ctangle processor to generate the updated .c
  256. files.  And beware:  CWEB version 3 needs a ctangle and cweave with
  257. `longest_name==1000', so any older version with `longest_name==400' will
  258. fail!  Furthermore, do not edit common.h, prod.w, or cwebmac.tex.  All
  259. system dependent changes to common.h are to be made in ctangle.ch AND
  260. cweave.ch, changes to the productions and macros should be made in
  261. additional change files.  To incorporate the changes you will need a
  262. working wmerge program.  This will be prepared when ctangle and cweave
  263. are created.  There is a tangled wmerge.c also in case you don't have
  264. a working ctangle processor so far.  However, feel free to make changes
  265. to the macro files (X|d|f|i)cwebmac.tex in the ./macros subdirectory,
  266. but notify the authors about any improvements.
  267.  
  268. If you want a full documentation of the tangle and weave programs,
  269. type `make docs'.  The documentation created will include all changes
  270. introduced by the .ch files.  To get a list of all catalog strings, you
  271. should also print the file ./bin/catalogs/cweb.h with the original set
  272. of output strings and possibly ./bin/catalogs/cweb.d.ct for a clue to
  273. translations.  If you want to use CWEB on a system without localization,
  274. there is the file ./bin/catalogs/dcweb.h, so German program versions
  275. can be created easily.  Thanks to Giuseppe Ghibò same holds for Italian.
  276.  
  277. To delete all intermediate files created in the make processes say
  278. `make clean'.  You will be left with the files in this distribution.
  279.  
  280. The weave and tangle processors as well as wmerge now recognize a
  281. CWEBINPUTS environment variable.  When an include file name (argument
  282. to the @i command) can not be found in the current directory or in the
  283. absolute path, a multi-path search is performed.  CWEBINPUTS---if not
  284. empty---may contain a list of search path names, delimited by
  285. PATH_SEPARATORs, e.g., commas.  The current directory is represented
  286. by an empty path entry, but it is searched first anyway.  Device names
  287. must end in an DEVICE_SEPARATOR, i.e., colons.  Example for AmigaOS:
  288.  
  289.     setenv CWEBINPUTS "RAM:,CWEB:includes"
  290.  
  291. In the respective makefiles for AMIGA, UNIX and PC some decent defaults
  292. are set in the compile time constant CWEBINPUTS, which always is appended
  293. to any environment variable, so you don't have to repeat the defaults.
  294.  
  295. The tangle and weave processors of this implementation are able to
  296. process traditional K&R C, ANSI C, and C++.  Note that ctangle always
  297. uses a default extension .c for its output file; this may not be
  298. appropriate for some C++ compilers, but you can work around this
  299. by supplying a third argument in the command line (see cwebman).
  300.  
  301.  
  302. Patch level [p9b] of this implementation introduced localization to other
  303. languages than English.  All output strings of ctangle and cweave were
  304. replaced by variable references to an array AppStrings in cweb.h, set to the
  305. English defaults at startup time.  This works for all systems and compilers
  306. in a compatible way.  However, version 2.1 of the AMIGA operating system
  307. introduced the use of language catalogs, thus enabling programs and
  308. applications to be inherently multilingual without recompilation.  To
  309. activate this feature, you only have to install AmigaOS 2.1/3.0.  Catalogs
  310. for various natural languages are already present at the correct place
  311. (./bin/catalogs/...), so ctangle and cweave will greet you in any of these
  312. languages, if you start them from their home directory ./bin and if your
  313. system default language is supported.  If you want to use CTANGLE, CWEAVE,
  314. and WMERGE as resident programs, you have to move the language catalogs to
  315. the appropriate directories of the LOCALE: drawer.  Catalog translations for
  316. other languages can easily be installed.  The author of this distribution
  317. would be grateful to receive catalog translations for other languages for
  318. inclusion in future versions.
  319.  
  320. Patch level [p9d] of this implementation introduced dynamic memory allocation
  321. for all internal arrays except for `flags[256]'.  By this method both ctangle
  322. and cweave can be compiled in the `NEAR' data segment, so on the AMIGA they
  323. can be made `resident', i.e., they can reside in RAM and don't have to be
  324. loaded from disk after the first time.
  325.  
  326. Patch level [p9d] of this implementation introduced an ARexx communication
  327. facility between CWEB (i.e., ctangle and cweave) and the `Message Browser'
  328. SCMSG, included in the SAS/C 6.X development system.  If you run CWEB with
  329. the `+m' option, any error messages will be displayed in the window of
  330. SCMSG.  The default setting is `off'.  You can control the behaviour of
  331. this feature by setting the environment variable SCMSGOPT to a string with
  332. any legal command line options for SCMSG as described in the documentation
  333. provided with the compiler package by SAS Institute. If the environment
  334. variable is not set, the default behaviour of SCMSG will be used.
  335.  
  336. Patch level [p9d] was evaluated on July 1, 1994, by Andreas Scherer and
  337. Burkhard Schmitt of Bayreuth University with CC and GCC on a HP Apollo
  338. workstation and a Sun 4 workstation and a SGI workstation.
  339.  
  340. Patch level [p9d] was evaluated on July 2, 1994, by Andreas Scherer
  341. with Borland C/C++ version 3.1 on a PC without any problems.  Future
  342. patch levels will not be tested with this configuration anymore.
  343. There are versions of both Makefile.pc and Makefile.unix providing
  344. better support for the internal dependencies.
  345.  
  346. Patch level [p10] was released to the AmiNet and the Comprehensive TeX
  347. Archive Network (CTAN) in August 1994 and is used on several different
  348. machines without any problems reported to the author of the distribution.
  349.  
  350.  
  351. SPECIAL NOTES for installation of CWEB 3.3 [p11] with Borland C++ 3.1
  352. for MSDOS in form of projects:
  353.  
  354. I had to follow the suggestions from the change files provided for MSDOS
  355. with the original distribution and reduce `max_toks' in CTANGLE from the
  356. obviously horribly high value 270,000 to 170,000 (Amiga and UNIX still
  357. use the original value).  This is done internally, so you don't have to
  358. care about changing anything.  170,000 still is conveniently high enough
  359. to process for example CWEAVE.W.  No other values have been changed, and
  360. on an IBM 286 CWEAVE could not be started due to "! Memory allocation
  361. failure", but maybe this is no problem nowadays in respect to PENTII.
  362.  
  363. Set up three projects for CTANGLE, CWEAVE, and WMERGE.  The first two
  364. consist of (COMMON.CC + CTANGLE.CC) and (COMMON.CC + CWEAVE.CC) (you will
  365. have to successfully install CTANGLE first and then "MAKE CWEAVE.CC"), the
  366. last works from the single source WMERGE.CC.
  367.  
  368. Select the HUGE memory model from the options menue.
  369.  
  370. Add "bin/catalogs" to the search path for header files.  ("cweb.h" is
  371. located there.)
  372.  
  373. Add DEFINE's _DEV_NULL="NUL", CWEBINPUTS="inputs/", SEPARATORS="\;\\:".
  374. (Be careful with the protective backslashes!  The first is for BCC, the
  375. second for C.)
  376.  
  377. Don't select any optimization.  Maybe you can strip the debug info somehow.
  378.  
  379. Good luck.
  380.