summaryrefslogtreecommitdiff
path: root/web/c_cpp/cweb/examples/README
diff options
context:
space:
mode:
Diffstat (limited to 'web/c_cpp/cweb/examples/README')
-rw-r--r--web/c_cpp/cweb/examples/README55
1 files changed, 55 insertions, 0 deletions
diff --git a/web/c_cpp/cweb/examples/README b/web/c_cpp/cweb/examples/README
new file mode 100644
index 0000000000..ca21cf075c
--- /dev/null
+++ b/web/c_cpp/cweb/examples/README
@@ -0,0 +1,55 @@
+This directory contains several files for programs that are tutorial
+and/or useful. If you are new to CWEB, read "wc.w" first; it's a
+typical example of CWEB applied to system programming.
+
+The Makefile on this directory is a generic way to build applications
+written in CWEB. Say, for example, "make wc" to get an executable
+program "wc" from wc.w. Say "make wc.dvi" to get a printable listing
+of its documentation. The program "wc" is a slight improvement over
+UNIX's standard word-count utility. (Try it, for example, with "wc *".)
+
+The treeprint program, by Norman Ramsey, generates tree-structured
+representations of file hierarchies. To use it, say "make treeprint.run"
+and then
+ find dir -type p -print | sort | treeprint
+(on a UNIX system), where dir is a directory with interesting subdirectories.
+
+The wmerge program, by Silvio Levy, produces a single CWEB file from a
+given CWEB file and a change file. It expands any "web include" (@i)
+specifications in the original CWEB file. To use it, say "make wmerge.run"
+and then, e.g., "wmerge foo.w bar.ch > foobar.w". Both CTANGLE and
+CWEAVE already accept change files, so you need not merge anything yourself
+in normal day-to-day operations; but wmerge can be useful in connection with
+the spelling checker described below.
+
+If you intend to read the source code of CTANGLE and CWEAVE, you may
+well wish to read wmerge.w first, or the hardcopy version obtained from
+"make wmerge.dvi"; it is similar but much simpler.
+
+The extex and wordtest programs, by Don Knuth, are useful spellcheckers.
+After "make extex.run" say also "ln extex excweb"; this gives
+you two filter programs, extex and excweb, that remove extraneous
+material from TeX and CWEB source files, respectively. To use them,
+you can say for example
+ cat foo.w | excweb | spell
+(or replace "cat foo.w" with "wmerge foo.w bar.ch"). A similar pipeline
+for TeX files would be
+ cat foo.tex | extex | spell
+Even better is to replace "spell" by "wordtest /usr/local/lib/dict/words",
+if you have a suitable dictionary. One such dictionary in the public domain
+can be found in directory ~ftp/pub/dict at ftp.cs.stanford.edu, available
+via anonymous ftp. To make your own dictionary from given ones,
+ cat dict1 dict2 dict3 dict4 | wordtest > words
+is quick and effective. See the documentation of wordtest for more info.
+
+A file kspell.el that provides an emacs user interface to extex+excweb+wordtest
+also appears in this directory. (Somebody should write ELWEB...)
+
+The files xview_types.w and xlib_types.w are examples of @i (include) files
+that can be used when writing XView programs. They are based on the header
+files in OpenWindows Version 3.0.
+
+An example XView application appears in Knuth's program oemacs.w, which
+he uses for heavy emacsing. It's not very portable, but if you have
+OpenWindows3 and a Sun Type-4 keyboard you may like it as much as he does.
+(It replaces "emacstool".) The file oemacs.el goes with it.