summaryrefslogtreecommitdiff
path: root/web/spiderweb/README
blob: c615d5adb355d0e1233e3b9a448c972253f2aa69 (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
This is Spidery WEB, tool for building a WEB system for the language
of your choice.  It was probably gotten by anonymous ftp from the
Comprehensive TeX Archive Network, possibly from niord.shsu.edu.  My
colleagues and I have used Spider to build WEB systems for Ada, C,
AWK, and other languages.  Spidery WEB is no longer supported; the
lessons learned in its implementation and use have been applied to the
design of `noweb', a much simpler literate-programming tool.  noweb is
available by anonymous ftp from csservices.princeton.edu:pub/noweb.shar.Z.
ORA Corp makes some effort to keep Spidery WEB working; bug reports,
fixes, and new language descriptions can be sent to spider-bugs@oracorp.com.
The rest of this file contains a brief description of Spidery WEB and
this distribution; more extensive documentation can be found in the
doc subdirectory.

INTRODUCTION

Spider reads a description of a programming language, and writes
source code for a Weave and Tangle which support that language.  The
language-dependent parts are derived from the description given
Spider, and the language-independent parts are taken from ``master
copies'' of Weave and Tangle.  The master copies are derived from
Silvio Levy's CWEB, and the Tangle and Weave that are constructed are
implemented in C.  Spider is implemented as an Awk program.

An exhaustive list of Spidery Web's features would interest only Web
experts, but I do want to mention some features that I hope will
encourage people to use Spidery {\tt WEB}.

	Tangle and Weave can read from multiple files (this feature is 
	present in Levy's CWEB), and Tangle can write to multiple files.
	Included files will be searched for on a path if not found in the
	current directory.  These features make Spidery WEB more
	usable on systems that have make.

	TANGLE can expand macros with multiple parameters.

	TANGLE writes #line directives, so you can debug at the	WEB
	source level if your compiler respects the C~conventions for #line.


Many features of WEB seem to exist only to compensate for deficiencies
in PASCAL, and most of those were dropped in CWEB.  I have changed
much of CWEB in order to avoid being bound too much by C conventions.
As a result, there are dozens of minor differences between Spidery WEB
and original WEB.  To give just one example, Spidery WEB supports
octal and hexadecimal constants using WEB-style notation, not the C
notation used in CWEB.

Spider can generate WEB systems for a variety of languages.  The
author has written Spider description files for C, AWK, Ada, SSL (a
language that describes attribute grammars to the Cornell Synthesizer
Generator), the Larch Shared Language (a language for describing
equational theories), and Dijkstra's language of guarded commands.
Debugging the grammar that WEAVE uses to prettyprint the language is
the most time-consuming part of creating a WEB system for a new target
language, and Spider makes it trivial to change that grammar.  To make
a Spider description file for an Algol-like language that uses infix
expression notation, an experienced systems programmer should be able
to adapt an existing Spider description file very quickly.

Spider's major limitations are lexical.  All Spidery WEBs assume that
spaces and tabs in the input are not significant, except as
separators; this makes it impossible to construct Spidery WEBs for
languages like Fortran and Miranda, where the position of text on a
line is significant.  (You would have to modify the ``master copies''
of Tangle and Weave to change the lexical analyzer.)  The lexical
structures of identifiers, string literals, and numeric literals are
fixed.

Spider's major value is that is makes it possible to create a new WEB
quickly, and to tinker with it easily.  My colleagues and I have used
Spidery WEB to write programs in Ada, C, and SSL, and has been pleased
with the result.  We have written in WEB an application of 24 thousand
lines, and we are very pleased at how easy it has been to review and
maintain this code.  I hope that the availability of Spidery WEB will
encourage other groups to try literate programming, and that they,
too, will be pleased with the results.


WHAT YOU GET

Although Spider is complete and useful, this distribution contains bug
fixes and enhancements that I have not folded into the code.
I have tested this system only under Unix, but other users have
provided Macintosh, MS-DOS, and OS/2 implementations.

This directory contains:

  bug-reports		reports of bugs that may or may not have been fixed
  doc			manuals and articles about Spider
  fixes-to-be-applied	bug fixes and enhancements
  mac			Macintosh binaries
  ms-dos		MS-DOS binaries
  os2			OS/2 source-code changes
  patches		patches for old versions of Spider (now useless)
  src			Spider source code & instructions for building Spider
  todo			a wish list
  tools			auxiliary tools that might be useful with Spidery WEB

Send comments or bug reports to spider-bugs@oracorp.com

Norman Ramsey