summaryrefslogtreecommitdiff
path: root/web/spiderweb/doc/overview.tex
blob: 0e568d0392d2d7f057d71b6d50c57b2d13aacbae (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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
% Copyright 1989 by Norman Ramsey, Odyssey Research Associates
% Not to be sold, but may be used freely for any purpose
% For more information, see file COPYRIGHT in the parent directory

\documentstyle[11pt]{article}
\title{A note about a new implementation of {\tt WEB}}
\author{Norman Ramsey\\Odyssey Research Associates}
\date{July 4, 1988}
\setcounter{secnumdepth}{0}
\begin{document}
\maketitle

\begin{abstract}
Literate programming has received recent attention in the {\sl
Communications of the ACM}~\cite{bentley:lp,cvw:loom}. 
{\tt WEB} is a tool intended for literate programming, but 
until recently it was  useful only for writing PASCAL programs.
The author has developed a new tool, {\tt SPIDER}, which reads a
description of a programming language and writes a {\tt WEB} system
that can be used to write programs in that language.
{\tt SPIDER} has been used in the author's organization to build {\tt
WEB} systems for Ada, C, AWK, and other languages.
The author hopes that {\tt SPIDER} will enable people to write
literate programs in many more languages than they could before.
\end{abstract}


\section{Introduction}
Donald Knuth developed the {\tt WEB} system of structured documentation 
as part of the {\TeX} project~\cite{knuth:literate-programming}.
His implementation of {\tt WEB} combined PASCAL and {\TeX}.
  The {\tt WEB} idea suggests a way of combining {\em any}
programming language with {\em any} document formatting language,
but until recently there was no software support for writing in {\tt
WEB} anything but PASCAL programs.
In~1987, Silvio Levy rewrote the {\tt WEB} system in C for C,
while retaining {\TeX} as the formatting language~\cite{levy:cweb}.
I have has modified Levy's implementation by removing the parts
that  make C the target programming language, and I have
 added a third tool, {\tt SPIDER}, which complements {\tt WEAVE}
and {\tt TANGLE}.
{\tt SPIDER} reads a description of a programming language, and writes
source code for a {\tt WEAVE} and {\tt TANGLE} which support that
language. 
Using {\tt SPIDER}, a C~compiler, and an AWK~interpreter, an experienced
systems programmer can generate in a few hours a {\tt WEB} system for
an Algol-like language.

\section{Features of Spidery {\tt WEB}}
An exhaustive list of Spidery {\tt WEB}'s features would interest only
{\tt WEB} experts, 
but I do want to mention some features that I hope will encourage
people to use Spidery {\tt WEB}.
\begin{itemize}
\item
{\tt TANGLE} and {\tt WEAVE} can read from multiple files (this
feature is present in Levy's {\tt CWEB}), and
{\tt 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 {\tt WEB} more usable on systems that have
{\tt make}.
\item
{\tt TANGLE} can expand macros with multiple parameters.
\item
The starred sections in Spidery {\tt WEB} can be organized
hierarchically (in three levels).
We have a UNIX tool that can extract different pieces of the hierarchy
from the output of {\tt WEAVE}, so that it is possible to take
excerpts from {\tt WEB} documents.
\item
{\tt TANGLE} writes {\tt \#line} directives, so you can debug at the
{\tt WEB} source level if your compiler respects the C~conventions for
{\tt\#line}.
\item
Many features of {\tt WEB} seem to exist only to compensate for
deficiencies in PASCAL, and most of those were dropped in {\tt CWEB}.
I have changed much of {\tt CWEB} in order to avoid being bound too
much by C conventions.
As a result, there are dozens of minor differences between Spidery
{\tt WEB} and original {\tt WEB}.
To give just one example, Spidery {\tt WEB} supports
octal and hexadecimal constants using {\tt WEB}-style
notation, not the C~notation used in {\tt CWEB}.
\end{itemize}

\section{Scope of {\tt SPIDER}}
{\tt SPIDER} can generate {\tt WEB} systems for a variety
of languages.
The author has written {\tt 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 {\tt WEAVE} uses to
prettyprint the language is the most time-consuming part of creating a
{\tt WEB} system for a new target language,
and {\tt SPIDER} makes it trivial to change that grammar.
To make a {\tt SPIDER} description file for an Algol-like language
that uses infix expression notation, an experienced systems programmer
should be able to adapt an existing {\tt SPIDER} description file very
quickly.

{\tt SPIDER}'s major limitations are lexical.
 All Spidery {\tt WEB}s
assume that spaces and tabs in the input are not significant, except
as separators;
this makes it impossible to construct Spidery {\tt WEB}s for languages
like Fortran and Miranda, where the position of text on a line is
significant.
The lexical structures of identifiers, string literals, and numeric
literals are fixed.

\section{Conclusions}
{\tt SPIDER} is a modest piece of engineering; it does not introduce
new ideas.
{\tt SPIDER}  does make it possible to create a new {\tt WEB} quickly,
and to tinker with it easily.
The author's group routinely uses Spidery {\tt WEB} to write programs
in Ada, C, and~SSL, and has been pleased with the result.
We have written in {\tt WEB} an application of eighteen thousand
lines, and
we are very pleased at how easy it has been to review and maintain
this code.
The author hopes that the availability of Spidery {\tt WEB} will
encourage other groups to try literate programming, and that they,
too, will be pleased with the results.



\begin{thebibliography}{Van~Wyk~9999}
\bibitem[Bentley~86]{bentley:lp}
Jon L. Bentley, ``Programming Pearls,''
{\sl Communications of the ACM} {\bf 29:5} (May~1986), 364--368, and
{\bf 29:6} (June~1986), 471--483.
\bibitem[Knuth~84]{knuth:literate-programming}
Donald E. Knuth, ``Literate Programming,'' {\sl The Computer Journal}
{\bf 27:2} (1984), 97--111.
\bibitem[Levy~87]{levy:cweb}
Silvio Levy, ``{\tt WEB} Adapted to C, Another Approach,''
 {\sl TUGBoat} {\bf 8:1} (1987), 12--13.
\bibitem[Van~Wyk~87]{cvw:loom}
Christopher J. Van~Wyk, ``Literate Programming,''
{\sl Communications of the ACM} {\bf 30:7} (July~1987), 593--599, and
{\bf 30:12} (December~1987), 1000--1010.
\end{thebibliography}

\end{document}