diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /web/spiderweb/doc |
Initial commit
Diffstat (limited to 'web/spiderweb/doc')
-rw-r--r-- | web/spiderweb/doc/Makefile | 3 | ||||
-rw-r--r-- | web/spiderweb/doc/abstracts.tex | 23 | ||||
-rw-r--r-- | web/spiderweb/doc/cacm.aux | 16 | ||||
-rw-r--r-- | web/spiderweb/doc/cacm.tex | 602 | ||||
-rw-r--r-- | web/spiderweb/doc/overview.aux | 12 | ||||
-rw-r--r-- | web/spiderweb/doc/overview.tex | 149 | ||||
-rw-r--r-- | web/spiderweb/doc/spdjman.tex | 2065 | ||||
-rw-r--r-- | web/spiderweb/doc/spe.aux | 70 | ||||
-rw-r--r-- | web/spiderweb/doc/spe.bbl | 186 | ||||
-rw-r--r-- | web/spiderweb/doc/spe.tex | 545 | ||||
-rw-r--r-- | web/spiderweb/doc/spiderman.aux | 56 | ||||
-rw-r--r-- | web/spiderweb/doc/spiderman.tex | 1693 | ||||
-rw-r--r-- | web/spiderweb/doc/spiderwebman.tex | 2268 | ||||
-rw-r--r-- | web/spiderweb/doc/spiderwebman.toc | 1 |
14 files changed, 7689 insertions, 0 deletions
diff --git a/web/spiderweb/doc/Makefile b/web/spiderweb/doc/Makefile new file mode 100644 index 0000000000..6f24dc9dbd --- /dev/null +++ b/web/spiderweb/doc/Makefile @@ -0,0 +1,3 @@ +clean: + -rm -f *.dvi *.log *~ + diff --git a/web/spiderweb/doc/abstracts.tex b/web/spiderweb/doc/abstracts.tex new file mode 100644 index 0000000000..bb4f38208e --- /dev/null +++ b/web/spiderweb/doc/abstracts.tex @@ -0,0 +1,23 @@ +\centerline{Spider User's Guide} + +This manual explains how to use the {Spider} program to generate a +{\tt WEB} system for any programming language. +It describes the syntax of the {Spider} description file used to +describe a programming language, giving several examples. +It does not say how to use the generated {\tt WEB} system; for that +see ``The Spidery {\tt WEB} System of Structured Documentation.'' + +\bigskip + +\centerline{The Spidery {\tt WEB} System of Structured Documentation} + + +This manual describes how to write programs in the {\tt WEB} language, +using {\tt WEB} systems generated by {Spider}. +Most of the material is taken verbatim from Donald Knuth's original +memo introducing {\tt WEB}. +It contains a brief introduction to the idea of literate programming, +a short explanation of how to run {\tt WEAVE} and {\tt TANGLE}, and a +list of all of the control sequences that can be used in {\tt WEB} +programs and their effects. + diff --git a/web/spiderweb/doc/cacm.aux b/web/spiderweb/doc/cacm.aux new file mode 100644 index 0000000000..7a91431f55 --- /dev/null +++ b/web/spiderweb/doc/cacm.aux @@ -0,0 +1,16 @@ +\relax +\citation{ramsey:developing} +\citation{levy:cweb} +\@writefile{lof}{\string\contentsline\space {figure}{\string\numberline\space {1}{\ignorespaces Processing a C\penalty \@M \ {\string\ptt\space web} file}}{2}} +\newlabel{instance}{{1}{2}} +\@writefile{lof}{\string\contentsline\space {figure}{\string\numberline\space {2}{\ignorespaces Building and using an instance of {\string\ptt\space WEB} (for language X)}}{3}} +\newlabel{building}{{2}{3}} +\@writefile{lof}{\string\contentsline\space {figure}{\string\numberline\space {3}{\ignorespaces Table Inversion}}{4}} +\newlabel{fragment}{{3}{4}} +\citation{oppen:prettyprinting} +\bibcite{bentley:lp}{Bentley\penalty \@M \ 86} +\bibcite{knuth:literate-programming}{Knuth\penalty \@M \ 84} +\bibcite{levy:cweb}{Levy\penalty \@M \ 87} +\bibcite{oppen:prettyprinting}{Oppen\penalty \@M \ 80} +\bibcite{ramsey:developing}{Ramsey\penalty \@M \ 89} +\bibcite{cvw:loom}{Van\penalty \@M \ Wyk\penalty \@M \ 87} diff --git a/web/spiderweb/doc/cacm.tex b/web/spiderweb/doc/cacm.tex new file mode 100644 index 0000000000..d16ccf5dff --- /dev/null +++ b/web/spiderweb/doc/cacm.tex @@ -0,0 +1,602 @@ +\documentstyle[11pt]{article} +\title{Building a Language-Independent {\tt WEB}\thanks{This research +has been sponsored in part by the USAF, Rome Air Development Center, +under contract number F30602--86--C--0071.}} +%\author{Norman Ramsey\\Department of Computer Science\\Princeton University} +\author{Norman Ramsey\thanks{Current address: Department of Computer +Science, Princeton University, Princeton, New Jersey 08544}% +\\Odyssey Research Associates} + +\newcommand{\token}{\cstok} +\def\sizedboxit#1#2{\vtop{\vbox{\hrule\hbox{\vrule\kern #2% + \vtop{\vbox{\kern #2\hbox{#1}}\kern #2}\kern #2\vrule}}\hrule}} +\def\boxit#1{\sizedboxit{#1}{3pt}} +\newcommand{\remark}{\marginpar} +\def\remark#1{\marginpar{\footnotesize\it #1}} +\def\cstok#1{\leavevmode\thinspace\hbox{\vrule\vtop{\vbox{\hrule\kern1pt + \hbox{\vphantom{\tt/}\thinspace{\tt#1}\thinspace}} + \kern1pt\hrule}\vrule}\thinspace} % control sequence token +\def\ttok#1{\leavevmode\thinspace\hbox{\vrule\vtop{\vbox{\hrule\kern1pt + \hbox{\vphantom{\tt(j}\thinspace{\tt#1}\thinspace}} + \kern1pt\hrule}\vrule}\thinspace} % token +\newcommand{\X}{} +\def\X:#1\X{\mbox{$\langle${#1}$\rangle$}} + +\begin{document} +\maketitle + +In the fall of~1987 I started planning the implementation of a +suite of tools for building verified Ada +programs~\cite{ramsey:developing}. +The first tool to be built was a +verification condition generator, which was to be formally defined +using the typed lambda calculus. +I was eager to include the definition with the code +so that it would be easy to check the code's correctness. +Using {\tt WEB} would have made this easy, but, +unfortunately, the target programming language was +SSL (a language for specifying structure editors), and the only +languages for which {\tt WEB} implementations were +available were Pascal and~C. + +Writing a new {\tt WEB} from scratch didn't make sense, so +I decided to modify Silvio Levy's implementation of {\tt WEB} +in~C~\cite{levy:cweb}, +to get a {\tt WEB} that would be written in C, but would read and +write SSL code. +From my previous experiences modifying {\tt WEB}, I knew that the +most time-consuming job would be fine-tuning the grammar that {\tt +WEAVE} uses to prettyprint code. +I believed I could make debugging that grammar a lot less painful +if, instead of trying to make dozens of small modifications by hand, I + wrote a simple program, perhaps an AWK script, that would read +a description of the grammar and generate C~code for {\tt WEAVE}. +That AWK script became {\tt SPIDER}, a program that turns language +descriptions into C~code for {\tt TANGLE} and {\tt WEAVE}. +I have used {\tt SPIDER} to generate {\tt WEB}s for C, AWK, SSL, Ada, +and a couple of other languages. +I won't go into the details of {\tt SPIDER}; instead, I'll try to +describe what {\tt SPIDER} does to accomplish its mission, or +how to take the ``essence of {\tt WEB}'' and make it +language-independent. + +\medskip + +When using {\tt WEB}, a programmer writes a single source file, {\tt +foo.{\tt web}}, that holds both code and documentation. +{\tt TANGLE} and {\tt WEAVE} read that file. +{\tt TANGLE} extracts +the code from the {\tt WEB} file and rewrites it in a form suitable +for compiling. +{\tt WEAVE} passes the documentation parts to a document formatter +({\TeX}), and prettyprints the code parts. +The whole process is shown in Figure~\ref{instance}, for C~programs +written in {\tt WEB}. +The~{\S} represents files that have to be written by hand. +{\sl Slant} type is used for the names of executable programs. +{\sl CTANGLE} and {\sl CWEAVE} are the C-language versions of {\tt +TANGLE} and {\tt WEAVE}, {\sl cc}~is a C~compiler, and {\sl ld}~is a +loader. + +\begin{figure} +\caption{Processing a C~{\tt web} file} +\label{instance} +\footnotesize +\setlength{\unitlength}{2pt} +\begin{picture}(170,80)(0,-40) +\tt +\put(20,12.5){\makebox(0,0)[l]{\ \sl CTANGLE}} +\put(20,-12.5){\makebox(0,0)[l]{\ \sl CWEAVE}} + +\put(0,-5){\framebox(30,10){foo.{\tt web}\smash{${}^{\S}$}}} +\put(15,5){\vector(1,2){7.5}} +\put(10,20){\framebox(30,10){foo.c}} +\put(15,-5){\vector(1,-2){7.5}} +\put(10,-30){\framebox(30,10){foo.tex}} + +\put(40,-25){\vector(1,0){20}} +\put(50,-23.5){\makebox(0,0)[b]{\sl {\TeX}}} +\put(60,-30){\framebox(30,10){foo.dvi}} +\put(90,-25){\vector(1,0){20}} +\put(100,-25){\makebox(0,0){\shortstack{\strut dvi\\\strut \rm driver}}} +\put(110,-25){\makebox(0,0)[l]{\rm\strut \ Typeset documentation for +{\tt foo}}} + +\put(40,25){\vector(1,0){20}} +\put(50,26.5){\makebox(0,0)[b]{\sl cc}} +\put(60,20){\framebox(30,10){foo.o}} +\put(90,25){\vector(1,0){20}} +\put(100,26.5){\makebox(0,0)[b]{\sl ld}} +\put(110,25){\makebox(0,0)[l]{\rm\strut \ Executable \sl foo}} + + + +\end{picture} + +\hrule +\end{figure} + +{\tt SPIDER} is used to construct {\em instances} of {\tt TANGLE} and +{\tt WEAVE}, and these instances are used to process programs as +shown in Figure~\ref{instance}. +Code for the language-dependent parts of these instances is generated +by {\tt SPIDER} when it +reads a language description file written by a {\tt WEB} designer. +Figure~\ref{building} shows how instances of {\tt TANGLE} and {\tt +WEAVE} are generated. +{\tt SPIDER} converts a hand-written description of a programming language +into C~{\tt WEB} code for the language-dependent parts of {\tt TANGLE} +and {\tt WEAVE}. +In Figure~\ref{building} the target programming language is a hypothetical +``X,'' and the description file is called ``{\tt x.spider}.'' +{\tt CTANGLE} combines the code {\tt SPIDER} writes with the ``master +copies'' of {\tt tangle.web} and {\tt weave.web}, which contain the +language-independent parts of {\tt TANGLE} and {\tt WEAVE}. +The result is C~source code for {\tt XTANGLE} and {\tt XWEAVE}. +After that code is compiled and loaded with {\tt WEB}'s I/O code, the +resulting executable versions of {\tt XTANGLE} and {\tt XWEAVE} can be +used to process X-language programs written in {\tt WEB} format, as +shown around the periphery of Figure~\ref{building}. + + +The master copies of {\tt tangle.web} and {\tt weave.web} are about +1800 and 3200 lines long, respectively. +About one third of these lines are comments. +To illustrate the other size, suppose X is the Ada programming language. +The {\tt ada.spider} file is about 260 lines long, and from it {\tt +SPIDER} generates +about 1400~lines of {\tt ADATANGLE} and {\tt ADAWEAVE}. +About one tenth of these lines are comments. +It is typical for {\tt SPIDER} to generate between $5n$ and $6n$ lines +of C~{\tt WEB} code from an $n$~line language description. + +\begin{figure} +\caption{Building and using an instance +of {\tt WEB} (for language X)} +\label{building} +\footnotesize +\setlength{\unitlength}{2pt} +\begin{picture}(215,115)(10,-55) +\tt +\put(185,-5){\framebox(30,10){x.spider\smash{${}^{\S}$}}} +\put(185,0){\line(-1,0){20}} +\put(174,1.5){\makebox(0,0)[b]{$\,$\sl SPIDER}} +\put(165,0){\vector(-1,1){10}} +\put(165,0){\vector(-1,-1){10}} + +\put(125,5){\framebox(30,10){xt.web}} +\put(125,-15){\framebox(30,10){xw.web}} +\put(125,25){\framebox(30,10){\shortstack{{\rm Master}\\tangle.{\tt web}}}} +\put(125,-35){\framebox(30,10){\shortstack{{\rm Master}\\weave.{\tt web}}}} +\put(125,-30){\line(-1,1){10}} +\put(125,-10){\line(-1,-1){10}} +\put(115,-20){\vector(-1,0){25}} + +\put(104,-18.5){\makebox(0,0)[b]{\scriptsize\sl CTANGLE}} + +\put(125,10){\line(-1,1){10}} +\put(125,30){\line(-1,-1){10}} +\put(115,20){\vector(-1,0){25}} + +\put(104,21.5){\makebox(0,0)[b]{\scriptsize\sl CTANGLE}} + +\put(60,15){\framebox(30,10){xtangle.c}} +\put(60,-25){\framebox(30,10){xweave.c}} +\put(60,-20){\vector(-1,0){20}} +\put(50,-18.5){\makebox(0,0)[b]{\sl cc, ld}} +\put(60,20){\vector(-1,0){20}} +\put(50,21.5){\makebox(0,0)[b]{\sl cc, ld}} +\put(38,20){\makebox(0,0)[r]{\sl XTANGLE}} +\put(38,-20){\makebox(0,0)[r]{\sl XWEAVE}} + +\put(-6.25,-5){\framebox(30,10){foo.{\tt web}\smash{${}^{\S}$}}} +\put(8.75,5){\vector(1,4){6.25}} +\put(0,30){\framebox(30,10){foo.x}} +\put(8.75,-5){\vector(1,-4){6.25}} +\put(0,-40){\framebox(30,10){foo.tex}} + +\put(30,-35){\vector(4,-1){20}} +\put(50,-48.75){\framebox(30,10){foo.dvi}} +\put(80,-47.5){\vector(4,-1){20}} +\put(100,-52.5){\makebox(0,0)[l]{\rm\strut \ Typeset documentation for +{\tt foo}}} + +\put(30,35){\vector(4,1){20}} +\put(50,38.75){\framebox(30,10){foo.o}} +\put(80,47.5){\vector(4,1){20}} +\put(100,52.5){\makebox(0,0)[l]{\rm\strut \ Executable \sl foo}} + + + +\end{picture} + +\hrule +\end{figure} + +\medskip + +A {\tt WEB} program is a collection of ``sections,'' each of which has a +documentation part, a definition part, and a code part. +The documentation part describes what the section is supposed to do, +and is intended to be processed by a formatter---my {\tt WEB}s use +{\TeX}, which is especially convenient for mathematical symbols like +those used in writing a formal semantics. +The definition part contains macro definitions. +Each macro may have parameters or not, as the programmer chooses. +The code in the code part is a fragment of the whole program. +It is called a ``module'' and can be named or unnamed. +When the module is named, the module name ``stands for'' that code, +just as a macro name stands for the code in its definition. +The unnamed module is special; the code in the unnamed module is +considered to be ``the program.'' + +Figure~\ref{fragment} shows a fragment of a {\tt WEB} program; the +fragment inverts an +EBCDIC-to-ASCII table to obtain an ASCII-to-EBCDIC table. +The target programming language is C. +One module, \X:Invert {\it to\_ascii}, producing {\it to\_ebcdic}\X, +uses the code defined in the other, \X:Set ${\it +to\_ebcdic}[i]\leftarrow {\it UNDEFINED\_CODE}$ for all $i$\X. +The program, {\tt foo}, of which this fragment is a part, can be input +to {\tt CTANGLE} and {\tt CWEAVE}, to produce {\tt foo.c} and {\tt +foo.tex} respectively, as shown in Figure~\ref{instance}. + +\begin{figure} +\caption{Table Inversion} +\label{fragment} +\begin{verbatim} +@ The array |to_ascii| converts an EBCDIC code to +an ASCII code, or to |-1| if there is no ASCII +equivalent to the given code. +@d UNDEFINED_CODE = -1 +@<Invert |to_ascii|, producing |to_ebcdic|@>= + @<Set |to_ebcdic[i]=UNDEFINED_CODE| for all |i|@>@; + for (i=0; i<256; i++) + if (to_ascii[i] != UNDEFINED_CODE) + to_ebcdic[to_ascii[i]]=i; + +@ @<Set |to_ebcdic[i]=UNDEFINED_CODE| for all |i|@>= + for (i=0; i<128; i++) to_ebcdic[i] = UNDEFINED_CODE; +\end{verbatim} +\hrule +\end{figure} + + + +{\tt TANGLE}'s job is to take a collection of sections and to +produce a compilable program. +{\tt TANGLE} reads all the sections, skipping the documentation parts +completely, but storing the macro definitions from the definition parts +and the module definitions from the code parts. +After it has read all the sections, {\tt TANGLE} then +writes out the code in the unnamed module. +But whenever it encounters a module name in that code, instead of +writing out the name, it writes out the code for which this name +stands. +That code may itself contain module names, which are replaced with the +code for which they stand, and so on until {\tt TANGLE} reaches code +which contains no occurrences of module names. +{\tt TANGLE} processes macros similarly, except that macros may +have parameters (modules may not). + +As I've described it, the ``essence of tangling'' is +language-independent. +In the full implementation of {\tt TANGLE} there are only a few +language-dependent details, and almost all of them come up only in +lexical analysis. +During its input phase, {\tt TANGLE} converts macro definitions and +module definitions into token lists. +%%%Every token is represented using either eight or sixteen bits. +The major kinds of tokens are +module name tokens, identifier tokens, and ordinary tokens. +Identifier tokens may be expandable (when they are macro names) or +unexpandable (when they are programming-language identifiers). +Module name tokens are always expandable, and ordinary tokens are +never expandable. +{\tt TANGLE} uses a stack to write out the token list corresponding to +the unnamed module, expanding expandable tokens as it goes. +No token is ever expanded until the time comes to write that token on +the output. + +To build the language-dependent part of {\tt TANGLE}, it is enough to +tell {\tt TANGLE} how to tokenize the input and how to write out a +token list. +{\tt TANGLE} uses a ``lowest common denominator'' lexical analyzer to +tokenize its input. +The set of tokens recognized by this lexical analyzer is the union of +the sets of legal tokens of many different languages. +For example, different ways of delimiting string literals are +recognized. +Identifiers may have underscores, even though some languages +(e.g.~Pascal) may not permit underscores in identifiers, and others +(e.g.~Ada) may not permit consecutive underscores in an identifier. +In general, {\tt TANGLE} and {\tt WEAVE} do the right thing with legal +programs, but they do not detect illegalities in a program. + +{\tt TANGLE}'s lexical analyzer recognizes a fixed set of tokens +representing identifiers, string literals, and numeric literals. +Any printable ASCII character which is not part of some other +token forms a token all by itself. +A {\tt WEB} builder can specify that certain strings should +be treated as single tokens, and +{\tt SPIDER} will convert the specifications into appropriate code for +{\tt TANGLE}. +For example, when building {\tt WEB} for~C, we tell {\tt SPIDER} +that the strings {\tt ++}, {\tt ==}, and {\tt \&\&} (and many others) +should be treated as single tokens, by putting the statements +\begin{quote}\tt +token ++ ...\\ +token == ...\\ +token \&\&\ ... +\end{quote} +into the language description file, {\tt c.spider}. + +{\tt TANGLE} discards comments, rather than attempting to tokenize +them. +Comments are assumed to begin with a special string, and to end either +with another string or with a newline. +We specify C comment conventions by telling {\tt SPIDER} +\begin{quote}\tt +comment begin <"/*"> end <"*/"> +\end{quote} + + +On output, {\tt TANGLE} converts tokens to text by inverting the +process of lexical analysis, so, for example, the token \token{++} is +written out as ``{\tt ++}''. +{\tt TANGLE}'s output phase inserts white space between adjacent +identifiers and numeric literals, but otherwise does not write white +space. +This can cause problems in some cases; for example, in older +C~compilers the string +``{\tt =-}'' is ambiguous. +We can solve this problem by telling {\tt SPIDER} to build a {\tt +TANGLE} that uses the text + ``{\tt =~}'' when writing the \token{=}: +\begin{quote}\tt +token = tangleto <"= "> +\end{quote} + +In sum, we can make {\tt TANGLE} language-independent with almost no +effort. +We do this by using a lowest common denominator lexical analyzer whose +only parameter is a description of comments, and by providing a way to +fine-tune the way {\tt TANGLE} writes tokens. + + + +\medskip +Unlike {\tt TANGLE}, {\tt WEAVE} does no rearranging of the sections; +its job is to translate its input into a prettyprinted program +listing. +The documentation part of each section is simply copied to the output, +but the definition and code parts are prettyprinted. +{\tt WEAVE}'s output is handed to a document formatter, which is +assumed to implement a prettyprinting algorithm like that described by +Oppen~\cite{oppen:prettyprinting}. +Since my {\tt WEB}s use {\TeX} as the document formatter, the back-end +prettyprinting is implemented by {\TeX} macros. + +{\tt WEAVE} copies the documentation parts as texts, but it converts +definition and code parts to token lists using the same lexical +analyzer used by {\tt TANGLE}. +{\tt WEAVE}'s part of the prettyprinting task (as distinct from +{\TeX}'s part) is converting these token lists to streams of {\TeX} +text, possibly with prettyprinting instructions intercalated between +tokens. +If you like, {\tt WEAVE}'s job is to produce the input to Oppen's +algorithm. +For simplicity, we'll discuss only three prettyprinting instructions: +{\em indent} +(increase the level of indentation), {\em outdent} (decrease the level +of indentation), and {\em force} (force a line break). + +We tell {\tt WEAVE} how to convert tokens to {\TeX} text by specifying +a {\em translation} for each token. +Suppose we want the C token \token{!=} to be printed as~``$\ne$'', +which is produced by the {\TeX} text ``\verb+\ne+''. +Then we write +\begin{quote} +\begin{verbatim} +token != translation <"\\ne"> +\end{verbatim} +\end{quote} +(Two backslashes appear in the translation because {\tt SPIDER} uses +C~conventions for string literals. +The angle brackets {\tt <...>} delimit translations.) +The default for translation is just as in {\tt TANGLE}, so if we want +``{\tt +}'' on input to produce ``$+$'' on output we need not specify a +translation for the token \token{+}. + +The process of deciding where to put line breaks and indentation is +the most complicated part of {\tt WEAVE}. +We have to do this based on the sequence of tokens we have, but the +exact details of which token is where usually aren't needed to do +prettyprinting. +Hence we introduce the {\em scrap}, which abstracts away from the +detail not needed to do prettyprinting. +A scrap has two parts: the translation, which we have already seen, +and the {\em category}, which + corresponds to a ``part of speech'' or a symbol in a grammar. +{\tt WEAVE} uses categories to decide where to put +indentation and line breaks. +Since there are usually many different tokens having the same category, +prettyprinting is simplified enormously. + +{\tt WEAVE} begins processing a program fragment by tokenizing the +fragment, then converting each token in the resulting token list into +a scrap. +It then attempts to reduce the length of the resulting scrap list by +combining adjacent scraps into a single scrap, possibly intercalating +additional translations, which may include +{\em indent}, {\em outdent}, and {\em force} instructions. +The scraps are combined according to one of many {\em reduction rules}. +{\tt WEAVE} decides which adjacent scraps are eligible to be reduced +based only on the categories of the scraps and a knowledge of the +reduction rules. +The reduction rules are the productions of the {\em prettyprinting +grammar}. +{\tt WEAVE}'s reductions of scraps are like the reductions done in +bottom-up parsing. + +To take an example, suppose that we want statements to be separated by +line breaks. +If we can guarantee that any scrap representing a statement has +category {\tt stmt}, it will be enough to specify the reduction rule +\begin{quote}\tt +stmt <force> stmt --> stmt +\end{quote} +which says ``two adjacent {\tt stmt} scraps may be reduced to a single +{\tt stmt} scrap by intercalating a forced line break between them.'' + +So we tell {\tt WEAVE} how to prettyprint a language by telling +how to assign a category to each token and how to combine scraps. +Here's another example: the language of C~expressions. + Let {\tt math} be the category of expressions, +{\tt binop} be the category of binary infix operators, and +{\tt unop} be the category of both unary prefix and unary postfix +operators. +Here are some sample tokens: +\begin{quote} +\begin{verbatim} +token identifier category math +token + category binop +token - category binop +token = category binop translation <"\\leftarrow"> +token == translation <"\\equiv"> category binop +token ( category open +token ) category close +\end{verbatim} +\end{quote} +Notice we print the \token{=} token (assignment) as $\leftarrow$, +whereas we print the \token{==}~token (comparison) as $\equiv$. +This makes it a bit easier for us to see when a programmer has +mistakenly used \token{=} instead of \token{==}. + + +The prettyprinting grammar for C~expressions is: +\begin{quote} +\begin{verbatim} +math binop math --> math +math unop --> math +unop math --> math +open math close --> math +\end{verbatim} +\end{quote} +Using this grammar, {\tt WEAVE} can take a long expression consisting +of many scraps, and reduce it all to a single scrap of category {\tt +math}. + +What about an operator like ``{\tt *}'', which is both binary infix +and unary prefix? +This does the job: +\begin{quote} +\begin{verbatim} +token * category unorbinop +unorbinop math --> math +math unorbinop math --> math +\end{verbatim} +\end{quote} + +% No Note about context-sensitive reductions? + +There is a mechanism for assigning categories and translations to +reserved words as well as to tokens, using slightly different syntax. + +To give an idea of the complexity of the grammars, the grammar +describing AWK uses 24~categories in 39~productions. +The Ada grammar uses 40~categories in 65~productions, and the +C~grammar uses 54~categories in 129~productions. + +\medskip + +{\tt SPIDER}-generated versions of {\tt TANGLE} and {\tt WEAVE} differ +subtly from the originals written by Donald Knuth. +The most important difference is that {\tt SPIDER}-generated {\tt WEB} +is not self-contained: where Knuth's Pascal {\tt WEB} required only a +Pascal compiler to bring up, {\tt SPIDER} would need a C~compiler and +an AWK~interpreter to generate a Pascal {\tt WEB}, and a Pascal +compiler for the resulting {\tt WEB} to be of any use. +Other differences are minor; for example, Knuth's {\tt TANGLE} +does arithmetic on constants at {\tt TANGLE} time, but {\tt +SPIDER}-generated {\tt TANGLE}s do not. +Knuth's {\tt TANGLE} provides three different kinds of macros, but +none with more than one parameter; +{\tt SPIDER}-generated {\tt TANGLE}s provide only one kind of macro, +but macros of that kind may have from zero to thirty-two parameters. + + + +{\tt SPIDER} is a {\tt WEB} generator, akin to parser generators. +Both read formal descriptions of some part of a programming language, +and both produce code that processes programs written in that language. +Since both produce code that is part of the ``compiler,'' using them +doesn't introduce any extra steps into the processing of user programs. +{\tt SPIDER} itself is a large AWK script, written as a {\tt WEB} +program. +{\tt spider.web} is about 2600 lines long; about a third of these are +comments. + + +The major cost of using {\tt SPIDER} is the cost of learning yet +another language. +Learning this language is supposed to substitute for learning how to +modify {\tt WEB}, so it is probably not an exorbitant cost. +Some other limitations are the the need for a C~compiler and an +AWK~interpreter, and the need to use a lowest-common-denominator +lexical analyzer. + +The major benefit of using {\tt SPIDER} is the ease with which new +{\tt WEB}s can be built. +%\remark{(Here is the place to talk about Oberon.)} +The {\tt SPIDER} description of a language is much smaller than the +{\tt WEB} implementation generated from that description, and {\tt +SPIDER} descriptions of similar languages are similar. +Using {\tt SPIDER} one can build a {\tt WEB} without understanding the +details of {\tt WEB}'s implementation, and one can easily adjust that +{\tt WEB} to change as a language definition changes. +%\remark{Could mention work with Larch/Ada-88} + + + +{\tt SPIDER} should make one literate programming tool, {\tt WEB}, +available to a much larger audience. +I hope that, by separating the language-independent parts of {\tt WEAVE} +and {\tt TANGLE}, {\tt SPIDER} will encourage us not just to think +about what the essence of tangling and weaving is, but also about what +the essence of literate programming is. + + +\medskip + +I enjoyed many useful discussions of {\tt WEB} with Charlie Mills. +I am grateful to +Silvio Levy for providing his {\tt CWEB} as the basis for the +``master copies'' of {\tt TANGLE} and {\tt WEAVE}, and to +Dave Hanson for comments on an earlier version of this paper. + +\begin{thebibliography}{van~Knuth~999} +\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[Oppen~80]{oppen:prettyprinting} +Derek Oppen, ``Prettyprinting,'' TOPLAS~{\bf 2:4} (October 1980), +465--483. +\bibitem[Ramsey~89]{ramsey:developing} +Norman Ramsey, ``Developing Formally Verified Ada Programs,'' +Proceedings, {\sl Fifth International Workshop on Software +Specification and Design}, to appear. +\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} diff --git a/web/spiderweb/doc/overview.aux b/web/spiderweb/doc/overview.aux new file mode 100644 index 0000000000..67eea2a819 --- /dev/null +++ b/web/spiderweb/doc/overview.aux @@ -0,0 +1,12 @@ +\relax +\citation{bentley:lp,cvw:loom} +\citation{knuth:literate-programming} +\citation{levy:cweb} +\@writefile{toc}{\string\contentsline\space {section}{Introduction}{1}} +\@writefile{toc}{\string\contentsline\space {section}{Features of Spidery {\string\ptt\space WEB}}{2}} +\@writefile{toc}{\string\contentsline\space {section}{Scope of {\string\ptt\space SPIDER}}{2}} +\bibcite{bentley:lp}{Bentley\penalty \@M \ 86} +\bibcite{knuth:literate-programming}{Knuth\penalty \@M \ 84} +\bibcite{levy:cweb}{Levy\penalty \@M \ 87} +\bibcite{cvw:loom}{Van\penalty \@M \ Wyk\penalty \@M \ 87} +\@writefile{toc}{\string\contentsline\space {section}{Conclusions}{3}} diff --git a/web/spiderweb/doc/overview.tex b/web/spiderweb/doc/overview.tex new file mode 100644 index 0000000000..0e568d0392 --- /dev/null +++ b/web/spiderweb/doc/overview.tex @@ -0,0 +1,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} diff --git a/web/spiderweb/doc/spdjman.tex b/web/spiderweb/doc/spdjman.tex new file mode 100644 index 0000000000..bcb6b28a8a --- /dev/null +++ b/web/spiderweb/doc/spdjman.tex @@ -0,0 +1,2065 @@ +% $Header: /usr2/nabe/Tools/WEB_Tool/Spiderweb/doc-j/RCS/spdjman.tex,v 1.5 92/02/28 16:34:11 nabe Exp $ +% This file is translated from English into Japanese by Izumi Watanabe, +% (nabe@miya.fujifilm.co.jp). +% As Mr. Ramsey wrote, to be used for reserch purposes only. +% This file contains Japanese Kanji-character codes, called EUC (Extended +% Unix Code), and is written for Japanese-LaTeX, called ASCII-jLaTeX. + + +%% Copyright 1989 by Norman Ramsey and Odyssey Research Associates +%% To be used for research purposes only +%% For more information, see file COPYRIGHT in the parent directory + +% ¤³¤ÎÆüËܸìÌõ¤Ï»²¹Í¤È¤·¤Æ ÅÏÊÕÀô(nabe@miya.fujifilm.co.jp)¤¬¹Ô¤Ê¤¤¤Þ¤·¤¿¡£ +% ¤³¤Î¥É¥¥å¥á¥ó¥È¤Ï¥ª¥ê¥¸¥Ê¥ë¤Î spider.man ¤ò½¤Àµ¤·¤¿¤â¤Î¤Ê¤Î¤Ç¡¢ +% Mr. Ramsey ¤Î»ØÄêÄ̤ê¤Ë¸¦µæÌÜŪ¤Ë¤Î¤ß»ÈÍѲÄǽ¤Ç¤¹¡£ +% °·¤¤¤Ë¤ÏÃí°Õ¤·¤Æ²¼¤µ¤¤¡£ + +%% spiderman.tex, with apologies to Stan Lee + +%%\documentstyle[11pt]{article} +\documentstyle[a4j]{jarticle} +\setcounter{secnumdepth}{0} +\newcommand{\syntax}[1]{\mbox{$\langle\hbox{\sl #1\/}\rangle$}} +\newcommand{\produces}{\mbox{${}::={}$}} +\newcommand{\opt}[1]{$[$#1$]$} +\newcommand{\BS}{\relax} +\chardef\BS=`\\ % backslash in a string +\def\jem{\em\gt} +\def\P#1#2{#2:#1} +\newcommand {\WEB}{{\tt WEB}} + +\title{{Spider} ¥æ¡¼¥¶¡¼¥º¥¬¥¤¥É} +\author{Norman Ramsey\thanks{ + Department of Computer Science, Princeton University, + ``A {Spider} User's Guide'',{July 1989}.}\ Ãø \\ + ÅÏÊÕÀô\thanks{Æü·Ðmix:w.izumi, nabe@miya.fujifilm.co.jp}\ Ìõ} +\date{Feb 1992 \\ J-$Revision: 1.5 $} + +\begin{document} +\maketitle + +\section{¤Ï¤¸¤á¤Ë} +Donald Knuth ¤Ï {\tt WEB} ¤È¤¤¤¦¡¢¹½Â¤²½¥É¥¥å¥á¥ó¥Æ¡¼¥·¥ç¥ó¡¦¥·¥¹¥Æ¥à¤ò +{\TeX} ¥×¥í¥¸¥§¥¯¥È~\cite{knuth:literate-programming} ¤Î°ìÉô¤È¤·¤Æ³«È¯¤·¤¿¡£ +{\tt WEB}¤ò»È¤¦¤È¡¢¥×¥í¥°¥é¥Þ¡¼¤Ï¼«Ê¬¤Î¥×¥í¥°¥é¥à¤ò¤¤¤¯¤Ä¤â¤Î¤«¤¿¤Þ¤ê ( +{\jem ¥â¥¸¥å¡¼¥ë}) ¤Ëʬ³ä¤·¤Æ¡¢¤½¤ì¤é¤Ëʸ¾Ï¤òÉÕÍ¿¤·¡¢¹¥¤¤Ê½çÈÖ¤ËÀâÌÀ¤¹¤ë¤³¤È¤¬¤Ç¤¤ë¤è¤¦¤Ë¤Ê¤ë¡£ +Knuth ¤¬ºî¤Ã¤¿¤â¤Î¤Ç¤Ï¡¢³Æ¥â¥¸¥å¡¼¥ë¤Ï PASCAL ¥×¥í¥°¥é¥à¤Ç¤¢¤ê¡¢ +¤½¤ì¤é¤¬ {\TeX} ¤ò»ÈÍѤ·¤ÆÀ¶½ñ¤µ¤ì¤ë¡£ + + {\tt WEB} ¤Î¥¢¥¤¥Ç¥¢¤Ï¡¢{\jem Ǥ°Õ}¤Î¥×¥í¥°¥é¥ß¥ó¥°¸À¸ì¤È +{\jem Ǥ°Õ}¤Îʸ½ñÀ¶½ñ¸À¸ì\index{\P{document formatting language}{ʸ½ñÀ¶½ñ¸À¸ì}} +¤ò·ë¹ç¤¹¤ëÊýË¡¤òÄó°Æ¤·¤Æ¤¤¤ë¡£ +¤·¤«¤·¡¢ºÇ¶á¤Þ¤Ç¤Ï¡¢PASCAL ¥×¥í¥°¥é¥àÍѤΠ\WEB °Ê³°¤Î +»Ù±ç¥½¥Õ¥È¥¦¥§¥¢¤Ï¤Ê¤«¤Ã¤¿¡£ +\hbox{1987ǯ}¤Ë¡¢Silvio Levy ¤¬ C¤Î¤¿¤á¤Î{\tt WEB} ¥·¥¹¥Æ¥à¤òC ¤Ç½ñ¤Ä¾¤·¤¿¡£ +¤³¤Î»þ¤âʸ½ñÀ¶½ñ¸À¸ì¤È¤·¤Æ¤Ï {\TeX} ¤¬°ú¤Â³¤»È¤ï¤ì¤¿~\cite{levy:cweb}¡£ +É®¼Ô¤Ï¡¢Levy ¤Î½ñ¤¤¤¿¤â¤Î¤ò½¤Àµ¤·¡¢ C ¤ò¥¿¡¼¥²¥Ã¥È¸À¸ì¤È¤¹¤ëÉôʬ¤ò¼è¤ê½ü¤¤¤¿¡£ +¤½¤·¤Æ¡¢{Spider}¤È¤¤¤¦ {\tt WEAVE}¤È{\tt TANGLE}¤òºî¤ë +Â裳¤Î¥Ä¡¼¥ë¤òÄɲä·¤¿¡£ +{Spider} ¤Ï¡¢¤¢¤ë ¥×¥í¥°¥é¥ß¥ó¥°¸À¸ì¤Ë¤Ä¤¤¤Æ¤Îµ½Ò¤òÆɤߡ¢ +¤½¤Î¸À¸ì¤ò¥µ¥Ý¡¼¥È¤·¤¿ {\tt WEAVE} ¤È {\tt TANGLE} ¤Î¥½¡¼¥¹¥³¡¼¥É¤ò +½ñ¤½Ð¤¹¡£ + {Spider}¡¢ C~¥³¥ó¥Ñ¥¤¥é¡¢ Awk~¥¤¥ó¥¿¥×¥ê¥¿¤ò»È¤¨¤Ð¡¢ + ·Ð¸³¤òÀѤó¤À¥·¥¹¥Æ¥à¥×¥í¥°¥é¥Þ¤Ê¤é Algol ¤Î¤è¤¦¤Ê¸À¸ì¤Î +{\tt WEB} ¥·¥¹¥Æ¥à¤ò ¿ô»þ´Ö¤ÇÀ¸À®¤¹¤ë¤³¤È¤¬¤Ç¤¤ë¤À¤í¤¦¡£ + +¤³¤Î¥É¥¥å¥á¥ó¥È¤Ï¡¢Ç¤°Õ¤Î¥×¥í¥°¥é¥à¸À¸ì¤Î¤¿¤á¤Î{\WEB}¥·¥¹¥Æ¥à¤òºî¤ë¤¿¤á¤Î +{Spider} ¤Î»È¤¤Êý¤òÀâÌÀ¤·¤Æ¤¤¤ë (¥×¥í¥°¥é¥ß¥ó¥°¸À¸ì¤ÎÁªÂò¤Ï¡¢ +¸å¤Ç¸«¤ë¤³¤È¤Ë¤Ê¤ë¤¬¡¢Spidery {\tt WEB}¤ÎÃæ +¤Ëºî¤ê¹þ¤Þ¤ì¤¿»ú¶ç¹½Â¤\index{\P{lexical structure}{»ú¶ç¹½Â¤}} +¤ÎÀ©¸Â¤Ë¤Î¤ßÀ©¸Â¤ò¼õ¤±¤ë)¡£ +»²¹Í½ñ¤È¤·¤Æ +¡ÖThe Spidery {\WEB} system of structured documentation¡×¤Ç¡¢ +{\WEB} system ¤Îºî¤êÊý¤ò³Ø¤ó¤Ç¤ª¤¯¤È¤è¤¤¡£ + + +\paragraph{»öÁ°½àÈ÷} +{Spider} ¤ò»È¤Ã¤Æ {\WEB} ¥·¥¹¥Æ¥à¤ò +ºî¤í¤¦¤È¤·¤Æ¤¤¤ë¤Ê¤é¡¢{\tt WEB}¤Ë¤Ê¤¸¤ó¤Ç¤ª¤¯¤³¤È¡£ +{\tt WEB} ¤¬²¿¤ò¤É¤¦¤¹¤ë¤Î¤«¤òÃΤꤿ¤±¤ì¤Ð¡¢ +Knuth ¤Î½ñ¤¤¤¿{\WEB}~\cite{knuth:literate-programming}¤Î¾Ò²ðµ»ö: + {\WEB} users' manual ¤òÆɤó¤Ç¤ª¤¯¤Ù¤¤Ç¤¢¤ë ( {\WEB} user's manual ¤Ï¡¢ +¼ê»Ï¤á¤È¤·¤Æ¤Ï¤«¤Ê¤ê½ÅÎ̵é¤Ç¤¢¤ë¡£ +»²¹Íʸ¸¥¤ÎÃæ¤Ë¡¢{\WEB}¤Î¤â¤Ã¤ÈƳÆþŪ¤Ê¤â¤Î¤òÁܤ·µá¤á¤Æ¤âÎɤ¤¡£ +Wayne Sewell ¤Î {\it Weaving a Program: Literate Programming in {\tt +WEB}} +¤ÏÌò¤ËΩ¤Ä¤À¤í¤¦~\cite{sewell:weaving})¡£ + +¤³¤ì°Ê¹ß¤Ï¡¢ÆɼԤ¬{\tt WEAVE} ¤È {\tt TANGLE} ¤È¤Ï¤Ê¤Ë¤«¤òÃΤäƤª¤ê¡¢ +¤½¤ì¤é¤¬²¿¤òÆþÎϤȤ·¡¢½ÐÎϤ¹¤ë¤â¤Î¤¬¤Ê¤Ë¤«¤òÃΤäƤ¤¤ë¤â¤Î¤È¤·¤ÆÏäò¿Ê¤á¤ë¡£ + + +\paragraph{¤³¤Î¥¬¥¤¥É¤Î¿Ê¤áÊý} +¤Þ¤º¡¢weaving ¤È tangling ¤ÎÉü½¬¤«¤é»Ï¤á¡¢¸À¸ì¤Ë°Í¸¤·¤Ê¤¤ {\WEB}¤ò +ºî¤ë¤Î¤ËɬÍפʥ¢¥¤¥Ç¥¢¤ò¤Ä¤«¤á¤ë¤è¤¦¤Ë¤¹¤ë¡£ +¤½¤ì¤«¤é¡¢{\WEB}¤Ë¥×¥í¥°¥é¥ß¥ó¥°¸À¸ì¤Ë¤Ä¤¤¤Æ¶µ¤¨¤ë¤È¤¤¤¦¡¢ +{Spider} ¤ÎÆÃħ¤Ë¤Ä¤¤¤Æ¤ÎµÄÏÀ¤ò½Ò¤Ù¤ë¡£ +¤³¤ì¤é¤ò¾ÜºÙ¤ËÄêµÁ¤·¡¢¤¤¤¯¤Ä¤«¤ÎÎã¤ò¼¨¤¹¡£ +¤½¤·¤ÆºÇ¸å¤Ë¡¢ +{Spider} ¸À¸ì¤È¥Ä¡¼¥ë¤Ë¤Ä¤¤¤Æ¤Î´°Á´¤Êµ½Ò¤ò¤â¤Ã¤Æ½ª¤ï¤ë¤³¤È¤Ë¤¹¤ë¡£ + + +\section{{\tt WEAVE} ¤È {\tt TANGLE} ¤«¤é¸«¤¿À¤³¦} +{\tt WEAVE} ¤È {\tt TANGLE} ¤Ï¤¤¤º¤ì¤âƱ°ì¤Î{\WEB}¥Õ¥¡¥¤¥ë¤òÆþÎϤȤ¹¤ë¡£ +{\tt WEAVE} ¤Ï¡¢ÆþÎϤò¸¡ºº¤·¡¢{\TeX}¥Æ¥¥¹¥È¤òÀ¸À®¤·¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£°ìÊý¡¢ +{\tt TANGLE} ¤Ï¡¢Æ±¤¸ÆþÎϤ«¤é¥×¥í¥°¥é¥à¥Æ¥¥¹¥È¤òÀ¸À®¤·¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£ +ÆþÎϤϡ¢{\TeX}Éô¡¢ÄêµÁÉô¡¢¥³¡¼¥ÉÉô¤«¤é¤Ê¤ë¡£ + {\TeX}Éô¤Ï¤â¤Ã¤È¤â°·¤¤¤¬ÍưפǤ¢¤ë: {\tt WEAVE} ¤Ç¤Ï¥³¥Ô¡¼¤·¡¢ + {\tt TANGLE} ¤Ç¤Ï¼Î¤Æ¤ì¤ÐÎɤ¤¡£ +ÄêµÁÉô¤Ï¾¯¤·Ê£»¨¤Ç¤¢¤ë: {\tt WEAVE}¤Î»Å»ö¤Ï¡¢¤½¤ì¤é¤òÁÈÈǤ·¡¢ +°ìÊý{\tt TANGLE} ¤ÏÄêµÁ¤òµ²±¤·Å¬ÀڤʤȤ¤ËŸ³«¤¹¤ë¡£ +¥³¡¼¥ÉÉô¤Ï°ìÈÖÊ£»¨¤Ç¤¢¤ë: {\tt WEAVE} ¤Ï¤½¤ì¤é¤òÀ¶½ñ¤·¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¤·¡¢ +{\tt TANGLE} ¤Ï°ì´Ó¤·¤¿¥×¥í¥°¥é¥à¥Æ¥¥¹¥È¤ËÀ°Íý¤·Ä¾¤µ¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£ + + +\paragraph{{\WEB}¤Î»ú¶ç²òÀÏ} +{\tt WEAVE} ¤È {\tt TANGLE} ¤Î¤¤¤º¤ì¤â¡¢¥³¡¼¥ÉÉô¤ò{\jem ¥È¡¼¥¯¥ó}¤ÎÏ¢¤Ê¤ê¤È¤·¤Æ +²ò¼á¤¹¤ë¡£ +¤¹¤Ù¤Æ¤Î¥×¥í¥°¥é¥ß¥ó¥°¸À¸ì¤¬Æ±¤¸¥È¡¼¥¯¥ó¤ò»ý¤Ã¤Æ¤¤¤ë¤ï¤±¤Ç¤Ï¤Ê¤¤¤Î¤Ç¡¢ +{Spider}¤Î»Å»ö¤Ï¡¢ {\tt WEAVE} ¤È {\tt TANGLE} ¤Ë +ÆþÎϤò¥È¡¼¥¯¥ó¤Ëʬ²ò¤¹¤ë¤ä¤êÊý¤ò¶µ¤¨¤ë¤³¤È¤Ë¤Ê¤ë +\footnote{% +¸½ºß¤Î{\tt WEB}¤Î»ú¶ç²òÀϤμÂÁõ¤Ï¸ÂÄꤵ¤ì¤Æ¤¤¤ë¡£ +¤³¤ì¤Ï¡¢Àµµ¬É½¸½¤ò»È¤Ã¤¿¤â¤Î¤ËÃÖ¤´¹¤¨¤é¤ì¤ë¤Ù¤¤Ç¤¢¤ë¡£ +}¡£ +Spidery {\WEB} ¥·¥¹¥Æ¥à¤Ï°Ê²¼¤Î¥È¡¼¥¯¥ó¤òǧ¼±¤¹¤ë¤³¤È¤¬¤Ç¤¤ë¡£ +\begin{itemize} +\item ¼±ÊÌ»Ò(identifiers) +\item ¿ôÃÍÄê¿ô¤Èʸ»úÎóÄê¿ô +\item ²þ¹Ô +\item ``µ¿»÷¥»¥ß¥³¥í¥ó'' ({\tt @;}) +\item ͽÌó¸ì +\item Èó±Ñ¿ô»ú¥È¡¼¥¯¥ó +\end{itemize} + +{\tt TANGLE} ¤Ï¡¢¤³¤ì¤é¤Î¥È¡¼¥¯¥ó¤ò1¤Ä¤ÎŤ¤¥×¥í¥°¥é¥à¥Æ¥¥¹¥È¤È¤·¤ÆºÆÀ°Íý +¤·¤¿¤Î¤Á¡¢¥È¡¼¥¯¥óËè¤Ë¥×¥í¥°¥é¥à¥Æ¥¥¹¥È¤ò½ñ¤½Ð¤¹¡£ +Ä̾ï {\tt TANGLE} ¤Ï¡¢¥È¡¼¥¯¥ó¤Î´Ö¤Ë¶õÇòʸ»ú¤òÁÞÆþ¤·¤Ê¤¤¡£ +¤·¤«¤·¡¢¼±Ê̻ҡ¢Í½Ìó¸ì¡¢¿ôÃÍÄê¿ô¤Î²ó¤ê¤Ë¤Ï¶õÇò¤ò¤ª¤¯¡£ +ÆþÎϤ¬¡¢ +\begin{quote} +\tt if 0 > x-y then z := -1; +\end{quote} +¤Ê¤é¤Ð¡¢½ÐÎϤϡ¢ +\begin{quote} +\tt if 0>x-y then z:=-1; +\end{quote} +¤È¤Ê¤ê¡¢²òÀϤǤ¤Ê¤¤¤è¤¦¤Ê +\begin{quote} +\tt if0>x-ythenz:=-1; +\end{quote} +¤È¤Ï¤Ê¤é¤Ê¤¤¡£ +{\tt TANGLE} ¤¬ÊÑ´¹¤¹¤ë¤Î¤È°ã¤¦¥È¡¼¥¯¥ó¤ò˾¤à»þ¤Ë¤Ï¡¢ +³Æ¥È¡¼¥¯¥ó¤Ë {\tt tangleto}°À¤òÍ¿¤¨¤ë¤³¤È¤¬¤Ç¤¤ë¡£ +¤³¤Î»ØÄê¤Ï¡¢¤½¤Î¥È¡¼¥¯¥ó¤ò¥×¥í¥°¥é¥à¥Æ¥¥¹¥È¤È¤·¤Æ¤É¤¦°õºþ¤¹¤Ù¤¤«¤ò»ØÄꤹ¤ë +¤â¤Î¤Ç¤¢¤ë¡£ +Î㤨¤Ð¡¢ +C{\WEB}¤òÀ¸À®¤¹¤ë¤¿¤á¤Î{\tt spider}¥Õ¥¡¥¤¥ë¤Ç¤Ï¡¢{\tt =} ¤ò\ {\tt "=\ "} +¤È¤¤¤¦Ê¸»úÎó¤Ç°õºþ¤µ¤ì¤ë¥È¡¼¥¯¥ó¤È¤·¤Æ¤ª¤¤¿¤¤¡£ C ¤Ç¤Ï\ {\tt "=-"} ¤È¤¤¤¦ +ʸ»úÎó¤Î°ÕÌ£¤¬Û£Ëæ¤Ë¤Ê¤Ã¤Æ¤·¤Þ¤¦¤«¤é¤Ç¤¢¤ë¡£ + +%{\tt WEAVE} must turn the token stream into a {\TeX} text that will +{\tt WEAVE} ¤Ï¥È¡¼¥¯¥ó¤ÎʤӤò{\TeX} ¥Æ¥¥¹¥È¤ËÊÑ´¹¤·¡¢ +À°·Á°õºþ¤·¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£ +¤³¤ì¤Ï 3¤Ä¤Î¥¹¥Æ¥Ã¥×¤Ç¼Â¸½¤µ¤ì¤ë¡£ +\begin{enumerate} +\item +{\tt WEAVE} ¤Ï¡¢³Æ¥È¡¼¥¯¥ó¤ò {\jem ¥¹¥¯¥é¥Ã¥×}¤ËÊÑ´¹¤¹¤ë¡£ +¥¹¥¯¥é¥Ã¥×¤Ï¡¢2¤Ä¤Î½ÅÍפÊÆÃÀÃͤò»ý¤Ä: ¤½¤ì¤Ï¡¢ +¹½Ê¸¾å¤Î{\jem ¥«¥Æ¥´¥ê¡¼} ¤È +{\jem ËÝÌõ$($translation$)$}\index{\P{translation}{ËÝÌõ}} +¤Ç¤¢¤ë¡£ +¥«¥Æ¥´¥ê¡¼¤Ï¡¢À¶½ñ¤ò¤¹¤ë¤¿¤á¤Îʸˡ¾å¤Îµ¹æ¤Ç¤¢¤ë; +¤³¤Îʸˡ¤È¤Ï¡¢{\tt WEAVE} ¤¬À¶½ñÍѤÎÌ¿Îá¤ò»È¤Ã¤Æ¥¹¥¯¥é¥Ã¥×¤òÁȤ߹ç¤ï¤»¤ë +ÊýË¡¤Ç¤¢¤ë¡£ +%The translations are the {\TeX} texts that will tell {\TeX} exactly +%how to print the scraps. +translation\index{translation}¤È¤Ï¡¢{\TeX}¤¬¥¹¥¯¥é¥Ã¥×¤ò°õºþ¤¹¤ë¤¿¤á¤Î +{\TeX}¥Æ¥¥¹¥È¤Ç¤¢¤ë¡£ +\item +{\tt WEAVE}¤Ï¡¢¥¹¥¯¥é¥Ã¥×¤ÎʤӤòÀ¶½ñʸˡ¤Ë¤·¤¿¤¬¤Ã¤Æ´Ô¸µ¤·¤Æ¤¤¤¯( +{\tt WEAVE} ¤Ï¡¢shift-reduce ¹½Ê¸²òÀϤΰì¼ï¤ò¹Ô¤Ê¤¦)¡£ +translation \index{translation} ¤ò·ë¹ç¤·¤Æ¤¤¤ë¤¢¤¤¤ÀÃæ¡¢{\tt WEAVE} ¤Ï +¥¤¥ó¥Ç¥ó¥È¡¢¥¢¥¦¥È¥Ç¥ó¥È¡¢¹ÔÊѤ¨¤Ê¤É¤ò¤¹¤ë¤¿¤á¤Î +{\TeX} ¥Æ¥¥¹¥È¤òÄɲ䷤Ƥ¤¤¯¡£ +\item +ÍýÁÛŪ¤Ê¾ì¹ç¤Ë¤Ï¡¢{\tt WEAVE}¤ÏÈó¾ï¤ËŤ¤ translation\index{translation}¤ò»ý¤Ã¤¿ +°ì¤Ä¤Î¥¹¥¯¥é¥Ã¥×¤Ë¤Ê¤ë¤Þ¤Ç¡¢´Ô¸µ¤·¤¿¥¹¥¯¥é¥Ã¥×¤òÊÝ»ý¤¹¤ë¡£ +¤·¤«¤·¡¢¤¿¤Ö¤ó¡¢´Ô¸µ¤Ç¤¤Ê¤¤¥¹¥¯¥é¥Ã¥×¤ÎʤӤˤè¤Ã¤Æ½ª¤Ã¤Æ¤·¤Þ¤¦¤À¤í¤¦¡£ +¤¤¤º¤ì¤Ë¤»¤è¡¢¤½¤ì°Ê¾å´Ô¸µ¤Ç¤¤Ê¤¯¤Ê¤Ã¤¿¸å¤Ï¡¢ +»Ä¤Ã¤¿¥¹¥¯¥é¥Ã¥×¤Î translation\index{translation}¤ò°ì¤Ä¤º¤Ä½ÐÎϤ¹¤ë¡£ +\end{enumerate} + + +\section{{Spider}¤ò»È¤Ã¤Æ {\WEB}¤Î¥È¡¼¥¯¥óʬ²ò¤ò·è¤á¤ë} +{Spider} ¤Ï ¥È¡¼¥¯¥ó¤ò ͽÌó¸ì¤È¤½¤Î¾ ¤Î 2¼ïÎà¤Ë¶èÊ̤¹¤ë¡£ +ͽÌó¸ì¤Ï¡¢¥³¥Þ¥ó¥É {\tt reserved} ¤È {\tt ilk} +¤ò»È¤Ã¤Æ»ØÄꤹ¤ë¡£ +¤½¤Î¾¤Î¥È¡¼¥¯¥ó¤Ï¡¢¥³¥Þ¥ó¥É{\tt token}¤ò»È¤Ã¤Æ»ØÄꤹ¤ë( +%This somewhat unusual setup is dictated by the way {\tt +%WEAVE} works; its advantage is that is is easy to define a whole group +%of reserved words that will be treated identically.) +¤³¤Î¤¤¤µ¤µ¤«ÈóÄê¾ïŪ¤ÊÀßÄê¤Ï¡¢{\tt WEAVE}¤ÎÊʤ˹ç¤ï¤»¤ë¤¿¤á¤Ç¤¢¤ë¡£ +¤³¤ì¤Ï¡¢¶èÊ̤·¤Æ°·¤Ã¤ÆÍߤ·¤¤Í½Ìó¸ì¤Î¥°¥ë¡¼¥×Á´ÂΤò´Êñ¤ËÄêµÁ¤Ç¤¤ë¤È¤¤¤¦ +Ĺ½ê¤ò»ý¤Ä)¡£ +%Here's how it works: the {\tt reserved} command designates +Ư¤¤ò°Ê²¼¤Ë¼¨¤½¤¦: {\tt reserved} ¥³¥Þ¥ó¥É¤ÏÆÃÄê¤Î¼±Ê̻Ҥò +ͽÌó¸ì¤È¤·¤Æ¤ß¤Ê¤·¡¢¤É¤Î¤è¤¦¤Ê{\jem ilk $($°À$)$}¤È¤·¤Æ°·¤ï¤ì¤ë¤«¤ò +ÌÀ¼¨¤¹¤ë¡£ +% a particular identifier as a reserved word, and says +%what {\jem ilk} it belongs to. +%The {\tt token} and {\tt ilk} commands tell {\tt WEAVE} and {\tt +%TANGLE} what to do with a particular token, or with all the reserved +%words of a particular ilk. +¥³¥Þ¥ó¥É {\tt token} ¤È {\tt ilk} ¤Ï¡¢{\tt WEAVE} ¤È {\tt TANGLE}¤Ë +¤½¤Î¥È¡¼¥¯¥ó¤ò¤É¤¦¤¹¤ë¤«¡¢¤Þ¤¿¤Ï¤½¤Î°À¤ò»ý¤ÄÁ´¤Æ¤ÎͽÌó¸ì¤ò +¤É¤¦¤¹¤ë¤«¤ò»ØÄꤹ¤ë¡£ + +%For each token or ilk one can specify the {\jem tangleto} field, the +%token's {\jem mathness} (whether it has to be typeset in math mode), and +%its {\jem category} and {\jem translation} (for conversion to scraps). +³Æ¥È¡¼¥¯¥ó¤È°À¤Ï {\jem tangleto} ¥Õ¥£¡¼¥ë¥É¤ò»ý¤Ä¤³¤È¤¬¤Ç¤¡¢ +¥È¡¼¥¯¥ó¤Î {\jem mathness} (¿ô¼°¥â¡¼¥É¤ÇÁÈÈǤ¹¤ë¤³¤È¤Î»ØÄê)¤È¡¢ +{\jem ¥«¥Æ¥´¥ê¡¼}¡¢{\jem translation}\index{translation} (¥¹¥¯¥é¥Ã¥×¤Ç¤Î +µ½Ò¤ò»²¾È)¤ò +»ØÄê¤Ç¤¤ë¡£ +¥«¥Æ¥´¥ê¡¼°Ê³°¤Ï¡¢{\tt defaults}¤Ç¤½¤Î¥Ç¥Õ¥©¥ë¥ÈÃͤòÀßÄꤹ¤ë¤³¤È¤¬¤Ç¤¤ë¡£ +¥«¥Æ¥´¥ê¡¼Ì¾¤Ï¥æ¡¼¥¶¡¼¤ÎǤ°Õ¤Ç¤¢¤ë¡£ + +¥È¡¼¥¯¥óʬ²ò¤Î¥³¥Þ¥ó¥É¤Ë¤Ä¤¤¤Æ¤Ï¡¢¸å¤Û¤É{Spider}¤Î¹½Ê¸¤ò¾ÜºÙ¤ËÀâÌÀ¤¹¤ë»þ¤Ë +µÄÏÀ¤·¤¿¤¤¡£ +¤È¤â¤«¤¯¡¢ +C~¸À¸ìÍѤÎ{\tt spider} ¥Õ¥¡¥¤¥ë¤Î¥È¡¼¥¯¥óʬ²ò¥³¥Þ¥ó¥É¤ÎÎã¤ò +¸«¤ë¤³¤È¤Ë¤·¤è¤¦: +\begin{verbatim} +token + category unorbinop +token - category unorbinop +token * category unorbinop +token = category equals translation <"\\leftarrow"> tangleto <"="-space> +token ~ category unop translation <"\\TI"> +token & category unorbinop translation <"\\amp"> +token ^ translation <"\\^"> category binop +token ? translation <"\\?"> category question +token % translation <"\\%"> category binop +token # translation <"\\#"> category sharp +token ! category unop translation <"\\neg"> +token ( category lpar +token ) category rpar +token [ category lpar +token ] category rpar +token { translation <"\\{"> category lbrace +token } translation <"\\}"> category rbrace +token ++ category unop translation <"\\PP"> +token -- category unop translation <"\\MM"> +token != translation <"\\I"> category binop +token == translation <"\\S"> category binop +token && translation <"\\W"> category binop + +ilk case_like category case +ilk int_like category int + +reserved auto ilk int_like +reserved break ilk case_like +reserved case ilk case_like +reserved char ilk int_like +\end{verbatim} +¤³¤³¤Ë¤Ï¡¢C¤Ç»È¤ï¤ì¤ë¥È¡¼¥¯¥ó¤Î¤¤¤¯¤Ä¤«¤ÎÄêµÁÎ㤬¼¨¤µ¤ì¤Æ¤¤¤ë¡£ +{\tt tangleto}¥ª¥×¥·¥ç¥ó¤¬ ¤Û¤È¤ó¤É¤Î¾ì¹ç¥Ç¥Õ¥©¥ë¥È¤Î¤Þ¤Þ¤Ç¤¢¤ë¤³¤È¤È¡¢ +¤½¤·¤Æ {\tt translation} ¥ª¥×¥·¥ç¥ó¤¬¤·¤Ð¤·¤Ð¥Ç¥Õ¥©¥ë¥È¤Î¤Þ¤Þ¤Ç¤¢¤ë¤³¤È¤Ë +Ãí°Õ¤·¤ÆÍߤ·¤¤¡£ + +%Once the tokens are specified, and each has a {\tt tangleto} string, +%we can almost construct a {\tt TANGLE} for the language. +°ìÅ٥ȡ¼¥¯¥ó¤¬»ØÄꤵ¤ì¡¢¤½¤ì¤¾¤ì{\tt tangleto} ʸ»úÎó¤ò»ý¤Ã¤Æ¤¤¤ì¤Ð¡¢ +¸À¸ì¤È¤·¤Æ¤Î{\tt TANGLE} ¤Ï¡¢¤Û¤È¤ó¤É¹½ÃۤǤ¤¿¤è¤¦¤Ê¤â¤Î¤Ç¤¢¤ë¡£ +% Before we can construct a {\tt WEAVE}, we have to tell it how to +%combine and reduce scraps. +{\tt WEAVE}¤ò¹½ÃÛ¤¹¤ë¤¿¤á¤Ë¤Ï¡¢¥¹¥¯¥é¥Ã¥×¤Î·ë¹ç¤È´Ô¸µ¤Ë¤Ä¤¤¤Æ¤Î¤ä¤êÊý¤ò +»ØÄꤷ¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£ + + + +\section{{Spider}¤Ç{\tt WEAVE}¤Î¥¹¥¯¥é¥Ã¥×¤Î´Ô¸µ¤Î»ÅÊý¤ò»ØÄꤹ¤ë} +%The most intricate part of {\tt WEAVE} is its mechanism for converting +%programming language code into \TeX\ code. +{\tt WEAVE}¤Î¤â¤Ã¤È¤âÊ£»¨¤ÊÉôʬ¤Ï¡¢¥×¥í¥°¥é¥à¸À¸ì¤Î¥³¡¼¥É¤ò \TeX\ ¥³¡¼¥É¤Ë +ËÝÌõ¤¹¤ë¤È¤³¤í¤Ë¤¢¤ë¡£ +%{\tt WEAVE} uses a simple bottom-up parsing algorithm, since it +% must deal with fragmentary +%constructions whose overall ``part of speech'' is not known. +{\tt WEAVE} ¤Ï¡¢Ã±½ã¤Ê ¾å¾º·¿¹½Ê¸²òÀÏ¥¢¥ë¥´¥ê¥º¥à¤ò»È¤Ã¤Æ¤¤¤ë¡£ +¤½¤ì¤Ï¡¢ ´ûÃΤΡÖÏä·¸ÀÍդΰìÉô¡×¤Ç¤Ï¤Ê¤¤¡¢Ê¬ÃǤµ¤ì¤Æ¤¤¤ë¹½Â¤¤ò +°·¤ï¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¤¿¤á¤Ç¤¢¤ë¡£ + +ÆþÎϤϡ¢{\jem ¥¹¥¯¥é¥Ã¥×} ¤ÎʤӤȤ·¤ÆÍ¿¤¨¤é¤ì¡¢ +³Æ¥¹¥¯¥é¥Ã¥×¤Ï 2¤Ä¤Î¾ðÊó¤ò´Þ¤ó¤Ç¤¤¤ë¡£ +{\jem category} ¤È {\jem translation}\index{translation}¤Ç¤¢¤ë¡£ +¥«¥Æ¥´¥ê¡¼¤Ï´ðËÜŪ¤Ë¹½Ê¸Åª¤Ê¥¯¥é¥¹¤ò¼¨¤·¡¢ +translation\index{translation} ¤Ï{\TeX}¥³¡¼¥É¤ò¼¨¤·¤Æ¤¤¤ë¡£ +¹½Ê¸µ¬Â§¤È°ÕÌ£µ¬Â§¤ÏÎÙ¤¢¤Ã¤¿¥¹¥¯¥é¥Ã¥×¤ò¤è¤êÂ礤ʤâ¤Î¤Ë¤Þ¤È¤á¤ëÊýË¡¤òµ¬Äꤹ¤ë¡£ +±¿¤¬Îɤ±¤ì¤Ð¡¢¥×¥í¥°¥é¥à¥Æ¥¥¹¥ÈÁ´Éô¤¬¡¢ +²¿É´¤â¤Î¾®¤µ¤Ê¥¹¥¯¥é¥Ã¥×¤À¤Ã¤¿¤È¤³¤í¤«¤é¡¢¸ß¤¤¤Ë·ë¹ç¤µ¤ì¤Æ¹Ô¤¡¢ +°ì¤Ä¤ÎµðÂç¤Ê¥¹¥¯¥é¥Ã¥×¤Ë¤Ê¤ê¡¢ +¤½¤Î translation\index{translation} ¤¬´üÂÔ¤·¤Æ¤¤¤¿ \TeX\ ¥³¡¼¥É¤Ë¤Ê¤ë¤À¤í¤¦¡£ +±¿¤¬°¤±¤ì¤Ð¡¢¤¤¤¯¤Ä¤«¤Î¥¹¥¯¥é¥Ã¥×¤Ï·ë¹ç¤µ¤ì¤Ê¤¤¤Þ¤Þ¤Ë¤Ê¤ë¤À¤í¤¦; +¤½¤ì¤é¤Î translation\index{translation} ¤Ïñ½ã¤Ë°ì¤Ä¤º¤Ä½ÐÎϤµ¤ì¤ë¤³¤È¤Ë¤Ê¤ë¡£ + +·ë¹çµ¬Â§¤Ï¡¢º¸¤«¤é±¦¤Ø¤Îʸ̮°Í¸À¸À®µ¬Â§\index{\P{context-sensitive productions}{ +ʸ̮°Í¸À¸À®µ¬Â§}} +¤È¤·¤ÆÍ¿¤¨¤é¤ì¤ë¡£ +º£¡¢ $s_1\,s_2\ldots s_n$ ¤È¤¤¤¦¥¹¥¯¥é¥Ã¥×¤ÎʤӤò½èÍý¤·¤Æ¤¤¤ë¤È¤¹¤ë¡£ +ºÇ½é¤ÎʤӤǤ¢¤ë$s_1\,s_2\ldots\,$ ¤ËÂФ¹¤ëºÇŤÎÀ¸À®µ¬Â§¤òõ¤¹¡£ +¤·¤«¤·¡¢¤â¤·¤½¤Î¤è¤¦¤ÊÀ¸À®µ¬Â§¤¬Â¸ºß¤·¤Ê¤±¤ì¤Ð¡¢ +¼¡¤Î $s_2\,s_3\ldots\,$ ¤ËÂФ·¤ÆºÇŤÎÀ¸À®µ¬Â§¤ò¼¡¡¹¤Ëõ¤·¤Æ¤æ¤¯¡£ +¤½¤·¤Æ¡¢¤½¤ì¤â¼ºÇÔ¤·¤¿¤é $s_3\,s_4\ldots\,$, etc. ¤È¤¤¤¦¶ñ¹ç¤Ë¥Þ¥Ã¥Á¥ó¥°¤ò»î¹Ô¤¹¤ë¡£ + +À¸À®µ¬Â§¤Ï¡¢¤¢¤é¤«¤¸¤áÍ¿¤¨¤é¤ì¤¿¥«¥Æ¥´¥ê¡¼¥³¡¼¥É¤Î¥Ñ¥¿¡¼¥ó¤ò»ý¤Ä»þ¤ËŬÍѤµ¤ì¤ë¡£ +Î㤨¤Ð¡¢¤¢¤ëÀ¸À®µ¬Â§¤¬ +$$\hbox{\tt open [ math semi <"\BS\BS,"-opt-5> ] --> +open math}$$ +¤Ç¤¢¤ì¤Ð¡¢¤½¤ì¤Ï¡¢ +¤½¤ì¤¾¤ì{\tt open}¡¢ {\tt math}¡¢ {\tt semi}¤È¤¤¤¦¥«¥Æ¥´¥ê¡¼¤ò»ý¤Ä3¤Ä¤Î +Ϣ³¤·¤¿¥¹¥¯¥é¥Ã¥×¤Ï¡¢ + {\tt open} ¤È {\tt math}¤È¤¤¤¦¥«¥Æ¥´¥ê¡¼¤ò»ý¤Ä +2¤Ä¤Î¥¹¥¯¥é¥Ã¥×¤ËÊÑ´¹¤µ¤ì¤ë¤³¤È¤ò°ÕÌ£¤¹¤ë¡£ +{\tt open}¥¹¥¯¥é¥Ã¥×¤ÏÊÑ´¹¤µ¤ì¤Ê¤¤¡£°ìÊý¡¢ +ʸ»úÎó {\tt <"\BS\BS,"-opt-5>} ¤¬»ØÄꤵ¤ì¤Æ¤¤¤ë¤Î¤Ç¡¢ +¿·¤·¤¤ {\tt math} ¥¹¥¯¥é¥Ã¥×¤Ï +¸µ¤Î{\tt math}¤Îtranslation\index{translation}¡¢ +{\tt semi} ¤Îtranslation\index{translation}¡¢ + `{\tt \BS,}'¡¢ `{\tt opt}'¡¢ `{\tt5}' +¤È¤¤¤¦°ìÏ¢¤Î¤â¤Î¤Ç¹½À®¤µ¤ë¤³¤È¤Ë¤Ê¤ë( + \TeX\ ¥Õ¥¡¥¤¥ë¤Ë¤ª¤¤¤Æ¡¢¤³¤ì¤ÏÄɲäµ¤¤¥¹¥Ú¡¼¥¹¤¬¥»¥ß¥³¥í¥ó¤Î¸å¤Ë +ÉÕ¤¡¢ +penalty 50 ¤Î optional line break ¤¬Â³¤¯¤³¤È¤ò°ÕÌ£¤¹¤ë)¡£ +translation\index{translation} ¤Ï ³Ñ³ç¸Ì ({\tt <>}) ¤Ç³ç¤é¤ì¤Æ¤ª¤ê¡¢ +°úÍÑÉä({\tt "})¤Ç³ç¤é¤ì¤¿Ê¸»úÎó( +C ¤Î´Ä¶¤Ç¤Ï¥Ð¥Ã¥¯¥¹¥é¥Ã¥·¥å({\tt \BS}) ¤Ç¥¨¥¹¥±¡¼¥×¤µ¤ì¤¿Ê¸»ú¤Ç¤âÎɤ¤)¡¢ +ÆÃÊ̤ʥ¡¼¥ï¡¼¥É¤ò´Þ¤à¤³¤È¤¬¤Ç¤¤ë¡£ + +Ìò¤ËΩ¤ÄÀ¸À®µ¬Â§¤ÎÎã¤ò¼¨¤¹Á°¤Ë¡¢ +{Spider}¤Î¹½Ê¸¤ÎÂçÉôʬ¤ò´Þ¤à¥µ¥Ö¥»¥Ã¥È¤Î¾ÜºÙ¤òÀâÌÀ¤·¤è¤¦¡£ + + + +\section{{\tt spider} ¥Õ¥¡¥¤¥ë¤Î¹½Ê¸} + +{Spider} ¤Ï¡¢{\tt WEAVE} ¤È {\tt TANGLE}¤Î¤¿¤á¤Ë +¸À¸ì¤Îµ½Ò¤òC¤Î¥³¡¼¥É¤ËÊÑ´¹¤¹¤ë Awk ¥×¥í¥°¥é¥à¤Ç¤¢¤ë¡£ +{Spider}¤¬ Awk ¥×¥í¥°¥é¥à¤Ê¤Î¤Ç¡¢ÆþÎϤϹԤΥ·¡¼¥±¥ó¥¹¤Ç¤¢¤ê¡¢ +Á´¤Æ¤Î {Spider} ¥³¥Þ¥ó¥É¤¬1¹Ô¤Ë¼ý¤Þ¤é¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£ + +\paragraph{¥³¥á¥ó¥È¤È¶õÇò¹Ô} +{\jem Ǥ°Õ¤Î} ʸ»úÎó¤¬¥×¥í¥°¥é¥ß¥ó¥°¸À¸ì¤Î¥È¡¼¥¯¥ó¤Ë¤Ê¤êÆÀ¤ë¤Î¤Ç¡¢ +ÆÃÄê¤Îʸ»úʤӤò ``¥³¥á¥ó¥È¤Î³«»Ïµ¹æ''¤È¤·¤Æ·è¤á¤Æ¤ª¤¯¤³¤È¤¬¤Ç¤¤Ê¤¤¡£ +½¾¤Ã¤Æ¡¢ {Spider} ¤Ë¤Ï¥³¥á¥ó¥È¤Ï¤Ê¤¯¡¢ {\jem ¥³¥á¥ó¥È¹Ô}¤Î¤ß¤¬¤¢¤ë¡£ +¥³¥á¥ó¥È¹Ô¤Ï¡¢ºÇ½é¤¬ ``{\tt \#}'' ¤Ç»Ï¤Þ¤Ã¤Æ¤¤¤ë¹Ô¤Ç¤¢¤ë¡£ +{Spider}½èÍý·Ï¤Ï¥³¥á¥ó¥È¹Ô¤È¶õÇò¹Ô¤ò̵»ë¤¹¤ë¡£ + +\paragraph{¥Õ¥£¡¼¥ë¥É} +{\tt spider} ¤Î³Æ¥³¥Þ¥ó¥É¤Ï¡¢{\jem ¥Õ¥£¡¼¥ë¥É}¤ÎʤӤ«¤é¤Ê¤ë¡£ +¤³¤ì¤Ï¡¢Awk ¤Î¥Õ¥£¡¼¥ë¥É¤ÈƱ°ì¤Ç¡¢¥Û¥ï¥¤¥È¥¹¥Ú¡¼¥¹\index{white space} +¤Ç¶èÀÚ¤é¤ì¤Æ¤¤¤ë¡£ +¤³¤Î Awk ¤«¤é·Ñ¾µ¤·¤¿À¼Á¤Î¤æ¤¨¤Ë¡¢{Spider}¤Ï¥Õ¥£¡¼¥ë¥ÉÃæ¤Ë +¥Û¥ï¥¤¥È¥¹¥Ú¡¼¥¹¤Ï»ÈÍѤǤ¤Ê¤¤¡£ + + +\subsection{ËÝÌõ} +%Most fields in a {Spider} file are simple identifiers, or perhaps +%strings of non-alphanumeric characters. +{Spider}¥Õ¥¡¥¤¥ë¤ÎÂçÉôʬ¤Î¥Õ¥£¡¼¥ë¥É¤Ï¡¢Ã±½ã¤Ê¼±ÊÌ»Ò\index{identifier}¤«¡¢ +¤¿¤Ö¤óÈó±Ñ¿ô»úʸ»ú\index{non-alphanumeric character}¤Ç¤¢¤ë¡£ +%The major exception is {\jem translations}. +ºÇÂç¤ÎÎã³°¤Ï¡¢{\jem ËÝÌõ}\index{translations}¤Ç¤¢¤ë¡£ +%Translations are always surrounded by angle brackets ({\tt <>}), +ËÝÌõ¤Ï¾ï¤Ë³Ñ¥«¥Ã¥³\index{angle bracket} ({\tt <>}) ¤Ç°Ï¤Þ¤ì¤Æ¤ª¤ê¡¢ +%and consist of a (possibly empty) list of translation pieces. +(¶õ¤Ç¤âÎɤ¤)ËÝÌõÍ×ÁÇ\index{translation pieces}¤Î¥ê¥¹¥È¤Ç¤¢¤ë¡£ +%The pieces on a list are separated by dashes ({\tt -}). +¥ê¥¹¥ÈÃæ¤Î³ÆÍ×ÁǤϡ¢¥À¥Ã¥·¥å({\tt -})¤Ç¶èÀÚ¤é¤ì¤ë¡£ +ËÝÌõÍ×ÁǤϡ¢²¼µ¤Î°ì¤Ä¤Ç¤¢¤ë¡£ +\begin{itemize} +\item °úÍÑÉä¤Ç°Ï¤Þ¤ì¤¿Ê¸»úÎó. +¤³¤Îʸ»úÎó¤Ï¡¢``\verb+\+'' ¤Ç¥¨¥¹¥±¡¼¥×¤µ¤ì¤¿Ê¸»ú¤òµö¤¹¤¬¡¢ +¥Û¥ï¥¤¥È¥¹¥Ú¡¼¥¹¤È¥À¥Ã¥·¥å¤ò´Þ¤ó¤Ç¤Ï¤Ê¤é¤Ê¤¤¡£ +\item ``self'' ¥Þ¡¼¥«¡¼, ``{\tt *}'', + ¤Ï¡¢ËÝÌõ¤µ¤ì¤è¤¦¤È¤·¤Æ¤¤¤ë¥È¡¼¥¯¥ó¤Îʸ»úÎó¤ò»²¾È¤¹¤ë¡£ +%refers to the sequence of characters making up the token being translated. +%The self marker is permitted only in certain contexts, and its precise +%meaning depends on the context. +¥»¥ë¥Õ¥Þ¡¼¥«¤Ï³ÎÄꤷ¤Æ¤¤¤ëʸ̮¤ÎÃæ¤Ç¤Î¤ßµö¤µ¤ì¤Æ¤ª¤ê¡¢¤½¤Î°ÕÌ£¤¹¤ë¤È¤³¤í¤Ï +ʸ̮¤Ë°Í¸¤·¤Æ¤¤¤ë¡£ +\item ¿ô»ú +\item ¥¡¼¥ï¡¼¥É: +{Spider} ¤Î¥¡¼¥ï¡¼¥É¤Ï¡¢°Ê²¼¤ÎÄ̤ê¤Ç¤¢¤ë¡£ +\begin{description} +\item [\tt space] 1¤Ä¤Î¶õÇòʸ»ú ({\tt "\ "})¤ò°ÕÌ£¤¹¤ë. +\item[\tt dash] 1¤Ä¤Î¥À¥Ã¥·¥å ({\tt "-"})¤ò°ÕÌ£¤¹¤ë. +\end{description} +¤½¤Î¾¤Î¥¡¼¥ï¡¼¥É¤Ï{\tt WEAVE}¤ËÅϤµ¤ì¤ë¡£ + +{\tt WEAVE} ¤Ï¡¢°Ê²¼¤Î¥¡¼¥ï¡¼¥É¤òǧ¼±¤¹¤ë: +\begin{description} +\item[\tt break\_space] optional line break ¤Þ¤¿¤Ï ¶õÇò; +\item[\tt force] line break; +\item[\tt big\_force] ¿âľ¥¹¥Ú¡¼¥¹¤ò»ý¤Ä line break; +\item[\tt opt] optional line break ( °Ê¹ß¤Î¹Ô¤ÏÄ̾ï¤Î³«»Ï°ÌÃÖ¤è¤ê +2em ¥¤¥ó¥Ç¥ó¥È¤µ¤ì¤ë)--- +¤³¤Î¥³¡¼¥É¤Ï¡¢À°¿ô$n$ ¤òȼ¤¤¡¢break ¤Ï¥Ú¥Ê¥ë¥Æ¥£ $10n$ ¤È¤·¤Æ°·¤ï¤ì¤ë¡£ +%code is followed by an integer $n$, and the break will occur with penalty +%$10n$; +\item[\tt backup] 1em ¤Î backspace; +\item[\tt cancel] Àè¹Ô¤·¤Æ¤¤¤¿\ ¤Þ¤¿¤Ï³¤¯¤¹¤Ù¤Æ¤Î {\tt break\_space}, + {\tt force},{\tt big\_force} ¤ò¼è¤ê¾Ã¤¹¡£¤µ¤é¤Ë¡¢ +³¤¯ {\tt backup} ¥È¡¼¥¯¥ó¤â¥¥ã¥ó¥»¥ë¤¹¤ë; +\item[\tt indent] °Ê¹ß¤Î¹Ô¤ò 1em ¥¤¥ó¥Ç¥ó¥È¤¹¤ë +\item[\tt outdent] °Ê¹ß¤Î¹Ô¤ò -1em ¥¤¥ó¥Ç¥ó¥È¤¹¤ë +\item[\tt math\_rel] \verb+\mathrel{+ ¤ËÊÑ´¹¤µ¤ì¤ë +\item[\tt math\_bin] \verb+\mathbin{+ ¤ËÊÑ´¹¤µ¤ì¤ë +\item[\tt math\_op] \verb+\mathop{+ ¤ËÊÑ´¹¤µ¤ì¤ë +\end{description} +¿ô¼°¥â¡¼¥É¤Ç¤âÀµ¤·¤¯½èÍý¤µ¤ì¤ë {\jem Í£°ì} ¤Î¥¡¼¥ï¡¼¥É¤Ï¡¢{\tt +indent} ¤È {\tt outdent}¤À¤±¤Ç¤¢¤ë¡£ +¤â¤·¡¢Â¾¤Î¥¡¼¥ï¡¼¥É¤ò´Þ¤àËÝÌõ¤òÄêµÁ¤·¤¿¤¤»þ¤Ï¡¢ +¤½¤Î¥È¡¼¥¯¥ó¤Ë¤Ï{\tt mathness~no} ¤ò»È¤ï¤Í¤Ð¤Ê¤é¤Ê¤¤¡£ +%You may use any recognized key words in the translations of a +%production; there the mathness is automatically taken care of for you. +À¸À®µ¬Â§¤ÎËÝÌõ¤ÎÃæ¤Ç¤Ï¡¢¤É¤ó¤Ê¥¡¼¥ï¡¼¥É¤ò»È¤Ã¤Æ¤â¹½¤ï¤Ê¤¤¡£ +¤½¤ì¤é¤Î¿ô¼°À¤Ï¼«Æ°Åª¤Ë½èÍý¤µ¤ì¤ë¡£ +\end{itemize} + +°Ê²¼¤Ï¡¢ËÝÌõ\index{translation}¤ÎÎã¤Ç¤¢¤ë¡£: +\begin{verbatim} +<"\\"-space> +<indent-force> +<"{\\let\\\\=\\bf"-space> +<"}"-indent-"{}"-space> +\end{verbatim} + +\paragraph{À©¸Â¤µ¤ì¤¿ËÝÌõ}\index{Restricted translations} +¤¤¤¯¤Ä¤«¤Î¾ì¹ç¤Ï¡¢Î㤨¤Ð¡¢{\tt tangleto} µ½Ò¤Ê¤É¤Ç¤Ï¡¢ +ËÝÌõ\index{translations}¤ÏÀ©¸Â¤µ¤ì¤ë¡£ +À©¸Â¤µ¤ì¤¿ËÝÌõ\index{restricted translation} ¤Ï¡¢¥¿¥¤¥×¥»¥Ã¥Æ¥£¥ó¥°¥³¡¼¥É¤Ë +ÊÑ´¹¤µ¤ì¤ë¤³¤È¤Ï¤Ê¤¯ ¾ï¤Ë ASCII ʸ»úÎó¤È¤Ê¤ë¡£ +%is never converted to typesetting code, +%but is always converted to an ASCII string, +%usually for output by {\tt +%TANGLE}, but sometimes for other things. +¤¿¤¤¤Æ¤¤¤Ï{\tt TANGLE} ¤Î½ÐÎÏÍѤ˻Ȥï¤ì¤ë¤¬¡¢Ê̤ÎÍÑÅӤǤâ»È¤¦¡£ +À©¸Â¤µ¤ì¤¿ËÝÌõ\index{restricted translation}¤Ï¡¢ +{\jem °úÍÑÉä¤Ç³ç¤é¤ì¤¿Ê¸»úÎó} ¤ª¤è¤Ó¡¢ +{\tt space} ¤È{\tt dash} ¤Î2¤Ä¤Î¥¡¼¥ï¡¼¥É¤Î¤ß¤¬µö¤µ¤ì¤ë¡£ + + +\subsection{{\tt token} ¥³¥Þ¥ó¥É} +{\tt token} ¥³¥Þ¥ó¥É¤Î¹½Ê¸¤Ï¡¢¼¡¤ÎÄ̤ê¤Ç¤¢¤ë: +\begin{quote} +\tt +\syntax{command} \produces~token \syntax{token-designator} +\syntax{token-descriptions} +\end{quote} +¤³¤³¤Ç \syntax{token-descriptions} ¤Ï (¶õ¤Ç¤âÎɤ¤) ¥È¡¼¥¯¥óµ½Ò¤Î¥ê¥¹¥È¤Ç¤¢¤ë¡£ + +\paragraph{¥È¡¼¥¯¥óµ½Ò} +¥È¡¼¥¯¥óµ½Ò¤Ï +\begin{itemize}\parindent=0pt +\item +{\tt tangleto \syntax{restricted translation}} + +\syntax{restricted translation} ¤Ï {\tt TANGLE}¤Ë +¤³¤Î¥È¡¼¥¯¥ó¤ò¥×¥í¥°¥é¥à¥Æ¥¥¹¥È¤Ë½ñ¤½Ð¤¹¤â¤Î¤òµ¬Äꤹ¤ë¡£ +À©¸Â¤µ¤ì¤¿ËÝÌõ\index{restricted translation}¤Ç͸ú¤Ê¤â¤Î¤Ï¡¢ +{\jem °úÍÑÉä¤Ç³ç¤é¤ì¤¿Ê¸»úÎó} ¤ª¤è¤Ó¡¢ +{\tt space} ¤È{\tt dash} ¤Î2¤Ä¤Î¥¡¼¥ï¡¼¥É¤Î¤ß¤Ç¤¢¤ë¡£ +¤â¤· {\tt tangleto} µ½Ò¤¬¤Ê¤±¤ì¤Ð¡¢ {\tt TANGLE} ¤Ï +¥È¡¼¥¯¥ó¤ò¹½À®¤·¤¿Ê¸»úÎó¤ò½ñ¤½Ð¤¹¡£ + +\item +{\tt translation \syntax{translation}} + +%Tells {\tt WEAVE} what translation to assign when making this token into +%a scrap. +{\tt WEAVE} ¤¬¥È¡¼¥¯¥ó¤ò¥¹¥¯¥é¥Ã¥×¤ÎÃæ¤ËÃÖ¤¯»þ¤Ë¤É¤¦ËÝÌõ¤¹¤ë¤«¤ò»Ø¼¨¤¹¤ë¡£ +%The self +%marker~({\tt*}) stands for the sequence of characters that were read in to +%make up the token. +¥»¥ë¥Õ¥Þ¡¼¥«¡¼~({\tt*}) ¤Ï¡¢¥È¡¼¥¯¥ó¤ò¹½À®¤·¤Æ¤¤¤ëʸ»úÎ󤽤Τâ¤Î¤ò¼¨¤¹¡£ +ËÝÌõ¤Ï¤·¤Ð¤·¤Ð \verb+translation <*>+ ¤¬¥Ç¥Õ¥©¥ë¥È¤È¤Ê¤ë; {Spider} +¤Ï¤³¤ì¤ò¤¢¤é¤«¤¸¤á¥Ç¥Õ¥©¥ë¥È¤È¤·¤ÆÁȤ߹þ¤ó¤Ç¤¢¤ë¡£ + +\item +{\tt category \syntax{category-name}} + +%Tells {\tt WEAVE} what category to assign when making this token into +%a scrap. +{\tt WEAVE} ¤¬¤³¤Î¥È¡¼¥¯¥ó¤ò¥¹¥¯¥é¥Ã¥×¤Ë¤¤¤ì¤ë¤È¤¤Ë»È¤¦¥«¥Æ¥´¥ê¡¼¤ò»ØÄꤹ¤ë¡£ +{Spider} ¥Õ¥¡¥¤¥ë¤ò½ñ¤¯»þ¤Ï¹¥¤¤Ê¥«¥Æ¥´¥ê¡¼Ì¾¤ò +»È¤¦¤³¤È¤¬¤Ç¤¤ë¡£ +¼é¤ë¤Ù¤¾ò·ï¤Ï¡¢{Spider} ¤¬ÃΤäƤ¤¤ë¾¤Î̾Á°(ͽÌ󥡼¥ï¡¼¥É¡¢ +ilk¤Î̾Á° ¤Ê¤É)¤È¾×Æͤ·¤Ê¤¤¤è¤¦¤Ë¤¹¤ë¤³¤È¤À¤±¤Ç¤¢¤ë¡£ +%Using category names that are identical to reserved words of the +%target programming language (¤Þ¤¿¤Ï C~¤ÎͽÌó¸ì) is not only +%supported, it is strongly encouraged, for clarity. +%Using category names that are identical to reserved words of the +¥«¥Æ¥´¥ê¡¼Ì¾¤ò +¥¿¡¼¥²¥Ã¥È¸À¸ì¤ÎͽÌó¸ì(¤Þ¤¿¤Ï C~¤ÎͽÌó¸ì)¤ÈƱ°ì¤Ë¤·¤Æ¤ª¤¯¤³¤È¤Ï¡¢ +ÌÀ²÷¤µ¤Î°Ù¤À¤±¤Ç¤Ê¤¯¡¢¶¯¤¤Í×ÀÁ¤Ç¤¢¤ë¡£ +%Also, when we get to the sample grammars later on, you will see some +%other conventions we use for category names. +¸å¤Û¤Éʸˡ¤ÎÎã¤ò¸«¤ë¤³¤È¤Ë¤Ê¤ë¤¬¡¢ +¥«¥Æ¥´¥ê¡¼Ì¾¤ò»È¤¦¤¿¤á¤Î¤¤¤¯¤Ä¤«¤ÎÌó«»ö¤¬¤¢¤ë¡£ + +\item +{\tt mathness \syntax{mathness-indicator}} + +¤³¤³¤Ç¡¢\syntax{mathness-indicator} ¤Ï {\tt yes}¡¢{\tt no}¡¢{\tt +maybe}¤Î¤¤¤º¤ì¤«¤Ç¤¢¤ë¡£ +%This indicates to {\tt WEAVE} whether the translation for this token +%needs to be typeset in {\TeX}'s math mode or not, or whether it +%doesn't matter. +¤³¤ì¤Ï {\tt WEAVE} ¤¬¤³¤Î¥È¡¼¥¯¥ó¤ò°õºþ¤¹¤ë¤¿¤á¤Î translation ¤È¤·¤Æ +{\TeX}¤Î¿ô¼°¥â¡¼¥É¤ò»È¤¦¤«Èݤ«¡¢¤Þ¤¿¤Ïµ¤¤Ë¤¹¤ëɬÍפ¬¤Ê¤¤¤«¤ò»Ø¼¨¤¹¤ë¡£ +¤³¤ÎÀ¸À®µ¬Â§¤¬Å¬ÍѤµ¤ì¤¿¤È¤¡¢ +{\tt WEAVE} ¤Ï¿ô¼°¥·¥Õ¥Èʸ»ú~(\verb+$+) ¤ò{\TeX}¥Æ¥¥¹¥ÈÃæ¤Ë¤ª¤¯¤³¤È¤Ç +Àµ¤·¤¤¥â¡¼¥É¤Ë¥È¡¼¥¯¥ó¤¬ÃÖ¤«¤ì¤ë¤³¤È¤òÊݾڤ·¤è¤¦¤È¤¹¤ë¡£ +%Tokens with the {\jem empty translation} (\verb+<>+) should always have +%{\tt mathness maybe}, lest they cause {\tt WEAVE} to place two +%consecutive math shift characters. +{\jem ¶õ¤Î translation} (\verb+<>+) ¤ò»ý¤Ä¥È¡¼¥¯¥ó¤Ï¾ï¤Ë +{\tt mathness maybe}¤Ç¤¢¤ë¤È¤ß¤Ê¤µ¤ì¡¢¤½¤Î·ë²Ì¤È¤·¤Æ {\tt WEAVE}¤¬ +2¤Ä¤Î¿ô¼°¥·¥Õ¥Èʸ»ú¤òÃÖ¤¯¤³¤È¤¬¤Ç¤¤ë¤è¤¦¤Ë°·¤ï¤ì¤ë¡£ + +\item +{\tt name \syntax{token-name}} + +¤³¤ì¤Ï¡¢{Spider} ¤Þ¤¿¤Ï {\WEB}¤Î¥Ç¥Ð¥Ã¥°¤Î»þ¤Î¤ß¤Ë»È¤ï¤ì¤ë¡£ +%It causes the specified name to be attached to the token, +¤³¤ì¤Ë¤è¤Ã¤Æ¡¢¥È¡¼¥¯¥ó¤Ï»ØÄꤵ¤ì¤¿Ì¾Á°¤¬ÉÕÍ¿¤µ¤ì¡¢ +%so that a programmer can search for that name in the C~code generated by +%{Spider}. +¥×¥í¥°¥é¥Þ¡¼¤Ï{Spider}¤Ë¤è¤Ã¤ÆÀ¸À®¤µ¤ì¤¿C~¥³¡¼¥É¤ÎÃ椫¤é¤³¤Î̾Á°¤ò +¸¡º÷¤¹¤ë¤³¤È¤¬²Äǽ¤Ë¤Ê¤ë¡£ + +\end{itemize} + +%\paragraph{Token designators} +\paragraph{¥È¡¼¥¯¥ó̾} +{Spider} ¤Ï°Ê²¼¤Î ¥È¡¼¥¯¥ó̾¤òǧ¼±¤¹¤ë: +\begin{description} +\item[{\tt ¼±ÊÌ»Ò(identifier)}] +¤³¤ì¤ò»È¤¦ {\tt token} ¥³¥Þ¥ó¥É¤Ï +{\tt WEAVE} ¤È {\tt TANGLE} ¤Ë¼±Ê̻ҥȡ¼¥¯¥ó¤ËÂФ¹¤ë½èÍý¤ò»Ø¼¨¤¹¤ë¡£ +»ÄÇ°¤Ê¤¬¤é¡¢{Spider} ¤Ë²¿¤ò¼±Ê̻ҤȤ¹¤Ù¤¤«¤ò»ØÄꤹ¤ë¤³¤È¤Ï¤Ç¤¤Ê¤¤¡£ +¼±Ê̻ҤÎÄêµÁ¤Ï{\tt WEAVE} ¤È {\tt TANGLE}¤ÎÆâÉô¤ËÁȤ߹þ¤Þ¤ì¤Æ¤¤¤ë¡£ +¼±Ê̻Ҥϰʲ¼¤ÎÀµµ¬É½¸½¼°¤Ë¹çÃפ¹¤ëºÇŤÎʸ»úÎó¤Ç¤¢¤ë% +\footnote{ÆɼԤ¬ Unix ¤ÎÀµµ¬É½¸½¤ËÆëÀ÷¤ß¤¬¤Ê¤¤¤Î¤Ç¤¢¤ì¤Ð¡¢ +{\it ed(1)} ¤Î¥Þ¥Ë¥å¥¢¥ë¥Ú¡¼¥¸¤ò»²¹Í¤Ë¤·¤ÆÍߤ·¤¤¡£}: +\begin{verbatim} +[a-zA-Z_][a-zA-Z0-9_]* +\end{verbatim} + +\item[{\tt ¿ôÃÍ(number)}] +{Spider} ¤È {\tt WEAVE}¤Î¸½¾õ¤Î¼Â¸½¤Î»ÅÊý¤Ç¤Ï¡¢ +{\tt token} ¥³¥Þ¥ó¥É¤Ï¿ôÃÍÄê¿ô¤Èʸ»úÎóÄê¿ô¤ÎξÊý¤ò¥«¥Ð¡¼¤¹¤ë¡£ +¼±Ê̻ҤÈƱÍͤˡ¢¿ôÃÍÄê¿ô¤Èʸ»úÄê¿ô¤¬²¿¤Ç¹½À®¤µ¤ì¤ë¤«¤È¤¤¤¦ÄêµÁ¤Ï +Êѹ¹¤¹¤ë¤³¤È¤¬¤Ç¤¤Ê¤¤¡£ +{\samepage +¿ôÃÍÄê¿ô¤Ï°Ê²¼¤Î¤è¤¦¤ÊºÇĹ¹çÃפǤ¢¤ë% +\footnote{¸À¸ì¤¬»ý¤ÄÉâÆ°¾®¿ôÅÀɽµ¤ò¥µ¥Ý¡¼¥È¤¹¤ë¤¿¤á¤Î +{\WEB} ¥³¥ó¥È¥í¡¼¥ë¥·¡¼¥±¥ó¥¹¤¬¤¢¤Ã¤ÆÅöÁ³¤Ç¤¢¤ë¡£}: +\begin{verbatim} +[0-9]+(\.[0-9]*)? +\end{verbatim} +} +ʸ»úÎóÄê¿ô¤Ï°Ê²¼¤Î¤è¤¦¤ÊºÇĹ¹çÃפǤ¢¤ë +\begin{verbatim} +\"([^"]*\\\")*[^"]*\"|'[^@\]'|'\\.'|'@@' +\end{verbatim} +¥Ð¥Ã¥¯¥¹¥é¥Ã¥·¥å~(\verb+\+)¤Ç¥¨¥¹¥±¡¼¥×¤µ¤ì¤¿²þ¹Ô¤Ïʸ»úÎóÄê¿ô¤Ë +´Þ¤à¤³¤È¤¬¤Ç¤¤ë¡£ + +\item[{\tt newline}] +¤³¤ì¤ò»È¤¦{\tt token} ¥³¥Þ¥ó¥É¤Ï {\tt WEAVE} ¤È {\tt +TANGLE} ¤Ë²þ¹Ô¤Î°·¤¤Êý¤ò»Ø¼¨¤¹¤ë¡£ +¸å¤Û¤É¡¢{\tt WEAVE} ¤Ë²þ¹Ô¤ò̵»ë¤µ¤»¤ëÊýË¡¤ò¼¨¤¹¡£ + +\item[{\tt pseudo\_semi}] +¤³¤ì¤ò»È¤¦{\tt token} ¥³¥Þ¥ó¥É¤Ï¡¢ +{\tt WEAVE} ¤¬ +{\tt @;}¤È¤¤¤¦{\WEB} ¥³¥ó¥È¥í¡¼¥ë¥·¡¼¥±¥ó¥¹¤Ç½èÍý¤¹¤ë¤³¤È¤ò»ØÄꤹ¤ë¡£ +¤³¤Î¥³¥ó¥È¥í¡¼¥ë¥·¡¼¥±¥ó¥¹¤Ï{\tt TANGLE}¤Ç¤Ï¾ï¤Ë̵»ë¤µ¤ì¤ë¡£ + +\item[\syntax{characters}] +¤³¤³¤Ç¡¢characters ¤ÏÈó±Ñ¿ô»ú¤Ç¤¢¤ë¡£ +¤³¤ì¤ò»È¤¦ {\tt token} ¥³¥Þ¥ó¥É¤Ï¡¢ +ʸ»úÎó¤ò¥È¡¼¥¯¥ó¤È¤·¤ÆÄêµÁ¤·¡¢ +{\tt WEAVE} ¤È {\tt TANGLE} ¤¬¤³¤Î¥È¡¼¥¯¥ó¤ËÂФ·¤Æ¹Ô¤Ê¤¦½èÍý¤ò»Ø¼¨¤¹¤ë¡£ +¥È¡¼¥¯¥ó¤Ï¾¤Î¥È¡¼¥¯¥ó¤ÎÀÜƬ¼¤Ç¤¢¤Ã¤Æ¤âÎɤ¤; {\tt WEAVE} ¤È {\tt TANGLE} +¤ÏºÇŤΤâ¤Î¤òºÎÍѤ¹¤ë¡£ +¤½¤¦¤¤¤¦¤ï¤±¤Ç¡¢ C~{\WEB}¤Ç¤Ï¡¢ \verb+==+ ¤Ïñ°ì¤Î\ \verb+==+ ¥È¡¼¥¯¥ó +¤È¤·¤ÆÆɤ߹þ¤Þ¤ì¡¢ +Æó¤Ä¤Î \verb+=+ ¥È¡¼¥¯¥ó¤È¤µ¤ì¤ë¤³¤È¤Ï¤Ê¤¤¡£ +\end{description} + + + + +\subsection{ͽÌó¸ì¥È¡¼¥¯¥ó} +%Reserved words are attached to a particular {\jem ilk} using the {\tt +%reserved} command. +ͽÌó¸ì¤Ï{\tt reserved} ¥³¥Þ¥ó¥É¤ÇÆÃÄê¤Î {\jem ilk} ¤È·ë¤ÓÉÕ¤±¤é¤ì¤ë¡£ +\begin{quote} +\tt reserved \syntax{reserved-word} $[$ilk \syntax{ilk-name}$]$ +\end{quote} +%If you're writing a {Spider} file, you may choose any ilk +%names you like, subject only to the restriction that they not conflict +%with other names known to {Spider} (e.g.~predefined key words, +%names of categories, and so on). +{Spider} ¥Õ¥¡¥¤¥ë¤ò½ñ¤¯»þ¤Ï¹¥¤¤Ê¥«¥Æ¥´¥ê¡¼Ì¾¤ò +»È¤¦¤³¤È¤¬¤Ç¤¤ë¡£ +¼é¤ë¤Ù¤¾ò·ï¤Ï¡¢{Spider} ¤¬ÃΤäƤ¤¤ë¾¤Î̾Á°(ͽÌ󥡼¥ï¡¼¥É¡¢ +ilk¤Î̾Á°¡¢ ¤Ê¤É)¤È¾×Æͤ·¤Ê¤¤¤è¤¦¤Ë¤¹¤ë¤³¤È¤À¤±¤Ç¤¢¤ë¡£ +%The convention, however, is to use ilk {\tt with\_like} for a reserved +%word {\tt with}, and so on.% +¤·¤«¤·¤Ê¤¬¤é¡¢Ìó«»ö¤È¤·¤ÆÎ㤨¤Ð{\tt with}¤È¤¤¤¦Í½Ìó¸ì¤Ë¤Ï{\tt with\_like} +¤È¤¤¤¦ ilk ¤¬»È¤ï¤ì¤ë% +\footnote{% +¤³¤ÎÌó«»ö¤Î¤»¤¤¤Ç¡¢É®¼Ô¤Ïͳ²¤Êµ¡Ç½¤ò{Spider}¤Ë²Ã¤¨¤ë¤È¤¤¤¦Í¶ÏÇ¤Ë +É餱¤Æ¤·¤Þ¤Ã¤¿ --- ¤â¤· {\tt reserved}¡¡¥³¥Þ¥ó¥É¤Ç ilk ¤ò¾Êά¤·¤Æ¤·¤Þ¤Ã¤¿¤é¡¢ +%{Spider} will make an ilk name by appending {\tt \_like} +%to the name of the reserved word. +{Spider}¤ÏͽÌó¸ì¤Î̾Á°¤Î¸å¤í¤Ë{\tt \_like}¤òÉղä·¤¿ ilk ̾¤òºî¤í¤¦¤È¤¹¤ë¡£ +%Furthermore, if that ilk doesn't already exist, {Spider} will +%construct one. +¤µ¤é¤Ë¡¢¤½¤Î¤è¤¦¤Ê ilk ¤¬¤Þ¤À¸ºß¤·¤Æ¤¤¤Ê¤±¤ì¤Ð¡¢ +{Spider}¤Ï¤½¤ì¤òºî¤Ã¤Æ¤·¤Þ¤¦¡£ +¤³¤Îµ¡Ç½¤ò»È¤Ã¤Æ¤Ï¤¤¤±¤Ê¤¤¡£ +}¡£ + +{\tt ilk}¥³¥Þ¥ó¥É¤È {\tt token} ¥³¥Þ¥ó¥É¤ÏÈó¾ï¤Ë»÷¤¿¹½Ê¸¤ò»ý¤Ä¡£ +{\tt ilk} ¥³¥Þ¥ó¥É¤Î¹½Ê¸¤Ï¡¢°Ê²¼¤ÎÄ̤ê: +\begin{quote}\tt +\syntax{command} \produces~ilk \syntax{ilk-name} +\syntax{token-descriptions} +\end{quote} +%In translations that appear in {\tt ilk} commands, the self +%marker~({\tt *}) designates the string of characters making up the +%reserved word, surrounded by \verb+\&{...}+, which makes the reserved +%words appear in bold face. +{\tt ilk}¥³¥Þ¥ó¥ÉÃæ¤Ë¸½¤ì¤ë translation ¤Ë¤ª¤¤¤Æ¡¢ +¥»¥ë¥Õ¥Þ¡¼¥«¡¼~({\tt *})¤ÏͽÌó¸ì¼«¿È¤ò¹½À®¤¹¤ëʸ»úÎó\ ¤ò°ÕÌ£¤·¡¢ +\verb+\&{...}+ ¤Ç°Ï¤Þ¤ì¤Æ +ͽÌó¸ì¤ò°ÕÌ£¤¹¤ë¥Ü¡¼¥ë¥ÉÂΤǰõºþ¤µ¤ì¤ë¡£ + + + + + + + + +\section{À°·Á°õºþʸˡ¤Î¹½Ê¸} +%Defining the tokens of a language is somewhat tedious, but it is +%essentially straightforward, and the definition usually does not need +%fine tuning. +¸À¸ì¤Î¥È¡¼¥¯¥ó¤òÄêµÁ¤¹¤ë¤³¤È¤Ï¡¢¤¤¤µ¤µ¤«Âà¶þ¤Ê¤â¤Î¤Ç¤¢¤ë¡£ +¤·¤«¤·¡¢´ðËÜŪ¤Ë¤ÏľÀÜŪ¤Ë¤Ç¤¡¢ +ÉáÄ̤ÏÄêµÁ¼«ÂΤ˥Á¥å¡¼¥Ë¥ó¥°¤ò¤¹¤ëɬÍפϤʤ¤¡£ +%When developing a new {\WEB} with {Spider}, you will spend most of +%your time writing the grammar that tells {\tt WEAVE} how to reduce +%scraps. +{Spider} ¤Ë¤è¤Ã¤Æ¿·¤·¤¤ {\WEB} ¤ò³«È¯¤¹¤ë¤È¤¤Ë¤Ï¡¢ +¤Û¤È¤ó¤É¤Î»þ´Ö¤ò {\tt WEAVE} ¤¬¥¹¥¯¥é¥Ã¥×¤ò´Ô¸µ¤¹¤ë¤¿¤á¤Îʸˡ¤ò½ñ¤¯¤³¤È¤Ë +Èñ¤ä¤¹¤³¤È¤Ë¤Ê¤ë¤À¤í¤¦¡£ +%The grammar is defined as a sequence of context-sensitive productions. +ʸˡ¤Ï¡¢Ê¸Ì®¤Ë°Í¸¤¹¤ëÀ¸À®µ¬Â§¤È¤·¤ÆÄêµÁ¤µ¤ì¤ë¡£ +%Each production has the form: +³Æ¡¹¤ÎÀ¸À®µ¬Â§¤Ï¼¡¤Î¤è¤¦¤Ê·Á¼°¤ò»ý¤Ä: +\begin{quote} +\tt +\syntax{left context} [ \syntax{firing instructions} ] \syntax{right context} +\\\null\qquad +--> \syntax{left context} \syntax{target category} \syntax{right context} +\end{quote} +%where the left and right contexts are (possibly empty) sequences of +%scrap designators, +¤³¤³¤Ç¡¢ left context ¤È right context ¤Ï(¶õ¤Ç¤âÎɤ¤) +¥¹¥¯¥é¥Ã¥×¥·¡¼¥±¥ó¥¹¤ò¼¨¤·¡¢ +%the firing instructions are a sequence of scrap +%designators and translations (containing at least one scrap +%designator), +firing instructions ¤Ï¡¢ +¥¹¥¯¥é¥Ã¥×̾¾Î¤È(¾¯¤Ê¤¯¤È¤â°ì¤Ä¤Î¥¹¥¯¥é¥Ã¥×¤ò»ØÄꤷ¤Æ¤¤¤ë) +¥È¥é¥ó¥¹¥ì¡¼¥·¥ç¥ó¤Î¥·¡¼¥±¥ó¥¹¤Ç¤¢¤ê¡¢¤½¤·¤Æ +%and the target category is a category designator. +target category ¤Ï¥«¥Æ¥´¥ê¡¼Ì¾¾Î¤Ç¤¢¤ë¡£ +%If the left and right contexts are both empty, the square brackets +%({\tt []}) can be omitted, and the production is context free. +¤â¤·¡¢ left context ¤È right context ¤Î¤¤¤º¤ì¤â¶õ¤Ç¤¢¤ì¤Ð¡¢ +³Ñ³ç¸Ì({\tt []}) ¤Ï¾Êά²Äǽ¤Ç¤¢¤ê¡¢À¸À®µ¬Â§¤Ïʸ̮¤Ë°Í¸¤·¤Ê¤¤¤â¤Î¤È¤Ê¤ë¡£ +%The left and right contexts must be the same on both sides of the {\tt +%-->}. +left context ¤È right context ¤Ï {\tt -->} ¤ÎξÊÕ¤ÇƱ°ì¤Ç¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£ + +%What does the production mean? +À¸À®µ¬Â§¤Î°ÕÌ£¤¹¤ë¤â¤Î¤Ï²¿¤À¤í¤¦¤« ? +%Well, {\tt WEAVE} is trying to reduce a sequence of scraps. +¤½¤¦¡¢{\tt WEAVE} ¤Ï¥¹¥¯¥é¥Ã¥×¤Î¥·¡¼¥±¥ó¥¹¤ò´Ô¸µ¤·¤è¤¦¤È¤¹¤ë¡£ +%So what {\tt WEAVE} does is look at the sequence, to find out whether +%the left hand side of some production matches an initial subsequence +%of the scraps. +¤·¤¿¤¬¤Ã¤Æ¡¢{\tt WEAVE} ¤Ï¥·¡¼¥±¥ó¥¹¤òÄ´¤Ù¡¢¤É¤ÎÀ¸À®µ¬Â§¤Îº¸ÊÕ¤¬ +ºÇ½é¤Ë¥¹¥¯¥é¥Ã¥×¤ÎÉôʬ¥·¡¼¥±¥ó¥¹¤Ë¹çÃפ¹¤ë¤«¤ò¸«¤Ä¤±¤è¤¦¤È¤¹¤ë¡£ +%{\tt WEAVE} picks the first matching production, and {\jem fires} it, +%reducing the scraps described in the firing instructions to a single +%scrap, and it gives the new scrap the {\jem target category}. +{\tt WEAVE} ¤ÏºÇ½é¤Ë¹çÃפ·¤¿À¸À®µ¬Â§¤ò¼è¤ê¾å¤²¡¢¤½¤ì¤ò {\jem ŬÍѤ·}¡¢ +{firing instructions} ¤Ëµ½Ò¤µ¤ì¤Æ¤¤¤¿¥¹¥¯¥é¥Ã¥×¤ò°ì¤Ä¤Î¥¹¥¯¥é¥Ã¥×¤Ë´Ô¸µ¤·¡¢ +¿·¤·¤¤¥¹¥¯¥é¥Ã¥×¤ò{\jem target category} ¤È¤¹¤ë¡£ +%The translation of the new scrap is formed by concatenating the +%translations in the {\jem firing instructions}, where a scrap +%designator stands for the translation of the designated scrap. +¿·¤·¤¤¥¹¥¯¥é¥Ã¥×¤Î¥È¥é¥ó¥¹¥ì¡¼¥·¥ç¥ó¤Ï{\jem fireing instructions} ¤Î +¥È¥é¥ó¥¹¥ì¡¼¥·¥ç¥ó¤È·ë¹ç¤¹¤ë¤³¤È¤Ë¤è¤Ã¤ÆÀ°·Á¤µ¤ì¤ë¡£ +¤³¤³¤Ç¡¢¥¹¥¯¥é¥Ã¥×̾¾Î¤Ï¡¢»ØÄꤵ¤ì¤¿¥¹¥¯¥é¥Ã¥×¤Î +¥È¥é¥ó¥¹¥ì¡¼¥·¥ç¥ó¤Î¤³¤È¤Ç¤¢¤ë¡£ + +%Here is the syntax that describes contexts, firing instructions, scrap +%designators, and so on. +°Ê²¼¤Ï¡¢Ê¸Ì®¡¢Ì¿Îá¤Îµ¯Æ°¡¢¥¹¥¯¥é¥Ã¥×¤Î»ØÄê¤Ê¤É¤òµ½Ò¤·¤¿¤â¤Î¤Ç¤¢¤ë¡£ +\begin{quote} +\tt +\syntax{left context} \produces~\syntax{scrap designators}\\ +\syntax{right context} \produces~\syntax{scrap designators}\\ +\syntax{firing instruction} \produces \syntax{scrap designator}\\ +\syntax{firing instruction} \produces \syntax{translation}\\ +\syntax{scrap designator} \produces~?\\ +\syntax{scrap designator} \produces~\opt{!}\syntax{category name}\opt{*}\\ +\syntax{scrap designator} + \produces~\opt{!}\syntax{category alternatives}\opt{*}\\ +\syntax{category alternatives} + \produces~\rlap{(\syntax{optional alternatives}\syntax{category name})}\\ +\syntax{optional alternative} \produces~\syntax{category name}|\\ +\syntax{target category} \produces~\#\syntax{integer}\\ +\syntax{target category} \produces~\syntax{category name}\\ +\end{quote} + + +%\paragraph{Matching the left hand side of a production} +\paragraph{À¸À®µ¬Â§¤Îº¸ÊդιçÃ×} +%When does a sequence of scraps match the left hand side of a +%production? +À¸À®µ¬Â§¤Îº¸ÊÕ¤¬¥¹¥¯¥é¥Ã¥×¤ÎʤӤȹçÃפ¹¤ë»þ¤È¤Ï¤¤¤Ä¤À¤í¤¦¤« ? +%For matching purposes, we can ignore the translations and the square +%brackets~({\tt []}), and look at the left hand side just as a sequence +%of scrap designators. +¹çÃפµ¤»¤ë¤È¤¤¤¦ÌÜŪ¤«¤é¤¤¤¨¤Ð¡¢¥È¥é¥ó¥¹¥ì¡¼¥·¥ç¥ó¤È³Ñ³ç¸Ì~({\tt []})¤Ï +̵»ë¤·¤Æ¡¢º¸ÊÕ¤ò¤¢¤¿¤«¤â¥¹¥¯¥é¥Ã¥×̾¾Î¤ÎʤӤ«¤é¤À¤±¤Ê¤ë¤â¤Î¤È¤ß¤Ê¤¹ +¤³¤È¤¬¤Ç¤¤ë¡£ +%A sequence of scraps matches a sequence of scrap designators if and +%only if each scrap on the sequence matches the corresponding scrap +%designator. +¤½¤ÎʤӤÎÃæ¤ÎÂбþ¤¹¤ë¤¹¤Ù¤Æ¤Î¥¹¥¯¥é¥Ã¥×¤Î̾¾Î¤¬°ìÃפ·¤¿¤È¤¤Ë¤Î¤ß +¥¹¥¯¥é¥Ã¥×¤ÎʤӤ¬¥¹¥¯¥é¥Ã¥×̾¾Î¤ÎʤӤ˰ìÃפ·¤¿¤È¸«¤Ê¤»¤ë¡£ +%Here are the rules for matching scrap designators (we can +%ignore starring% +¤³¤³¤Ç¡¢¥¹¥¯¥é¥Ã¥×̾¾Î¤Î°ìÃפΤ¿¤á¤Îµ¬Â§¤Ï°Ê²¼¤ÎÄ̤ê(¥¹¥¿¡¼¤Ï̵»ë¤·¤ÆÎɤ¤ +\footnote{¥ª¥×¥·¥ç¥ó¤Î {\tt *}¤òȼ¤¦¥«¥Æ¥´¥ê¡¼Ì¾¤Ï¡¢ +{\jem ¥¹¥¿¡¼ÉÕ¤(starred)}¤È¸Æ¤Ð¤ì¤ë¡£}% +): +\begin{itemize} +\item +%Every scrap matches the designator {\tt ?}. +¤¹¤Ù¤Æ¤Î¥¹¥¯¥é¥Ã¥×¤Ï {\tt ?}¤Ë°ìÃפ¹¤ë¡£ +\item +%A scrap matches \syntax{marked category} if and only if its category +%is the same as the category of the designator. +¤½¤Î¥¹¥¯¥é¥Ã¥×¤Î¥«¥Æ¥´¥ê¡¼¤¬»ØÄꤵ¤ì¤Æ¤¤¤ë¥¹¥¯¥é¥Ã¥×̾¤È°ìÃפ·¤¿¤È¤¤Ë¸Â¤ê¡¢ +¤½¤Î¥¹¥¯¥é¥Ã¥×¤Ï \syntax{marked category} ¤È°ìÃפ¹¤ë¡£ +\item +%A scrap matches {\tt!}\syntax{marked category} if and only if its category +%is {\jem not} the same as the category of the designator. +¥¹¥¯¥é¥Ã¥×¤Î¥«¥Æ¥´¥ê¡¼¤¬»ØÄꤵ¤ì¤Æ¤¤¤ë¥«¥Æ¥´¥ê¡¼Ì¾¤È°ìÃפ·¤Æ{\jem ¤¤¤Ê¤«¤Ã¤¿} +»þ¤Ë¤Î¤ß¡¢¤½¤Î¥¹¥¯¥é¥Ã¥×¤Ï {\tt!}\syntax{marked category} ¤È°ìÃפ¹¤ë +({\tt !} ¤ÏÈÝÄê¤ò°ÕÌ£¤¹¤ë)¡£ +\item +%A scrap matches a list of category alternatives if and only if its +%category is on the list of alternatives. +¥¹¥¯¥é¥Ã¥×¤Î¥«¥Æ¥´¥ê¡¼¤¬ÁªÂò¥ê¥¹¥È¤ÎÃæ¤Ë¤¢¤Ã¤¿¾ì¹ç¤Î¤ß¡¢ +¤½¤Î¥¹¥¯¥é¥Ã¥×¤Ï¥«¥Æ¥´¥ê¡¼¤ÎÁªÂò¥ê¥¹¥È¤Ë°ìÃפ¹¤ë¡£ +\item +%A scrap matches a {\jem negated} list of category alternatives if and +%only if its category is {\jem not} on the list of alternatives. +¥¹¥¯¥é¥Ã¥×¤Î¥«¥Æ¥´¥ê¡¼¤¬ÁªÂò¥ê¥¹¥È¤ÎÃæ¤Ë{\jem ̵¤«¤Ã¤¿}¾ì¹ç¤Ë¤Î¤ß¡¢ +¤½¤Î¥¹¥¯¥é¥Ã¥×¤Ï{\jem ÈÝÄꤵ¤ì¤¿}ÁªÂò¥ê¥¹¥È¤Ë°ìÃפ¹¤ë¡£ +\end{itemize} + + +%\paragraph{Firing a production} +\paragraph{À¸À®µ¬Â§¤ÎŬÍÑ} +%Once a match is found, {\tt WEAVE} fires the production by replacing +%the subsequence of scraps matching the firing instructions. +¤¤¤Ã¤¿¤ó¹çÃפ¹¤ë¤â¤Î¤¬¸«¤Ä¤«¤Ã¤¿¤é¡¢{\tt WEAVE} ¤ÏÀ¸À®µ¬Â§¤òŬÍѤ·¡¢ +ŬÍѤ·¤¿Ì¿Îá¤Ë°ìÃפ·¤¿¥¹¥¯¥é¥Ã¥×¤Î¥µ¥Ö¥·¡¼¥±¥ó¥¹¤òÃÖ¤´¹¤¨¤Æ¤æ¤¯¡£ +%{\tt WEAVE} replaces this subsequence with a new scrap whose category +%is the target category, and whose translation is the concatenation of +%all the translations in the firing instructions. +{\tt WEAVE}¤Ï¤³¤Î¥µ¥Ö¥·¡¼¥±¥ó¥¹¤òÌÜŪ¤Î¥«¥Æ¥´¥ê¡¼¤ò»ý¤Ä¿·¤·¤¤¥¹¥¯¥é¥Ã¥×¤Ç +ÃÖ¤´¹¤¨¡¢¤½¤Î¥È¥é¥ó¥¹¥ì¡¼¥·¥ç¥ó¤ÏŬÍѤµ¤ì¤¿µ¬Â§¤ÎÃæ¤Î +¤¹¤Ù¤Æ¤Î¥È¥é¥ó¥¹¥ì¡¼¥·¥ç¥ó¤ò¹ç¤ï¤»¤¿¤â¤Î¤È¤¹¤ë +%(When the new translation is constructed, the +%translations of the old scraps are included at the positions of the +%corresponding scrap designators.) +(¿·¤·¤¤¥È¥é¥ó¥¹¥ì¡¼¥·¥ç¥ó¤¬ºîÀ®¤µ¤ì¤ë¤È¤¤Ï¡¢ +¸Å¤¤¥¹¥¯¥é¥Ã¥×¤Î¥È¥é¥ó¥¹¥ì¡¼¥·¥ç¥ó¤Ï¥¹¥¯¥é¥Ã¥×¤ÎÂбþ¤¹¤ë¾ì½ê¤Ë¼è¤ê¹þ¤Þ¤ì¤ë +)¡£ +%If the target category is not given by name, but rather by +%number~({\tt \#$n$}), {\tt WEAVE} will take the category of the $n$th +%scrap in the subsequence that matches the left hand side of the +%production, and make that the target category. +¤â¤·ÌÜŪ¤Î¥«¥Æ¥´¥ê¡¼¤¬Ì¾Á°¤Ç¤Ï¤Ê¤¯ {\tt \#$n$}¤È¤¤¤¦ÈÖ¹æ¤Ç»ØÄꤵ¤ì¤Æ¤¤¤¿¤é¡¢ +{\tt WEAVE} ¤ÏÀ¸À®µ¬Â§¤Îº¸ÊÕ¤ÎÂбþ¤¹¤ë $n$ÈÖÌܤΥ«¥Æ¥´¥ê¡¼¤ò¼è¤ê¾å¤²¡¢ +¤½¤ì¤òÌÜŪ¤Î¥«¥Æ¥´¥ê¡¼¤È¤ß¤Ê¤¹¡£ + +\subparagraph{À¸À®µ¬Â§Å¬ÍѤÎÉûºîÍÑ} +À¸À®µ¬Â§¤¬Å¬ÍѤµ¤ì¤ë¤È¡¢ {\tt WEAVE} ¤Ï +%for the first identifier in any {\jem starred} scrap. +¥¹¥¿¡¼¥É¡¦¥¹¥¯¥é¥Ã¥×¤ÎºÇ½é¤Î¼±Ê̻Ҥò \hbox{\jem ²¼ÀþÉդθ«½Ð¤·¸ì}¤È¤¹¤ë¡£ + + +%\paragraph{If no initial subsequence matches any production} +\paragraph{ºÇ½é¤Î¥µ¥Ö¥·¡¼¥±¥ó¥¹¤¬À¸À®µ¬Â§¤Ë¹çÃפ·¤Ê¤«¤Ã¤¿¾ì¹ç} +%If the initial subsequence of scraps does not match the left hand side +%of any production, {\tt WEAVE} will try to match the subsequence +%beginning with the second scrap, and so on, until a match is found. +%Once a match is found, {\tt WEAVE} fires the production, changing its +%sequence of scraps. +%It then starts all over again at the beginning of the new sequence, +%looking for a match.% +½é´ü¥µ¥Ö¥·¡¼¥±¥ó¥¹¤¬º¸ÊÕ¤ÎÀ¸À®µ¬Â§¤È¹çÃפ·¤Ê¤±¤ì¤Ð¡¢ +{\tt WEAVE}¤Ï¼¡¤Î¥µ¥Ö¥·¡¼¥±¥ó¥¹°Ê¹ß¤Ç¹çÃפ¹¤ë¤â¤Î¤ò¸«¤Ä¤±¤è¤¦¤È¤¹¤ë¡£ +¹çÃפ¹¤ë¤â¤Î¤¬¸«¤Ä¤«¤ì¤Ð¡¢ {\tt WEAVE}¤ÏÀ¸À®µ¬Â§¤òŬÍѤ·¡¢ +³Æ¥¹¥¯¥é¥Ã¥×¤ÎʤӤòÊѹ¹¤¹¤ë¡£ +¤½¤·¤Æ¡¢¿·¤·¤¤¥·¡¼¥±¥ó¥¹¤ËÂФ·¤ÆºÇ½é¤«¤é¤â¤¦°ìÅÙ¤ä¤êľ¤¹% +\footnote{ +%The implementation is better than that; {Spider} figures out just +%how much {\tt WEAVE} must backtrack to get the same effect as +%returning to the beginning.% +¤³¤Î¼Â¸½ÊýË¡¤Ï¡¢ +¡ÖºÇ½é¤ËÌá¤ë¤ÈƱ¤¸¸ú²Ì¤òÆÀ¤ë¤¿¤á¤Ë¤Ï +{\tt WEAVE}¤¬²¿²ó¥Ð¥Ã¥¯¥È¥é¥Ã¥¯¤ò¤·¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¤«¤ò +{Spider}¤¬ »»½Ð¤¹¤ë¡× +¤È¤¤¤¦¤â¤Î¤è¤ê¤âÎɤ¤¡£ +}¡£ +%If {\jem no} subsequence of the scraps matches any production, then the +%sequence of scraps is irreducible, and {\tt WEAVE} writes out the +%translations of the scraps, one at a time. +¤¹¤Ù¤Æ¤Î¥µ¥Ö¥·¡¼¥±¥ó¥¹¤¬¤¤¤º¤ì¤ÎÀ¸À®µ¬Â§¤È¤â¹çÃפ·¤Ê¤«¤Ã¤¿¤Ê¤é¤Ð¡¢ +¥¹¥¯¥é¥Ã¥×¤Î¥·¡¼¥±¥ó¥¹¤Ï¸µ¤ËÌᤵ¤ì¤ë¤³¤È¤Ê¤¯ {\tt WEAVE} ¤Ï +°ì¤Ä¤º¤Ä¥¹¥¯¥é¥Ã¥×¤ÎËÝÌõ¤ò½ñ¤½Ð¤¹¡£ + + + + + +\section{{\tt WEAVE} ʸˡ¤ÎÎã} +%This all must seem very intimidating, but it's not really. +%In this section we present some grammar fragments and explain what's +%going on. +¤³¤³¤Þ¤Ç¤Î¤¹¤Ù¤Æ¤Î¤³¤È¤Ï¶¼¤·¤Î¤è¤¦¤Ë´¶¤¸¤¿¤«¤âÃΤì¤Ê¤¤¤¬¡¢Á´¤¯¤½¤ó¤Ê¤³¤È¤Ï¤Ê¤¤¡£ +¤³¤Î¾Ï¤Ç¤Ï¤¤¤¯¤Ä¤«¤Îʸˡ¤ò¼¨¤·¡¢²¿¤¬¤Ê¤µ¤ì¤ë¤«¤ò²òÀ⤹¤ë¡£ + +\paragraph{´Êñ¤ÊÎã} +\begin{verbatim} +? ignore_scrap --> #1 +\end{verbatim} +%This production should appear in every grammar, because Spidery {\tt +%WEAVE} expects category \verb+ignore_scrap+ to exist with roughly this +%semantics. +¤³¤ÎÀ¸À®µ¬Â§¤Ï¤¹¤Ù¤Æ¤Îʸˡ¤Ë¸ºß¤·¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£ +¤Ê¤¼¤Ê¤é¡¢Spidery {\tt WEAVE} ¤Ï +\verb+ignore_scrap+ ¤È¤¤¤¦¥«¥Æ¥´¥ê¡¼¤¬Íð˽¤Ë¤â¤³¤Î°ÕÌ£¤Ç¸ºß¤·¤Æ¤¤¤ë¤È +¤ß¤Ê¤·¤Æ¤¤¤ë¤¿¤á¤Ç¤¢¤ë +(Î㤨¤Ð¡¢¥³¥á¥ó¥È¤ÏÁ´¤Æ {\tt ignore\_scrap} ¤È¤¤¤¦¥«¥Æ¥´¥ê¡¼¤Î +¥¹¥¯¥é¥Ã¥×¤òÀ¸À®¤¹¤ë) ¡£ +%Any scrap of category \verb+ignore_scrap+ essentially doesn't affect +%the reduction of scraps: it is absorbed into the scrap to its left. +\verb+ignore_scrap+ ¤È¤¤¤¦¥«¥Æ¥´¥ê¡¼¤Î¤¤¤«¤Ê¤ë¥¹¥¯¥é¥Ã¥×¤â +´ðËÜŪ¤Ë¤Ï¥¹¥¯¥é¥Ã¥×¤Î´Ô¸µ¤Î±Æ¶Á¤ò¼õ¤±¤Ê¤¤: +¤½¤Î¤Þ¤Þ¥¹¥¯¥é¥Ã¥×¤ÎÃæ¤ËÃÖ¤«¤ì¤¿¤Þ¤Þ¤Ë¤Ê¤ë¡£ + +\begin{verbatim} +token newline category newline translation <> +newline --> ignore_scrap +\end{verbatim} +%This token definition and production, combined with the previous +%production, causes {\tt WEAVE} to ignore all newlines. +¤³¤ÎÄêµÁ¤ÈÀ¸À®µ¬Â§¤Ï¡¢Á°½Ò¤ÎÀ¸À®µ¬Â§¤ÈÁȤ߹ç¤ï¤µ¤ì¤Æ +¤¹¤Ù¤Æ¤Î newline ¤ò{\tt WEAVE}¤Ë̵»ë¤µ¤»¤ë¤³¤È¤Ë¤Ê¤ë¡£ + +%For this next example, from the C~grammar, you will need to know that +%{\tt math} represents a mathematical expression, {\tt semi} a +%semicolon, and {\tt stmt} a statement or sequence of statements. +¼¡¤Î C¤Îʸˡ¤ÎÎã¤Ç¤Ï¡¢{\tt math} ¤Ï»»½Ñ¼°¡¢ +{\tt semi}¤Ï¥»¥ß¥³¥í¥ó¡¢{\tt stmt}¤Ïʸ¤Þ¤¿¤Ïʸ¤ÎʤӤò°ÕÌ£¤·¤Æ¤¤¤ë¤³¤È¤ò +ÃǤäƤª¤³¤¦¡£ +\begin{verbatim} +math semi --> stmt +stmt <force> stmt --> stmt +\end{verbatim} +%The first production says that a mathematical expression, followed by +%a semicolon, should be treated as a statement. +Âè°ì¤ÎÀ¸À®µ¬Â§¤Ï¥»¥ß¥³¥í¥ó¤òȼ¤¦»»½Ñ¼°¤Ïʸ¤È¤·¤Æ°·¤ï¤ì¤ë¤³¤È¤ò»Ø¼¨¤¹¤ë¡£ +%The second says that two statements can be combined to make a single +%statement by putting a line break between them. +ÂèÆó¤ÎÀ¸À®µ¬Â§¤Ç¤Ï¡¢ 2 ¤Ä¤Îʸ¤Ï 1 ¤Ä¤Îʸ¤È¤·¤Æ·ë¹ç¤µ¤ì¡¢ +´Ö¤Ë²þ¹Ô¤¬ÃÖ¤«¤ì¤ë¤³¤È¤ò»Ø¼¨¤¹¤ë¡£ + +\paragraph{¼°} +%This more extended example shows the treatment of expressions in Awk. +¤³¤Î³ÈÄ¥¤µ¤ì¤¿Îã¤Ï¡¢ Awk ¤Î¼°¤Î°·¤¤¤ò¼¨¤·¤Æ¤¤¤ë¡£ +%This is identical to the treatment of expressions in C and in several +%other languages. +¤³¤ì¤Ï¡¢C ¤ä¤¤¤¯¤Ä¤«¤Î¸À¸ì¤Ë¤ª¤±¤ë¼°¤Î°·¤¤¤ÈƱ°ì¤Ç¤¢¤ë¡£ +%We will use the following categories: +°Ê²¼¤Î¤è¤¦¤Ê¥«¥Æ¥´¥ê¡¼¤ò»È¤¦¤³¤È¤Ë¤¹¤ë: +\begin{description} +\item[math] »»½Ñ¼° %A mathematical expression +\item[binop] Æó¹àÃæÃֱ黻»Ò %A binary infix operator +\item[unop] ñ¹àÁ°Ãֱ黻»Ò¤Þ¤¿¤Ïñ¹à¸åÃֱ黻»Ò + %A unary prefix or postfix operator +\item[unorbinop] Æó¹àÃæÃÖ¤«Ã±¹àÁ°Ã֤ˤʤꤦ¤ë±é»»»Ò + %An operator that could be binary infix or unary prefix +\end{description} +%To show you how these might be used, here are some sample token +%definitions using these categories: +¤É¤¦¤ä¤Ã¤Æ»È¤ï¤ì¤ë¤«¤ò¼¨¤¹¤¿¤á¤Ë¡¢¤³¤ì¤é¤Î¥«¥Æ¥´¥ê¡¼¤òÍѤ¤¤¿ +¥È¡¼¥¯¥ó¤ÎÄêµÁÎã¤ò¼¨¤¹¡£ +\begin{verbatim} +token + category unorbinop +token - category unorbinop +token * category binop +token / category binop +token < category binop +token > category binop +token , category binop translation <",\\,"-opt-3> +token = category binop translation <"\\K"> +token != translation <"\\I"> category binop +token == name eq_eq translation <"\\S"> category binop +token ++ name gt_gt category unop translation <"\\uparrow"> +token -- name lt_lt category unop translation <"\\downarrow"> +\end{verbatim} +%Notice that the translation for the comma specifies a thin space and +%an optional line break after the comma. +¤³¤³¤Ç¤Ï¥«¥ó¥Þ¤Ï¾®¤µ¤Ê¥¹¥Ú¡¼¥¹¤Î¸å optional line break +¤òÃÖ¤¯¤³¤È¤ËÃí°Õ¤·¤ÆÍߤ·¤¤¡£ +{\tt =}¡¢ {\tt !=}¡¢ {\tt ==} ¤ÎËÝÌõ¤Ï¤½¤ì¤¾¤ì +\ $\leftarrow$¡¢ $\ne$¡¢ $\equiv$ ¤È¤Ê¤ë¡£ + + +%Here is the grammar for expressions. +°Ê²¼¤Ï¡¢¼°¤Î¤¿¤á¤Îʸˡ¤Ç¤¢¤ë¡£ +\begin{verbatim} +math (binop|unorbinop) math --> math +(unop|unorbinop) math --> math +math unop --> math +math <"\\"-space> math --> math +\end{verbatim} +%In Awk there is no concatenation operator; concatenation is by +%juxtaposition. +Awk ¤Ç¤Ï¡¢Ê¸»úÎó¤Î·ë¹ç»Ò¤¬¤Ê¤¤; ·ë¹ç¤Ïʤ٤ÆÃÖ¤¯¤³¤È¤Çɽµ¤µ¤ì¤ë¡£ +%The last production tells {\tt WEAVE} to insert a space between two +%juxtaposed expressions. +ºÇ¸å¤ÎÀ¸À®µ¬Â§¤Ï {\tt WEAVE} ¤ËÊÂÃÖ¤µ¤ì¤¿¼°¤Î´Ö¤Ë +¥¹¥Ú¡¼¥¹¤òÁÞÆþ¤µ¤»¤ë¤¿¤á¤Î¤â¤Î¤Ç¤¢¤ë¡£ + +%So far we haven't dealt with parentheses, but that's easily done: +º£¤Þ¤Ç¤Ï³ç¸Ì¤ò½èÍý¤·¤Æ¤¤¤Ê¤«¤Ã¤¿¤¬¡¢°Ê²¼¤Î¤è¤¦¤ËÍưפ˵½Ò¤Ç¤¤ë: +\begin{verbatim} +token ( category open +token ) category close +token [ category open +token ] category close +open math close --> math +\end{verbatim} + + +%Now this grammar just given doesn't handle the Awk or C {\tt +=} +%feature very well; {\tt x+=1} comes out as~$x+\leftarrow 1$, and {\tt +%x/=2} is irreducible! +¤µ¤Æ¡¢¤³¤Îʸˡ¤Î¤Þ¤Þ¤Ç¤Ï Awk ¤ä C ¤Î {\tt +=} ¤È¤¤¤¦µ¡Ç½¤ò +¤¦¤Þ¤¯°·¤¦¤³¤È¤¬¤Ç¤¤Ê¤¤; +{\tt x+=1} ¤Ï $x+\leftarrow 1$ ¤Î¤è¤¦¤Ë¤Ê¤ê¡¢{\tt x/=2} ¤Ï +´Ô¸µ¤¹¤ë¤³¤È¤¬¤Ç¤¤Ê¤¤¡£ +%Here's the cure; first, we make a new category for assignment: +°Ê²¼¤Ë½¤Àµ¤Î»ÅÊý¤ò½Ò¤Ù¤ë; +¤Þ¤ººÇ½é¤Ë¡¢ÂåÆþ¤Î¤¿¤á¿·¤·¤¤¥«¥Æ¥´¥ê¡¼¤òºî¤ë¤³¤È¤Ë¤¹¤ë¡£ +\begin{verbatim} +token = category equals translation <"\\K"> +\end{verbatim} +%And then we write productions that reduces assignment (possibly +%preceded by another operator) to a binary operator: +¼¡¤Ë¡¢(¾¤Î±é»»»Ò¤¬Àè¹Ô¤·¤Æ¤â¤«¤Þ¤ï¤Ê¤¤)ÂåÆþ¤òÆó¹à±é»»»Ò¤Ë´Ô¸µ¤¹¤ë¤¿¤á¤Î +À¸À®µ¬Â§¤ò½ñ¤³¤¦¡£ +\begin{verbatim} +<"\\buildrel"> (binop|unorbinop) <"\\over{"> equals <"}"> --> binop +equals --> binop +\end{verbatim} +%Notice that, given the rules stated above, the second production can +%fire only if {\tt equals} is {\jem not} preceded by an operator. +¾åµ¤Îµ¬Â§¤ÇÃí°Õ¤¹¤Ù¤¤³¤È¤Ï¡¢ÂèÆó¤ÎÀ¸À®µ¬Â§¤Ï +{\tt equals}¤¬±é»»»Ò¤òÁ°¤Ë{\jem ȼ¤ï¤Ê¤¤}»þ¤Ë¤Î¤ßŬÍѲÄǽ¤À¤È¤¤¤¦¤³¤È¤Ç¤¢¤ë¡£ +%On input~{\tt x+=1}, the first production fires, and we have the +%translation~$x\buildrel+\over{\leftarrow} 1$. +{\tt x+=1}¤È¤¤¤¦ÆþÎϤËÂФ·¤Æ¡¢Âè°ì¤ÎÀ¸À®µ¬Â§¤¬ºÇ½é¤ËŬÍѤµ¤ì¡¢ +$x\buildrel+\over{\leftarrow} 1$ ¤È¤¤¤¦ËÝÌõ¤òÆÀ¤ë¤³¤È¤Ë¤Ê¤ë¡£ + +\paragraph{¾ò·ïʸ} +%Here is the grammar for (possibly nested) conditional statements in +%Awk. +°Ê²¼¤Ï¡¢Awk ¤Ë¤ª¤±¤ë(¥Í¥¹¥È²Äǽ¤Ê)¾ò·ïʸ¤Îʸˡ¤Ç¤¢¤ë¡£ +\begin{verbatim} +if <"\\"-space> math --> ifmath +ifmath lbrace --> ifbrace +ifmath newline --> ifline +ifbrace <force> stmt --> ifbrace +ifbrace <outdent-force> close else <"\\"-space> if --> if +ifbrace <outdent-force> close else lbrace --> ifbrace +ifbrace <outdent-force> close else newline --> ifline +ifbrace <outdent-force> close --> stmt +(ifline|ifmath) <indent-force> stmt <outdent> --> stmt +\end{verbatim} +%It relies on the following token definitions: +°Ê²¼¤Î¥È¡¼¥¯¥ó¤ÎÄêµÁ¤Ë°Í¸¤¹¤ë: +\begin{verbatim} +ilk if_like category if +reserved if +ilk else_like category else +reserved else +token { translation <"\\;\\{"-indent> category lbrace +token } translation <"\\}\\"-space> category close +token newline category newline translation <> +\end{verbatim} + +\paragraph{C ¤Î¥×¥ê¥×¥í¥»¥Ã¥µÍÑÌ¿Îá¤Î°·¤¤} +¤³¤³¤Ç¤ÏC¥×¥ê¥×¥í¥»¥Ã¥µÍÑÌ¿Îá¤ò°·¤¦¤¿¤á¤Îʸˡ¤Î +´Êñ¤Ê¥Ð¡¼¥¸¥ç¥ó¤ò¼¨¤¹¡£ +¥×¥ê¥×¥í¥»¥Ã¥µÌ¿Îá¤Ï¹Ô¤Îº¸Ã¼¤Ë¤ª¤«¤ì¡¢¥Ð¥Ã¥¯¥¹¥é¥Ã¥·¥å¤Ç¥¨¥¹¥±¡¼¥×¤µ¤ì¤¿ +²þ¹Ô¤âÀµ¤·¤¯°·¤ï¤ì¤ë¡£ +(ºÇ½ª¥Ð¡¼¥¸¥ç¥ó¤Ï¥Õ¥¡¥¤¥ë̾¤ò {\tt <...>}¤È¤¤¤¦ +``¤è¤ê¾®¤µ¤¤'' ¤È ``¤è¤êÂ礤¤'' ¤ò°ÕÌ£¤¹¤ëƱ°ì¤Îµ¹æ¤Ç³ç¤Ã¤¿É½µ¤â +²Äǽ¤Ç¤¢¤ë¡£) + +{\small\advance\hsize 1in +\begin{verbatim} +# control sequence \8 puts things on the left margin +<"\\8"> sharp <"{\\let\\\\=\\bf"-space> math <"}"-indent-"{}"-space> --> preproc +preproc backslash <force-"\\8\\hskip1em"-space> newline --> preproc +<force> preproc <force-outdent> newline --> ignore_scrap +preproc math --> preproc +newline --> ignore_scrap +\end{verbatim} +} +ºÇ½é¤ÎÀ¸À®µ¬Â§¤Ë¤¢¤ë \verb+\let+ ¤Ë¤è¤Ã¤Æ¡¢ +{\tt \#} ¤Ë³¤¯¼±Ê̻Ҥò¥Ü¡¼¥ë¥ÉÂΤËÊѹ¹¤¹¤ë¡£ + + +%\subsection{Using context-dependent productions} +\subsection{ʸ̮°Í¸À¸À®µ¬Â§¤Î»ÈÍÑ} +%So far we've been able to do a lot without using the +%context-dependent features of {Spider} productions. +%(For example, the entire {\tt spider} file for Awk is written using +%only context-free productions.) +%Now we'll show some examples that use the context-dependence. +º£¤Þ¤Ç¤Î¤Ï¡¢Â¿¤¯¤Î¤³¤È¤òʸ̮¤Ë°Í¸¤·¤Ê¤¤ÊýË¡¤Ç¤ä¤Ã¤Æ¤³¤ì¤¿ +(Î㤨¤Ð¡¢Awk ÍѤΠ{\tt spider}¥Õ¥¡¥¤¥ë¤Ïʸ̮¼«Í³µ¬Â§¤Î¤ß¤Ç½ñ¤«¤ì¤Æ¤¤¤ë)¡£ +º£¤«¤é¡¢Ê¸Ì®°Í¸ʸˡ¤ò»È¤Ã¤¿Îã¤ò¼¨¤¹¤³¤È¤Ë¤¹¤ë¡£ + +%In the grammar for Ada, a semicolon is used as a terminator for +%statements. +%But semicolons are also used as {\jem separators} in parameter +%declarations. +%The first two productions here find the statements, but the third +%production supersedes them when a semicolon is seen in a parenthesized +%list. +Ada ¤Îʸˡ¤Ç¤Ï¡¢¥»¥ß¥³¥í¥ó¤Ïʸ¤Î½ªÃ¼µ¹æ¤Ç¤¢¤ë¡£ +¤·¤«¤·¡¢¥Ñ¥é¥á¡¼¥¿Àë¸À¤Ç¤Ï {\jem ¥»¥Ñ¥ì¡¼¥¿} ¤È¤·¤Æ¤â»È¤ï¤ì¤ë¡£ +°Ê²¼¤ÎºÇ½é¤Î 2 ¤Ä¤Îµ¬Â§¤Ïʸ¤ò¸«¤Ä¤±¤ë¤¿¤á¤Ë¤¢¤ë¡£ +¤·¤«¤·3ÈÖÌܤϡ¢³ç¸Ì¤Ç³ç¤é¤ì¤¿¥ê¥¹¥È¤ÎÃæ¤Ë¤¢¤ë¥»¥ß¥³¥í¥ó¤Î°·¤¤¤òÊѤ¨¤ë¡£ +\begin{verbatim} +semi --> terminator +math terminator --> stmt +open [ math semi ] --> open math +\end{verbatim} + + +%\paragraph{Underlining the index entry for the name of a declared +%function} +\paragraph{Àë¸À¤µ¤ì¤¿´Ø¿ô̾¤Î²¼ÀþÉÕ¤±¤µ¤ì¤¿º÷°úÅÐÏ¿} +%In SSL, function declarations begin with the type of the function +%being declared, followed by the name of that function. +SSL ¤Ç¤Ï¡¢´Ø¿ô¤ÎÀë¸À¤Ï´Ø¿ô̾¤ÎÁ°¤Ë´Ø¿ô¤Î·¿¤òÀë¸À¤¹¤ë¡£ +%The following production causes the index entry for that function to +%be underlined, so that we can look up the function name in the index +%and easily find the section in which the function is declared: +°Ê²¼¤ÎÀ¸À®µ¬Â§¤Ï¡¢´Ø¿ô¤ò²¼ÀþÉÕ¤¤Çº÷°ú¤ËÅÐÏ¿¤¹¤ë¡£¤·¤¿¤¬¤Ã¤Æ¡¢ +º÷°ú¤ÎÃæ¤Ç´Ø¿ô̾¤òÄ´¤Ù¤ë¤³¤È¤¬¤Ç¤¡¢Àë¸À¤µ¤ì¤Æ¤¤¤ë¥»¥¯¥·¥ç¥ó¤ò +¸«¤Ä¤±¤ë¤³¤È¤¬²Äǽ¤Ç¤¢¤ë¡£ +\begin{verbatim} +decl simp [ simp* ] --> decl simp math +\end{verbatim} +%Where we've relied on +¤³¤³¤Ç¤Ï¡¢°Ê²¼¤ÎÄêµÁ¤Ë°Í¸¤·¤Æ¤¤¤ë¡£ +\begin{verbatim} +token identifier category simp mathness yes +\end{verbatim} + + +\paragraph{¾ò·ï¼°} +%Suppose we want to format conditional expressions (for example in C) +%like this: +(Î㤨¤Ð C ¤Ë¤ª¤¤¤Æ)¼¡¤Î¤è¤¦¤Ë¾ò·ï¼°¤òÀ°·Á¤¹¤ë¤³¤È¤ò¹Í¤¨¤è¤¦¡£ +\begin{quote} +\syntax{condition}\\ +\mbox{\qquad}$?$ \syntax{expression}\\ +\mbox{\qquad}$:$ \syntax{expression} +\end{quote} +%The problem is that it's hard to know when the conditional expression +%ends. +¤³¤³¤Ç¤ÎÌäÂê¤Ï¡¢¤¤¤Ä¾ò·ï¼°¤¬½ª¤ë¤«¤òȽÃǤ¹¤ë¤Î¤¬Æñ¤·¤¤¤³¤È¤Ç¤¢¤ë¡£ +%It's essentially a question of precedence, +¤³¤ì¤Ï¡¢´ðËÜŪ¤ËÀèÆɤßÌäÂê¤Ç¤¢¤ê¡¢ +%and what we're going to do +%is look ahead until we see an operator with sufficiently low +%precedence that it terminates a conditional expression. +¤ä¤ë¤Ù¤¤³¤È¤Ï¡¢¾ò·ï¼°¤ò½ªÃ¼¤µ¤»¤ë¤Ë½½Ê¬¤ÊÄøÅÙ¤Ë +±é»»»Ò¤òÀèÆɤߤ¹¤ë¤³¤È¤Ç¤¢¤ë¡£ +%In SSL a conditional expression can be terminated by a semicolon, a +%right parenthesis, a comma, or a colon. +SSL ¤Ç¤Ï¡¢¾ò·ï¼°¤Ï¥»¥ß¥³¥í¥ó¡¢±¦³ç¸Ì¡¢¥«¥ó¥Þ¡¢¥³¥í¥ó¤Ç½ªÃ¼¤·ÆÀ¤ë¡£ +%We'll use the {\jem right context} to do the lookahead. +ÀèÆɤߤò¤¹¤ë¤¿¤á¤Ë¡¢{\jem right context} ¤ò»È¤¦¤³¤È¤Ë¤·¤è¤¦¡£ +{\small +\begin{verbatim} +token ? translation <"\\?"> category question +token : category colon + +<indent-force> question math <force> colon --> condbegin +[ condbegin math <outdent> ] (semi|close|comma|colon) --> math (semi|close|comma|colon) +\end{verbatim} +} + + + + +\subsection{À°·Á°õºþʸˡ¤Î¥Ç¥Ð¥Ã¥°} +{\tt WEAVE} ¤ÏÀ°·Á°õºþʸˡ¤Î¥Ç¥Ð¥Ã¥°¤ËÌòΩ¤Ä 2 ¤Ä¤Î¥â¡¼¥É¤ò»ý¤Ä¡£ +{\tt @1} ¤È¤¤¤¦À©¸æ¥·¡¼¥±¥ó¥¹¤ÏÉôʬ¥È¥ì¡¼¥¹¤ò³«»Ï¤·¡¢ +{\tt @2} ¤Ï¥Õ¥ë¥È¥ì¡¼¥¹¤ò³«»Ï¤¹¤ë¡£ +{\tt @0} ¤Ï¥È¥ì¡¼¥¹¤ò¥ª¥Õ¤Ë¤¹¤ë¡£%turns tracing back off again. +%In the partial tracing mode, {\tt WEAVE} applies all the productions +%as many times as possible, +Éôʬ¥È¥ì¡¼¥¹¥â¡¼¥É¤Ç¤Ï¡¢{\tt WEAVE} ¤Ï²Äǽ¤Ê¸Â¤ê¤¹¤Ù¤Æ¤ÎÀ¸À®µ¬Â§¤ò +ŬÍѤ·¡¢·ë²Ì¤È¤·¤Æ´Ô¸µ¤Ç¤¤Ê¤«¤Ã¤¿»Ä¤ê¤Î¥¹¥¯¥é¥Ã¥×¤ò¥×¥ê¥ó¥È¥¢¥¦¥È¤¹¤ë¡£ +%and then it prints out the irreducible +%scraps that remain. +%If the scraps reduce to a single scrap, no diagnostics are printed. +¥¹¥¯¥é¥Ã¥×¤¬¤¹¤Ù¤Æ°ì¤Ä¤Î¥¹¥¯¥é¥Ã¥×¤Ë´Ô¸µ¤Ç¤¤¿¾ì¹ç¤Ï¡¢ +¿ÇÃÇ¥á¥Ã¥»¡¼¥¸¤Ï¥×¥ê¥ó¥È¤µ¤ì¤Ê¤¤¡£ + +%When a scrap is printed, {\tt WEAVE} prints a leading +%{\tt+}~or~{\tt-}, the name of the category of that scrap, and a +%trailing {\tt+}~or~{\tt-}. +¥¹¥¯¥é¥Ã¥×¤¬¥×¥ê¥ó¥È¤µ¤ì¤ë¤È¤¡¢{\tt WEAVE} ¤Ï¡¢{\tt+}~¤«~{\tt-}¤Î¥ê¡¼¥À¡¼¡¢ +¤½¤Î¥¹¥¯¥é¥Ã¥×¤Î¥«¥Æ¥´¥ê¡¼Ì¾¡¢{\tt+}~¤«~{\tt-}¤Î¥È¥ì¡¼¥é¡¼¤ò¥×¥ê¥ó¥È¤¹¤ë¡£ +%The {\tt+} indicates that {\TeX} should be in math mode, and the +%{\tt-} that {\TeX} should not be in math mode, at the beginning and +%end of the scrap's translation, respectively. +¤½¤ì¤¾¤ì¤Î¥¹¥¯¥é¥Ã¥×¤Î¥È¥é¥ó¥¹¥ì¡¼¥·¥ç¥ó¤Î»Ï¤á¤È½ª¤ï¤ê¤Ç¡¢ +{\tt+} ¤Ï {\TeX} ¤¬¿ô¼°¥â¡¼¥É¤ËÆþ¤Ã¤¿¤³¤È¤ò¼¨¤·¡¢ +{\tt-} ¤Ï {\TeX} ¤¬¿ô¼°¥â¡¼¥É¤Ç¤Ê¤¯¤Ê¤Ã¤¿¤³¤È¤ò¼¨¤¹ +%(You can see the translations by looking at the {\tt.tex} file, since +%that's where they're written out.) +(¥È¥é¥ó¥¹¥ì¡¼¥·¥ç¥ó¤Ï{\tt.tex}¥Õ¥¡¥¤¥ë¤ò¸«¤ì¤Ð²ò¤ë)¡£ + +%For beginners, the full trace is more helpful. +½é¿´¼Ô¤Ë¤È¤Ã¤Æ¤Ï¡¢¥Õ¥ë¥È¥ì¡¼¥¹¤ÎÊý¤¬Ìò¤ËΩ¤Ä¡£ +%It prints out the following information every time a production is +%fired: +¥Õ¥ë¥È¥ì¡¼¥¹¥â¡¼¥É¤Ç¤Ï¡¢À¸À®µ¬Â§¤¬Å¬ÍѤµ¤ì¤ëÅ٤˰ʲ¼¤Î¾ðÊó¤ò¥×¥ê¥ó¥È¤¹¤ë: +\begin{itemize} +\item +%The number of the production just fired (from {\tt productions.list}); +ŬÍѤ·¤¿À¸À®µ¬Â§¤Î({\tt productions.list}¤Ë½ñ¤½Ð¤µ¤ì¤¿)ÈÖ¹æ; +\item +%The sequence of scraps {\tt WEAVE} is now trying to reduce; +{\tt WEAVE}¤¬¸½ºß´Ô¸µ¤·¤è¤¦¤È¤·¤Æ¤¤¤ë¥¹¥¯¥é¥Ã¥×¤ÎʤÓ; +\item +%A {\tt*} indicating what subsequence {\tt WEAVE} will try to reduce next. +{\tt*} ¤Ç¼¨¤µ¤ì¤ë {\tt WEAVE} ¤¬¼¡¤Ë´Ô¸µ¤·¤è¤¦¤È¤·¤Æ¤¤¤ë¥µ¥Ö¥·¡¼¥±¥ó¥¹¡£ +\end{itemize} +%A good way to understand how À°·Á°õºþʸˡ work is to take +%a {\tt productions.list} file, and look at a full trace of the +%corresponding {\tt WEAVE}. +À°·Á°õºþʸˡ ¤ÎƯ¤¤òÃΤëÎɤ¤ÊýË¡¤Ï¡¢ +{\tt productions.list} ¥Õ¥¡¥¤¥ë¤ò¼ê¤Ë¤È¤Ã¤Æ¡¢ +{\tt WEAVE} ¤¬¥×¥ê¥ó¤È¤·¤¿¥Õ¥ë¥È¥ì¡¼¥¹¤È +Æͤ¹ç¤ï¤»¤ë¤³¤È¤Ç¤¢¤ë¡£ +%Or, if you prefer, you can simulate by hand the action of {\tt WEAVE} +%on a sequence of scraps. +¤â¤·¤¯¤Ï¡¢¤ªË¾¤ß¤Ê¤é¤Ð¡¢{\tt WEAVE} ¤¬¥¹¥¯¥é¥Ã¥×¤ÎʤӤËÂФ·¤Æ¹Ô¤¦Æ°ºî¤ò¼ê¤Ç +¥·¥ß¥å¥ì¡¼¥È¤·¤Æ¤â¤¤¤¤¤À¤í¤¦¡£ + + +\section{{Spider} ¸À¸ì¤Î»Ä¤ê} +%The tokens and the grammar are not quite the whole story. +%Here's the rest of the truth about what you can do with {Spider}. +¥È¡¼¥¯¥ó¤Èʸˡ¤ÇÏä·¤¬¤¹¤Ù¤Æ½ª¤Ã¤¿¤ï¤±¤Ç¤Ï¤Ê¤¤¡£ +¤³¤Î¾Ï¤Ç¤Ï¡¢ {Spider} ¤Ç¤Ç¤¤ë¤³¤È¤Î̤ÀâÌÀ¤ÎÉôʬ¤ò½Ò¤Ù¤ë¡£ + +\subsection{¥¿¡¼¥²¥Ã¥È¸À¸ì¤Î̿̾} +%When a Spidery {\tt WEAVE} or {\tt TANGLE} starts up, it prints the +%target language for which it was generated, and the date and time of +%the generation. +Spidery {\tt WEAVE} ¤Þ¤¿¤Ï Spidery {\tt TANGLE} ¤¬µ¯Æ°¤µ¤ì¤¿»þ¡¢ +¥¿¡¼¥²¥Ã¥È¸À¸ì¤ÈºîÀ®Æü»þ¤òɽ¼¨¤¹¤ë¡£ +{\tt language} ¥³¥Þ¥ó¥É¤Ï¥¿¡¼¥²¥Ã¥È¤Ë¤¹¤ë¸À¸ì¤ò»ØÄꤹ¤ë¡£ + +¹½Ê¸¤Ï°Ê²¼¤ÎÄ̤ꡣ +\begin{quote} +\tt language \syntax{language-name} +\opt{extension \syntax{extension-name}}\\ +\mbox{\qquad\qquad}\opt{version \syntax{version-name}} +\end{quote} +extension--name ¤Ï¡¢{\tt TANGLE} ¤¬¥×¥í¥°¥é¥à¤ò½ñ¤½Ð¤¹ +³ÈÄ¥»Ò¤È¤·¤Æ({\tt .web}¥Õ¥¡¥¤¥ë¤ËËä¤á¹þ¤à¤¿¤á¤Ë)»È¤ï¤ì¤ë¡£ +extension ¤Ï¡¢{\tt WEAVE} ¤Ç»È¤ï¤ì¤ë ¸À¸ì¤Ë¸ÇͤΠ+{\TeX} ¥Þ¥¯¥í¥Õ¥¡¥¤¥ë¤òÀ¸À®¤¹¤ë»þ¤Ë¤â»È¤ï¤ì¤ë¡£ +¤·¤¿¤¬¤Ã¤Æ¡¢°Û¤Ê¤ë¸À¸ì¤Ï°Û¤Ê¤ë³ÈÄ¥»Ò(extension) ¤ò»ý¤¿¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£ +extension ¤¬»ØÄꤵ¤ì¤Æ¤¤¤Ê¤¤»þ¤Ï¡¢¸À¸ì̾¤¬¥Ç¥Õ¥©¥ë¥È¤È¤Ê¤ë¡£ +version ¾ðÊ󤬻ØÄꤵ¤ì¤Æ¤¤¤ì¤Ð¡¢¤½¤ì¤â¥×¥í¥°¥é¥àµ¯Æ°»þ¤Ëɽ¼¨¤µ¤ì¤ë¤è¤¦¤Ë¤Ê¤ë¡£ + +É®¼Ô¤¬ Unix ¤Ç»È¤Ã¤Æ¤¤¤ë {\tt c.spider} ¤Ç¤Ï¡¢°Ê²¼¤Î¤è¤¦¤Ë¤Ê¤Ã¤Æ¤¤¤ë¡£ +\begin{verbatim} +language C extension c +\end{verbatim} + + + + +\subsection{{\TeX} ¥Þ¥¯¥í¤ÎÄêµÁ} +%In addition to the ``kernel'' {\WEB} macros stored in {\tt +%webkernel.tex}, you may want to create some {\TeX} macros of your +%own for use in translations. +{\tt webkernel.tex}¤Ëµ½Ò¤µ¤ì¤Æ¤¤¤ë¡Ö¥«¡¼¥Í¥ë¡×{\WEB}¥Þ¥¯¥í¤ò³ÈÄ¥¤¹¤ë¤¿¤á¤Ë¡¢ +translations ¤ÎÃæ¤Ç»È¤¦ÀìÍѤÎ{\TeX}¥Þ¥¯¥í¤ò +ÄêµÁ¤¹¤ë¤³¤È¤¬¤Ç¤¤ë¡£ +%Any macro definitions you put between lines saying {\tt macros begin} +%and {\tt macros end} will be included verbatim in the {\TeX} macro +%file for this language. +¤É¤ó¤Ê¥Þ¥¯¥í¤Ç¤â¡¢{\tt macros begin}¹Ô¤È +{\tt macros end} ¹Ô¤Î´Ö¤Ë¤¢¤ë¤â¤Î¤Ï +¤½¤Î¤Þ¤Þ¤½¤Î¸À¸ìÍѤΠ{\TeX} ¥Þ¥¯¥í¥Õ¥¡¥¤¥ë¤ÎÃæ¤Ë¼è¤ê¹þ¤Þ¤ì¤ë¡£ +%That macro file will automatically be \verb+\input+ by every {\TeX} +%file generated by this {\tt WEAVE}. +¤³¤Î¥Þ¥¯¥í¥Õ¥¡¥¤¥ë¤Ï¡¢%That macro file will automatically be +{\tt WEAVE}¤Ë¤è¤Ã¤ÆÀ¸À®¤µ¤ì¤ë¤¹¤Ù¤Æ¤Î {\TeX}¥Õ¥¡¥¤¥ë¤Ë +\verb+\input+ Ì¿Îá¤Ç¼«Æ°Åª¤Ë¼è¤ê¹þ¤Þ¤ì¤ë¤è¤¦¤Ë¤Ê¤ë¡£ + +%For example, the C grammar includes productions to handle preprocessor +%directives. +%These directives may include file names that are delimited by angle +%brackets. +%I wanted to use the abbreviations \verb+\LN+ and \verb+\RN+ for left +%and right angle brackets, so I included +Î㤨¤Ð¡¢C ¤Îʸˡ¤Ï¥×¥ê¥×¥í¥»¥Ã¥µÌ¿Îá¤ò°·¤¦µ¬Â§¤ò´Þ¤ó¤Ç¤¤¤ë¡£ +¤³¤ÎÌ¿Îá¤Ï³Ñ¥«¥Ã¥³¤Ç³ç¤Ã¤¿¥Õ¥¡¥¤¥ë̾¤ò»È¤¦¡£ +É®¼Ô¤Ï¡¢\verb+\LN+ , \verb+\RN+ ¤òº¸³Ñ¥«¥Ã¥³, +±¦³Ñ¥«¥Ã¥³¤Îû½Ì·Á¤È¤·¤Æ»È¤¦¤¿¤á¡¢ +°Ê²¼¤ÎÄêµÁ¤ò{\tt c.spider} ¥Õ¥¡¥¤¥ë¤Ë½ñ¤¤¤Æ¤¢¤ë¡£ +\begin{verbatim} +macros begin +\let\LN\langle +\let\RN\rangle +macros end +\end{verbatim} + + +\subsection{¥Ç¥Õ¥©¥ë¥È¤Î¥È¡¼¥¯¥ó¾ðÊó¤ÎÀßÄê} +%It's possible to set default values for the {\tt translation} and {\tt +%mathness} properties of tokens, so that they don't have to be +%repeated. +¥È¡¼¥¯¥ó¤Î \hbox{\tt translation} ¤È \hbox{\tt mathness} ¤Î¥Ç¥Õ¥©¥ë¥ÈÃͤò +ÀßÄꤹ¤ë¤³¤È¤Ë¤è¤ê¡¢Ëè²ó·«¤êÊÖ¤·¤Æµ½Ò¤¹¤ëɬÍפ¬¤Ê¤¯¤Ê¤ë¡£ +%This is done with the {\tt default} command, whose syntax is: +¤³¤ì¤Ï\hbox{\tt default} ¥³¥Þ¥ó¥É¤ò»È¤¦¡£½ñ¼°¤Ï°Ê²¼¤ÎÄ̤ê: +\begin{quote} +\tt +default \syntax{token descriptions} +\end{quote} +%The initial defaults (when {Spider} begins execution) are {\tt +%translation~<*>} and {\tt mathness~maybe}. +({Spider}¤¬¼Â¹Ô³«»Ï¤·¤¿¤È¤¤Î)¥Ç¥Õ¥©¥ë¥ÈÃͤνé´üÃÍ¤Ï +{\tt translation~<*>} ¤È {\tt mathness~maybe}¤Ç¤¢¤ë¡£ + + + + + + +\subsection{¥â¥¸¥å¡¼¥ë¤Î°·¤¤Êý¤Î»ØÄê} +{\WEB} ¤Ï¡¢Â¾¤Î¤É¤ó¤Ê¥×¥í¥°¥é¥ß¥ó¥°¸À¸ì¤Ë¤â¤Ê¤«¤Ã¤¿¼ïÎà¤Î¥È¡¼¥¯¥ó +¡Ö¥â¥¸¥å¡¼¥ë̾¡×¤òƳÆþ¤·¤¿({\tt @<...@>} ¤Þ¤¿¤Ï {\tt @(...@>})¡£ +%introduces a new kind of token that isn't in any programming +%language, and that's the module name ({\tt @<...@>} or {\tt @(...@>}). +{\tt TANGLE}¤Î»Å»ö¤Ï¡¢¤³¤Î¥â¥¸¥å¡¼¥ë̾¤ò¥×¥í¥°¥é¥à¥Æ¥¥¹¥È¤Ë¤¹¤ë¤³¤È¤Ç¤¢¤ê¡¢ +%'s job is to convert the module names to program text, and +¥â¥¸¥å¡¼¥ë̾¤¬¤Ê¤¯¤Ê¤Ã¤¿»þ¤Ë½ªÎ»¤¹¤ë¡£ +%when {\tt TANGLE} is finished no module names remain. +¤·¤«¤·¡¢{\tt WEAVE} ¤Ï¥â¥¸¥å¡¼¥ë̾¤òÁÈÈǤ·¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¤Î¤Ç¡¢ +%has to typeset the module names, and we need to tell +{\tt WEAVE} ¤¬¥â¥¸¥å¡¼¥ë̾¤ò¤É¤ó¤Ê¥«¥Æ¥´¥ê¡¼¤Î¥¹¥¯¥é¥Ã¥×¤Ë¤¹¤ë¤«¤ò +µ¬Äꤷ¤Æ¤ä¤ëɬÍפ¬¤¢¤ë¡£ +%what category to give a scrap created from a module name. +2¤Ä¤Î¥«¥Æ¥´¥ê¡¼¤¬µö¤µ¤ì¤ë¡£ +%We allow two different categories, +1¤Ä¤Ï¥â¥¸¥å¡¼¥ë̾¤ÎÄêµÁ (¥â¥¸¥å¡¼¥ë¤Î³«»Ï)ÍѤǤ¢¤ê¡¢ +¤â¤¦°ì¤Ä¤Ï¡¢¥â¥¸¥å¡¼¥ë̾¤Î»ÈÍÑ»þ¤Î¤â¤Î¤Ç¤¢¤ë¡£ +{\samepage +{\tt module}¥³¥Þ¥ó¥É¤Î¹½Ê¸¤Ï°Ê²¼¤ÎÄ̤ꡣ +\begin{quote} +\tt +module \opt{definition \syntax{category name}} +\opt{use \syntax{category name}} +\end{quote} +} + +{\tt c.spider} ¤Ç¤Ï°Ê²¼¤Î¤è¤¦¤Ë¤·¤Æ¤¤¤ë¡£ +\begin{verbatim} +module definition decl use math +\end{verbatim} + +\subsection{at sign ¤Î·èÄê} +{Spider}¤Ç{\WEB}¥·¥¹¥Æ¥à¤òºî¤ë¤Ê¤é¤Ð¡¢ + ``{\tt @}'' ¤ò ``magic at sign'' ¤È¤·¤Æ{\WEB}¤ÎÀ©¸æ¥³¥Þ¥ó¥É¤Î +³«»Ï¥¥ã¥é¥¯¥¿¤Ë¤¹¤ëɬÍפϤʤ¤¡£ +¤·¤«¤·¤Ê¤¬¤é¡¢´·Îã¤È¤·¤Æ¡¢Ë¾¤Þ¤·¤¯¤Ê¤¤¾ì¹ç°Ê³°¤Ï ``{\tt @}'' +¤ò»È¤¦¤³¤È¤Ë¤·¤è¤¦¡£ +``{\tt @}'' ¤¬Ë¾¤Þ¤·¤¯¤Ê¤¤»þ¤Ï¡¢Âå¤ï¤ê¤Ë ``{\tt \#}''¤ò»È¤¦¤³¤È¤Ë¤¹¤ë¡£ +{Spider} ¤Ç {\tt WEAVE} ¤È {\tt TANGLE} ¤Î C~{\WEB} ¥³¡¼¥É¤ò½ñ¤¯¤Ë¤Ï¡¢ +¿¤¯¤Î {\tt @} ¤ò½ñ¤¯¤³¤È¤Ë¤Ê¤ë¡£ +°ì¤Ä°ì¤Ä¤ò¥¨¥¹¥±¡¼¥×¤·¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤»þ¤ËÉ®¼Ô¤Ï¤½¤¦¤Ï¤·¤Ê¤«¤Ã¤¿¡£ +``{\tt \#}'' Awk~{\WEB}¤Î at~sign ¤ò ``{\tt \#}'' ¤Ë¤·¤¿: +\begin{verbatim} +at_sign # +\end{verbatim} +»ØÄꤵ¤ì¤Ê¤¤»þ¤Ë¤Ï¥Ç¥Õ¥©¥ë¥È¤Ï ``{\tt @}'' ¤Î¤Þ¤Þ¤Ç¤¢¤ë¡£ + +\paragraph{¥³¥ó¥È¥í¡¼¥ë¥·¡¼¥±¥ó¥¹¤ÎÊѹ¹} +at~sign ¤ÎÊѹ¹¤Ï¤Ò¤È¤Ä¤«Æó¤Ä¤Î¥³¥ó¥È¥í¡¼¥ë¥·¡¼¥±¥ó¥¹¤Î°ÕÌ£¤òÊѹ¹¤¹¤ë¡£ +%This is more easily illustrated by example than explained. +¸ÀÍÕ¤ÇÀâÌÀ¤¹¤ë¤è¤ê¤ÏÎã¤ò¼¨¤·¤¿Êý¤¬²ò¤ê¤ä¤¹¤¤¤Î¤Ç¡¢ +at~sign ¤ò{\tt\#}¤ËÊѤ¨¤¿¾ì¹ç¤ò¼¨¤½¤¦¡£ +·ë²Ì¤È¤·¤Æ {\WEB} ¤ÎÆó¤Ä¤Î¥³¥ó¥È¥í¡¼¥ë¥·¡¼¥±¥ó¥¹¤Ï¿·¤·¤¤°ÕÌ£¤ò»ý¤Ä¤³¤È¤Ë¤Ê¤ë: +\begin{description} +\item[{\tt \#\#}] +%Stands for a {\tt \#} in the input, by analogy with {\tt @@} in normal +%{\WEB}. +Ä̾ï¤Î{WEB}¤Î{\tt @@}¤ÈƱÍͤʰÕÌ£¤Ç¡¢ÆþÎÏÃæ¤Î{\tt\#}¤ò¼¨¤¹¡£ +%You will need this when defining {\TeX} macros that take parameters. +¥Ñ¥é¥á¡¼¥¿¤òȼ¤¦{\TeX} ¥Þ¥¯¥í¤òÄêµÁ¤¹¤ë¤È¤¤ËɬÍפˤʤ롣 +\item[{\tt \#@}] +%This is the new name of the control sequence normally represented by +%{\tt@\#}. +¤³¤ì¤Ï¡¢Ä̾ï¤Î{\tt@\#}¤È¤¤¤¦À©¸æ¥·¡¼¥±¥ó¥¹¤Î¿·¤·¤¤Ì¾Á°¤Ç¤¢¤ë¡£ +% You would use {\tt\#@} to get a line break followed by vertical +%white space. +{\tt\#@}¤Ï¡¢¿âľ¥¹¥Ú¡¼¥¹¤òȼ¤¦²þ¹Ô¤òÆÀ¤ë¤È¤¤Ë»È¤¦¡£ +\end{description} +%If you change the at sign to something other than {\tt@}~or~{\tt\#}, +%the above will still hold provided you substitute your at sign for +%{\tt\#}. +¤â¤·¤¢¤Ê¤¿¤¬ at~sign ¤ò {\tt@}~¤Þ¤¿¤Ï~{\tt\#} °Ê³°¤Î²¿¤«¤ËÊѤ¨¤¿¤Ê¤é¡¢ +¾å¤Îµ½Ò¤Î{\tt\#}¤ò¤¢¤Ê¤¿¤¬»ØÄꤷ¤¿ at~sign ¤ËÃÖ¤´¹¤¨¤ÆÆɤá¤ÐÎɤ¤¡£ + + + + +\subsection{¥×¥í¥°¥é¥à¸À¸ìÆâ¤Ç¤Î¥³¥á¥ó¥È} +{\tt WEAVE} ¤È {\tt TANGLE} ¤Ë¥¿¡¼¥²¥Ã¥È¸À¸ì¤ÎÃæ¤Î¥³¥á¥ó¥È¤Î°·¤¤¤ò +»ØÄꤷ¤Æ¤ª¤«¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£ +¥³¥á¥ó¥È¥Æ¥¥¹¥È¤Ï¡¢ +{\tt WEAVE}¤Ç¤Ï{\TeX}¥Æ¥¥¹¥È¤È¤·¤Æ°·¤ï¤ì¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¤·¡¢ +{\tt TANGLE}¤Ç¤Ï̵»ë¤µ¤ì¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£ +{\tt comment} ¥³¥Þ¥ó¥É¤Î¹½Ê¸¤Ï¡¢°Ê²¼¤ÎÄ̤ꡣ +\begin{quote} +\tt +comment begin \syntax{restricted translation} \\ +\null\qquad end $(\syntax{restricted translation}|{\tt newline})$ +\end{quote} +³ç¤é¤ì¤¿Ê¸»úÎó¡¢{\tt space}¡¢{\tt dash} ¤Î¤ß¤¬¡¢ +À©¸Â¤Ä¤¤Î translation ¤È¤·¤Æµ½Ò¤Ç¤¤ë¡£ +%They give the character sequences that begin and end comments. +¤³¤ì¤é¤Ï¥³¥á¥ó¥È¤Î³«»Ï¤È½ªÎ»¤Îʸ»úÎó¤Ç¤¢¤ë¡£ +¥³¥á¥ó¥È¤¬²þ¹Ô¤Ç½ªÎ»¤¹¤ë¤Î¤Ê¤é¡¢Àµ¤·¤¤¤ª¤Þ¤¸¤Ê¤¤¤Ï {\tt end +newline}¤Ç¤¢¤ë¡£ + +¤â¤·¥³¥á¥ó¥Èʸ»ú¤¬ ``at sign''¤ÈƱ¤¸¤Ç¤¢¤ì¤Ð¡¢ +{\WEB} ¥Õ¥¡¥¤¥ë¤ÎÃæ¤Ç¤ÏÆó½Å¤Ë½ñ¤«¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£ +%file to have any effect. +É®¼Ô¤¬Ëº¤ì¤Æ¤·¤Þ¤Ã¤¿¤»¤¤¤Ç¡¢ +{Spider} ¤³¤ì¤ò¸¡½Ð¤Ç¤¤Ê¤¤Çϼ¯¼Ô¤Ë¤Ê¤Ã¤Æ¤·¤Þ¤¤¡¢ +%is too dumb to figure this out +{\jem {\tt Spider} ¥Õ¥¡¥¤¥ë¤ÎÃæ¤Ç +¥³¥á¥ó¥Èʸ»ú¤òÆó½Å¤Ë½ñ¤«¤Í¤Ð¤Ê¤é¤Ê¤¯¤Ê¤Ã¤Æ¤·¤Þ¤Ã¤¿}¡£ +%This is not totally unreasonable since any at sign that actually appears in a +%{\WEB} file will have to be double to be interpreted correctly. +{\WEB}¥Õ¥¡¥¤¥ë¤¬Àµ¤·¤¯²ò¼á¤¹¤ë¤¿¤á¤Ë at~sign ¤¬¸½¼Â¤Ë¤Ï +Æó½Å¤Ë½ñ¤«¤ì¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¤Î¤Ç¡¢Áí¹çŪ¤Ë¤ÏÁ´¤¯ÉÔÅö¤È¤¤¤¦¤ï¤±¤Ç¤Ï¤Ê¤¤¡£ + + +{\tt WEAVE} ¤Ï \verb+\commentbegin+ ¤È +\verb+\commentend+ ¤È¤¤¤¦¥Þ¥¯¥í¤ò +¥³¥á¥ó¥È¤Î³«»Ï¤È½ªÎ»¤Ë»È¤¦¡£ +%at the beginning and end of comments, so you can +¤è¤Ã¤Æ¡¢{Spider}¤Î¥Ç¥Õ¥©¥ë¥È¤¬µ¤¤ËÆþ¤é¤Ê¤±¤ì¤Ð +({\tt macros}¥³¥Þ¥ó¥É¤ò»È¤Ã¤Æ)¹¥¤¤Ê¤è¤¦¤ËÄêµÁ¤¹¤ë¤³¤È¤¬¤Ç¤¤ë¡£ +{Spider} ¤Ï{\TeX}¤Î¥Ç¥Õ¥©¥ë¥È¤ÎÆüìʸ»ú¤ò²óÈò¤¹¤ëÄøÅ٤ˤϽ½Ê¬¥¹¥Þ¡¼¥È¤Ç¤¢¤ë¡£ +%is smart enough to escape {\TeX}'s special characters in +%coming up with these defaults. + +%Here's a real-world ugly example of how things really are, from the +%{\tt spider} file for Awk: +°Ê²¼¤Ë¼ÂºÝ¤Ë¤É¤¦¤·¤Æ¤¤¤ë¤«¤ò Awk ¤Î{\tt spider} ¥Õ¥¡¥¤¥ë¤«¤é°úÍѤ¹¤ë: +\begin{verbatim} +comment begin <"##"> end newline +macros begin +\def\commentbegin{\#} % we don't want \#\# +macros end +\end{verbatim} + + + +\subsection{¹ÔÈÖ¹æ¤ÎÀ©¸æ} + ¥³¥ó¥Ñ¥¤¥é¤¬{\WEB}¥Õ¥¡¥¤¥ë¤òľÀܸ«¤ë¤³¤È¤Ï¤Ê¤¤¡£{\tt TANGLE} ¤Î +½ÐÎϤòÆɤޤͤФʤé¤Ê¤¤¡£ +{\tt TANGLE}¤¬ºî¤Ã¤¿¥Õ¥¡¥¤¥ë¤Î¹ÔÈÖ¹æ¤ò¼¨¤¹¥¨¥é¡¼¥á¥Ã¥»¡¼¥¸¤Ï¡¢ +Èó¾ï¤Ë͸ú¤À¤È¤Ï¸À¤¤Æñ¤¤¡£¤½¤³¤Ç¡¢ +Spidery {\tt TANGLE} ¤Ï¡¢Â¿¾¯²þÁ±¤·¤¿¾õ¶·¤òÄ󶡤¹¤ë¤¿¤á¡¢ + C~¥×¥ê¥×¥í¥»¥Ã¥µ¡¼ÍѤΠ{\tt \#line} Ì¿Îá¤ò½ÐÎϤ˽ñ¤¯( +{\tt TANGLE} ¤â{\WEB} ¥½¡¼¥¹¤Î²þ¹Ô¾ðÊó¤òÊÝ»ý¤·¤Æ¤¤¤ë¤Î¤Ç¡¢ + {\tt \#line} ¾ðÊó¤ÏÍÍѤÀ¤í¤¦)¡£ +{\tt cc} ¤È {\tt dbx}¤ò»ý¤Ã¤¿ +Unix ¤Î¤è¤¦¤Ê¥·¥¹¥Æ¥à¤Ç¤Ï¡¢¥³¥ó¥Ñ¥¤¥ë»þ¤È¥é¥ó¥¿¥¤¥à»þ¤ÎξÊý¤Ç +{\WEB}¥½¡¼¥¹¤ÎÍѸì¤Ç¥Ç¥Ð¥Ã¥°¤¹¤ë¤³¤È¤¬¤Ç¤¤ë¡£ +Ãæ´Ö¤Î¥×¥í¥°¥é¥ß¥ó¥°¥½¡¼¥¹¤Ï¤±¤Ã¤·¤ÆÄ´¤Ù¤ëɬÍפ¬¤Ê¤¤¡£ + +Á´¤Æ¤Î¥³¥ó¥Ñ¥¤¥é¤¬{\tt \#line}Ì¿Îá¤ò¥µ¥Ý¡¼¥È¤·¤Æ¤¤¤ë¤ï¤±¤Ç¤Ï¤Ê¤¤¤Î¤Ç¡¢ +{Spider}¤Ï {\tt line} ¥³¥Þ¥ó¥É¤Ç + {\tt \#line} Ì¿Îá¤Î¥Õ¥©¡¼¥Þ¥Ã¥È¤òÊѹ¹¤Ç¤¤ë¤è¤¦¤Ë¤Ê¤Ã¤Æ¤¤¤ë¡£ +¼«Ê¬¤Î¥³¥ó¥Ñ¥¤¥é¤¬ {\tt \#line} ¤ò¥µ¥Ý¡¼¥È¤·¤Æ¤¤¤Ê¤±¤ì¤Ð¡¢ +{\tt line} ¥³¥Þ¥ó¥É¤ò»È¤Ã¤Æ¹ÔÈÖ¹æ¾ðÊó¤ò¥³¥á¥ó¥È¤ÎÃæ¤ËÆþ¤ì¤ë¤è¤¦¤Ë +Êѹ¹¤¹¤ë¤³¤È¤¬¤Ç¤¤ë\footnote{% +¹ÔÈÖ¹æ¤ò½Ð¤µ¤Ê¤¤¥³¥Þ¥ó¥É¤¬¤¢¤ë¤Ù¤¤Ç¤¢¤ë¡£% +}¡£ +¹½Ê¸¤Ï°Ê²¼¤ÎÄ̤ê: +\begin{quote} +\tt +line begin \syntax{restricted translation} end \syntax{restricted translation} +\end{quote} +{\tt begin} ¤Ï¥Õ¥¡¥¤¥ë̾¤È¹ÔÈÖ¹æ¤ÎÁ°¤ËÃÖ¤¯Ê¸»úÎó¤ò»ØÄꤷ¡¢ +{\tt end} ¤Ï¸å¤ËÃÖ¤¯Ê¸»úÎó¤ò»ØÄꤹ¤ë¡£ +¥Ç¥Õ¥©¥ë¥È¤Ï (CÍѤËÀßÄꤵ¤ì¤Æ¤¤¤ë¤¬)°Ê²¼¤ÎÄ̤ꡣ +\begin{verbatim} +line begin <"#line"> end <""> +\end{verbatim} +¼¡¤Î¤Ï Ada~{Spider}¥Õ¥¡¥¤¥ë¤Ç¤ÎÎã¤Ç¤¢¤ë¡£ +¤³¤³¤Ç¤Ï¡¢¹ÔÈÖ¹æ¾ðÊó¤ò Ada ¤Î¥³¥á¥ó¥È¤È¤·¤Æ¤¤¤ë: +\begin{verbatim} +line begin <"--"-space-"line"> end <""> +\end{verbatim} + + + + +\subsection{ºîÀ®Æü»þ¤Îɽ¼¨} +Spidery {\tt WEAVE} ¤È{\tt TANGLE}¤¬½èÍý¤ò»Ï¤á¤ë»þ¡¢ +{Spider}¥Õ¥¡¥¤¥ë¤ò½èÍý¤·¤¿Æü»þ¤¬É½¼¨¤µ¤ì¤ë¡£ +¤³¤ì¤Ï¡¢{Spider}¤Î {\tt date}¥³¥Þ¥ó¥É¤Ë¤è¤Ã¤Æ¼¡¤Î¤è¤¦¤ËÀßÄꤵ¤ì¤ë¡£ +\begin{quote} +\tt +date \syntax{date} +\end{quote} +¤³¤³¤Ç \syntax{date} ¤Ï¡¢{\tt "Fri Dec 11 11:31:18 EST 1987"} ¤Ê¤É¤Ç¤¢¤ë¡£ +Ä̾{\tt date} ¥³¥Þ¥ó¥É¤ÎɬÍפϤʤ¤¡£ +{Spider} ¥Ä¡¼¥ë¤¬¼«Æ°Åª¤ËÁÞÆþ¤¹¤ë¡£ +¤·¤«¤·¡¢Unix ¥Þ¥·¥ó¤Ç¤Ê¤¤¥·¥¹¥Æ¥à¤Ë{Spider}¤ò°Ü¿¢¤¹¤ë»þ¤Ë¤Ï¡¢ +¾åµ¤Î¤³¤È¤¬É¬Íפˤʤ롣 + + + + + +\section{Spider¤Î¥¨¥é¡¼¥á¥Ã¥»¡¼¥¸} +{Spider} ¤Ï»ÅÍ;å¤Î¥¨¥é¡¼¤ò¸¡½Ð¤¹¤ë¤¿¤á¤ËÈó¾ï¤ÊÅØÎϤò¤¹¤ë¡£ +{Spider}¤Î¥¨¥é¡¼¥á¥Ã¥»¡¼¥¸¤ÏÆɤá¤Ð¤ï¤«¤ë¤è¤¦¤Ëºî¤ë¤Ä¤â¤ê¤Ç¤¢¤ë¤¬¡¢ +¤¦¤Þ¤¯À®¸ù¤µ¤»¤ëÊýË¡¤òÃΤé¤Ê¤¤¡£ +¥È¥é¥Ö¥ë¤Ë¤¢¤Ã¤¿»þ¤Î¤¿¤á¤Ë¡¢°Ê²¼¤Ë{Spider}¤¬¸¡½Ð¤·¤è¤¦¤È¤·¤Æ¤¤¤ë¾ò·ï¤ò¼¨¤·¤Æ¤ª¤¯: +\begin{itemize} +\item + ̤ÄêµÁ¤Ê¥³¥Þ¥ó¥É¡¢¸í¤Ã¤¿¥Õ¥£¡¼¥ë¥É¤ò´Þ¤à¹Ô¡¢ +%Garbled commands, lines with bad fields in them, or commands with +»È¤ï¤ì¤Ê¤¤¥Õ¥£¡¼¥ë¥É¤ò»ý¤Ä¥³¥Þ¥ó¥É¡£ +%Any command with a field {Spider} can't follow or with an extra +%field is ignored from the bad field onward, but the earlier fields may +%have an effect. +¥Õ¥£¡¼¥ë¥É¤¬É¬Íפʤ¹¤Ù¤Æ¤Î¥³¥Þ¥ó¥É¤Ë¤Ä¤¤¤Æ¡¢ +{Spider}¤Ï¥Õ¥£¡¼¥ë¥É¤òÊä¤ï¤Ê¤¤¤·¤è¤±¤¤¤Ê¥Õ¥£¡¼¥ë¥É°Ê¹ß¤ò̵¸ú¤È¤¹¤ë¡£ +¤¿¤À¤·¡¢¤½¤ì°ÊÁ°¤Î¥Õ¥£¡¼¥ë¥É¤Ï͸ú¤Ë¤Ê¤ë¤«¤âÃΤì¤Ê¤¤¡£ +¸í¤Ã¤¿¥Õ¥£¡¼¥ë¥É¤ä¥¨¥é¡¼¤Î¤¢¤ëÀ¸À®µ¬Â§¤Ï´°Á´¤Ë̵¸ú¤È¤µ¤ì¤ë¡£ +\item +{\tt language} ¥³¥Þ¥ó¥É¤¬¤Ê¤¤¡£ +\item +{\tt macros} ¤Þ¤¿¤Ï {\tt comment} ¥³¥Þ¥ó¥É¤¬ {\tt language} ¥³¥Þ¥ó¥É¤Î +Á°¤ËÄêµÁ¤µ¤ì¤Æ¤¤¤ë¡£ +{Spider} ¤Ï {\tt extension} ¾ðÊó¤ò +from the {\tt language} ¥³¥Þ¥ó¥É¤«¤éÆÀ¤Æ¤ª¤ê¡¢ +¥Þ¥¯¥í¤ò½ñ¤½Ð¤¹¥Õ¥¡¥¤¥ë̾¤ò·èÄꤹ¤ë¤¿¤á¤Ë»È¤¦¡£ +¤Þ¤¿{\tt comment} ¥³¥Þ¥ó¥É¤Ï +{Spider} ¤¬{\TeX}¤Î¤¿¤á¤Ë¥³¥á¥ó¥È¤Î»Ï¤Þ¤ê¤È½ª¤ê¤ò +¥Þ¥¯¥í¥Õ¥¡¥¤¥ë¤Ë½ñ¤¯¤³¤È¤òÍ×ÀÁ¤¹¤ë¡£ +\item +ʸ̮¤¬º¸Æ³½Ð¡¢±¦Æ³½Ð¤Î¤¤¤º¤ì¤Ë¤â¹çÃפ·¤Ê¤¤¡£ +\item +%A numbered target token doesn't fall in the range defined by the +%left hand side of its production. +ÈÖ¹æ¤Ç»²¾È¤µ¤ì¤¿¥È¡¼¥¯¥ó¤¬¤½¤ÎÀ¸À®µ¬Â§¤Îº¸Êդˤʤ¤¡£ +\item +{\jem ÄɲäǤ¤Ê¤¤}¥«¥Æ¥´¥ê¡¼¤¬¤¢¤ë¡£ +¤³¤ì¤Ï¡¢¤½¤Î¥«¥Æ¥´¥ê¡¼¤¬¥¹¥¯¥é¥Ã¥×¤òÀ¸À®¤¹¤ëÊýË¡¤¬¤Ê¤¤¤³¤È¤ò°ÕÌ£¤¹¤ë¡£ +{Spider} ¤Ïñ¤Ë¤¹¤Ù¤Æ¤Î¥«¥Æ¥´¥ê¡¼¤¬¾¯¤Ê¤¯¤È¤â°ìÅÙ¤Ï +¥È¡¼¥¯¥ó¤«¥¿¡¼¥²¥Ã¥È¥È¡¼¥¯¥ó¤È¤·¤ÆÀ¸À®µ¬Â§¤ÎÃæ¤Ë¸½¤ì¤ë¤³¤È¤ò +Ä´¤Ù¤Æ¤¤¤ë¤À¤±¤Ç¤¢¤ë¡£ +(¤â¤·¤±¤·¤ÆŬÍѤµ¤ì¤Ê¤¤À¸À®µ¬Â§¤¬¤¢¤ë¤Ê¤é¤Ð) +{Spider}¤Ï¾ò·ï¤ò¸¡½Ð¤Ç¤¤Ê¤¤¤Î¤Ç¼ºÇÔ¤¹¤ë¡£ +\item +{\jem ´Ô¸µ¤Ç¤¤Ê¤¤}¥«¥Æ¥´¥ê¡¼¤¬¤¢¤ë¡£ +¤³¤ì¤Ï¡¢¤³¤Î¥«¥Æ¥´¥ê¡¼¤¬À¸À®µ¬Â§¤ÎÃæ¤Ç»²¾È¤µ¤ì¤Æ¤¤¤Ê¤¤¤³¤È¤ò°ÕÌ£¤¹¤ë¡£ +%This means that the category never appears in a scrap +%designator from the firing instructions of a production. +¥«¥Æ¥´¥ê¡¼¤¬´Ô¸µ¤Ç¤¤Ê¤±¤ì¤Ð¡¢ +{Spider} ¤Ïñ¤Ë·Ù¹ð¤ò½Ð¤¹¤Î¤ß¤Ç¡¢ +¥¨¥é¡¼¤Ë¤è¤Ã¤Æ½èÍý¤òÄä»ß¤¹¤ë¤³¤È¤Ï¤Ê¤¤¡£ + +¥«¥Æ¥´¥ê¡¼Ì¾¤ÎÄ֤θí¤ê¤Ë¤è¤ëÄɲäȴԸµ¤Î¥Á¥§¥Ã¥¯¤Ï¤¿¤¤¤Æ¤¤¸¡½Ð¤µ¤ì¤ë¡£ +\item +{\tt WEAVE} ¤È {\tt TANGLE} ¤¬°·¤¨¤ë°Ê¾å¤Î +¥È¡¼¥¯¥ó¤ò»ØÄꤷ¤Æ¤¤¤ë¡£ +\item +¥È¡¼¥¯¥ó¤Î¾ðÊó¤¬ÉÔ´°Á´; ¼±Ê̻ҡ¢¿ôÃÍÄê¿ô¡¢newline¡¢ +µ¿»÷¥»¥ß¥³¥í¥ó~({\tt @;})¡¢¥â¥¸¥å¡¼¥ëÄêµÁ¡¢¥â¥¸¥å¡¼¥ë¤Î»ÈÍѤò˺¤ì¤Æ¤¤¤ë¡£ +\item +ilk ¤¬ translation ¤ò»ý¤¿¤Ê¤¤¡¢¤Þ¤¿¤ÏͽÌó¸ì¤ò»ý¤¿¤Ê¤¤ ilk ¤¬¤¢¤Ã¤¿¡£ +%no reserved words. +\end{itemize} + + + + +\section{{Spider}¤Î½ÐÎÏ¥Õ¥¡¥¤¥ë} +{Spider} ¤Ï¿¤¯¤Î½ÐÎÏ¥Õ¥¡¥¤¥ë¤òÀ¸À®¤¹¤ë¡£É¬Íפʤ餽¤ì¤é¤òÄ´¤Ù¡¢ +²¿¤¬¤Ê¤µ¤ì¤Æ¤¤¤ë¤«¤ò²òÀϤǤ¤ë¡£ +°Ê²¼¤Ï¤½¤Î°ìÉô¤Ç¤¢¤ë (´°Á´¤Ê¥Õ¥¡¥¤¥ë¤Î¥ê¥¹¥È¤Ï +{\tt spider.web}¤òÄ´¤Ù¤ì¤Ð¤ï¤«¤ë): +\begin{description} +\item[\tt cycle.test] +ʸˡ¤Î¥ë¡¼¥×²ÄǽÀ¤ò¸¡½Ð¤¹¤ë¤Î¤Ë»ÈÍѤµ¤ì¤ë¡£ +¤³¤Î¤è¤¦¤Ê¥ë¡¼¥×¤Ï ÆÃÄê¤ÎÆþÎϤËÂФ·{\tt WEAVE} ¤ò̵¸Â¤Ë (¥á¥â¥ê¡¼¤ò»È¤¤¤¤ë¤Þ¤Ç) +Áö¤é¤»¤ë¤³¤È¤Ë¤Ê¤ë¤è¤¦¤Ê¤â¤Î¤Ç¤¢¤ë¡£ +¸å¤Ç {Spider}¥Ä¡¼¥ë¤È°ì½ï¤ËµÄÏÀ¤¹¤ë¡£ +\item[\tt spider.slog] +{Spider} ¤¬¥Õ¥¡¥¤¥ë¤ò½èÍýÃæ¤Î¤¹¤Ù¤Æ¤Î¾éŤÊÆâÍÆ¡£ +¤Ò¤É¤¤¤³¤È¤¬µ¯¤¤¿»þ¤ËÄ´¤Ù¤ë¤¿¤á¤Î¤â¤Î¤Ç¤¢¤ë¡£ +\item[\tt *web.tex] +À¸À®¤µ¤ì¤¿{\WEB}¤Î¤¿¤á¤Î¥Þ¥¯¥í¡£ +\item[\tt productions.list] +¤¹¤Ù¤Æ¤Îµ¬Â§¤ÎÈÖ¹æÉÕ¤±¤·¤¿¥ê¥¹¥È¡£ +Spidery {\tt WEAVE}¤Î¥È¥ì¡¼¥¹µ¡Ç½ ({\tt @2})¤ò»È¤Ã¤Æʸˡ¤Î¥Ç¥Ð¥Ã¥°¤ò +¤¹¤ëºÝ¤Ë½ÅÊõ¤¹¤ë¡£ +\end{description} + + + + +\section{{Spider} ¤Ç{\WEB}¤òºî¤ë ({Spider} tools)} +¿¤¯¤Î {Spider} ¥Ä¡¼¥ë¤¬¥¨¥é¡¼¤ò¥Á¥§¥Ã¥¯¤¹¤ë¡£Î㤨¤Ð: +\begin{itemize} +\item +¥«¥Æ¥´¥ê¡¼¡¢ilk¡¢translation ¤Î¥¡¼¥ï¡¼¥É̾¤Î½ÅÊ£¥Á¥§¥Ã¥¯¤ò¤¹¤ë¡£ +\item +translation ¥¡¼¥ï¡¼¥É¤¬{\tt WEAVE}¤Î¥¡¼¥ï¡¼¥É¤È¾×Æͤ·¤Æ¤¤¤Ê¤¤¤«¤ò¥Á¥§¥Ã¥¯¤·¡¢ +¾×Æͤ·¤Æ¤¤¤ì¤Ð·Ù¹ð¤òȯ¤¹¤ë¡£ +%keywords against a list of those recognized by +% and yelps if trouble happens. +\item +{\tt WEAVE}¤¬Ìµ¸Â¥ë¡¼¥×¤Ë´Ù¤ë¤è¤¦¤Ê¡ÖÀ¸À®µ¬Â§¤Î½Û´Ä¡×¤¬¤Ê¤¤¤«¤ò¸¡½Ð¤¹¤ë¡£ +%Try to determine whether there is a ``production cycle'' that could +%cause to loop infinitely by firing the productions in the +%cycle one after another. +\end{itemize} + +¤³¤³¤Ç¤Ï¡¢¤½¤ì¤é¤¬¤É¤¦¤Ê¤Ã¤Æ¤¤¤ë¤«¡¢{\tt WEAVE} ¤ä {\tt TANGLE}¤ò +¤É¤¦¤ä¤Ã¤ÆÀ¸À®¤¹¤ë¤«¤Ë¤Ä¤¤¤Æ¡¢Â¿¤¯¤òÀâÌÀ¤¹¤ë¤Ä¤â¤ê¤Ï¤Ê¤¤¡£ +%I'm not going to say much about how to do all this, or how to make +Âå¤ï¤ê¤Ë¡¢{\tt Makefile} ¤òÄ󼨤·¡¢¾¯¡¹¥³¥á¥ó¥È¤¹¤ë¤³¤È¤Ë¤·¤è¤¦¡£ +%and comment on it a little bit. +%Since right now Spidery {\tt WEB} is available only on Unix systems, +%chances are you have the {\tt Makefile} and can just type ``{\tt +%make~tangle}'' or ``{\tt make~weave}.'' +¸½ºß¤Î¤È¤³¤í¡¢ Spidery {\tt WEB} ¤Ï Unix ¥·¥¹¥Æ¥à¤Î¾å¤Ë¤·¤«Â¸ºß¤·¤Æ¤¤¤Ê¤¤¡£ +{\tt Makefile} ¤òÆþ¼ê¤·¡¢ + ``{\tt make~tangle}'' ¤Þ¤¿¤Ï ``{\tt make~weave}'' ¤È¥¿¥¤¥×¤¹¤ë¤À¤±¤Ç +¤è¤¤²ÄǽÀ¤¬¤¢¤ë¡£ +%If not, reading the Makefile is still your best bet to figure out what +%the tools do. +¤½¤¦¤Ç¤Ê¤¤¤È¤·¤Æ¤â¡¢ Makefile ¤òÆɤó¤Ç¥Ä¡¼¥ë¤Î¤¹¤ë¤³¤È¤òÍý²ò¤¹¤ë¤Î¤¬ +ºÇÁ±¤ÎÊýË¡¤Ç¤¢¤ë¡£ + +%We assume that you are making {\tt WEAVE} and {\tt TANGLE} in some +%directory, and that the ``master sources'' for Spidery {\WEB} are kept +%in some other directory. +¤¢¤Ê¤¿¤Ï´û¤Ë {\tt WEAVE} ¤È {\tt TANGLE} ¤ò¤É¤³¤«¤Î¥Ç¥£¥ì¥¯¥È¥ê¡¼¤Ëºî¤Ã¤Æ¤¢¤ê¡¢ +Spidery {\WEB} ¤Î ``master sources'' ¤¬¤É¤³¤«Ê̤Υǥ£¥ì¥¯¥È¥ê¡¼¤Ë +Êݴɤµ¤ì¤Æ¤¤¤ë¤Î¤òÁ°Äó¤È¤¹¤ë¡£ +%Some of the {\tt Makefile} macros deserve special mention: +{\tt Makefile} ¤Î ¥Þ¥¯¥í¤Î¤¤¤¯¤Ä¤«¤ÏÆä˸ÀµÚ¤¹¤ë²ÁÃͤ¬¤¢¤ë: +\begin{description} +\renewcommand{\makelabel}[1]{{\tt#1}\hfil} +\item[THETANGLE] +À¸À®¤·¤è¤¦¤È¤·¤Æ¤¤¤ë {\tt TANGLE} ¤Î̾Á°¡£ +\item[THEWEAVE] +À¸À®¤·¤è¤¦¤È¤·¤Æ¤¤¤ë{\tt WEAVE} ¤Î̾Á°¡£ +\item[SPIDER] +{Spider} ¤ÎÆþÎÏ¥Õ¥¡¥¤¥ë̾¡£ +\item[DEST] +\verb+$(TANGLE)+ ¤È\verb+$(WEAVE)+ ¤È¤·¤ÆÄêµÁ¤µ¤ì¤¿¼Â¹Ô¥Õ¥¡¥¤¥ë¤¬ÃÖ¤«¤ì¤ë¤Ù¤ +¥Ç¥£¥ì¥¯¥È¥ê¡¼¡£ +\item[WEBROOT] +Spidery {\WEB} ÇÛÉÛʪ¤Î¥ë¡¼¥È¥Ç¥£¥ì¥¯¥È¥ê¡¼¡£ +\item[MASTER] +``¥Þ¥¹¥¿¡¼¥½¡¼¥¹''¤Î¤¢¤ë¾ì½ê¡£ +¤³¤ì¤Ï¡¢É¬¤º {\tt make} ¤¬¼Â¹Ô¤µ¤ì¤ë¥Ç¥£¥ì¥¯¥È¥ê¡¼¤È°Û¤Ê¤Ã¤Æ¤¤¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£ +¤µ¤â¤Ê¤±¤ì¤ÐÂæ̵¤·¤Ë¤Ê¤Ã¤Æ¤·¤Þ¤¦¤À¤í¤¦¡£ +%This should always be different from the directory in which {\tt make} +%is called, or havoc will result. +\item[CTANGLE] +tangle ¤Î C ¥³¡¼¥É¤Ç»È¤ï¤ì¤ë¥×¥í¥°¥é¥à̾¡£ +\item[AWKTANGLE] +Awk¤Î¥³¡¼¥É¤ò tangle ¤¹¤ë¥×¥í¥°¥é¥à¤Î̾Á°¡£ + +\item[MACROS] +%The name of a directory in which to put {\TeX} macro definitions (a +%{\tt *web.tex} file. +{\TeX}¥Þ¥¯¥í¥Õ¥¡¥¤¥ë({\tt *web.tex} )¤ò³ÊǼ¤¹¤ë¤Ù¤¥Ç¥£¥ì¥¯¥È¥ê¡¼Ì¾¡£ +\end{description} + +%Usually we will only be interested in two commands: ``\/{\tt +%make~weave}'' and ``\/{\tt make~tangle}.'' +ÉáÃÊÎɤ¯»È¤¦¤Î¤Ï \hbox{``{\tt make~weave}''} ¤È +\hbox{``\/{\tt make~tangle}''} ¤Î +2¤Ä¤Î¥³¥Þ¥ó¥É¤À¤±¤Ç¤¢¤í¤¦¡£ +%It's safe to use ``\/{\tt make~clean}'' only if you use the current +%directory for nothing exception spidering; ``\/{\tt make~clean}'' is +%really vicious. +\hbox{``{\tt make~clean}''} ¤Ï¡¢ ¸½ºß¤Î¥Ç¥£¥ì¥¯¥È¥ê¡¼¤Ç +{\WEB} ºîÀ®ºî¶È°Ê³°¤Î¤³¤È¤ò¤·¤Ê¤¤»þ¤Ç¤Ê¤±¤ì¤Ð°ÂÁ´¤Ç¤Ï¤Ê¤¤¡£ +%only if you use the current directory +%for nothing exception spidering; +\hbox{``\/{\tt make~clean}''}¤Ï¡¢ ËÜÅö¤Ë¤Ò¤É¤¤¤³¤È¤ò¤¹¤ë¡£ + +ËÜÅö¤Ë¶½Ì£¿¼¤¤¹Ô¤Ï¡¢ +{\tt grammar.web} ¤Î°Í¸´Ø·¸¤òɽµ¤·¤Æ¤¤¤ë¤È¤³¤í¤Ç¤¢¤ë¡£ +Âè°ì¤Ë¡¢ {Spider}¤òµ¯Æ°¤¹¤ë¡£ +¼¡¤Ë¡¢À°·Á°õºþʸˡ ¤ÎÃæ¤Ë¡¢´Ö°ã¤Ã¤¿ translation ¥¡¼¥ï¡¼¥É¤ä +½Û´Ä¤Î²ÄǽÀ¤¬¤Ê¤¤¤«¤ò¥Á¥§¥Ã¥¯¤¹¤ë¡£ +¤½¤·¤Æ¡¢Ì¾Á°¤Î¤Ë½ÅÊ£ÄêµÁ¤¬¤Ê¤¤¤³¤È¤ò¥Á¥§¥Ã¥¯¤·¡¢ +ºÇ¸å¤Ë (Á´¤Æ¤¬OK¤À¤Ã¤¿¤é) +{\tt *web.tex} ¥Õ¥¡¥¤¥ë¤ò½ÐÎϤ¹¤ë¡£ + +\newpage +°Ê²¼¤Ï¡¢ \verb+$(MASTER)/WebMakefile+¤Ç¤¢¤ë: +\begingroup\small +\begin{verbatim} +# Copyright 1989 by Norman Ramsey and Odyssey Research Associates. +# To be used for research purposes only. +# For more information, see file COPYRIGHT in the parent directory. + +HOME=/u/nr# # Make no longer inherits environment vars +THETANGLE=tangle +THEWEAVE=weave +SPIDER=any.spider +# +DVI=dvi +CFLAGS=-DDEBUG -g -DSTAT + +# CPUTYPE is a grim hack that attempts to solve the problem of multiple +# cpus sharing a file system. In my environment I have to have different +# copies of object and executable for vax, sun3, next, iris, and other +# cpu types. If you will be using Spidery WEB in a homogeneous processor +# environment, you can just set CPUTYPE to a constant, or eliminate it +# entirely. +# +# In my environment, the 'cputype' program returns a string that +# describes the current processor. That means that the easiest thing +# for you to do is to define a 'cputype' program that does something +# sensible. A shell script that says 'echo "vax"' is fine. + +CPUTYPE=`cputype` + +# Change the following three directories to match your installation +# +# the odd placement of # is to prevent any trailing spaces from slipping in + +WEBROOT=$(HOME)/web/src# # root of the WEB source distribution +DEST=$(HOME)/bin/$(CPUTYPE)# # place where the executables go +MACROS=$(HOME)/tex/macros# # place where the macros go + +MASTER=$(WEBROOT)/master# # master source directory +OBDIR=$(MASTER)/$(CPUTYPE)# # common object files + +TANGLESRC=tangle +CTANGLE=ceetangle -I$(MASTER) +CWEAVE=ceeweave -I$(MASTER) +AWKTANGLE=awktangle -I$(MASTER) +COMMONOBJS=$(OBDIR)/common.o $(OBDIR)/pathopen.o +COMMONC=$(MASTER)/common.c $(MASTER)/pathopen.c +COMMONSRC=$(COMMONC) $(MASTER)/spider.awk + + + +# Our purpose is to make tangle and weave + +web: tangle weave + +tangle: $(COMMONOBJS) $(TANGLESRC).o + cc $(CFLAGS) -o $(DEST)/$(THETANGLE) $(COMMONOBJS) $(TANGLESRC).o + +weave: $(COMMONOBJS) weave.o + cc $(CFLAGS) -o $(DEST)/$(THEWEAVE) $(COMMONOBJS) weave.o + + +source: $(TANGLESRC).c $(COMMONSRC) # make tangle.c and common src, then clean + if [ -f WebMakefile ]; then exit 1; fi # don't clean the master! + if [ -f spiderman.tex ]; then exit 1; fi # don't clean the manual + -rm -f tangle.web weave.* common.* # remove links that may be obsolete + -rm -f *.unsorted *.list grammar.web outtoks.web scraps.web + -rm -f cycle.test spider.slog + -rm -f *.o *.tex *.toc *.dvi *.log *.makelog *~ *.wlog *.printlog + +# Here is how we make the common stuff + +$(MASTER)/common.c: $(MASTER)/common.web # no change file + $(CTANGLE) $(MASTER)/common + +$(OBDIR)/common.o: $(MASTER)/common.c + cc $(CFLAGS) -c $(MASTER)/common.c + mv common.o $(OBDIR) + + +$(MASTER)/pathopen.c: $(MASTER)/pathopen.web # no change file + $(CTANGLE) $(MASTER)/pathopen + mv pathopen.h $(MASTER) + +$(OBDIR)/pathopen.o: $(MASTER)/pathopen.c + cc $(CFLAGS) -c $(MASTER)/pathopen.c + mv pathopen.o $(OBDIR) + + +## Now we make the tangle and weave source locally + +$(TANGLESRC).c: $(MASTER)/$(TANGLESRC).web $(MASTER)/common.h grammar.web + -/bin/rm -f $(TANGLESRC).web + ln $(MASTER)/$(TANGLESRC).web $(TANGLESRC).web +# chmod -w $(TANGLESRC).web + $(CTANGLE) $(TANGLESRC) + +weave.c: $(MASTER)/weave.web $(MASTER)/common.h grammar.web + -/bin/rm -f weave.web + ln $(MASTER)/weave.web weave.web +# chmod -w weave.web + $(CTANGLE) weave + +## Here's where we run SPIDER to create the source + +grammar.web: $(MASTER)/cycle.awk $(MASTER)/spider.awk $(SPIDER) + echo "date" `date` | cat - $(SPIDER) | awk -f $(MASTER)/spider.awk + cat $(MASTER)/transcheck.list trans_keys.unsorted | awk -f $(MASTER)/transcheck.awk + awk -f $(MASTER)/cycle.awk < cycle.test + sort *.unsorted | awk -f $(MASTER)/nodups.awk + mv *web.tex $(MACROS) + +## We might have to make spider first. + +$(MASTER)/spider.awk: $(MASTER)/spider.web + $(AWKTANGLE) $(MASTER)/spider + mv cycle.awk nodups.awk transcheck.awk $(MASTER) + rm junk.list + + +# $(MASTER)/cycle.awk: $(MASTER)/cycle.web # making spider also makes cycle +# $(AWKTANGLE) $(MASTER)/cycle + + +# This cleanup applies to every language + +clean: + if [ -f WebMakefile ]; then exit 1; fi # don't clean the master! + if [ -f spiderman.tex ]; then exit 1; fi # don't clean the manual + -rm -f tangle.* weave.* common.* # remove links that may be obsolete + -rm -f *.unsorted *.list grammar.web outtoks.web scraps.web + -rm -f cycle.test spider.slog + -rm -f *.c *.o *.tex *.toc *.dvi *.log *.makelog *~ *.wlog *.printlog + + + +# booting the new distribution +boot: + cd ../master; rm -f *.o; for i in $(COMMONC); do \ + cc $(CFLAGS) -c $$i; \ + mv *.o $(OBDIR) ; \ + done; cd ../c + cc $(CFLAGS) -c $(TANGLESRC).c; \ + cc $(CFLAGS) -o $(DEST)/$(THETANGLE) $(COMMONOBJS) $(TANGLESRC).o + + +\end{verbatim} +\endgroup + +\section{¼«Ê¬ÍѤΠSpidery {\tt WEB}¤òºî¤ë} +º£¤Î¤È¤³¤í¡¢ Spidery {\tt WEB} ¤ÏUnix ¥Þ¥·¥ó¤Ç¤·¤«¥Æ¥¹¥È¤µ¤ì¤Æ¤¤¤Ê¤¤¡£ +C¥³¥ó¥Ñ¥¤¥é¤È Awk ¥¤¥ó¥¿¡¼¥×¥ê¥¿¡¼¤ÎÆ°¤¯¥Þ¥·¥ó¤Ç¤¢¤ì¤Ð¡¢°Ü¿¢¤Ï´Êñ¤Ê¤Ï¤º¤À¤¬¡¢ +´Ö°ã¤¤¤Ê¤¯¡¢¤¤¤¯¤Ä¤«¤Î½¤Àµ¤¬É¬ÍפǤ¢¤í¤¦¡£ +¤³¤Î¥Þ¥Ë¥å¥¢¥ë¤â´Þ¤ó¤À ´°Á´¤Ê{Spider}¤ÎÇÛÉۤϡ¢anonymous {\tt ftp} +( {\tt princeton.edu:~ftp/pub/spiderweb.tar.Z}) ¤ÇÆþ¼ê¤Ç¤¤ë¡£ +{Spider} ¤ò¥¤¥ó¥¹¥È¡¼¥ë¤¹¤ë¥Ç¥£¥ì¥¯¥È¥ê¡¼¤òÁª¤Ó¡¢ÇÛÉÛ¤µ¤ì¤¿¤â¤Î¤ò untar ¤·¡¢ +%distribution, and follow the directions in the +README ¥Õ¥¡¥¤¥ë¤Î»Ø¼¨¤Ë½¾¤¨¤ÐÎɤ¤¡£ +Áª¤ó¤À¥Ç¥£¥ì¥¯¥È¥ê¡¼¤Ï¡¢{\tt WEBROOT}¤È¤Ê¤ë¡£ + +¤â¤·¡¢ÇÛÉÛ¤ÎÃæ¤Î {\tt Makefile} ¤¬¡¢¾åµ¤Ç¼¨¤·¤¿¤â¤Î¤È°ã¤Ã¤Æ¤¤¤¿¤é¡¢ +ÇÛÉÛ¤ÎÃæ¤Î¤â¤Î¤¬Àµ¤·¤¤¤È¹Í¤¨¤ÆÍߤ·¤¤¡£ + + + + +\pagebreak +\section{¼ÂºÝ¤Î {Spider} ¥Õ¥¡¥¤¥ë} +¤³¤ì¤Þ¤Ç¡¢{Spider}¤Î»È¤¤Êý¤òÀâÌÀ¤¹¤ë¤¿¤á¤Ë¼ÂºÝ¤ÎÎã¤ò»È¤Ã¤Æ¤¤¿¡£ +¤³¤³¤Ç¤Ï¡¢Awk ¸À¸ìÍѤδ°Á´¤Ê {Spider} ¥Õ¥¡¥¤¥ë¤òȯŸ¤·¤¿Îã¤È¤·¤Æ°Ê²¼¤Ë¼¨¤¹¡£ +ÇÛÉÛ¤µ¤ì¤¿¤â¤Î¤ò´Êñ¤Ë¸¦µæ¤Ç¤¤Ê¤¤¿Í¤Ï¡¢¤³¤ì¤¬ÌòΩ¤Ä¤Ç¤¢¤í¤¦¡£ +\begingroup\small +\begin{verbatim} +# Copyright 1989 by Norman Ramsey and Odyssey Research Associates. +# To be used for research purposes only. +# For more information, see file COPYRIGHT in the parent directory. + +language AWK extension awk + +at_sign # + +module definition stmt use stmt +# use as stmt is unavoidable since tangle introduces line breaks + +comment begin <"##"> end newline +macros begin +\def\commentbegin{\#} % we don't want \#\# +macros end + +line begin <"#line"> end <""> + +default translation <*> mathness yes + +token identifier category math mathness yes +token number category math mathness yes +token newline category newline translation <> mathness maybe +token pseudo_semi category ignore_scrap mathness no translation <opt-0> + +token \ category backslash translation <> mathness maybe +token + category unorbinop +token - category unorbinop +token * category binop +token / category binop +token < category binop +token > category binop +token >> category binop translation <"\\GG"> +token = category equals translation <"\\K"> +token ~ category binop translation <"\\TI"> +token !~ category binop translation <"\\not\\TI"> +token & category binop translation <"\\amp"> +token % translation <"\\%"> category binop +token ( category open +token [ category lsquare +token ) category close +token ] category close +token { translation <"\\;\\{"-indent> category lbrace +token } translation <"\\}\\"-space> category close +token , category binop translation <",\\,"-opt-3> + +token ; category semi translation <";"-space-opt-2> mathness no +# stuff with semi can be empty in for statements +open semi --> open +semi semi --> semi +semi close --> close +semi --> binop + +# token : category colon +# token | category bar +token != name not_eq translation <"\\I"> category binop +token <= name lt_eq translation <"\\L"> category binop +token >= name gt_eq translation <"\\G"> category binop +token == name eq_eq translation <"\\S"> category binop +token && name and_and translation <"\\W"> category binop +token || name or_or translation <"\\V"> category binop +# token -> name minus_gt translation <"\\MG"> category binop +token ++ name gt_gt category unop translation <"\\uparrow"> +token -- name lt_lt category unop translation <"\\downarrow"> +# preunop is for unary operators that are prefix only +token $ category preunop translation <"\\DO"> mathness yes + +default mathness yes translation <*> + +ilk pattern_like category math +reserved BEGIN ilk pattern_like +reserved END ilk pattern_like + +ilk if_like category if +reserved if +ilk else_like category else +reserved else + +ilk print_like category math +# math forces space between this and other math... +reserved print ilk print_like +reserved printf ilk print_like +reserved sprintf ilk print_like + + +ilk functions category unop mathness yes +reserved length ilk functions +reserved substr ilk functions +reserved index ilk functions +reserved split ilk functions +reserved sqrt ilk functions +reserved log ilk functions +reserved exp ilk functions +reserved int ilk functions + +ilk variables category math mathness yes +reserved NR ilk variables +reserved NF ilk variables +reserved FS ilk variables +reserved RS ilk variables +reserved OFS ilk variables +reserved ORS ilk variables + +ilk for_like category for +reserved for ilk for_like +reserved while ilk for_like + +ilk in_like category binop translation <math_bin-*-"}"> mathness yes +# translation <"\\"-space-*-"\\"-space> +reserved in ilk in_like + +ilk stmt_like category math +reserved break ilk stmt_like +reserved continue ilk stmt_like +reserved next ilk stmt_like +reserved exit ilk stmt_like + + +backslash newline --> math +# The following line must be changed to make a backslash +backslash <"\\backslash"> --> math + +math (binop|unorbinop) math --> math +<"\\buildrel"> (binop|unorbinop) <"\\over{"> equals <"}"> --> binop +equals --> binop +(unop|preunop|unorbinop) math --> math +# unorbinop can only act like unary op as *prefix*, not postfix +math unop --> math +math <"\\"-space> math --> math +# concatenation + +math newline --> stmt +newline --> ignore_scrap + +stmt <force> stmt --> stmt + +(open|lsquare) math close --> math + +math lbrace --> lbrace +lbrace <force> stmt --> lbrace +lbrace <outdent-force> close --> stmt + +if <"\\"-space> math --> ifmath +ifmath lbrace --> ifbrace +ifmath newline --> ifline +ifbrace <force> stmt --> ifbrace +ifbrace <outdent-force> close else <"\\"-space> if --> if +ifbrace <outdent-force> close else lbrace --> ifbrace +ifbrace <outdent-force> close else newline --> ifline +ifbrace <outdent-force> close --> stmt +(ifline|ifmath) <indent-force> stmt <outdent-force> else <"\\"-space> if --> if +(ifline|ifmath) <indent-force> stmt <outdent-force> else lbrace --> ifbrace +(ifline|ifmath) <indent-force> stmt <outdent-force> else newline --> ifline +(ifline|ifmath) <indent-force> stmt <outdent-force> else --> ifmath +(ifline|ifmath) <indent-force> stmt <outdent> --> stmt + +for <"\\"-space> math --> formath +formath lbrace --> forbrace +formath newline --> forline +forbrace <force> stmt --> forbrace +forbrace <outdent-force> close --> stmt +(forline|formath) <indent-force> stmt <outdent> --> stmt + + +? ignore_scrap --> #1 +\end{verbatim} +\endgroup + + +\newpage +\section{Bibliography} +\begin{thebibliography}{Knuth~999} +\bibitem[Bentley~87]{bentley:pearls} +Jon L. Bentley, ``Programming Pearls,'' {\sl Communications of the +ACM}~{\bf 29:5}(May 1986), 364--?, and {\bf 29:6}(June 1986), +471--483. +ʸ½ñ²½¥×¥í¥°¥é¥ß¥ó¥°¤Ë¤Ä¤¤¤Æ¤Î2¤Ä¤Î¥³¥é¥à¡£ +ºÇ½é¤Î¤â¤Î¤ÏÆþÌçÊÔ¡£ÆóÈÖÌÜ¤Î¤Ï +Donald Knuth ¤Ë¤è¤ë³ÈÄ¥¤µ¤ì¤¿Îã¤Ç +Douglas MacIlroy ¤¬¥³¥á¥ó¥È¤·¤Æ¤¤¤ë¡£ +\bibitem[Knuth~83]{knuth:web} +Donald~E. Knuth, +``The {{\tt WEB}} system of structured documentation'' + Technical Report 980, Stanford Computer Science, Stanford, + California, September 1983. +¥ª¥ê¥¸¥Ê¥ë¤Î {\tt WEB}¤Î¥Þ¥Ë¥å¥¢¥ë¡£ +\bibitem[Knuth~84]{knuth:literate-programming} +Donald E. Knuth, ``Literate Programming,'' {\sl The Computer Journal} +{\bf 27:2}(1984), 97--111. +{\WEB}¤Ë¤è¤ëʸ½ñ²½¥×¥í¥°¥é¥ß¥ó¥°¤Î¥ª¥ê¥¸¥Ê¥ë¤ÎÆþÌç½ñ¡£ +\bibitem[Levy~87]{levy:cweb} +Silvio Levy, ``Web Adapted to C, Another Approach'' {\sl TUGBoat} +{\bf 8:2}(1987), 12--13. +{\WEB}¤ò C ¤Ç¼Â¸½¤¹¤ë¤³¤È¤Ë¤Ä¤¤¤Æ¤Î¾®Êó¹ð½ñ¡£ +¤³¤ì¤«¤é Spidery {\WEB} ¤ÏÇÉÀ¸¤·¤¿¡£ +\bibitem[Sewell~89]{sewell:weaving} +Wayne Sewell, ``Weaving a program: Literate programming in {\tt +WEB},'' +Van Nostrand Reinhold, 1989. +\end{thebibliography} + + +\end{document} diff --git a/web/spiderweb/doc/spe.aux b/web/spiderweb/doc/spe.aux new file mode 100644 index 0000000000..c2471f652f --- /dev/null +++ b/web/spiderweb/doc/spe.aux @@ -0,0 +1,70 @@ +\relax +\citation{knuth:literate} +\citation{bentley:lp1,bentley:lp2,cvw:loom,gries:pearls} +\citation{knuth:tex,knuth:metafont} +\citation{bentley:lp1,bentley:lp2} +\citation{cvw:loom} +\citation{gries:pearls} +\citation{cvw:assessment} +\citation{thimbleby:review} +\citation{knuth:literate,thimbleby:cweb,guntermann:cweb,levy:cweb,sewell:mangle,ramsey:building} +\@writefile{toc}{\string\contentsline\space {section}{Introduction}{2}} +\citation{knuth:literate} +\citation{ramsey:developing,marceau:interactive,guaspari:formal} +\citation{reps:synthesizer:89} +\citation{reps:generating} +\citation{adalrm,polak:predicate} +\citation{marceau:verified,weber:beyond,anderson:asos} +\@writefile{toc}{\string\contentsline\space {section}{Using Literate Programming}{3}} +\citation{polak:predicate,polak:program} +\citation{adalrm} +\citation{ganzinger:operator} +\citation{cvw:assessment} +\citation{thimbleby:review} +\citation{bentley:more-pearls:graphics,bentley:lp2,sedgewick:algorithms} +\@writefile{toc}{\string\contentsline\space {section}{Evaluating {\string\ptt\space WEB}}{5}} +\citation{knuth:tex} +\citation{feldman:make} +\citation{johnson:yacc} +\citation{kernighan:unix} +\citation{ramsey:spiderwebman} +\citation{thimbleby:review} +\citation{parnas:rational} +\@writefile{toc}{\string\contentsline\space {section}{Discussion}{9}} +\citation{reps:synthesizer:89} +\bibstyle{unsrt} +\bibdata{web,ada,cs,ramsey} +\bibcite{knuth:literate}{1} +\bibcite{bentley:lp1}{2} +\bibcite{bentley:lp2}{3} +\bibcite{cvw:loom}{4} +\bibcite{gries:pearls}{5} +\bibcite{knuth:tex}{6} +\bibcite{knuth:metafont}{7} +\bibcite{cvw:assessment}{8} +\@writefile{toc}{\string\contentsline\space {section}{Acknowledgments}{11}} +\bibcite{thimbleby:review}{9} +\bibcite{thimbleby:cweb}{10} +\bibcite{guntermann:cweb}{11} +\bibcite{levy:cweb}{12} +\bibcite{sewell:mangle}{13} +\bibcite{ramsey:building}{14} +\bibcite{ramsey:developing}{15} +\bibcite{marceau:interactive}{16} +\bibcite{guaspari:formal}{17} +\bibcite{reps:synthesizer:89}{18} +\bibcite{reps:generating}{19} +\bibcite{adalrm}{20} +\bibcite{polak:predicate}{21} +\bibcite{marceau:verified}{22} +\bibcite{weber:beyond}{23} +\bibcite{anderson:asos}{24} +\bibcite{polak:program}{25} +\bibcite{ganzinger:operator}{26} +\bibcite{bentley:more-pearls:graphics}{27} +\bibcite{sedgewick:algorithms}{28} +\bibcite{feldman:make}{29} +\bibcite{johnson:yacc}{30} +\bibcite{kernighan:unix}{31} +\bibcite{ramsey:spiderwebman}{32} +\bibcite{parnas:rational}{33} diff --git a/web/spiderweb/doc/spe.bbl b/web/spiderweb/doc/spe.bbl new file mode 100644 index 0000000000..fe18d98426 --- /dev/null +++ b/web/spiderweb/doc/spe.bbl @@ -0,0 +1,186 @@ +\begin{thebibliography}{10} + +\bibitem{knuth:literate} +Donald~E. Knuth. +\newblock Literate programming. +\newblock {\em The Computer Journal}, 27(2):97--111, 1984. + +\bibitem{bentley:lp1} +Donald~E. Knuth and Jon~L. Bentley. +\newblock Programming pearls: Literate programming. +\newblock {\em Communications of the ACM}, 29(5):364--368, May 1986. + +\bibitem{bentley:lp2} +Donald~E. Knuth. +\newblock Programming pearls: A literate program. +\newblock {\em Communications of the ACM}, 29(6):471--483, June 1986. +\newblock Reviewed by M. Douglas McIlroy. + +\bibitem{cvw:loom} +David~R. Hanson. +\newblock Literate programming: Printing common words. +\newblock {\em Communications of the ACM}, 30(7):593--599, July 1987. +\newblock Reviewed by John Gilbert. + +\bibitem{gries:pearls} +David Gries and Jon Bentley. +\newblock Programming pearls: Abstract data types. +\newblock {\em Communications of the ACM}, 30(4):284--290, April 1987. + +\bibitem{knuth:tex} +Donald~E. Knuth. +\newblock {\em {{\TeX}}: The Program}, volume~B of {\em Computers \& + Typesetting}. +\newblock Addison-Wesley, 1986. + +\bibitem{knuth:metafont} +Donald~E. Knuth. +\newblock {\em {{\metafont}}: The Program}, volume~D of {\em Computers \& + Typesetting}. +\newblock Addison-Wesley, 1986. + +\bibitem{cvw:assessment} +Christopher~J. Van~Wyk. +\newblock Literate programming: An assessment. +\newblock {\em Communications of the ACM}, 33(3):361--365, March 1990. + +\bibitem{thimbleby:review} +Harold Thimbleby. +\newblock A review of {Donald} {C}. {L}indsay's text file difference utility, + {{\em diff}}. +\newblock {\em Communications of the ACM}, 32(6):752--755, June 1989. + +\bibitem{thimbleby:cweb} +Harold Thimbleby. +\newblock Experiences of `literate programming' using cweb (a variant of + {K}nuth's {WEB}). +\newblock {\em Computer Journal}, 29(3):201--211, 1986. + +\bibitem{guntermann:cweb} +Klaus Guntermann and Joachim Schrod. +\newblock {{\tt WEB}} adapted to {C}. +\newblock {\em {TUG}boat}, 7(3):134--137, October 1986. + +\bibitem{levy:cweb} +Silvio Levy. +\newblock {\tt WEB} adapted to {C}, another approach. +\newblock {\em TUGBoat}, 8(1):12--13, 1987. + +\bibitem{sewell:mangle} +Wayne Sewell. +\newblock How to {{\tt MANGLE}} your software: the {{\tt WEB}} system for + {M}odula-2. +\newblock {\em {TUG}boat}, 8(2):118--128, July 1987. + +\bibitem{ramsey:building} +Norman Ramsey. +\newblock {L}iterate programming: {\hskip 0pt plus 0.5em}{W}eaving a + language-independent {{\tt WEB}}. +\newblock {\em Communications of the ACM}, 32(9):1051--1055, September 1989. + +\bibitem{ramsey:developing} +Norman Ramsey. +\newblock Developing formally verified {A}da programs. +\newblock In {\em Proceedings of the 5th International Workshop on Software + Specification and Design}, pages 257--265, Pittsburgh, Pennsylvania, May + 1989. + +\bibitem{marceau:interactive} +Carla Marceau and C.~Douglas Harper. +\newblock An interactive approach to {A}da verification. +\newblock In {\em Proceedings of the 12th National Computer Security + Conference}, pages 28--51, Baltimore, Maryland, October 1989. + +\bibitem{guaspari:formal} +David Guaspari, Carla Marceau, and Wolfgang Polak. +\newblock Formal verification of {A}da programs. +\newblock {\em IEEE Transactions on Software Engineering}, 16(9):1058--1075, + September 1990. + +\bibitem{reps:synthesizer:89} +Thomas Reps and Tim Teitelbaum. +\newblock {\em The {S}ynthesizer {G}enerator Reference Manual}. +\newblock Springer-Verlag, 1989. + +\bibitem{reps:generating} +Thomas Reps. +\newblock {\em Generating Language-Based Environments}. +\newblock MIT Press, 1984. + +\bibitem{adalrm} +{US Department of Defense}. +\newblock {\em The {A}da Programming Language Reference Manual}, 1983. +\newblock ANSI/MILSTD~1815A. + +\bibitem{polak:predicate} +Wolfgang Polak. +\newblock Predicate transformer semantics for {A}da. +\newblock Technical Report 89-39, Odyssey Research Associates, September 1989. + +\bibitem{marceau:verified} +Carla Marceau and Geoffrey Hird. +\newblock A verified software implementation of an {RS}-232 repeater using + {P}enelope. +\newblock Technical Report 90-12, Odyssey Research Associates, 1990. + +\bibitem{weber:beyond} +D.~G. Weber and Roger~L. Costello. +\newblock Beyond {A1} using {A}da code verification. +\newblock Technical Report 89-9, Odyssey Research Associates, April 1989. + +\bibitem{anderson:asos} +Eric~R. Anderson, Ben DiVitto, and Ruth~M. Hart. +\newblock {ASOS}: Information security for real-time systems. +\newblock In {\em {AFCEA} West Intelligence Symposium}, 1987. + +\bibitem{polak:program} +Wolfgang Polak. +\newblock Program verification based on denotational semantics. +\newblock In {\em ACM Symposium on Principles of Programming Languages}, pages + 149--158. Association for Computing Machinery, 1981. + +\bibitem{ganzinger:operator} +H.~Ganzinger and K.~Ripken. +\newblock Operator identification in {A}da. +\newblock {\em ACM SIGPLAN Notices}, 15(2):30--42, February 1980. + +\bibitem{bentley:more-pearls:graphics} +Jon Bentley. +\newblock {\em More Programming Pearls: Confessions of a Coder}, chapter 10 and + 11, pages 101--126. +\newblock Addison-Wesley, 1988. + +\bibitem{sedgewick:algorithms} +Robert Sedgewick. +\newblock {\em Algorithms}. +\newblock Addison-Wesley, second edition, 1988. + +\bibitem{feldman:make} +Stuart~I. Feldman. +\newblock Make---a program for maintaining computer programs. +\newblock {\em Software---Practice and Experience}, 9:255--265, 1979. + +\bibitem{johnson:yacc} +Steve~C. Johnson. +\newblock Yacc---yet another compiler compiler. +\newblock Technical Report~32, Computer Science, AT\&T Bell Laboratories, + Murray Hill, New Jersey, 1975. + +\bibitem{kernighan:unix} +Brian~W. Kernighan and Rob Pike. +\newblock {\em The {UNIX} Programming Environment}. +\newblock Prentice-Hall, 1984. + +\bibitem{ramsey:spiderwebman} +Norman Ramsey. +\newblock The {S}pidery {{\tt WEB}} system of structured documentation. +\newblock Technical Report TR-226-89, Department of Computer Science, Princeton + University, August 1989. + +\bibitem{parnas:rational} +David~Lorge Parnas and Paul~C. Clements. +\newblock A rational design process: How and why to fake it. +\newblock {\em IEEE Transactions on Software Engineering}, SE-12(2):251--257, + February 1986. + +\end{thebibliography} diff --git a/web/spiderweb/doc/spe.tex b/web/spiderweb/doc/spe.tex new file mode 100644 index 0000000000..4a4dc42416 --- /dev/null +++ b/web/spiderweb/doc/spe.tex @@ -0,0 +1,545 @@ +\documentstyle[11pt]{article} +\title {Literate Programming on a Team Project\thanks{This research +has been sponsored in part by the USAF, Rome Air Development Center, under +contract number F30602--86--C--0071. +The first author gratefully acknowledges the support of the Fannie and +John Hertz Foundation. +This paper is reprinted from {\em Software---Practice \& Experience}, 21(7):677--683, July 1991.}} +\author{Norman Ramsey\thanks{Current address: Department of Computer +Science, Princeton University, Princeton, New Jersey 08544.} + \hskip3pt and Carla Marceau\\\mbox{}\\Odyssey Research Associates\\ +301A Harris B. Dates Drive\\Ithaca, New York 14850} +\date{February 4, 1991} +\setcounter{secnumdepth}{0} +\setcounter{tocdepth}{6} +\renewcommand{\baselinestretch}{1.33} + +\makeatletter +\def\refno#1{\nocite{#1}\@ifundefined + {b@#1}{{\bf ?}\@warning + {Reference number `#1' on page \thepage \space undefined}}% +{\hbox{\csname b@#1\endcsname}}} +\makeatother + +\def\remark#1{\marginpar{\raggedright\hbadness=10000\footnotesize\it #1}} +% \def\remark#1{\relax} +\let\logo=\sc +\font\logo=logo10 +\def\metafont{{\logo METAFONT}} + + +\begin{document} % 1 +\clubpenalty=10000 +\widowpenalty=10000 +\maketitle + +\begin{abstract} % 2 +% % We used {\tt WEB} on a group project to write a large program, over +% % 33,000~lines. +% % The program was not intended to be published. +% % We encountered many problems using {\tt WEB}, but we believe we are +% % better off for having used it. +% % We describe both the problems and why we believe {\tt WEB} was +% % beneficial despite them. +% We used literate programming, with {\tt WEB}, on a group project to +% write a program of +% over 33,000~lines. +% The program, Penelope, was not intended to be published, but the +% literate source has served as good internal documentation through +% development and maintenance. +% Using {\tt WEB} without help from its developer uncovered a number of +% problems, which are described below. +% Despite the problems, {\tt WEB} has been effective in helping us +% document the design and implementation of Penelope. +We used literate programming on a team project to write a 33,000-line +program for the Synthesizer Generator. The program, Penelope, was +written using {\tt WEB}, a tool designed for writing literate +programs. Unlike other {\tt WEB} programs, many of which have been +written by {\tt WEB}'s developer or by individuals, Penelope was not +intended to be published. We used {\tt WEB} in the hope that +both our team and its final product would benefit from the advantages +often attributed to literate programming. The {\tt +WEB} source served as good internal documentation throughout +development and maintenance, and it continues to document Penelope's +design and implementation. +Our experience also uncovered a number of +problems with {\tt WEB}. +\end{abstract} % 2 + + +\section{Introduction} + +Donald Knuth coined the term ``literate programming'' when describing +{\tt WEB}, the tool he used to build \TeX~\cite{knuth:literate}. +He believes that ``the time is ripe for significantly better +documentation of programs, and that we can best achieve this by +considering programs to be {\em works of literature}.'' +Knuth and others have presented examples of such +programs~\cite{bentley:lp1,bentley:lp2,cvw:loom,gries:pearls}. + + +Literate programming is usually discussed in the context of +publishing programs or of publishing books or articles about programs. +\TeX\ and {\metafont}, the original applications of {\tt WEB}, +have been published as books~\cite{knuth:tex,knuth:metafont}. +Other published literate programs seem to be primarily for teaching. +Programs to find random sequences and count common words +were written to illustrate the power of literate +programming~\cite{bentley:lp1,bentley:lp2}. +Another program to count common words +is a tutorial on how to +develop and tune a small program~\cite{cvw:loom}. +Another illustrates formal methods of program +development and the use of abstract data types~\cite{gries:pearls}. + + +A valedictory assessment points out three common aspects of the published +literate programs: cosmetics, polish, and verisimilitude, of which +verisimilitude---the property of using one input to produce both +compilable program and published document--is deemed +essential~\cite{cvw:assessment}. +Additional expectations of a literate +programming tool include flexible order of elaboration, +ability to develop program and documentation concurrently in one +place, cross-references, and indexing~\cite{thimbleby:review}. + +{\tt WEB} is the principal tool used for literate programming; a +number of implementations are +available~\cite{knuth:literate,thimbleby:cweb,guntermann:cweb,levy:cweb,sewell:mangle,ramsey:building}. +{\tt WEB} programmers + interleave source code and descriptive text in a single document. +When using {\tt WEB}, a programmer divides the source code into +small textual units called {\em modules}, and each module carries +associated documentation. +In the {\tt WEB} source, different modules may +be written in any order. + The programmer is encouraged to choose an +order that helps explain the program. +The modules are like macro definitions; they have +the form +\begin{quote} % 2 +\tt@<{\em module name\/}@>={\em body} +\end{quote} % 2 +where the body contains both code and references to other modules. +{\tt WEB} programmers can also define and use macros similar to +C~preprocessor macros. + One module is unnamed; its body represents the underlying program. + +Two filters process {\tt WEB} source. + {\tt TANGLE} reads the {\tt WEB} source and expands the +unnamed module according to its definition. +References to named modules are expanded where they occur, and the end +result is that {\tt TANGLE} extracts the underlying program from the +{\tt WEB} source. +This program is formed from the code fragments that the programmer put +into the module definitions, assembled in the order required by the compiler. +A second filter, {\tt WEAVE}, reads the {\tt WEB} source and converts +it to \TeX\ input, with which {\TeX} can produce +high-quality typeset documentation of the program. +Examples of {\tt WEB} source and typeset documentation can be found in +Reference~\refno{knuth:literate}. + + +\section{Using Literate Programming} + + Penelope is a language-based editor intended to help +programmers develop formally verified Ada +programs~\cite{ramsey:developing,marceau:interactive,guaspari:formal}. +It parses annotated Ada programs, +performs static semantic checking and overload resolution, +computes weakest preconditions by predicate transformation, +simplifies the resulting preconditions, +and +helps users construct proofs of those preconditions. +Its source code is +an editor specification for +the Synthesizer Generator~\cite{reps:synthesizer:89}. +The Synthesizer Generator builds an editor of attributed syntax +trees. +When a user defines a tree, the editor attributes it. +When the user changes the tree, +the editor recomputes only those attribute values that have +changed~\cite{reps:generating}. + +Penelope has two written specifications: the Ada language +reference manual and a denotational-style definition of Ada predicate +transformers~\cite{adalrm,polak:predicate}. +After three years of work, the {\tt WEB} source for the editor +is over 33,000 lines. +Over 13,000 of those lines are interleaved documentation. +The editor has been used to verify a software repeater for an +asynchronous +communication line +and security properties of a part of the +ASOS operating system +kernel~\cite{marceau:verified,weber:beyond,anderson:asos}. +Seven programmers have written {\tt WEB} source, +but no more than four have worked +on it at any one time. +At this writing, the editor is being extended +to support Ada libraries. % programs that use data abstraction. + +We decided to write the editor as a literate program because +we expected implementing predicate +transformation to be error-prone. +To avoid errors, we used {\tt WEB} to juxtapose +the specification and implementation of +each predicate transformer. +We used {\TeX}'s math mode to write the specifications in the notation +of denotational semantics.~\cite{polak:predicate,polak:program}. + +The right model for a literate program that is being maintained and +extended is not the novel but the car repair manual. +We began writing new code as an +explanation or tutorial for our colleagues, but +as the text grew we treated it more like a reference work. +As with any document, we revised repeatedly to clarify meaning. +We often used +{\tt TANGLE}'s reordering mechanism to make major revisions in the +{\tt WEB} source without changing the underlying program. +% Parnas and Clements say this; see {parnas:rational} + + +We divided Penelope into parts according to functionality: +we wrote chapters on +abstract syntax, +concrete syntax, +predicate transformation, +static semantic checking, +proof construction, +and simplification of terms. +Each of the first four chapters follows the structure of the Ada +Language Reference Manual, since each is closely related to +Ada. +Only knowledge of the Ada manual is required to navigate this code; +a reader who knows where to find the +{\tt exit} statement in the Ada manual can find the predicate +transformation of the {\tt exit} statement in the corresponding +section of the predicate transformation chapter. +We gave the final chapters structures related to the problems of +simplification and proof construction. + + +Penelope has grown so large that each chapter +is itself structured like a reference work. + Sections within chapters have a different structure. +They are tutorials that use the traditional approach +to documentation: begin with a problem statement or specification, +discuss possible solutions, explain the design of the preferred +solution, then develop the implementation and its description. +A short introductory chapter describes the major parts of the program +the organization used to form the text. +A ``how to find it'' section helps readers find source code. + +We have used the Penelope source +not only for reference but also to introduce new programmers to the +project. % ??? +% For example, as a prelude to extending the +% Ada subset handled by Penelope, a new project member might read Chapter +% 6 of the Red Dragon Book and also the chapter of Penelope on static +% semantic checking. + + + + +We used some of the cosmetic features of {\tt WEB}; +we found +tables of variables, functions, and files all useful to describe the +organization of the code. +When working on Ada static semantic checking, we found it useful to +include in the {\tt WEB} source some fragments of relevant documents. +The fragments included visibility and overloading rules from the Ada reference +manual~\cite{adalrm} and a presentation of the Ada type system derived +from Reference~\refno{ganzinger:operator}. + + +\section{Evaluating {\tt WEB}} + + Using {\tt WEB} without help from its developer uncovered a number of +problems. +Some problems relate to the criteria in References +\refno{cvw:assessment}~and~\refno{thimbleby:review}, but others do not. + +We had no trouble with +{\tt WEB}'s fundamental mechanisms, the section and +the named module. +They provide verisimilitude and flexible order of elaboration. +The small size of modules makes it feasible to develop code and +documentation in one place using an ordinary text editor. +The order of fragments is the same in the {\tt WEB} source and in the +published document, which simplifies polishing. + +\medskip +We found some of {\tt WEB}'s cosmetic features inadequate, others +superfluous. +Cosmetics should include appropriate media for presenting programs: +not just math and tables but also diagrams and +figures~\cite{bentley:more-pearls:graphics,bentley:lp2,sedgewick:algorithms}. + Describing data structures was hampered by {\TeX}'s lack of support for +diagrams and pictures. +{\TeX} does make it easy to use mathematical notation, which + helped considerably in describing + predicate transformation, + the simplifier, and + the proof system used in the proof constructor. + +Programmers complained more about prettyprinting than about all other {\tt WEB} +problems combined. +{\tt WEAVE} ignores the programmer's choice of indentation +and line breaks; it breaks and indents lines on the basis of +the syntactic categories of tokens. +(Programmers can force line breaks by inserting special control sequences +like {\tt@/} into their program text, but that's about all.) +We spent too much time tinkering +with prettyprinting, trying to make {\tt WEAVE}'s output +acceptable to everyone. +We would have been better off with no prettyprinter, or with a +prettyprinter that changed +only the typographic treatment of program fragments without changing +the placement of tokens on the page. + +We used the index of identifiers + during reviews only, usually to find function definitions +and to locate code that had been misplaced. + +\medskip +{\tt WEB} formats interleaved documentation using {\TeX}, which some +programmers already use for writing documents. +{\tt WEB} and {\TeX} are integrated poorly. +One cannot lift pieces of {\tt WEAVE}'s output and put them in other +documents without adjusting the \TeX\ code. +{\tt WEB} works even less well with \LaTeX; \LaTeX\ constructs cannot +be used in {\tt WEB} source, and getting {\tt WEAVE} output +to work in \LaTeX\ documents requires tedious adjustments by hand. +The other direction is easier; +we wrote project documents using \LaTeX, and, with some adjustments, +we could include excerpts from these documents in our code. +%%%%%%%% Carla wants no more details +% \remark{I can give more details. For example, the {\tt webmac} macros +% should make it easy to pull out the {\tt WEAVE} output routine and use +% a plain \TeX\ or \LaTeX output routine---but they don't. +% This is a sore point with me.} +%%%%%%%%% + We were accustomed to writing \LaTeX\ documents, +so it was annoying to be forced to switch to plain +\TeX\ to write programs. + +% \paragraph{Editing {\tt WEB} source} +\medskip + +\TeX's input often looks very different from \TeX's output, especially +when mathematics is used. +Similarly, {\tt WEB} source looks very different from the typeset +document produced by {\tt WEAVE} and {\TeX}. +When people use \TeX\ to write papers, +it may be acceptable for the \TeX\ input to be full of +confusing hieroglyphics, because the {\TeX} input is almost never +read---only the printed version is read. +{\tt WEB} source is read frequently because programmers must edit it. +Both the difficulty of reading the source and the marked difference between +source and listing complicate editing. + +\medskip % \paragraph{Structuring the document} + +{\tt WEAVE}'s standard table of contents mechanism is a list of +section names. + (A section is a named group of modules together with their +interleaved documentation.) +This flat structure is inadequate for +describing even a moderate-sized program. +Extra structure in the form of ``parts'' has been added to +the book version of {\TeX}; a part contains several +sections~\cite{knuth:tex}. + + +We changed {\tt WEAVE}'s table of contents mechanism to make +hierarchical organization possible. + The new mechanism supports +chapters, sections, and two levels of subsections. +We did so without changing {\tt WEAVE} itself; instead we changed the +\TeX\ macros that support {\tt WEAVE}. +The new macros recognize special symbols at the beginnings of section +names; these symbols indicate which sections are really chapters, +subsections, and so on. +Using this hierarchy made the table of contents +an important guide to the code; +the only practical way to find a particular part of the editor code +was to begin with the table of contents. + + + + +The {\tt WEAVE} listing of Penelope is over 800~pages; +its table of contents is about 8~pages. +We needed to extract and print parts of this document, +but {\tt WEAVE} processes only complete documents. +We extracted parts in two ways. +When we wanted just a few, small, closely related parts, we created a +special {\tt WEB} file that held just those parts, and printed it. +For something more general, we used a shell script that +removed parts of {\tt WEAVE}'s output before passing the rest to {\TeX}. +This script recognized the special symbols in the section names so that, for +example, we could include or exclude whole chapters by name, +without having to +enumerate their contents. +It would have been more expensive, and no less awkward, to use +standard mechanisms for extracting pages from {\TeX}'s output. + +Special symbols in section names are an awkward way of indicating +structure. + A more natural way of indicating structure, like the +{\LaTeX} mechanism, would have been welcome. +Tools should make it easy to use the + structure to help readers extract excerpts from literate +programs. + +\medskip % \paragraph{Fit with configuration management tools} + + {\tt WEB} works poorly with {\tt make}~\cite{feldman:make}. + {\tt TANGLE} is designed to read and write a complete program. +Some {\tt TANGLE}s can write multiple files, +which can then be compiled separately, but +those files all get rewritten + every time the {\tt WEB} source changes, +and {\tt make} therefore recompiles them all. +This problem is familiar; +other preprocessors, like {\tt yacc}~\cite{johnson:yacc}, can also +cause excessive recompilation. +The workaround described on page 265 of +Reference~\refno{kernighan:unix} works for {\tt TANGLE}. +%%%%%%%% Carla wants no more details +% \remark{Workaround doesn't help too much when the output +% from {\tt TANGLE} includes information about source line numbers?} +%%%%%%%%% + +{\tt WEB} users may be tempted +to break their {\tt WEB} source into many files and run them through +{\tt TANGLE} separately. +Doing so defeats the purpose of writing a literate +program; separate compilation does not necessarily imply separate +explanation. +For example, one would prefer to place a +unit's specification and implementation in the same {\tt WEB} +source, even when +they should be compiled separately. + +\medskip % \paragraph{Fit with compilers and debuggers} + +Our {\tt TANGLE}~\cite{ramsey:spiderwebman} emits +the {\tt\#line} directive of the C preprocessor, making +messages from compilers and debuggers refer to line numbers in +the {\tt WEB} source instead of to those in {\tt TANGLE}'s output. +Not all compilers or all {\tt TANGLE}s support such mechanisms. +Renumbering is essential for large programs. + + + + + +\section{Discussion} + +Most literate programming papers refer to programs that are +polished, publishable ``works of art.'' +Our primary goal in writing Penelope +was not to write a publishable program, nor to +evaluate literate programming as a software engineering technique, +but to build a prototype editor embodying the results +of research in formal verification. +Our experience has given us some subjective +impressions of the benefits of applying literate programming +to team development, as well as more specific conclusions about +the difficulties of applying literate programming. + +There are few published techniques for writing literate +programs, especially for writing large ones. +Most of our programmers complained about the awkward tools and about +the lack of guidance in their use. +We were unable to develop precise methods for writing literate +programs or even clear criteria about what constituted a +literate program. +Instead, we relied on peer review of programs, rewriting them +until the project members understood them. +These programs were rarely polished to the point necessary for +publication; less polished presentations were adequate. + +One review of a literate program emphasizes the role of +juxtaposed code and documentation~\cite{thimbleby:review}. +It cites several benefits of this juxtaposition, including an +incentive to explain and hence to understand what one is doing. +During peer reviews of Penelope, +we insisted that explanations of programs include explanations of design. +% this insistence mitigated against the +% tendency of programmers to begin implementing without thinking about +% design. +% We found that +% the juxtaposition reduced the overhead +% involved in maintenance; +Juxtaposing design documentation and code reduced the overhead of +maintenance because maintainers reading the code did not have to look +elsewhere for design documents. + +We cannot say to what extent literate programming can replace +standard software development methodology. However, putting a +clear description of design in our source code helped make it possible +for a changing team of programmers to develop it over a span of three +years. We were able to apply standard guidelines, like those in +Reference~\refno{parnas:rational}, to describing Penelope's design. + +We believe +literate programming helped us substantially. +This belief is based not on measurements but on our subjective +comparisons of experience on this project to other projects. +A programmer who has used standard software development systems at an +international computer manufacturing company reports that a key +difference in Penelope was that the documentation was {\em used}, precisely +because of its proximity to the source code. +The project manager, when at a large software house, +learned to expect technical staff first to criticize +implementations +for drifting away from the original intent, then to +call for complete rewrites. +There have been no complaints about the quality of Penelope's +implementation. +The programmers have been surprised at how easily they have extended +and modified one another's work. +For example, an editor for constructing proofs was implemented by a +programmer who then left the project. +The programmer who took over the job of maintaining the proof +constructor read the program in two hours and found herself well +prepared to change the code. + +We do not ascribe Penelope's success purely to literate programming; +other factors contributed. +We began implementation with a clearly defined +goal and worked from detailed, sometimes formal, specifications. +We had time to design the system carefully and used a declarative +programming language. +We did not have to develop a user interface but used the one provided +by the Synthesizer Generator~\cite{reps:synthesizer:89}. + + +We will continue to use literate programming +for Penelope and for future projects. +{\tt WEB}'s problems are such that we believe it will be +cost-effective for future projects to develop literate programming +tools that address some of the criticisms presented here. + + +\section{Acknowledgments} +Silvio Levy provided his {\tt CWEB} implementation as a base for the +{\tt WEB} used to implement the Penelope editor. +The staff of the Ada Verification project at Odyssey Research made +possible the experience with Penelope on which this paper is based. +This paper has been much improved by comments from David Hanson and +from the anonymous referees. +Stuart Feldman commented on this paper and discussed ideas for better +tools. + +\bibliographystyle{unsrt} +\bibliography{web,ada,cs,ramsey} + +%\newpage +%\tableofcontents + +\end{document} % 1 + diff --git a/web/spiderweb/doc/spiderman.aux b/web/spiderweb/doc/spiderman.aux new file mode 100644 index 0000000000..a5db7cabc5 --- /dev/null +++ b/web/spiderweb/doc/spiderman.aux @@ -0,0 +1,56 @@ +\relax +\citation{knuth:literate-programming} +\citation{levy:cweb} +\citation{knuth:literate-programming} +\citation{sewell:weaving} +\@writefile{toc}{\string\contentsline\space {section}{Introduction}{1}} +\@writefile{toc}{\string\contentsline\space {paragraph}{Prerequisites}{2}} +\@writefile{toc}{\string\contentsline\space {paragraph}{Plan of this guide}{2}} +\@writefile{toc}{\string\contentsline\space {section}{How {\string\ptt\space WEAVE} and {\string\ptt\space TANGLE} see the world}{2}} +\@writefile{toc}{\string\contentsline\space {paragraph}{Lexical analysis in {{\string\ptt\space WEB}}}{2}} +\@writefile{toc}{\string\contentsline\space {section}{Using {Spider} to tell {{\string\ptt\space WEB}} how to tokenize}{4}} +\@writefile{toc}{\string\contentsline\space {section}{Using {Spider} to tell {\string\ptt\space WEAVE} how to reduce scraps}{5}} +\@writefile{toc}{\string\contentsline\space {section}{Syntax of {\string\ptt\space spider} files}{6}} +\@writefile{toc}{\string\contentsline\space {paragraph}{Comments and blank lines}{6}} +\@writefile{toc}{\string\contentsline\space {paragraph}{Fields}{6}} +\@writefile{toc}{\string\contentsline\space {subsection}{Translations}{7}} +\@writefile{toc}{\string\contentsline\space {paragraph}{Restricted translations}{8}} +\@writefile{toc}{\string\contentsline\space {subsection}{{\string\ptt\space token} commands}{8}} +\@writefile{toc}{\string\contentsline\space {paragraph}{Token descriptions}{8}} +\@writefile{toc}{\string\contentsline\space {paragraph}{Token designators}{9}} +\@writefile{toc}{\string\contentsline\space {subsection}{Reserved word tokens}{11}} +\@writefile{toc}{\string\contentsline\space {section}{Syntax of the prettyprinting grammar}{11}} +\@writefile{toc}{\string\contentsline\space {paragraph}{Matching the left hand side of a production}{12}} +\@writefile{toc}{\string\contentsline\space {paragraph}{Firing a production}{13}} +\@writefile{toc}{\string\contentsline\space {subparagraph}{Side effects of firing a production}{13}} +\@writefile{toc}{\string\contentsline\space {paragraph}{If no initial subsequence matches any production}{13}} +\@writefile{toc}{\string\contentsline\space {section}{Examples of {\string\ptt\space WEAVE} grammars}{13}} +\@writefile{toc}{\string\contentsline\space {paragraph}{Short examples}{14}} +\@writefile{toc}{\string\contentsline\space {paragraph}{Expressions}{14}} +\@writefile{toc}{\string\contentsline\space {paragraph}{Conditional statements}{16}} +\@writefile{toc}{\string\contentsline\space {paragraph}{Handling preprocessor directives in C}{16}} +\@writefile{toc}{\string\contentsline\space {subsection}{Using context-dependent productions}{17}} +\@writefile{toc}{\string\contentsline\space {paragraph}{Underlining the index entry for the name of a declared function}{17}} +\@writefile{toc}{\string\contentsline\space {paragraph}{Conditional expressions}{17}} +\@writefile{toc}{\string\contentsline\space {subsection}{Debugging a prettyprinting grammar}{18}} +\@writefile{toc}{\string\contentsline\space {section}{The rest of the {Spider} language}{18}} +\@writefile{toc}{\string\contentsline\space {subsection}{Naming the target language}{19}} +\@writefile{toc}{\string\contentsline\space {subsection}{Defining {T\kern -.1667em\lower .5ex\hbox {E}\kern -.125emX} macros}{19}} +\@writefile{toc}{\string\contentsline\space {subsection}{Setting default token information}{20}} +\@writefile{toc}{\string\contentsline\space {subsection}{Specifying the treatment of modules}{20}} +\@writefile{toc}{\string\contentsline\space {subsection}{Determining the at sign}{20}} +\@writefile{toc}{\string\contentsline\space {paragraph}{Changing control sequences}{21}} +\@writefile{toc}{\string\contentsline\space {subsection}{Comments in the programming language}{21}} +\@writefile{toc}{\string\contentsline\space {subsection}{Controlling line numbering}{22}} +\@writefile{toc}{\string\contentsline\space {subsection}{Showing the date of generation}{22}} +\@writefile{toc}{\string\contentsline\space {section}{Spider's error messages}{23}} +\@writefile{toc}{\string\contentsline\space {section}{{Spider}'s output files}{24}} +\@writefile{toc}{\string\contentsline\space {section}{Using {Spider} to make {{\string\ptt\space WEB}} (the {Spider} tools)}{24}} +\@writefile{toc}{\string\contentsline\space {section}{Getting your own Spidery {\string\ptt\space WEB}}{29}} +\@writefile{toc}{\string\contentsline\space {section}{A real {Spider} file}{29}} +\bibcite{bentley:pearls}{Bentley\penalty \@M \ 87} +\bibcite{knuth:web}{Knuth\penalty \@M \ 83} +\bibcite{knuth:literate-programming}{Knuth\penalty \@M \ 84} +\@writefile{toc}{\string\contentsline\space {section}{Bibliography}{33}} +\bibcite{levy:cweb}{Levy\penalty \@M \ 87} +\bibcite{sewell:weaving}{Sewell\penalty \@M \ 89} diff --git a/web/spiderweb/doc/spiderman.tex b/web/spiderweb/doc/spiderman.tex new file mode 100644 index 0000000000..e59087373d --- /dev/null +++ b/web/spiderweb/doc/spiderman.tex @@ -0,0 +1,1693 @@ +% Copyright 1989 by Norman Ramsey and 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 + +% spiderman.tex, with apologies to Stan Lee + +\documentstyle[11pt]{article} +\setcounter{secnumdepth}{0} +\newcommand{\syntax}[1]{\mbox{$\langle\hbox{\sl #1\/}\rangle$}} +\newcommand{\produces}{\mbox{${}::={}$}} +\newcommand{\opt}[1]{$[$#1$]$} +\newcommand{\BS}{\relax} +\chardef\BS=`\\ % backslash in a string + +\title{A {Spider} User's Guide} +\author{Norman Ramsey\\Department of Computer Science\\Princeton University} +\date{July 1989} +\newcommand {\WEB}{{\tt WEB}} + +\begin{document} +\maketitle + +\section{Introduction} +Donald Knuth developed the {\tt WEB} system of structured documentation +as part of the {\TeX} project~\cite{knuth:literate-programming}. +{\WEB} enables a programmer to divide his or her program into chunks (called +{\em modules}), to associate text with each chunk, and to present the +chunks in in any order. +In Knuth's implementation, the chunks are pieces of PASCAL programs, +and the chunks are formatted using {\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 anything +but PASCAL programs using {\tt WEB}. +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, {Spider}, which complements {\tt WEAVE} +and {\tt TANGLE}. +{Spider} reads a description of a programming language, and writes +source code for a {\tt WEAVE} and {\tt TANGLE} which support that +language. +Using {Spider}, a C~compiler, and an Awk~interpreter, an experienced +systems programmer can generate a {\tt WEB} system for +an Algol-like language in a few hours. + +This document explains how to use {Spider} to generate a {\WEB} +system for any programming language. +(The choice of programming language is limited only by the lexical +structure built into Spidery {\tt WEB}, as we shall see.) +You should consult the companion document, ``The Spidery {\WEB} system of +structured documentation,'' to learn how to use the generated {\WEB} system. + +\paragraph{Prerequisites} +If you are going to use {Spider} to build a {\WEB} system, +you should be comfortable using {\tt WEB}. +To get an idea how {\tt WEB} works, you should have read Knuth's +introductory article +on {\WEB}~\cite{knuth:literate-programming}, as well as the {\WEB} +users' manual. +(The {\WEB} user's manual is pretty heavy going, so you may want to +consult the Bibliography for more introductory material on {\WEB}. +Wayne Sewell's {\it Weaving a Program: Literate Programming in {\tt +WEB}} +may be helpful~\cite{sewell:weaving}.) + +In what follows we will assume that you know what {\tt WEAVE} and {\tt +TANGLE} are, what input they expect, and what output they produce. + +\paragraph{Plan of this guide} +We'll begin with a review of weaving and tangling, so that we can get +an idea what is necessary to build a language-independent {\WEB}. +Then we'll present a discussion of the features of {Spider} that +tell {\WEB} about the programming language. +We'll define these in detail and give some examples, and then +we'll close with a complete description of the {Spider} language +and tools. + +\section{How {\tt WEAVE} and {\tt TANGLE} see the world} +Both {\tt WEAVE} and {\tt TANGLE} operate on the same input, a {\WEB} +file. +{\tt WEAVE} must examine this input and produce a {\TeX} text, while +{\tt TANGLE} must produce a program text from the same input. +The input consists of {\TeX} parts, definition parts, and code parts. +The {\TeX} parts are the easiest to consider: {\tt WEAVE} just copies +them and {\tt TANGLE} throws them away. +The definition parts are a bit more complicated: {\tt WEAVE}'s job is +to typeset them, while {\tt TANGLE} must remember the definitions and +expand them at the proper time. +The code parts are the most complex of all: {\tt WEAVE} must +prettyprint them, and {\tt TANGLE} must rearrange them into a coherent +program text. + +\paragraph{Lexical analysis in {\WEB}} +Both {\tt WEAVE} and {\tt TANGLE} interpret the code parts as a stream +of {\em tokens}. +Since not all programming languages have the same tokens, it is +{Spider}'s job to tell {\tt WEAVE} and {\tt TANGLE} how to tokenize the +input.% +\footnote{% +The current implementation of {\tt WEB}'s lexical analysis is limited. +It should be replaced with something using regular +expressions.% +} +A Spidery {\WEB} system can recognize the following kinds of +tokens: +\begin{itemize} +\item identifiers +\item numeric and string constants +\item newlines +\item ``pseudo-semicolons'' (the token {\tt @;}) +\item reserved words +\item non-alphanumeric tokens +\end{itemize} + +{\tt TANGLE} rearranges these tokens into one long program +text, then writes out the program text token by token. +Normally, {\tt TANGLE} puts no white space between tokens, but it +will put blanks between adjacent identifier, reserved word, and +numeric constant tokens. +Thus the input +\begin{quote} +\tt if 0 > x-y then z := -1; +\end{quote} +will be written out as +\begin{quote} +\tt if 0>x-y then z:=-1; +\end{quote} +and not +\begin{quote} +\tt if0>x-ythenz:=-1; +\end{quote} +which wouldn't parse. +When it is desirable to have {\tt TANGLE} translate +the tokens differently, each token can be given a {\tt tangleto} +attribute, which specifies what program text is printed out for that +token. +For example, +the {\tt spider} file used to generate C~{\WEB} forces the {\tt =} +tokento be printed out as the string {\tt "=\ "}, because in C the string +{\tt "=-"} can be ambiguous. + +{\tt WEAVE} must turn the token stream into a {\TeX} text that will +cause the code to be prettyprinted. +It does so in three steps: +\begin{enumerate} +\item +{\tt WEAVE} turns each token into a {\em scrap}. +A scrap has two important properties: its syntactic +{\em category} and its {\em translation}. +The categories are symbols in a prettyprinting grammar; that grammar +tells {\tt WEAVE} how to combine the scraps +with prettyprinting instructions. +The translations are the {\TeX} texts that will tell {\TeX} exactly +how to print the scraps. +\item +{\tt WEAVE} reduces the scrap stream by combining scraps according to +the productions of its prettyprinting grammar. +({\tt WEAVE} does a kind of shift-reduce parsing of program fragments.) +While combining the translations, {\tt WEAVE} adds {\TeX} text that +will cause indenting, outdenting, line breaking, and so on. +\item +Ideally, {\tt WEAVE} keeps reducing scraps until it has a single scrap with +a very long translation, but perhaps it will end up +with an irreducible sequence of scraps. +In any case, after no more reductions can be done, the translations of the +remaining scraps are output one at a time. +\end{enumerate} + +\section{Using {Spider} to tell {\WEB} how to tokenize} +{Spider} divides tokens into two classes; reserved words and +other. +The reserved words as specified using the {\tt reserved} and {\tt ilk} +commands; the other tokens are specified using the {\tt token} +command. +(This somewhat unusual setup is dictated by the way {\tt +WEAVE} works; its advantage is that is is easy to define a whole group +of reserved words that will be treated identically.) +Here's how it works: the {\tt reserved} command designates + a particular identifier as a reserved word, and says +what {\em ilk} it belongs to. +The {\tt token} and {\tt ilk} commands tell {\tt WEAVE} and {\tt +TANGLE} what to do with a particular token, or with all the reserved +words of a particular ilk. +For each token or ilk one can specify the {\em tangleto} field, the +token's {\em mathness} (whether it has to be typeset in math mode), and +its {\em category} and {\em translation} (for conversion to scraps). +All but the category can have defaults, set with the {\tt defaults} +command. +Choice of category names is up to the user. + +We will discuss the tokenization commands more later when we present +the syntax of {Spider} in detail. +Meanwhile, +here are some example tokenization commands from the {\tt spider} file +for~C: +\begin{verbatim} +token + category unorbinop +token - category unorbinop +token * category unorbinop +token = category equals translation <"\\leftarrow"> tangleto <"="-space> +token ~ category unop translation <"\\TI"> +token & category unorbinop translation <"\\amp"> +token ^ translation <"\\^"> category binop +token ? translation <"\\?"> category question +token % translation <"\\%"> category binop +token # translation <"\\#"> category sharp +token ! category unop translation <"\\neg"> +token ( category lpar +token ) category rpar +token [ category lpar +token ] category rpar +token { translation <"\\{"> category lbrace +token } translation <"\\}"> category rbrace +token ++ category unop translation <"\\PP"> +token -- category unop translation <"\\MM"> +token != translation <"\\I"> category binop +token == translation <"\\S"> category binop +token && translation <"\\W"> category binop + +ilk case_like category case +ilk int_like category int + +reserved auto ilk int_like +reserved break ilk case_like +reserved case ilk case_like +reserved char ilk int_like +\end{verbatim} +These show the definitions of some of the tokens used in C. +Notice the {\tt tangleto} option is almost always left to default, and +the {\tt translation} option is often left to default. + +Once the tokens are specified, and each has a {\tt tangleto} string, +we can almost construct a {\tt TANGLE} for the language. + Before we can construct a {\tt WEAVE}, we have to tell it how to +combine and reduce scraps. + +\section{Using {Spider} to tell {\tt WEAVE} how to reduce scraps} +The most intricate part of {\tt WEAVE} is its mechanism for converting +programming language code into \TeX\ code. +{\tt WEAVE} uses a simple bottom-up parsing algorithm, since it + must deal with fragmentary +constructions whose overall ``part of speech'' is not known. + +The input is represented as a sequence of {\em scraps}, +where each scrap of information consists +of two parts, its {\em category} and its {\em translation}. +The category +is essentially a syntactic class, and the translation represents +{\TeX} code. +Rules of syntax and semantics tell us how to +combine adjacent scraps into larger ones, and if we are lucky an entire +program text that starts out as hundreds of small scraps will join +together into one gigantic scrap whose translation is the desired \TeX\ +code. +If we are unlucky, we will be left with several scraps that don't +combine; their translations will simply be output, one by one. + +The combination rules are given as context-sensitive productions that are +applied from left to right. Suppose that we are currently working on the +sequence of scraps $s_1\,s_2\ldots s_n$. We try first to find the longest +production that applies to an initial substring $s_1\,s_2\ldots\,$; but if +no such productions exist, we find to find the longest production +applicable to the next substring $s_2\,s_3\ldots\,$; and if that fails, we +try to match $s_3\,s_4\ldots\,$, et cetera. + +A production applies if the category codes have a given pattern. For +example, if one of the productions is +$$\hbox{\tt open [ math semi <"\BS\BS,"-opt-5> ] --> +open math}$$ +then it means that three consecutive scraps whose respective categories are +{\tt open}, {\tt math}, and {\tt semi} are con\-verted to two scraps whose categories +are {\tt open} and {\tt math}. + The {\tt open} scrap has not changed, while the string +{\tt <"\BS\BS,"-opt-5>} +indicates that the new {\tt math} scrap +has a translation composed of the translation of the original +{\tt math} scrap followed by the translation of the {\tt semi} scrap followed +by `{\tt \BS,}' followed by `{\tt opt}' followed by `{\tt5}'. (In the \TeX\ file, +this will specify an additional thin space after the semicolon, followed +by an optional line break with penalty 50.) +Translations are enclosed in angle brackets, and may contain quoted +strings (using the C conventions to escape backslashes and so on), or +may contain special keywords. + +Before giving examples of useful productions, we'll break to give the +detailed syntax of the {Spider} subset covered so far. + + + +\section{Syntax of {\tt spider} files} + +{Spider} is an Awk program which converts a description of a +language into C~code for {\tt WEAVE} and {\tt TANGLE}. +Since {Spider} is an Awk program, its input is a sequence of +lines, and all {Spider} commands must fit on one line. + +\paragraph{Comments and blank lines} +Because {\em any} character sequence can be a token of a programming +language, we can't just designate a particular sequence as a ``begin +comment'' marker. +So in {Spider} there are no comments, only {\em comment lines}. +A comment line is one whose first character is ``{\tt \#}''. +The {Spider} processor ignores comment lines and blank lines. + +\paragraph{Fields} +Each command in the {\tt spider} file consists of a sequence of {\em +fields}. +These are just the Awk fields, and they are separated by white space. +This feature of {Spider} (inherited from Awk) forbids the use of +white space within a field. + +\subsection{Translations} +Most fields in a {Spider} file are simple identifiers, or perhaps +strings of non-alphanumeric characters. +The major exception is {\em translations}. +Translations are always surrounded by angle brackets ({\tt <>}), +and consist of a (possibly empty) list of translation pieces. +The pieces on a list are separated by dashes ({\tt -}). +A piece is one of: +\begin{itemize} +\item A quoted string. +This string may contain embedded quotes escaped by ``\verb+\+'', but +it {\em must not} contain embedded white space or an embedded dash. +\item The ``self'' marker, ``{\tt *}'', + refers to the sequence of characters making up the token being +translated. +The self marker is permitted only in certain contexts, and its precise +meaning depends on the context. +\item A digit. +\item A key word. +The key words known to {Spider} are +\begin{description} +\item [\tt space] Stands for one space ({\tt "\ "}). +\item[\tt dash] Stands for a dash ({\tt "-"}). +\end{description} +The other key words are passed on to {\tt WEAVE}. + +{\tt WEAVE} recognizes the following key words: +\begin{description} +\item[\tt break\_space] denotes an optional line break or an en space; +\item[\tt force] denotes a line break; +\item[\tt big\_force] denotes a line break with additional vertical space; +\item[\tt opt] denotes an optional line break (with the continuation +line indented two ems with respect to the normal starting position)---this +code is followed by an integer $n$, and the break will occur with penalty +$10n$; +\item[\tt backup] denotes a backspace of one em; +\item[\tt cancel] obliterates any {\tt break\_space} or {\tt force} or +{\tt big\_force} +tokens that immediately precede or follow it and also cancels any +{\tt backup} tokens that follow it; +\item[\tt indent] causes future lines to be indented one more em; +\item[\tt outdent] causes future lines to be indented one less em. +\item[\tt math\_rel] translates to \verb+\mathrel{+ +\item[\tt math\_bin]translates to \verb+\mathbin{+ +\item[\tt math\_op] translates to \verb+\mathop{+ +\end{description} +The {\em only} key words that will work properly in math mode are {\tt +indent} and {\tt outdent}, so when you're defining the translations of +tokens you must use {\tt mathness~no} if your translations contain +other key words. +You may use any recognized key words in the translations of a +production; there the mathness is automatically taken care of for you. +\end{itemize} + +Here are some example translations: +\begin{verbatim} +<"\\"-space> +<indent-force> +<"{\\let\\\\=\\bf"-space> +<"}"-indent-"{}"-space> +\end{verbatim} + +\paragraph{Restricted translations} +In some cases, notably for a {\tt tangleto} description, translations +are {\em restricted}. +A restricted translation is never converted to typesetting code, +but is always converted to an ASCII string, usually for output by {\tt +TANGLE}, but sometimes for other things. +A restricted translation may contain only {\em quoted strings} and the +keywords {\tt space} and {\tt dash}. + + +\subsection{{\tt token} commands} +The syntax of the {\tt token} command is: +\begin{quote} +\tt +\syntax{command} \produces~token \syntax{token-designator} +\syntax{token-descriptions} +\end{quote} +Where \syntax{token-descriptions} is a (possibly empty) list of token +descriptions. + +\paragraph{Token descriptions} +The token descriptions are +\begin{itemize}\parindent=0pt +\item +{\tt tangleto \syntax{restricted translation}} + +The \syntax{restricted translation} tells {\tt TANGLE} what program +text to write out for this token. +The only kinds of translation pieces valid in a restricted translation +are quoted strings and the special words {\tt space} and {\tt dash}. +If no {\tt tangleto} description is present, {\tt TANGLE} just writes +out the sequence of characters that constitute the token. + +\item +{\tt translation \syntax{translation}} + +Tells {\tt WEAVE} what translation to assign when making this token into +a scrap. +The self +marker~({\tt*}) stands for the sequence of characters that were read in to +make up the token. +The translation often defaults to \verb+translation <*>+; {Spider} +is set up to have this default initially. + +\item +{\tt category \syntax{category-name}} + +Tells {\tt WEAVE} what category to assign when making this token into +a scrap. +If you're writing a {Spider} file, you may choose any category +names you like, subject only to the restriction that they not conflict +with other names known to {Spider} (e.g.~predefined key words, +names of ilks, and so on). +Using category names that are identical to reserved words of the +target programming language (or reserved words of~C) is not only +supported, it is strongly encouraged, for clarity. +Also, when we get to the sample grammars later on, you will see some +other conventions we use for category names. + +\item +{\tt mathness \syntax{mathness-indicator}} + +where \syntax{mathness-indicator} is {\tt yes}, {\tt no}, or {\tt +maybe}. +This indicates to {\tt WEAVE} whether the translation for this token +needs to be typeset in {\TeX}'s math mode or not, or whether it +doesn't matter. +When firing productions, +{\tt WEAVE} will place math shift characters~(\verb+$+) in the {\TeX} +text that guarantee the placement of tokens in the correct modes. +Tokens with the {\em empty translation} (\verb+<>+) should always have +{\tt mathness maybe}, lest they cause {\tt WEAVE} to place two +consecutive math shift characters. + +\item +{\tt name \syntax{token-name}} + +This should only be necessary in debugging {Spider} or {\WEB}. +It causes the specified name to be attached to the token, so that a +programmer can search for that name in the C~code generated by +{Spider}. + +\end{itemize} + +\paragraph{Token designators} +{Spider} recognizes the following token designators: +\begin{description} +\item[{\tt identifier}] +A {\tt token} command using this designator tells {\tt WEAVE} and {\tt +TANGLE} what to do with identifier tokens. +Unfortunately it is not possible to specify with {Spider} just +what an identifier is; that definition is hard-wired into {\tt WEAVE} +and {\tt TANGLE}. +An identifier is the longest string matching this regular expression% +\footnote{The reader unfamiliar with the Unix notation for regular +expressions should consult the {\it ed(1)} man page.}: +\begin{verbatim} +[a-zA-Z_][a-zA-Z0-9_]* +\end{verbatim} + +\item[{\tt number}] +In the current implementation of {Spider} and {\tt WEAVE}, a {\tt token} +command using this designator covers the treatment of both numeric +constants and string constants. +Like the identifiers, the definitions of what constitutes a numeric or +string constant cannot be changed. +{\samepage +A numeric constant is the longest string matching% +\footnote{There ought to be some kind of {\WEB} control sequence to +support floating point notation for those languages that have it.}: +\begin{verbatim} +[0-9]+(\.[0-9]*)? +\end{verbatim} +} +A string constant is the longest string matching +\begin{verbatim} +\"([^"]*\\\")*[^"]*\"|'[^@\]'|'\\.'|'@@' +\end{verbatim} +Carriage returns may appear in string constants if escaped by a +backslash~(\verb+\+). + +\item[{\tt newline}] +A {\tt token} command using this descriptor tells {\tt WEAVE} and {\tt +TANGLE} how to treat a newline. +We'll see later how to make {\tt WEAVE} ignore newlines. + +\item[{\tt pseudo\_semi}] +A {\tt token} command using this descriptor tells {\tt WEAVE} what to +do with the {\WEB} control sequence {\tt @;}. +This control sequence is always ignored by {\tt TANGLE}. + +\item[\syntax{characters}] +where none of the characters is alphanumeric. +A {\tt token} command using this descriptor defines the sequence of +characters as a token, and tells {\tt WEAVE} and {\tt TANGLE} what to +do with that token. +A token may be a prefix of another token; {\tt WEAVE} and {\tt TANGLE} +will prefer the longer token to the shorter. +Thus, in a C~{\WEB}, \verb+==+ will be read as a single \verb+==+ +token, not as two \verb+=+ tokens. +\end{description} + + + + +\subsection{Reserved word tokens} +Reserved words are attached to a particular {\em ilk} using the {\tt +reserved} command. +\begin{quote} +\tt reserved \syntax{reserved-word} $[$ilk \syntax{ilk-name}$]$ +\end{quote} +If you're writing a {Spider} file, you may choose any ilk +names you like, subject only to the restriction that they not conflict +with other names known to {Spider} (e.g.~predefined key words, +names of categories, and so on). +The convention, however, is to use ilk {\tt with\_like} for a reserved +word {\tt with}, and so on.% +\footnote{% +The existence of this convention seduced me into adding a pernicious +feature to {Spider}---if you omit the ilk from a {\tt reserved} +command, {Spider} will make an ilk name by appending {\tt \_like} +to the name of the reserved word. +Furthermore, if that ilk doesn't already exist, {Spider} will +construct one. +Don't use this feature. +} + +The {\tt ilk} and {\tt token} commands have nearly identical syntax. +The syntax of the {\tt ilk} command is: +\begin{quote}\tt +\syntax{command} \produces~ilk \syntax{ilk-name} +\syntax{token-descriptions} +\end{quote} +In translations that appear in {\tt ilk} commands, the self +marker~({\tt *}) designates the string of characters making up the +reserved word, surrounded by \verb+\&{...}+, which makes the reserved +words appear in bold face. + +\section{Syntax of the prettyprinting grammar} +Defining the tokens of a language is somewhat tedious, but it is +essentially straightforward, and the definition usually does not need +fine tuning. +When developing a new {\WEB} with {Spider}, you will spend most of +your time writing the grammar that tells {\tt WEAVE} how to reduce +scraps. +The grammar is defined as a sequence of context-sensitive productions. +Each production has the form: +\begin{quote} +\tt +\syntax{left context} [ \syntax{firing instructions} ] \syntax{right context} +\\\null\qquad +--> \syntax{left context} \syntax{target category} \syntax{right context} +\end{quote} +where the left and right contexts are (possibly empty) sequences of +scrap designators, the firing instructions are a sequence of scrap +designators and translations (containing at least one scrap +designator), and the target category is a category designator. +If the left and right contexts are both empty, the square brackets +({\tt []}) can be omitted, and the production is context free. +The left and right contexts must be the same on both sides of the {\tt +-->}. + +What does the production mean? +Well, {\tt WEAVE} is trying to reduce a sequence of scraps. +So what {\tt WEAVE} does is look at the sequence, to find out whether +the left hand side of some production matches an initial subsequence +of the scraps. +{\tt WEAVE} picks the first matching production, and {\em fires} it, +reducing the scraps described in the firing instructions to a single +scrap, and it gives the new scrap the {\em target category}. +The translation of the new scrap is formed by concatenating the +translations in the {\em firing instructions}, where a scrap +designator stands for the translation of the designated scrap. + +Here is the syntax that describes contexts, firing instructions, scrap +designators, and so on. +\begin{quote} +\tt +\syntax{left context} \produces~\syntax{scrap designators}\\ +\syntax{right context} \produces~\syntax{scrap designators}\\ +\syntax{firing instruction} \produces \syntax{scrap designator}\\ +\syntax{firing instruction} \produces \syntax{translation}\\ +\syntax{scrap designator} \produces~?\\ +\syntax{scrap designator} \produces~\opt{!}\syntax{category name}\opt{*}\\ +\syntax{scrap designator} + \produces~\opt{!}\syntax{category alternatives}\opt{*}\\ +\syntax{category alternatives} + \produces~\rlap{(\syntax{optional alternatives}\syntax{category name})}\\ +\syntax{optional alternative} \produces~\syntax{category name}|\\ +\syntax{target category} \produces~\#\syntax{integer}\\ +\syntax{target category} \produces~\syntax{category name}\\ +\end{quote} + +\paragraph{Matching the left hand side of a production} +When does a sequence of scraps match the left hand side of a +production? +For matching purposes, we can ignore the translations and the square +brackets~({\tt []}), and look at the left hand side just as a sequence +of scrap designators. +A sequence of scraps matches a sequence of scrap designators if and +only if each scrap on the sequence matches the corresponding scrap +designator. +Here are the rules for matching scrap designators (we can +ignore starring% +\footnote{A category name is said to be {\em starred} if it has the +optional {\tt *}.}% +): +\begin{itemize} +\item +Every scrap matches the designator {\tt ?}. +\item +A scrap matches \syntax{marked category} if and only if its category +is the same as the category of the designator. +\item +A scrap matches {\tt!}\syntax{marked category} if and only if its category +is {\em not} the same as the category of the designator. +(The {\tt !} indicates negation.) +\item +A scrap matches a list of category alternatives if and only if its +category is on the list of alternatives. +\item +A scrap matches a {\em negated} list of category alternatives if and +only if its category is {\em not} on the list of alternatives. +\end{itemize} + +\paragraph{Firing a production} +Once a match is found, {\tt WEAVE} fires the production by replacing +the subsequence of scraps matching the firing instructions. +{\tt WEAVE} replaces this subsequence with a new scrap whose category +is the target category, and whose translation is the concatenation of +all the translations in the firing instructions. +(When the new translation is constructed, the +translations of the old scraps are included at the positions of the +corresponding scrap designators.) +If the target category is not given by name, but rather by +number~({\tt \#$n$}), {\tt WEAVE} will take the category of the $n$th +scrap in the subsequence that matches the left hand side of the +production, and make that the target category. + +\subparagraph{Side effects of firing a production} +When a production fires, {\tt WEAVE} will {\em underline the +index entry} for the first identifier in any {\em starred} scrap. + +\paragraph{If no initial subsequence matches any production} +If the initial subsequence of scraps does not match the left hand side +of any production, {\tt WEAVE} will try to match the subsequence +beginning with the second scrap, and so on, until a match is found. +Once a match is found, {\tt WEAVE} fires the production, changing its +sequence of scraps. +It then starts all over again at the beginning of the new sequence, +looking for a match.% +\footnote{ +The implementation is better than that; {Spider} figures out just +how much {\tt WEAVE} must backtrack to get the same effect as +returning to the beginning.} +If {\em no} subsequence of the scraps matches any production, then the +sequence of scraps is irreducible, and {\tt WEAVE} writes out the +translations of the scraps, one at a time. + +\section{Examples of {\tt WEAVE} grammars} +This all must seem very intimidating, but it's not really. +In this section we present some grammar fragments and explain what's +going on. + +\paragraph{Short examples} +\begin{verbatim} +? ignore_scrap --> #1 +\end{verbatim} +This production should appear in every grammar, because Spidery {\tt +WEAVE} expects category \verb+ignore_scrap+ to exist with roughly this +semantics. +(For example, all comments generate scraps of category {\tt +ignore\_scrap}.) +Any scrap of category \verb+ignore_scrap+ essentially doesn't affect +the reduction of scraps: it is absorbed into the scrap to its left. + +\begin{verbatim} +token newline category newline translation <> +newline --> ignore_scrap +\end{verbatim} +This token definition and production, combined with the previous +production, causes {\tt WEAVE} to ignore all newlines. + +For this next example, from the C~grammar, you will need to know that +{\tt math} represents a mathematical expression, {\tt semi} a +semicolon, and {\tt stmt} a statement or sequence of statements. +\begin{verbatim} +math semi --> stmt +stmt <force> stmt --> stmt +\end{verbatim} +The first production says that a mathematical expression, followed by +a semicolon, should be treated as a statement. +The second says that two statements can be combined to make a single +statement by putting a line break between them. + +\paragraph{Expressions} +This more extended example shows the treatment of expressions in Awk. +This is identical to the treatment of expressions in C and in several +other languages. +We will use the following categories: +\begin{description} +\item[math] A mathematical expression +\item[binop] A binary infix operator +\item[unop] A unary prefix or postfix operator +\item[unorbinop] An operator that could be binary infix or unary +prefix +\end{description} +To show you how these might be used, here are some sample token +definitions using these categories: +\begin{verbatim} +token + category unorbinop +token - category unorbinop +token * category binop +token / category binop +token < category binop +token > category binop +token , category binop translation <",\\,"-opt-3> +token = category binop translation <"\\K"> +token != translation <"\\I"> category binop +token == name eq_eq translation <"\\S"> category binop +token ++ name gt_gt category unop translation <"\\uparrow"> +token -- name lt_lt category unop translation <"\\downarrow"> +\end{verbatim} +Notice that the translation for the comma specifies a thin space and +an optional line break after the comma. +The translations of {\tt =}, {\tt !=}, and {\tt ==} +produce~$\leftarrow$, $\ne$, and~$\equiv$. + +Here is the grammar for expressions. +\begin{verbatim} +math (binop|unorbinop) math --> math +(unop|unorbinop) math --> math +math unop --> math +math <"\\"-space> math --> math +\end{verbatim} +In Awk there is no concatenation operator; concatenation is by +juxtaposition. +The last production tells {\tt WEAVE} to insert a space between two +juxtaposed expressions. + +So far we haven't dealt with parentheses, but that's easily done: +\begin{verbatim} +token ( category open +token ) category close +token [ category open +token ] category close +open math close --> math +\end{verbatim} + + +Now this grammar just given doesn't handle the Awk or C {\tt +=} +feature very well; {\tt x+=1} comes out as~$x+\leftarrow 1$, and {\tt +x/=2} is irreducible! +Here's the cure; first, we make a new category for assignment: +\begin{verbatim} +token = category equals translation <"\\K"> +\end{verbatim} +And then we write productions that reduces assignment (possibly +preceded by another operator) to a binary operator: +\begin{verbatim} +<"\\buildrel"> (binop|unorbinop) <"\\over{"> equals <"}"> --> binop +equals --> binop +\end{verbatim} +Notice that, given the rules stated above, the second production can +fire only if {\tt equals} is {\em not} preceded by an operator. +On input~{\tt x+=1}, the first production fires, and we have the +translation~$x\buildrel+\over{\leftarrow} 1$. + +\paragraph{Conditional statements} +Here is the grammar for (possibly nested) conditional statements in +Awk. +\begin{verbatim} +if <"\\"-space> math --> ifmath +ifmath lbrace --> ifbrace +ifmath newline --> ifline +ifbrace <force> stmt --> ifbrace +ifbrace <outdent-force> close else <"\\"-space> if --> if +ifbrace <outdent-force> close else lbrace --> ifbrace +ifbrace <outdent-force> close else newline --> ifline +ifbrace <outdent-force> close --> stmt +(ifline|ifmath) <indent-force> stmt <outdent> --> stmt +\end{verbatim} +It relies on the following token definitions: +\begin{verbatim} +ilk if_like category if +reserved if +ilk else_like category else +reserved else +token { translation <"\\;\\{"-indent> category lbrace +token } translation <"\\}\\"-space> category close +token newline category newline translation <> +\end{verbatim} + +\paragraph{Handling preprocessor directives in C} +Here is a simplified version of +the grammar that handles C preprocessor directives. +It puts the directives on the left hand margin, and correctly handles +newlines escaped with backslashes. +(The full version is also able to distinguish {\tt <...>} +bracketing a file name from the use of the same symbols to mean ``less +than'' and ``greater than.'') +{\small\advance\hsize 1in +\begin{verbatim} +# control sequence \8 puts things on the left margin +<"\\8"> sharp <"{\\let\\\\=\\bf"-space> math <"}"-indent-"{}"-space> --> preproc +preproc backslash <force-"\\8\\hskip1em"-space> newline --> preproc +<force> preproc <force-outdent> newline --> ignore_scrap +preproc math --> preproc +newline --> ignore_scrap +\end{verbatim} +} +The \verb+\let+ in the first production makes the identifier following +the {\tt \#} come out in bold face. + + +\subsection{Using context-dependent productions} +So far we've been able to do a lot without using the +context-dependent features of {Spider} productions. +(For example, the entire {\tt spider} file for Awk is written using +only context-free productions.) +Now we'll show some examples that use the context-dependence. + +In the grammar for Ada, a semicolon is used as a terminator for +statements. +But semicolons are also used as {\em separators} in parameter +declarations. +The first two productions here find the statements, but the third +production supersedes them when a semicolon is seen in a parenthesized +list. +\begin{verbatim} +semi --> terminator +math terminator --> stmt +open [ math semi ] --> open math +\end{verbatim} + + +\paragraph{Underlining the index entry for the name of a declared +function} +In SSL, function declarations begin with the type of the function +being declared, followed by the name of that function. +The following production causes the index entry for that function to +be underlined, so that we can look up the function name in the index +and easily find the section in which the function is declared: +\begin{verbatim} +decl simp [ simp* ] --> decl simp math +\end{verbatim} +Where we've relied on +\begin{verbatim} +token identifier category simp mathness yes +\end{verbatim} + + +\paragraph{Conditional expressions} +Suppose we want to format conditional expressions (for example in C) +like this: +\begin{quote} +\syntax{condition}\\ +\mbox{\qquad}$?$ \syntax{expression}\\ +\mbox{\qquad}$:$ \syntax{expression} +\end{quote} +The problem is that it's hard to know when the conditional expression +ends. +It's essentially a question of precedence, and what we're going to do +is look ahead until we see an operator with sufficiently low +precedence that it terminates a conditional expression. +In SSL a conditional expression can be terminated by a semicolon, a +right parenthesis, a comma, or a colon. +We'll use the {\em right context} to do the lookahead. +{\small +\begin{verbatim} +token ? translation <"\\?"> category question +token : category colon + +<indent-force> question math <force> colon --> condbegin +[ condbegin math <outdent> ] (semi|close|comma|colon) --> math (semi|close|comma|colon) +\end{verbatim} +} + +\subsection{Debugging a prettyprinting grammar} +{\tt WEAVE} has two tracing modes that can help you debug a +prettyprinting grammar. +The control sequence {\tt @1} turns on partial tracing, and {\tt @2} +turns on a full trace. +{\tt @0} turns tracing back off again. +In the partial tracing mode, {\tt WEAVE} applies all the productions +as many times as possible, and then it prints out the irreducible +scraps that remain. +If the scraps reduce to a single scrap, no diagnostics are printed. + + +When a scrap is printed, {\tt WEAVE} prints a leading +{\tt+}~or~{\tt-}, the name of the category of that scrap, and a +trailing {\tt+}~or~{\tt-}. +The {\tt+} indicates that {\TeX} should be in math mode, and the +{\tt-} that {\TeX} should not be in math mode, at the beginning and +end of the scrap's translation, respectively. +(You can see the translations by looking at the {\tt.tex} file, since +that's where they're written out.) + +For beginners, the full trace is more helpful. +It prints out the following information every time a production is +fired: +\begin{itemize} +\item +The number of the production just fired (from {\tt productions.list}); +\item +The sequence of scraps {\tt WEAVE} is now trying to reduce; +\item +A {\tt*} indicating what subsequence {\tt WEAVE} will try to reduce +next. +\end{itemize} +A good way to understand how prettyprinting grammars work is to take +a {\tt productions.list} file, and look at a full trace of the +corresponding {\tt WEAVE}. +Or, if you prefer, you can simulate by hand the action of {\tt WEAVE} +on a sequence of scraps. + +\section{The rest of the {Spider} language} +The tokens and the grammar are not quite the whole story. +Here's the rest of the truth about what you can do with {Spider}. + +\subsection{Naming the target language} +When a Spidery {\tt WEAVE} or {\tt TANGLE} starts up, it prints the +target language for which it was generated, and the date and time of +the generation. +The {\tt language} command is used to identify the language being +targeted. +Its syntax is +\begin{quote} +\tt language \syntax{language-name} +\opt{extension \syntax{extension-name}}\\ +\mbox{\qquad\qquad}\opt{version \syntax{version-name}} +\end{quote} +The extension name is the extension used (in place of {\tt .web}) by +{\tt TANGLE} to write out the program text for the unnamed module. +The extension is also used to construct a language-specific file of +{\TeX} macros to be used by {\tt WEAVE}, so different languages should +always have different extensions. +If the extension is not given it defaults to the language name. +If the version information is given, it too will be printed out at +startup. + +The {\tt c.spider} file I use for Unix has +\begin{verbatim} +language C extension c +\end{verbatim} + + +\subsection{Defining {\TeX} macros} +In addition to the ``kernel'' {\WEB} macros stored in {\tt +webkernel.tex}, you may want to create some {\TeX} macros of your +own for use in translations. +Any macro definitions you put between lines saying {\tt macros begin} +and {\tt macros end} will be included verbatim in the {\TeX} macro +file for this language. +That macro file will automatically be \verb+\input+ by every {\TeX} +file generated by this {\tt WEAVE}. + +For example, the C grammar includes productions to handle preprocessor +directives. +These directives may include file names that are delimited by angle +brackets. +I wanted to use the abbreviations \verb+\LN+ and \verb+\RN+ for left +and right angle brackets, so I included +\begin{verbatim} +macros begin +\let\LN\langle +\let\RN\rangle +macros end +\end{verbatim} +in the {\tt c.spider} file. + +\subsection{Setting default token information} +It's possible to set default values for the {\tt translation} and {\tt +mathness} properties of tokens, so that they don't have to be +repeated. +This is done with the {\tt default} command, whose syntax is: +\begin{quote} +\tt +default \syntax{token descriptions} +\end{quote} +The initial defaults (when {Spider} begins execution) are {\tt +translation~<*>} and {\tt mathness~maybe}. + +\subsection{Specifying the treatment of modules} +{\WEB} introduces a new kind of token that isn't in any programming +language, and that's the module name ({\tt @<...@>} or {\tt @(...@>}). +{\tt TANGLE}'s job is to convert the module names to program text, and +when {\tt TANGLE} is finished no module names remain. +But {\tt WEAVE} has to typeset the module names, and we need to tell +{\tt WEAVE} what category to give a scrap created from a module name. +We allow two different categories, one for the definition of the +module name (at the beginning of a module), and one for a use of a +module name. +{\samepage +The syntax of the {\tt module} command is: +\begin{quote} +\tt +module \opt{definition \syntax{category name}} +\opt{use \syntax{category name}} +\end{quote} +} + +The {\tt c.spider} file contains the line +\begin{verbatim} +module definition decl use math +\end{verbatim} + +\subsection{Determining the at sign} +When generating a {\WEB} system with {Spider}, you're not required +to use ``{\tt @}'' as the ``magic at sign'' that introduces {\WEB} +control sequences. +By convention, however, we use ``{\tt @}'' unless that is deemed +unsuitable. +If ``{\tt @}'' is unsuitable, we use ``{\tt \#}.'' +Since {Spider} writes C~{\WEB} code for {\tt WEAVE} and {\tt +TANGLE}, it writes a lot of {\tt @} signs. +I didn't when to have to escape each one, so I chose +``{\tt \#}'' for Awk~{\WEB}'s at sign: +\begin{verbatim} +at_sign # +\end{verbatim} +The at sign defaults to ``{\tt @}'' if left unspecified. + +\paragraph{Changing control sequences} +Changing the at sign changes the meaning of one or two control +sequences. +This is more easily illustrated by example than explained. +Suppose we change the at sign to {\tt\#}. +Then in the resulting {\WEB} two control sequences have new meanings: +\begin{description} +\item[{\tt \#\#}] +Stands for a {\tt \#} in the input, by analogy with {\tt @@} in normal +{\WEB}. +You will need this when defining {\TeX} macros that take parameters. +\item[{\tt \#@}] +This is the new name of the control sequence normally represented by +{\tt@\#}. + You would use {\tt\#@} to get a line break followed by vertical +white space. +\end{description} +If you change the at sign to something other than {\tt@}~or~{\tt\#}, +the above will still hold provided you substitute your at sign for +{\tt\#}. + + +\subsection{Comments in the programming language} +We have to tell {\tt WEAVE} and {\tt TANGLE} how to recognize +comments in our target programming language, since comment text is +treated as {\TeX} text by {\tt WEAVE} and is ignored by {\tt TANGLE}. +The syntax of the {\tt comment} command is +\begin{quote} +\tt +comment begin \syntax{restricted translation} \\ +\null\qquad end $(\syntax{restricted translation}|{\tt newline})$ +\end{quote} +The restricted translations can include only quoted +strings, {\tt space}, and +{\tt dash}. +They give the character sequences that begin and end comments. +If comments end with newlines the correct incantation is {\tt end +newline}. + +If the comment character is the same as the at sign, it has to be +doubled in the {\WEB} file to have any effect. +For reasons that I've forgotten, {Spider} is too dumb +to figure this out and {\em you must double the comment character in +the {Spider} file}. +This is not totally unreasonable since any at sign that actually appears in a +{\WEB} file will have to be double to be interpreted correctly. + +{\tt WEAVE} uses the macros \verb+\commentbegin+ and +\verb+\commentend+ at the beginning and end of comments, so you can +define these to be whatever you like (using the {\tt macros} command) +if you don't like {Spider}'s defaults. +{Spider} is smart enough to escape {\TeX}'s special characters in +coming up with these defaults. + +Here's a real-world ugly example of how things really are, from the +{\tt spider} file for Awk: +\begin{verbatim} +comment begin <"##"> end newline +macros begin +\def\commentbegin{\#} % we don't want \#\# +macros end +\end{verbatim} + +\subsection{Controlling line numbering} + A compiler doesn't get to see {\WEB} files directly; it has to +read the output of {\tt TANGLE}. +Error messages labelled with line numbers from a tangled file aren't +very helpful, so Spidery {\tt TANGLE} does something to improve the +situation: it writes {\tt \#line} directives into its output, in the +manner of the C~preprocessor. +({\tt TANGLE} also preserves the line breaking of the {\WEB} source, +so that the {\tt \#line} information will be useful.) +For systems like Unix with {\tt cc} and {\tt dbx}, both compile-time +and run-time debugging can be done in terms of the {\WEB} source, and +the intermediate programming language source need never be consulted. + +Not all compilers support line numbering with {\tt \#line} directives, +so {Spider} provides a {\tt line} command to change the format of +the {\tt \#line} directives. +If your compiler doesn't support {\tt \#line}, you can use the {\tt +line} command to turn the line number information into a comment.% +\footnote{% +There should be a command that turns off line numbering.% +} +The syntax is: +\begin{quote} +\tt +line begin \syntax{restricted translation} end \syntax{restricted translation} +\end{quote} +The {\tt begin} translation tells what string to put in front of the file +name and line number information; the {\tt end} translation tells what to +put afterward. +The defaults (which are set for C) are +\begin{verbatim} +line begin <"#line"> end <""> +\end{verbatim} +Here's an example from the Ada~{Spider} file, which makes the line +number information into an Ada comment: +\begin{verbatim} +line begin <"--"-space-"line"> end <""> +\end{verbatim} + + + + +\subsection{Showing the date of generation} +When Spidery {\tt WEAVE} and {\tt TANGLE} start up, they print the +date and time at which their {Spider} file was processed. +This is done through the good offices of {Spider}'s {\tt date} +command, which is +\begin{quote} +\tt +date \syntax{date} +\end{quote} +where \syntax{date} looks like {\tt "Fri Dec 11 11:31:18 EST 1987"} or +some such. +Normally you never need to use the {\tt date} command, because one is +inserted automatically by the {Spider} tools, but if you're +porting {Spider} to a non-Unix machine you need to know about it. + + + + +\section{Spider's error messages} +{Spider} makes a lot of attempts to detect errors in a +{Spider} specification. +{Spider}'s error messages are intended to be self-explanatory, but +I don't know how well they succeed. +In case you run into trouble, here are the error +conditions {Spider} tries to detect: +\begin{itemize} +\item + Garbled commands, lines with bad fields in them, or commands with +unused fields. +Any command with a field {Spider} can't follow or with an extra +field is ignored from the bad field onward, but the earlier fields may +have an effect. +Any production with a bad field or other error is dropped completely. +\item +Missing {\tt language} command. +\item +{\tt macros} or {\tt comment} command before {\tt language} command. +{Spider} uses the {\tt extension} information +from the {\tt language} command to determine the name of the file to +which the macros will be written, and the {\tt comment} command +causes {Spider} to write macros telling {\TeX} what to do at the +beginning and end of comments. +\item +Contexts don't match on the left and right sides of a production. +\item +A numbered target token doesn't fall in the range defined by the +left hand side of its production. +\item +Some category is never {\em appended}. +This means there is no way to create a scrap with this category. +{Spider} only looks to see that each +category appears at least once as the category of some token or as the +category of the target token in some production, so {Spider} might +fail to detect this condition (if there is some production that can +never fire). +\item +Some category is never {\em reduced}. +This means that the category never appears in a scrap +designator from the firing instructions of a production. +If a category is never reduced, {Spider} only issues a warning, +and does not halt the compilation process with an error. + +The append +and reduce checks will usually catch you if you misspell a category +name. +\item +You defined more tokens than {\tt WEAVE} and {\tt TANGLE} can handle. +\item +You forgot token information for identifiers, numeric +constants, newlines, pseudo-semicolons~({\tt @;}), module definitions, +or module uses. +\item +Some ilk has no translation, or there is some ilk of which there are +no reserved words. +\end{itemize} + + + + +\section{{Spider}'s output files} +{Spider} writes many output files, and you may want to look at +them to figure out what's going on. +Here is a partial list (you can find a complete list by consulting +{\tt spider.web}): +\begin{description} +\item[\tt cycle.test] +Used to try to detect potential loops in the grammar. +Such loops can cause {\tt WEAVE} to run indefinitely (until it runs +out of memory) on certain inputs. +Discussed below with the {Spider} tools. +\item[\tt spider.slog] +A verbose discussion of everything {Spider} did while it was +processing your file. +To be consulted when things go very wrong. +\item[\tt *web.tex] +The macros specific to the generated {\WEB}. +\item[\tt productions.list] +A numbered list of all the productions. +This list is invaluable when you are trying to debug a grammar using +Spidery {\tt WEAVE}'s tracing facilities ({\tt @2}). +\end{description} + + + + +\section{Using {Spider} to make {\WEB} (the {Spider} tools)} +Many of the {Spider} tools do error checking, like: +\begin{itemize} +\item +Check to see there are no duplicate names among the categories, ilks, +and translation keywords. +\item +Check the translation keywords against a list of those recognized by +{\tt WEAVE}, and yelps if trouble happens. +\item +Try to determine whether there is a ``production cycle'' that could +cause {\tt WEAVE} to loop infinitely by firing the productions in the +cycle one after another. +\end{itemize} + +I'm not going to say much about how to do all this, or how to make +{\tt WEAVE} and {\tt TANGLE}; instead I'm going to show you a {\tt +Makefile} and comment on it a little bit. +Since right now Spidery {\tt WEB} is available only on Unix systems, +chances are you have the {\tt Makefile} and can just type ``{\tt +make~tangle}'' or ``{\tt make~weave}.'' +If not, reading the Makefile is still your best bet to figure out what +the tools do. + +We assume that you are making {\tt WEAVE} and {\tt TANGLE} in some +directory, and that the ``master sources'' for Spidery {\WEB} are kept +in some other directory. +Some of the {\tt Makefile} macros deserve special mention: +\begin{description} +\renewcommand{\makelabel}[1]{{\tt#1}\hfil} +\item[THETANGLE] +Name of the {\tt TANGLE} we will generate. +\item[THEWEAVE] +Name of the {\tt WEAVE} we will generate. +\item[SPIDER] +Name of the {Spider} input file. +\item[DEST] +The directory in which the executables defined by \verb+$(TANGLE)+ and +\verb+$(WEAVE)+ will be placed. +\item[WEBROOT] +The directory that is the root of the Spidery {\WEB} distribution. +\item[MASTER] +The location of the ``master sources.'' +This should always be different from the directory in which {\tt make} +is called, or havoc will result. +\item[CTANGLE] +The name of the program used to tangle C code. +\item[AWKTANGLE] +The name of the program used to tangle Awk code. +\item[MACROS] +The name of a directory in which to put {\TeX} macro definitions (a +{\tt *web.tex} file. +\end{description} + +Usually we will only be interested in two commands: ``\/{\tt +make~weave}'' and ``\/{\tt make~tangle}.'' +It's safe to use ``\/{\tt make~clean}'' only if you use the current +directory for nothing exception spidering; ``\/{\tt make~clean}'' is +really vicious. + +The line that's really of interest is the line showing the dependency +for {\tt grammar.web}. +First we run {Spider}. +Then we check for bad translation keywords and for potential cycles in +the prettyprinting grammar. +We check for duplicate names, and then finally (if everything else +works), we put the {\tt *web.tex} file in the right place. + +Here's \verb+$(MASTER)/WebMakefile+: +\begingroup\small +\begin{verbatim} +# Copyright 1989 by Norman Ramsey and 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. + +HOME=/u/nr# # Make no longer inherits environment vars +THETANGLE=tangle +THEWEAVE=weave +SPIDER=any.spider +# +DVI=dvi +CFLAGS=-DDEBUG -g -DSTAT + +# CPUTYPE is a grim hack that attempts to solve the problem of multiple +# cpus sharing a file system. In my environment I have to have different +# copies of object and executable for vax, sun3, next, iris, and other +# cpu types. If you will be using Spidery WEB in a homogeneous processor +# environment, you can just set CPUTYPE to a constant, or eliminate it +# entirely. +# +# In my environment, the 'cputype' program returns a string that +# describes the current processor. That means that the easiest thing +# for you to do is to define a 'cputype' program that does something +# sensible. A shell script that says 'echo "vax"' is fine. + +CPUTYPE=`cputype` + +# Change the following three directories to match your installation +# +# the odd placement of # is to prevent any trailing spaces from slipping in + +WEBROOT=$(HOME)/web/src# # root of the WEB source distribution +DEST=$(HOME)/bin/$(CPUTYPE)# # place where the executables go +MACROS=$(HOME)/tex/macros# # place where the macros go + +MASTER=$(WEBROOT)/master# # master source directory +OBDIR=$(MASTER)/$(CPUTYPE)# # common object files + +TANGLESRC=tangle +CTANGLE=ceetangle -I$(MASTER) +CWEAVE=ceeweave -I$(MASTER) +AWKTANGLE=awktangle -I$(MASTER) +COMMONOBJS=$(OBDIR)/common.o $(OBDIR)/pathopen.o +COMMONC=$(MASTER)/common.c $(MASTER)/pathopen.c +COMMONSRC=$(COMMONC) $(MASTER)/spider.awk + + + +# Our purpose is to make tangle and weave + +web: tangle weave + +tangle: $(COMMONOBJS) $(TANGLESRC).o + cc $(CFLAGS) -o $(DEST)/$(THETANGLE) $(COMMONOBJS) $(TANGLESRC).o + +weave: $(COMMONOBJS) weave.o + cc $(CFLAGS) -o $(DEST)/$(THEWEAVE) $(COMMONOBJS) weave.o + + +source: $(TANGLESRC).c $(COMMONSRC) # make tangle.c and common src, then clean + if [ -f WebMakefile ]; then exit 1; fi # don't clean the master! + if [ -f spiderman.tex ]; then exit 1; fi # don't clean the manual + -rm -f tangle.web weave.* common.* # remove links that may be obsolete + -rm -f *.unsorted *.list grammar.web outtoks.web scraps.web + -rm -f cycle.test spider.slog + -rm -f *.o *.tex *.toc *.dvi *.log *.makelog *~ *.wlog *.printlog + +# Here is how we make the common stuff + +$(MASTER)/common.c: $(MASTER)/common.web # no change file + $(CTANGLE) $(MASTER)/common + +$(OBDIR)/common.o: $(MASTER)/common.c + cc $(CFLAGS) -c $(MASTER)/common.c + mv common.o $(OBDIR) + + +$(MASTER)/pathopen.c: $(MASTER)/pathopen.web # no change file + $(CTANGLE) $(MASTER)/pathopen + mv pathopen.h $(MASTER) + +$(OBDIR)/pathopen.o: $(MASTER)/pathopen.c + cc $(CFLAGS) -c $(MASTER)/pathopen.c + mv pathopen.o $(OBDIR) + + +## Now we make the tangle and weave source locally + +$(TANGLESRC).c: $(MASTER)/$(TANGLESRC).web $(MASTER)/common.h grammar.web + -/bin/rm -f $(TANGLESRC).web + ln $(MASTER)/$(TANGLESRC).web $(TANGLESRC).web +# chmod -w $(TANGLESRC).web + $(CTANGLE) $(TANGLESRC) + +weave.c: $(MASTER)/weave.web $(MASTER)/common.h grammar.web + -/bin/rm -f weave.web + ln $(MASTER)/weave.web weave.web +# chmod -w weave.web + $(CTANGLE) weave + +## Here's where we run SPIDER to create the source + +grammar.web: $(MASTER)/cycle.awk $(MASTER)/spider.awk $(SPIDER) + echo "date" `date` | cat - $(SPIDER) | awk -f $(MASTER)/spider.awk + cat $(MASTER)/transcheck.list trans_keys.unsorted | awk -f $(MASTER)/transcheck.awk + awk -f $(MASTER)/cycle.awk < cycle.test + sort *.unsorted | awk -f $(MASTER)/nodups.awk + mv *web.tex $(MACROS) + +## We might have to make spider first. + +$(MASTER)/spider.awk: $(MASTER)/spider.web + $(AWKTANGLE) $(MASTER)/spider + mv cycle.awk nodups.awk transcheck.awk $(MASTER) + rm junk.list + + +# $(MASTER)/cycle.awk: $(MASTER)/cycle.web # making spider also makes cycle +# $(AWKTANGLE) $(MASTER)/cycle + + +# This cleanup applies to every language + +clean: + if [ -f WebMakefile ]; then exit 1; fi # don't clean the master! + if [ -f spiderman.tex ]; then exit 1; fi # don't clean the manual + -rm -f tangle.* weave.* common.* # remove links that may be obsolete + -rm -f *.unsorted *.list grammar.web outtoks.web scraps.web + -rm -f cycle.test spider.slog + -rm -f *.c *.o *.tex *.toc *.dvi *.log *.makelog *~ *.wlog *.printlog + + + +# booting the new distribution +boot: + cd ../master; rm -f *.o; for i in $(COMMONC); do \ + cc $(CFLAGS) -c $$i; \ + mv *.o $(OBDIR) ; \ + done; cd ../c + cc $(CFLAGS) -c $(TANGLESRC).c; \ + cc $(CFLAGS) -o $(DEST)/$(THETANGLE) $(COMMONOBJS) $(TANGLESRC).o + + +\end{verbatim} +\endgroup + +\section{Getting your own Spidery {\tt WEB}} +At this time, Spidery {\tt WEB} has been tested only on Unix machines. +It should be easy to port to any machine having a C compiler and an +Awk interpreter, but undoubtedly some changes will be necessary. +The full {Spider} distribution, including this manual, is available by +anonymous {\tt ftp} from {\tt princeton.edu:~ftp/pub/spiderweb.tar.Z}. +You should pick a directory to install {Spider} in, untar the +distribution, and follow the directions in the README file. +The directory you have picked becomes {\tt WEBROOT}. + +If the {\tt Makefile} in the distribution differs from the one given +above, the one in the distribution should be considered the correct +one. + + + + +\section{A real {Spider} file} +I have tried to use real examples to illustrate the use of {Spider}. +I include here, as an extended example, the complete {Spider} file for +the Awk language. +Those who cannot easily study the distribution may find it useful to +study this. +\begingroup\small +\begin{verbatim} +# Copyright 1989 by Norman Ramsey and 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. + +language AWK extension awk + +at_sign # + +module definition stmt use stmt +# use as stmt is unavoidable since tangle introduces line breaks + +comment begin <"##"> end newline +macros begin +\def\commentbegin{\#} % we don't want \#\# +macros end + +line begin <"#line"> end <""> + +default translation <*> mathness yes + +token identifier category math mathness yes +token number category math mathness yes +token newline category newline translation <> mathness maybe +token pseudo_semi category ignore_scrap mathness no translation <opt-0> + +token \ category backslash translation <> mathness maybe +token + category unorbinop +token - category unorbinop +token * category binop +token / category binop +token < category binop +token > category binop +token >> category binop translation <"\\GG"> +token = category equals translation <"\\K"> +token ~ category binop translation <"\\TI"> +token !~ category binop translation <"\\not\\TI"> +token & category binop translation <"\\amp"> +token % translation <"\\%"> category binop +token ( category open +token [ category lsquare +token ) category close +token ] category close +token { translation <"\\;\\{"-indent> category lbrace +token } translation <"\\}\\"-space> category close +token , category binop translation <",\\,"-opt-3> + +token ; category semi translation <";"-space-opt-2> mathness no +# stuff with semi can be empty in for statements +open semi --> open +semi semi --> semi +semi close --> close +semi --> binop + +# token : category colon +# token | category bar +token != name not_eq translation <"\\I"> category binop +token <= name lt_eq translation <"\\L"> category binop +token >= name gt_eq translation <"\\G"> category binop +token == name eq_eq translation <"\\S"> category binop +token && name and_and translation <"\\W"> category binop +token || name or_or translation <"\\V"> category binop +# token -> name minus_gt translation <"\\MG"> category binop +token ++ name gt_gt category unop translation <"\\uparrow"> +token -- name lt_lt category unop translation <"\\downarrow"> +# preunop is for unary operators that are prefix only +token $ category preunop translation <"\\DO"> mathness yes + +default mathness yes translation <*> + +ilk pattern_like category math +reserved BEGIN ilk pattern_like +reserved END ilk pattern_like + +ilk if_like category if +reserved if +ilk else_like category else +reserved else + +ilk print_like category math +# math forces space between this and other math... +reserved print ilk print_like +reserved printf ilk print_like +reserved sprintf ilk print_like + + +ilk functions category unop mathness yes +reserved length ilk functions +reserved substr ilk functions +reserved index ilk functions +reserved split ilk functions +reserved sqrt ilk functions +reserved log ilk functions +reserved exp ilk functions +reserved int ilk functions + +ilk variables category math mathness yes +reserved NR ilk variables +reserved NF ilk variables +reserved FS ilk variables +reserved RS ilk variables +reserved OFS ilk variables +reserved ORS ilk variables + +ilk for_like category for +reserved for ilk for_like +reserved while ilk for_like + +ilk in_like category binop translation <math_bin-*-"}"> mathness yes +# translation <"\\"-space-*-"\\"-space> +reserved in ilk in_like + +ilk stmt_like category math +reserved break ilk stmt_like +reserved continue ilk stmt_like +reserved next ilk stmt_like +reserved exit ilk stmt_like + + +backslash newline --> math +# The following line must be changed to make a backslash +backslash <"\\backslash"> --> math + +math (binop|unorbinop) math --> math +<"\\buildrel"> (binop|unorbinop) <"\\over{"> equals <"}"> --> binop +equals --> binop +(unop|preunop|unorbinop) math --> math +# unorbinop can only act like unary op as *prefix*, not postfix +math unop --> math +math <"\\"-space> math --> math +# concatenation + +math newline --> stmt +newline --> ignore_scrap + +stmt <force> stmt --> stmt + +(open|lsquare) math close --> math + +math lbrace --> lbrace +lbrace <force> stmt --> lbrace +lbrace <outdent-force> close --> stmt + +if <"\\"-space> math --> ifmath +ifmath lbrace --> ifbrace +ifmath newline --> ifline +ifbrace <force> stmt --> ifbrace +ifbrace <outdent-force> close else <"\\"-space> if --> if +ifbrace <outdent-force> close else lbrace --> ifbrace +ifbrace <outdent-force> close else newline --> ifline +ifbrace <outdent-force> close --> stmt +(ifline|ifmath) <indent-force> stmt <outdent-force> else <"\\"-space> if --> if +(ifline|ifmath) <indent-force> stmt <outdent-force> else lbrace --> ifbrace +(ifline|ifmath) <indent-force> stmt <outdent-force> else newline --> ifline +(ifline|ifmath) <indent-force> stmt <outdent-force> else --> ifmath +(ifline|ifmath) <indent-force> stmt <outdent> --> stmt + +for <"\\"-space> math --> formath +formath lbrace --> forbrace +formath newline --> forline +forbrace <force> stmt --> forbrace +forbrace <outdent-force> close --> stmt +(forline|formath) <indent-force> stmt <outdent> --> stmt + + +? ignore_scrap --> #1 +\end{verbatim} +\endgroup + + + +\section{Bibliography} +\begin{thebibliography}{Knuth~999} +\bibitem[Bentley~87]{bentley:pearls} +Jon L. Bentley, ``Programming Pearls,'' {\sl Communications of the +ACM}~{\bf 29:5}(May 1986), 364--?, and {\bf 29:6}(June 1986), +471--483. +Two columns on literate programming. +The first is an introduction, and the second is an extended example by +Donald Knuth, with commentary by Douglas MacIlroy. +\bibitem[Knuth~83]{knuth:web} +Donald~E. Knuth, +``The {{\tt WEB}} system of structured documentation'' + Technical Report 980, Stanford Computer Science, Stanford, + California, September 1983. +The manual for the original {\tt WEB}. +\bibitem[Knuth~84]{knuth:literate-programming} +Donald E. Knuth, ``Literate Programming,'' {\sl The Computer Journal} +{\bf 27:2}(1984), 97--111. +The original introduction to literate programming with {\WEB}. +\bibitem[Levy~87]{levy:cweb} +Silvio Levy, ``Web Adapted to C, Another Approach'' {\sl TUGBoat} +{\bf 8:2}(1987), 12--13. +A short note about the C implementation of {\WEB}, from which Spidery +{\WEB} is descended. +\bibitem[Sewell~89]{sewell:weaving} +Wayne Sewell, ``Weaving a program: Literate programming in {\tt +WEB},'' +Van Nostrand Reinhold, 1989. +\end{thebibliography} + + +\end{document} diff --git a/web/spiderweb/doc/spiderwebman.tex b/web/spiderweb/doc/spiderwebman.tex new file mode 100644 index 0000000000..c512983ee1 --- /dev/null +++ b/web/spiderweb/doc/spiderwebman.tex @@ -0,0 +1,2268 @@ +% 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 + +\input webkernel % rank bravery; was webmac + +% macros for itemized lists +\newcount\level +\level=0 + +\def\enum#1{\ifcase\the#1 x\or i\or ii\or iii\else iv\fi} +\def\setenum{\edef\theenum{\csname enum\enum\level\endcsname}} + + +\def\itemize{\begingroup\advance\level by1 + \def\item{\par\noindent + \raise2pt\llap{$\scriptstyle\bullet$\ }}% + \par\advance\leftskip by2em\advance\rightskip by2em} +\def\enditemize{\par\endgroup\noindent\ignorespaces} +% end of stuff for itemized lists + +\parskip 0pt plus 1pt +\def\RA{\char'31 } % right arrow +\def\hang{\hangindent 4em\ignorespaces} +\font\ninerm=cmr9 +\font\ninett=cmtt9 +\font\eighttt=cmtt8 +\let\mc=\ninerm % medium caps for names like SAIL +\def\PASCAL{\newstuff ``X''\endnewstuff} +\def\PAS{\newstuff X\endnewstuff} % used to mark file extensions +\def\oP{{\sl \overline X}} % used in table of control sequences +\font\quoterm=cmssq8 +\font\quoteit=cmssqi8 +\def\pb{\.{|...|}} +\def\lpile{\def\cr{\hfill\endline}\matrix} % I only use \lpile by + % itself + +\def\newstuff{\begingroup\sl} +\def\endnewstuff{\endgroup} + +\outer\def\section #1.{\penalty-50\vskip 12pt plus 3pt minus 3pt + \noindent{\bf #1.}\quad\ignorespaces} + +\def\titlepage{T} +\def\lheader{\mainfont\the\pageno\hfill\sc\runninghead\hfill} +\def\rheader{\hfill\sc\runninghead\hfill\mainfont\the\pageno} +\def\runninghead{SPIDERY {\tentt WEB} USER MANUAL} + +% This verbatim mode assumed that no ? appears in the text being copied. +\def\verbatim{\begingroup + \def\do##1{\catcode`##1=12 } \dospecials + \parskip 0pt \parindent 0pt + \catcode`\ =13 \catcode`\^^M=13 + \tt \catcode`\?=0 \verbatimdefs \verbatimgobble} +{\catcode`\^^M=13{\catcode`\ =13\gdef\verbatimdefs{\def^^M{\ \par}\let =\ }} % + \gdef\verbatimgobble#1^^M{}} + +\centerline{\titlefont The Spidery {\ttitlefont WEB} System + of Structured Documentation} + +\vskip 15pt plus 3pt minus 3pt +\noindent +\newstuff +This memo describes how to write programs in the \.{WEB} language, +using \.{WEB} systems generated by {Spider}. +This class of \.{WEB} systems will be referred to (collectively) as +``Spidery \.{WEB}.'' +Most of the material is taken verbatim from Donald Knuth's original +memo introducing \.{WEB}; new material (like this paragraph) appears +in slant type. +Knuth's original memo is available as Stanford University CS technical + report number 980 (September 1983). +Unlike Knuth's, this memo is not accompanied by the full \.{WEB} +documentation for Spidery \.{WEAVE} and \.{TANGLE}, the programs that +read \.{WEB} input and produce {\TeX} output and code, respectively. +Nor does it contain the \.{WEB} documentation for {Spider}, the program that + generates the +language-dependent parts of \.{WEAVE} and \.{TANGLE}. +This memo should be accompanied by ``A {Spider} User's Guide,'' which +explains how to use {Spider} to build a Spidery \.{WEB} system. +\endnewstuff + +The philosophy behind \.{WEB} is +that an experienced system programmer, who wants to provide the best +possible documentation of his or her software products, needs two things +simultaneously: a language like \TeX\ for formatting, and a language +for programming. +\newstuff For convenience, we'll give this programming language a +name; let's call it the \PASCAL\ programming language. +\endnewstuff +Neither type of language can provide the best +documentation by itself; but when both are appropriately combined, we +obtain a system that is much more useful than either language +separately. + + +The structure of a software program may be thought of as a ``web'' that is +made up of many interconnected pieces. +To document such a program, we want +to explain each individual part of the web and how it relates to its +neighbors. +The typographic tools provided by \TeX\ give us an opportunity +to explain the local structure of each part by making that structure +visible, and the programming tools provided by \PASCAL\ make it possible +for us to specify the algorithms formally and unambiguously. +By combining +the two, we can develop a style of programming that maximizes our ability +to perceive the structure of a complex piece of software, and at the same +time the documented programs can be mechanically translated into a working +software system that matches the documentation. + +Since \.{WEB} is an experimental system developed for internal use within +the \TeX\ project at Stanford, this report is rather terse, and it assumes +that the reader is an experienced programmer who is highly motivated to +read a detailed description of \.{WEB}'s rules. +{\newstuff Spidery \.{WEB} is also an experimental system and +the same warning applies.\endnewstuff} +\newstuff +Before continuing, you may want to read some more introductory +material on {Spider} and \.{WEB}. +Here are some references worth looking at: +\itemize +\rm +\item Donald E. Knuth, ``Literate Programming,'' {\sl Computer +Journal} {\bf 27:2} (1984), 97--111.. +The original introduction of \.{WEB}. +\item 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. +Two columns on literate programming with \.{WEB}. +\item Norman Ramsey, ``Building a Language-Independent \.{WEB},'' +{\sl Communications of the ACM}, September 1989. +An overview of how {Spider} and \.{WEB} work. +\item +Wayne Sewell, ``Weaving a program: Literate programming in \.{WEB},'' +Van Nostrand Reinhold, 1989. +\enditemize +In addition to these, there is a periodic column in the {\sl +Communications of the ACM} devoted to literate programming. +\endnewstuff + +Even if a +less terse manual were to be written, the reader would have to be warned +in advance that \.{WEB} is not for beginners and it never will be: The +user of \.{WEB} must be familiar with both \TeX\ and \PASCAL. +When one +writes a \.{WEB} description of a software system, it is possible to make +mistakes by breaking the rules of \.{WEB} and/or the rules of \TeX\ and/or +the rules of \PASCAL. +In practice, all three types of errors will occur, +and you will get different error messages from the different language +processors. +In compensation for the sophisticated expertise needed to cope +with such a variety of languages, however, experience has shown that +reliable software can be created quite rapidly by working entirely in +\.{WEB} from the beginning; and the documentation of such programs seems +to be better than the documentation obtained by any other known method. +Thus, \.{WEB} users need to be highly qualified, but they can get some +satisfaction and perhaps even a special feeling of accomplishment when +they have successfully created a software system with this method. + +To use \.{WEB}, you prepare a file called \.{COB.WEB} (say), and then you +apply a system program called \.{WEAVE} to this file, obtaining an output +file called \.{COB.TEX}. +When \TeX\ processes \.{COB.TEX}, your output +will be a ``pretty printed'' version of \.{COB.WEB} that takes appropriate +care of typographic details like page layout and the use of indentation, +italics, boldface, etc.; this output will contain extensive cross-index +information that is gathered automatically. +You can also submit the same +file \.{COB.WEB} to another system program called \.{TANGLE}, which will +produce a file \.{COB.\PAS} that contains the \PASCAL\ code of your \.{COB} +program. +The \PASCAL\ compiler will convert \.{COB.\PAS} into +machine-language instructions corresponding to the algorithms that were so +nicely formatted by \.{WEAVE} and \TeX. +Finally, you can (and should) +delete the files \.{COB.TEX} and \.{COB.\PAS}, because \.{COB.WEB} contains +the definitive source code. +Examples of the behavior of \.{WEAVE} and +\.{TANGLE} are +\newstuff +not +\endnewstuff +appended to this manual. +\newstuff +The names {\tt WEAVE} and \.{TANGLE} may vary, especially since there +may be versions for multiple languages. +My site supports, in addition to the original \.{TANGLE}, +\.{CEETANGLE}, \.{AWKTANGLE}, and \.{ADATANGLE}. +\endnewstuff + +Besides providing a documentation tool, \.{WEB} enhances the \PASCAL\ +language by providing a +%rudimentary + macro capability together with the +ability to permute pieces of the program text, so that a large system can +be understood entirely in terms of small modules and their local +interrelationships. +The \.{TANGLE} program is so named because it takes a +given web and moves the modules from their web structure into the order +required by \PASCAL; the advantage of programming in \.{WEB} is that the +algorithms can be expressed in ``untangled'' form, with each module +explained separately. +The \.{WEAVE} program is so named because it takes +a given web and intertwines the \TeX\ and \PASCAL\ portions contained in +each module, then it knits the whole fabric into a structured document. +(Get it? Wow.) +Perhaps there is some deep connection here with the fact +that the German word for ``weave'' is ``{\it web\/}'', and the +corresponding Latin imperative is ``{\it texe\/}''! + +It is impossible to list all of the related work that has influenced the +design of \.{WEB}, but the key contributions should be mentioned +here.\quad (1)~Myrtle Kellington, as executive editor for ACM +publications, developed excellent typographic standards for the +typesetting of Algol programs during the 1960s, based on the original +designs of Peter Naur; the subtlety and quality of this influential work +can be appreciated only by people who have seen what happens when other +printers try to typeset Algol without the advice of ACM's copy +editors.\quad(2)~Bill McKeeman introduced a program intended to automate +some of this task [Algorithm 268, ``Algol~60 reference language editor,'' +{\sl CACM \bf8} (1965), 667--668]; and a considerable flowering of such +programs has occurred in recent years [see especially Derek Oppen, +``Prettyprinting,'' {\sl ACM TOPLAS \bf2} (1980), 465--483; G.~A. +Rose and +J. +Welsh, ``Formatted programming languages,'' {\sl SOFTWARE Practice +\char`\&\ Exper.\ \bf11} (1981), 651--669].\quad(3)~The top-down style of +exposition encouraged by \.{WEB} was of course chiefly influenced by Edsger +Dijkstra's essays on structured programming in the late 1960s. +The less +well known work of Pierre-Arnoul de Marneffe [``Holon programming: A +survey,'' Univ.\ de Liege, Service Informatique, Liege, Belgium, 1973; 135 +pp.\null] also had a significant influence on the author as \.{WEB} was +being formulated.\quad(4)~Edwin Towster has proposed a similar style of +documentation in which the programmer is supposed to specify the relevant +data structure environment in the name of each submodule [``A convention +for explicit declaration of environments and top-down refinement of +data,'' {\sl IEEE Trans.\ on Software Eng.\ \bf SE--5} (1979), 374--386]; +this requirement seems to make the documentation a bit too verbose, +although experience with \.{WEB} has shown that any unusual control +structure or data structure should definitely be incorporated into the +module names on psychological grounds.\quad(5)~Discussions with Luis +Trabb~Pardo in the spring of 1979 were extremely helpful for setting up a +prototype version of \.{WEB} that was called \.{DOC}.\quad (6)~Ignacio +Zabala's extensive experience with \.{DOC}, in which he created a full +implementation of \TeX\ in {Pascal} that was successfully transported to +many different computers, was of immense value while \.{WEB} was taking +its present form.\quad(7)~David~R. +Fuchs made several crucial suggestions +about how to make \.{WEB} more portable; he and Arthur~L. +Samuel +coordinated the initial installations of \.{WEB} on dozens of computer +systems, making changes to the code so that it would be acceptable to +a wide variety of \.{Pascal} compilers.\quad(8)~The name \.{WEB} itself +was chosen in honor of my wife's mother, Wilda Ernestine Bates. + +\newstuff +The work on Spidery \.{WEB} would not have been possible without the +help of Silvio Levy, who first ported \.{WEB} to C. +The name {Spider} was chosen because (in nature at least) webs are +built by spiders. +\endnewstuff + +The appendices to this report +\newstuff +do not +\endnewstuff +contain complete \.{WEB} programs for the +\newstuff {Spider}, \endnewstuff +\.{WEAVE}, and \.{TANGLE} processors. +A study of these examples, together +with an attempt to write \.{WEB} programs by yourself, is the best way +to understand why \.{WEB} has come to be like it is. + +\section General rules. +A \.{WEB} file is a long string of text that has been divided into +individual lines. +\newstuff +Unlike original {\tt WEB}, Spidery {\tt WEB} respects the programmer's +choice of line breaks. +A newline in code is normally passed along through tangle and will +appear in the resulting program. +This is important in languages like awk where line breaks are +significant. +In documentation, +\endnewstuff +the exact line boundaries are not terribly crucial, and +a programmer can pretty much chop up the \.{WEB} file in whatever way seems +to look best as the file is being edited; but string constants and control +texts must end on the same line on which they begin, since this convention +helps to keep errors from propagating. +\newstuff +The line length of the input is limited and is rather small. +\endnewstuff +% The end of a line means +% the same thing as a blank space. + +Two kinds of material go into \.{WEB} files: \TeX\ text and \PASCAL\ text. +A programmer writing in \.{WEB} should be thinking both of the +documentation and of the \PASCAL\ program that he or she is creating; +i.e., the programmer should be instinctively aware of the different +actions that \.{WEAVE} and \.{TANGLE} will perform on the \.{WEB} file. +\TeX\ text is essentially copied without change by \.{WEAVE}, and it is +entirely deleted by \.{TANGLE}, since the \TeX\ text is ``pure +documentation.'' +\PASCAL\ text, on the other hand, is formatted by +\.{WEAVE} and it is shuffled around by \.{TANGLE}, according to rules that +will become clear later. +For now the important point to keep in mind is +that there are two kinds of text. +Writing \.{WEB} programs is something +like writing \TeX\ documents, but with an additional ``\PAS\ mode'' +that is added to \TeX's horizontal mode, vertical mode, and math mode. + +A \.{WEB} file is built up from units called {\sl modules\/} that are more +or less self-contained. +Each module has three parts: + +\yskip\item{1)} A \TeX\ part, containing explanatory material about what +is going on in the module. + +\item{2)} A definition part, containing macro definitions that serve as +abbreviations for \PASCAL\ constructions that would be less comprehensible +if written out in full each time. + +\item{3)} An \PASCAL\ part, containing a piece of the program that +\.{TANGLE} will produce. +This \PASCAL\ code should ideally be about a +dozen lines long, so that it is easily comprehensible as a unit and so +that its structure is readily perceived. + +\yskip\noindent The three parts of each module must appear in this order; +i.e., the \TeX\ commentary must come first, then the definitions, and +finally the \PASCAL\ code. +Any of the parts may be empty. + +A module begins with the pair of symbols `\.{@\ }' or `\.{@*}', where +`\.{\ }' denotes a blank space. +A module ends +at the beginning of the next module (i.e., at the next +`\.{@\ }' or `\.{@*}'), or at the end of the file, whichever comes first. +The \.{WEB} file may also contain material that is not part of any module +at all, namely the text (if any) that occurs before the first module. +Such text is said to be ``in limbo''; it is ignored by \.{TANGLE} +and copied essentially verbatim by \.{WEAVE}, so its function is to +provide any additional formatting instructions that may be desired in the +\TeX\ output. +Indeed, it is customary to begin a \.{WEB} file with +\TeX\ code in limbo that loads special fonts, defines special macros, +changes the page sizes, and/or produces a title page. + +Modules are numbered consecutively, starting with 1; these numbers appear +at the beginning of each module of the \TeX\ documentation, and they appear +as bracketed comments at the beginning of the code generated by that +module in the \PASCAL\ program. + +Fortunately, you never mention these numbers yourself when you are writing +in \.{WEB}. +You just say `\.{@\ }' or `\.{@*}' at the beginning of each +new module, and the numbers are supplied automatically by \.{WEAVE} and +\.{TANGLE}. +As far as you are concerned, a module has a +name instead of a number; such a name is specified by writing +`\.{@<}' followed by \TeX\ text followed by `\.{@>}'. +When \.{WEAVE} +outputs a module name, it replaces the `\.{@<}' and `\.{@>}' by +angle brackets and inserts the module number in small type. +Thus, when you +read the output of \.{WEAVE} it is easy to locate any module that is +referred to in another module. + +\newstuff +Spidery {\tt WEB} supports a new kind of module called a ``file +module.'' +File modules open with \.{@(} instead of \.{@<}, and the module name + is taken to be the name of a file to which \.{TANGLE} will write the +contents of the module. +When \.{WEAVE} +outputs a file module name, it replaces the `\.{@(}' and `\.{@>}' by +parentheses and sets the entire name in {\tt typewriter} font. +\endnewstuff + + +For expository purposes, a module name should be a good description of the +contents of that module, i.e., it should stand for the abstraction +represented by the module; then the module can be ``plugged into'' one or +more other modules so that the unimportant details of its inner workings +are suppressed. +A module name therefore ought to be long enough to convey +the necessary meaning. +Unfortunately, however, it is laborious to type +such long names over and over again, and it is also difficult to specify a +long name twice in exactly the same way so that \.{WEAVE} and \.{TANGLE} +will be able to match the names to the modules. +Therefore a module name +can be abbreviated after its first appearance in the \.{WEB} file, by +typing `\.{@<$\alpha$...@>}', where $\alpha$ is any string that is a prefix of +exactly one module name that appears in the file. +For example, `\.{@<Clear +the arrays@>}' can be abbreviated to `\.{@<Clear...@>}' if no other module +name begins with the five letters `\.{Clear}'. +Module names must otherwise +match character for character, except that consecutive blank spaces and/or +tab marks are treated as equivalent to single spaces, and such spaces are +deleted at the beginning and end of the name. +Thus, `\.{@< Clear { }the +arrays @>}' will also match the name in the previous example. + +We have said that a module begins with `\.{@\ }' or `\.{@*}', but we +didn't say how it gets divided up into a \TeX\ part, a definition part, +and an \PASCAL\ part. +The definition part begins with the first appearance +of `\.{@d}' or `\.{@f}' in the module, and the \PASCAL\ part begins with +the first appearance of `\.{@u}', `\.{@<}', +\newstuff or `\.{@(}'.\endnewstuff +The +%latter + options `\.{@<}' \newstuff and `\.{@(}'.\endnewstuff +stand for the beginning of a module name, which is the name of the module +itself. +An equals sign (\.=) must follow the `\.{@>}' at the end of this +module name; you are saying, in effect, that the module name stands for +the \PASCAL\ text that follows, so you say `$\langle\,$module +name$\,\rangle=\null$\PASCAL\ text'. +Alternatively, if the \PASCAL\ part +begins with `\.{@u}' instead of a module name, the current module is said +to be {\sl unnamed}. +Note that module names cannot appear in the +definition part of a module, because the first `\.{@<}' \newstuff or +`\.{@(}'.\endnewstuff in a module +signals the beginning of its \PASCAL\ part. +Any number of module names +might appear in the \PASCAL\ part, however, once it has started. + +The general idea of \.{TANGLE} is to make an \PASCAL\ program out of these +modules in the following way: First all the \PASCAL\ parts of unnamed +modules are copied down, in order; this constitutes the initial +approximation $T_0$ to the text of the program. +(There should be at least +one unnamed module, otherwise +\newstuff unless there are file modules \endnewstuff +there will be no program.) Then all module +names that appear in the initial text $T_0$ are replaced by the \PASCAL\ +parts of the corresponding modules, and this substitution process +continues until no module names remain. +Then all defined macros are +replaced by their equivalents, according to certain rules that are +explained later. +%The resulting \PASCAL\ code is ``sanitized'' so that it +%will be acceptable to an average garden-variety \PASCAL\ compiler; i.e., +%lowercase letters are converted to uppercase, long identifiers are +%chopped, and the lines of the output file are constrained to be at most 72 +%characters long. +All comments will have been removed from this \PASCAL\ +program except for the meta-comments delimited by `\.{@\{}' and +`\.{@\}}', as explained below, and except for the module-number comments +that point to the source location where each piece of the program text +originated in the \.{WEB} file. +\newstuff +Spidery {\tt WEB} does not support the use of the meta-comments + `\.{@\{}' and `\.{@\}}'. +Their absence can be partially compensated for by clever use of the +``verbatim'' control sequence `\.{@=...@>}'. +\endnewstuff + +Incidentally, module numbers are automatically inserted +as meta-comments into the \PASCAL\ program, in order to help correlate the +outputs of \.{WEAVE} and \.{TANGLE} (see Appendix~C\null). +\newstuff So are {\tt\#line} directives, the exact workings of which +are obscure (but see the ``{Spider} User's Guide'' for more information). +\endnewstuff + +If the same name has been given to more than one module, the \PASCAL\ text +for that name is obtained by putting together all of the \PASCAL\ parts in +the corresponding modules. +This feature is useful, for example, in a +module named `Global variables in the outer block', since one can then +declare global variables in whatever modules those variables are +introduced. +When several modules have the same name, \.{WEAVE} assigns the +first module number as the number corresponding to that name, and it +inserts a note at the bottom of that module telling the reader to `See +also sections so-and-so'; this footnote gives the numbers of all the other +modules having the same name as the present one. +The \PASCAL\ text +corresponding to a module is usually formatted by \.{WEAVE} so that the +output has an equivalence sign in place of the equals sign in the \.{WEB} +file; i.e., the output says `$\langle\,$module +name$\,\rangle\equiv\null$\PASCAL\ text'. +However, in the case of the second +and subsequent appearances of a module with the same name, this `$\equiv$' +sign is replaced by `$\mathrel+\equiv$', as an indication that the \PASCAL\ +text that follows is being appended to the \PASCAL\ text of another +module. + + +The general idea of \.{WEAVE} is to make a \.{TEX} file from the \.{WEB} +file in the following way: The first line of the \.{TEX} file will be +`\.{\\input \PAS web}'; this will cause \TeX\ to read in the macros that +define \.{WEB}'s documentation conventions +\newstuff +for the \PASCAL\ programming language. +\endnewstuff +The next lines of the file +will be copied from whatever \TeX\ text is in limbo before the first +module. +Then comes the output for each module in turn, possibly +interspersed with end-of-page marks. +Finally, \.{WEAVE} will generate a +cross-reference index that lists each module number in which each \PASCAL\ +identifier appears, and it will also generate an alphabetized list +of the module names, as well as a table of contents that +shows the page and module numbers for each ``starred'' module. + +What is a ``starred'' module, you ask? +A module that begins with `\.{@*}' +instead of `\.{@\ }' is slightly special in that it denotes a new major +group of modules. +The `\.{@*}' should be followed by the title of this +group, followed by a period. +Such modules will always start on a new page +in the \TeX\ output, and the group title will appear as a running headline +on all subsequent pages until the next starred module. +The title will also +appear in the table of contents, and in boldface type at the beginning of +its module. + +\newstuff +Spidery {\tt WEB} supports a hack that makes the module structure +appear more hierarchical in the table of contents. +If the title begins with the special character {\tt =}, or one of the +digits {\tt 1}~through~{\tt 4}, it will be formatted specially. +This table shows the effect of the special titles: +\medskip +{ +\tabskip=0pt plus 1fil +\noindent\halign to \hsize{\strut\tt#\hfil +\tabskip=2em&#\hfil&\hfil #\hfil&#\hfil\tabskip=0pt plus 1fil\cr +\bf Marker&\bf Level&\bf Page Eject?&\bf Other\cr +\noalign{\smallskip} +@*=&chapter&yes&Bold in toc\cr +@*§ion&yes\cr +@*1&subsection&yes\cr +@*2&subsection&no\cr +@*3&subsubsection&yes\cr +@*4&subsubsection&no\cr +} +} +\medskip +\endnewstuff + +Caution: Do not use \TeX\ control sequences in such titles, +unless you know that the \.{webmac} macros will do the right thing with +them. +The reason is that these titles are converted to uppercase when +they appear as running heads, and they are converted to boldface when they +appear at the beginning of their modules, and they are also written out to +a table-of-contents file used for temporary storage while \TeX\ is +working; whatever control sequences you use must be meaningful in all +three of these modes. + +\newstuff +Second caution: +do not allow the titles to begin with a non-letter, unless the +non-letter is the control sequence \.{\\relax}. +The reason is that the first character of the titles is checked to see +whether it is the special character {\tt =}, or one of the +digits {\tt 1}~through~{\tt 4}. +A non-letter that is not one of these will only confuse the formatter. +\endnewstuff + +The \TeX\ output produced by \.{WEAVE} for each module consists of +the following: First comes the module number (e.g., `\.{\\M123.}' +at the beginning of module 123, except that `\.{\\N}' appears in place of +`\.{\\M}' at the beginning of a starred module). +Then comes the +\TeX\ part of the module, copied almost verbatim except as noted +below. +Then comes the definition part and the \PASCAL\ part, formatted +so that there will be a little extra space between them if both are +nonempty. +The definition and \PASCAL\ parts are obtained by inserting +a bunch of funny looking \TeX\ macros into the \PASCAL\ program; these +macros handle typographic details about fonts and proper math spacing, +as well as line breaks and indentation. + +When you are typing \TeX\ text, you will probably want to make frequent +reference to variables and other quantities in your \PASCAL\ code, and you +will want those variables to have the same typographic treatment +when they appear in your text as when they appear in your +program. +Therefore the \.{WEB} language allows you to get the effect of +\PASCAL\ editing within \TeX\ text, if you place `\.|' marks before and +after the \PASCAL\ material. +For example, suppose +\newstuff +you are writing Pascal code and +\endnewstuff +you want to say something +like this: +$$\hbox{The characters are placed into \\{buffer}, which is a +\&{packed} \&{array} $[1\to\|n]$ \&{of} \\{char}.}$$ +The \TeX\ text would look like this in your \.{WEB} file: +$$\.{The characters are placed into |buffer|, which is a |packed +array [1..n] of char|.}$$ +And \.{WEAVE} translates this into something you are glad you didn't have +to type: +$$\lpile{\.{The characters are placed into \\\\\{buffer\},}\cr + \.{which is a \\\&\{packed\}{ }\\\&\{array\}{ }\$ + [1\\to\\|n]\${ }\\\&\{of\}{ }\\\\\{char\}.}\cr}$$ +Incidentally, the cross-reference index that \.{WEAVE} would make, in +the presence of a comment like this, would include +the current module number as one of the index entries for \\{buffer} +and \\{char}, even though \\{buffer} and \\{char} +might not appear in the \PASCAL\ part of +this module. +Thus, the index covers references to identifiers in +the explanatory comments as well as in the program itself; you will +soon learn to appreciate this feature. +However, the identifiers +\&{packed} and \&{array} and \|n\ and \&{of\/} would not be indexed, +because \.{WEAVE} does not make index entries for reserved words or +single-letter identifiers. +Such identifiers are felt to be so ubiquitous +that it would be pointless to mention every place where they occur. + +Speaking of identifiers, the author of \.{WEB} thinks that +\\{IdentifiersSeveralWordsLong} look terribly ugly when they mix +uppercase and lowercase letters. +He recommends that +\\{identifiers\_several\_words\_long} be written with underline characters +to get a much better effect. +%The actual identifiers sent to the \PASCAL\ +%compiler by \.{TANGLE} will have such underlines removed, and \.{TANGLE} +%will check to make sure that two different identifiers do not become +%identical when this happens. +%(In fact, \.{TANGLE} even checks that +%the first seven characters of identifiers are unique, when lowercase +%letters have been converted to uppercase; the number seven in this +%constraint is more strict than \PASCAL's eight, and it can +%be changed if desired.) +The \.{WEAVE} processor will properly +alphabetize identifiers that have embedded underlines +when it makes the index. +\newstuff +Using Spidery \.{WEB}, you're out of luck if programming language +\PASCAL\ doesn't support underlines in identifiers. +\endnewstuff + +Although a module begins with \TeX\ text and ends with \PASCAL\ text, we +have noted that the dividing line isn't sharp, since \PASCAL\ text can be +included in \TeX\ text if it is enclosed in `\pb'. +Conversely, \TeX\ text +also appears frequently within \PASCAL\ text, because everything in +\PASCAL\ comments is treated as \TeX\ text. +Furthermore, a module name consists of \TeX\ text; thus, a \.{WEB} file +typically involves constructions like `\.{if} \.x \.= \.0 \.{then} +\.{@<Empty} \.{the} \.{|buffer|} \.{array@>}' where we go back and forth +between \PASCAL\ and \TeX\ conventions in a natural way. + +\section Macros. +\newstuff +In the current implementation of Spidery \.{WEB}, a \.{WEB} programmer +can define two kinds of macros to make the programs shorter and more +readable. + +\yskip\hang`\.{@d} \\{identifier} \.{=} \PASCAL\ text' defines a {\sl +simple\/} macro, where the identifier will be replaced by the \PASCAL\ text +when \.{TANGLE} produces its output. + +\yskip\hang`\.{@d} \\{identifier} \.{(}\\{formal parameters}\.{)} +\.{=} \PASCAL\ text' defines a +{\sl parametric\/} macro, where the identifier will be replaced by the +\PASCAL\ +text and where occurrences of the \\{formal parameters} in that +\PASCAL\ text will be replaced by arguments. +For C programmers, this is similar to the C macro processor, but +the \.{=} sign is used to avoid the need for bizarre lexical +requirements. +Whitespace can appear between a macro name and a list of formal +paramters, and newlines in macros need not be escaped with +backslashes. +A macro definition is terminated by a following \.{@d}, \.{@f}, +\.{@u}, \.{@<}, or \.{@(}. +\endnewstuff + + + + +%A \.{WEB} programmer can define three kinds of macros to make the programs +%shorter and more readable: +% +%\yskip\hang`\.{@d} \\{identifier} \.= \\{constant}' defines a {\sl numeric\/} +%macro, allowing \.{TANGLE} to do rudimentary arithmetic. +% +%\yskip\hang`\.{@d} \\{identifier} \.{==} \PASCAL\ text' defines a {\sl +%simple\/} macro, where the identifier will be replaced by the \PASCAL\ text +%when \.{TANGLE} produces its output. +% +%\yskip\hang`\.{@d} \\{identifier}\.{(\#) ==} \PASCAL\ text' defines a +%{\sl parametric\/} macro, where the identifier will be replaced by the \PASCAL\ +%text and where occurrences of \.{\#} in that \PASCAL\ text will be +%replaced by an argument. +% +%\yskip\noindent In all three cases, the identifier must have length greater +%than one; it must not be a single letter. +%Furthermore, the identifier must +%be making its first appearance in the \.{WEB} file; a macro must be defined +%before it is used. +% +%Numeric macros are subject to the following restrictions:\quad +%(1)~The right-hand side of the numeric definition must be made entirely from +%integer constants, numeric macros, preprocessed strings (see below), and +%plus~signs or minus signs. +%No other operations or symbols are allowed, +%not even parentheses, except that \PASCAL-like comments (enclosed in +%braces) can appear. +%Indeed, comments are recommended, since it is usually +%wise to give a brief explanation of the significance of each identifier as +%it is defined.\quad +%(2)~The numeric value must be less than $2^{15}=32768$ in absolute value. +%(For larger values, you can use `\.{==}' in place of~`\.=', thus making use +%of a simple macro instead of a numeric one. +%Note, however, that simple +%macros sometimes have a different effect. +%For example, consider the three +%definitions `\.{@d n1=2 @d n2=2+n1 @d n3==2+n1}'; then `\.{x-n2}' will +%expand into `\.{x-4}', while `\.{x-n3}' will expand into `\.{x-2+2}' which +%is quite different! It is wise to include parentheses in non-numeric +%macros, e.g., `\.{@d n3==(2+n1)}', to avoid such errors.) +% +%When constants are connected by plus signs or minus +%signs in an \PASCAL\ program, \.{TANGLE} does the arithmetic before putting +%the constant into the output file. +%Therefore it is permissible to say, for +%example, `\&{array} $[0\,.\,.\,\\{size}-1]$' if \\{size} has been declared +%as a macro; note that \PASCAL\ doesn't allow this kind of compile-time +%arithmetic if \\{size} is a \&{constant} quantity in the program. +%Another +%use of \.{TANGLE}'s arithmetic is to make \&{case} statement labels such +%as `$\\{flag}+1$' legitimate. +%Of course, it is improper to change \.{2+2} +%into \.4 without looking at the surrounding context; many counterexamples +%exist, such as the phrases `\.{-2+2}', `\.{x/2+2}', and `\.{2+2E5}'. +%The +%program for \.{TANGLE}, in the appendix, gives precise details about this +%conversion, which \.{TANGLE} does only when it is safe. +% +%The right-hand sides of simple and parametric macros +%are required to have balanced parentheses, and the \PASCAL\ texts of +%modules must have balanced parentheses too. +%Therefore when the argument +%to a para\-metric macro appears in parentheses, both parentheses +%will belong to the same \PASCAL\ text. +% +%The appendices to this report contain hundreds of typical examples of the +%usefulness of \.{WEB} macros, so it is not necessary to dwell on the +%subject here. +%However, the reader should know that \.{WEB}'s apparently +%primitive macro capabilities can actually do a lot of rather surprising +%things. +%Here is a construction that sheds further light on what is +%possible: After making the definitions +%$$\catcode`\#=12 +%\lpile{\.{@d two\_cases(#)==case j of 1:#(1); 2:#(2); end}\cr +%\.{@d reset\_file(#)==reset(input\_file@\&#)}\cr}$$ +%one can write `\.{two\_cases(reset\_file)}' and the resulting \PASCAL\ +%output will be +%$$\.{case j of 1:reset(input\_file1); 2:reset(input\_file2); end}$$ +%(but in uppercase letters and with \.\_'s removed). +%The `\.{@\&}' operation used here joins together two adjacent tokens +%into a single token, as explained later; otherwise the \PASCAL\ file would +%contain a space between \.{input\_file} and the digit that followed it. +%This trick can be used to provide the effect of an array of files, if you +%are unfortunate enough to have a \PASCAL\ compiler that doesn't allow such +%arrays. +%Incidentally, the cross-reference index made by \.{WEAVE} from +%this example would contain the identifier \\{input\_file} but it would not +%contain \\{input\_file1} or \\{input\_file2}. +%Furthermore, \.{TANGLE} +%would not catch the error that \.{INPUTFILE1} and \.{INPUTFILE2} both +%begin with the same nine letters; one should be more careful when using +%`\.{@\&}'! But such aspects of the construction in this trick are +%peripheral to our main point, which is that a parametric macro name without +%arguments can be used as an argument to another parametric macro. +% +%Although \.{WEB}'s macros are allowed to have at most one parameter, the +%following example shows that this is not as much of a restriction as it +%may seem at first. +%Let \\{amac} and \\{bmac} be any parametric macros, and +%suppose that we want to get the effect of +%$$\catcode`\#=12 +%\.{@d cmac(#1,#2) == amac(#1) bmac(#2)}$$ +%which \.{WEB} doesn't permit. +%The solution is to make the definitions +%$$\catcode`\#=12 +%\lpile{\.{@d cmac(#) == amac(#) dmac}\cr +%\.{@d dmac(#) == bmac(#)}\cr}$$ +%and then to say `\.{cmac(x)(y)}'. +% +%There is one restriction in the generality of \.{WEB}'s parametric +%macros, however: the argument to a para\-metric macro must not come from +%the expansion of a macro that has not already been ``started.'' For +%example, here is one of the things \.{WEB} cannot handle: +%$$\catcode`\#=12 +%\lpile{\.{@d arg == (p)}\cr +%\.{@d identity(#) == #}\cr +%\.{@p identity arg}\cr}$$ +%In this case \.{TANGLE} will complain that the \.{identity} macro is not +%followed by an argument in parentheses. + +%The \.{WEB} language has another feature that is somewhat similar to a +%numeric macro. +%A {\sl preprocessed string\/} is a string that is like +%a \PASCAL\ string but delimited by double-quote marks (\.") instead of +%single-quotes. +%Double-quote marks inside of such strings are indicated by +%giving two double-quotes in a row. +%If a preprocessed string is +%of length one (e.g., \.{"A"} or \.{""""}), it will be treated by \.{TANGLE} +%as equivalent to the corresponding ASCII-code integer (e.g., \.{65} or +%\.{34}). +%And if a preprocessed string is not of length one, it will be +%converted into an integer equal to 128 or more. +%A {\sl string pool\/} +%containing all such strings will be written out by the \.{TANGLE} +%processor; this string pool file consists of string 128, then string 129, +%etc., where each string is followed by an end-of-line and prefixed by two +%decimal digits that define its length. +%Thus, for example, the empty string +%\.{""} would be represented in the string pool file by a line containing +%the two characters `\.{00}', while the string \.{"""String"""} would be +%represented by `\.{08"String"}'. +%A given string appears at most once in +%the string pool; the use of such a pool makes it easier to cope with +%\PASCAL's restrictions on string manipulation. +%The string pool ends with +%`\.{*nnnnnnnnn}', where \.{nnnnnnnnn} is a decimal number +%called the {\sl string pool check sum}. +%If any string changes, the check +%sum almost surely changes too; thus, the `\.{@\$}' feature +%described below makes it possible for a program to assure itself that it +%is reading its own string pool. +% +%Here is a simple example that combines numeric macros with preprocessed +%strings of length one: +%$$\lpile{\.{@d upper\_case\_Y = "Y"}\cr +%\.{@d case\_difference = -"y"+upper\_case\_Y}\cr}$$ +%The result is to define +%$\\{upper\_case\_Y}=89$, $\\{case\_difference}=-32$. + +\newstuff +Spidery \.{WEB} does not support a string pool file. +Pleas for its restoration will be heard. +\endnewstuff + +\section Control codes. +We have seen several magic uses of `\.{@}' signs in \.{WEB} files, and it +is time to make a systematic study of +these special features. +A \.{WEB} {\sl control code\/} +is a two-character combination of which the first is `\.@'. +\newstuff +In Spidery \.{WEB} the ``magic at sign'' need not be `\.@'; the person +who built your \.{WEB} (with {Spider}) may have defined it to be +something else. +By convention, people building Spidery {\tt WEB}s + use `\.@' as the magic at sign, except when it is +deemed unsuitable for some reason, in which case + cases they use `\.\#'. +\endnewstuff + +Here is a complete list of the legal control codes. +The letters $L$, $T$, +$\PAS$, $M$, $C$, and/or $S$ following each code indicate whether or not that +code is allowable in limbo, in \TeX\ text, in \PASCAL\ text, in module +names, in comments, and/or in strings. +A bar over such a letter means +that the control code terminates the present part of the \.{WEB} file; for +example, $\overline L$ means that this control code ends the limbo material +before the first module. + +\def\@#1[#2] {\yskip\hangindent 2em\noindent\.{@#1\unskip + \spacefactor1000{ }}$[#2]$\quad} +\def\oT{\overline T} + +\@@ [C,L,M,\PAS,S,T] A double \.@ denotes the single character `\.@'. +This is +the only control code that is legal in limbo, in comments, and in strings. + +\@i [L,T] +\newstuff +The \.{@i} control code should always be followed by a file name and a +newline. +It causes the file to be included at the current point in the +\.{WEB} source, just like the C \.{\#include} facility. +\endnewstuff + +\@\ [\overline L,\oP,\oT] This denotes the beginning of a new +(unstarred) module. +A tab mark or end-of-line (carriage return) +is equivalent to a space when it follows an \.@ sign. + +\@* [\overline L,\oP,\oT] This denotes the beginning of a new starred +module, i.e., a module that begins a new major group. +The title of the new +group should appear after the \.{@*}, followed by a period. +\newstuff +As explained above, the first character of the title should be either +a letter or the control sequence \.{\\relax}, unless special +formatting is desired. +Titles beginning with \.=, \.1, \.2, \.3, or \.4 are formatted +specially. +\endnewstuff +As explained +above, \TeX\ control sequences should be avoided in such titles unless +they are quite simple. +When \.{WEAVE} and \.{TANGLE} read a \.{@*}, they +print an asterisk followed by the current module number, so that the user +can see some indication of progress. +The very first module should be starred. + +\@d [\oP,\oT] Macro definitions begin with \.{@d} (or \.{@D}), followed by +the \PASCAL\ text for one of the three kinds of macros, as explained +earlier. + +\@f [\oP,\oT] Format definitions begin with \.{@f} (or \.{@F}); they cause +\.{WEAVE} to treat identifiers in a special way when they appear in +\PASCAL\ text. +The general form of a format definition is `\.{@f} \|l %\.{=} +\|r', followed by an optional comment enclosed in braces, where \|l and \|r +are identifiers; \.{WEAVE} will subsequently treat identifier \|l as it +currently treats \|r. +This feature allows a \.{WEB} programmer to invent +new reserved words and/or to unreserve some of \PASCAL's reserved +identifiers. +\newstuff +It is offensive that the syntax is different from the \.{2d} syntax, +but it is that way for historical reasons (to avoid invalidating +existing code. +\endnewstuff +The definition part of each module consists of any number of +macro definitions (beginning with \.{@d}) and format definitions (beginning +with \.{@f}), intermixed in any order. + + +\@u [\oP,\oT] \newstuff +The \PASCAL\ part of an unnamed module begins with \.{@u} +(or \.{@U}). +\endnewstuff +This causes \.{TANGLE} to append the following \PASCAL\ code +to the initial program text $T_0$ as explained above. +The \.{WEAVE} +processor does not cause a `\.{@u}' to appear explicitly in the \TeX\ +output, so if you are creating a \.{WEB} file based on a \TeX-printed +\.{WEB} documentation you have to remember to insert \.{@u} in the +appropriate places of the unnamed modules. + +\@< [\PAS,\oT] A module name begins with \.{@<} followed by \TeX\ text followed +by \.{@>}; the \TeX\ text should not contain any \.{WEB} control sequences +except \.{@@}, unless these control sequences appear in \PASCAL\ text that +is delimited by \pb. +The module name may be abbreviated, after its first +appearance in a \.{WEB} file, by giving any unique prefix followed by \.{...}, +where the three dots immediately precede the closing \.{@>}. +Module names may +not appear in \PASCAL\ text that is enclosed in \pb, nor may they appear +in the definition part of a module (since the appearance of a module name +ends the definition part and begins the \PASCAL\ part). + + +\@( [\PAS,\oT] \newstuff A module beginning +with \.{@(} is treated like one beginning with \.{@<}, +except that the module name is treated as the name of a file to which +the module will be written. +If such modules are used in other modules the results are undefined. +\endnewstuff + +\@\' [\PAS,T] This denotes an octal constant, to be formed from the +succeeding digits. +For example, if the \.{WEB} file contains `\.{@\'100}', +the \.{TANGLE} processor will treat this an equivalent to `\.{64}'; +the constant will be formatted as ``\O{\~100}'' in the \TeX\ output +produced via \.{WEAVE}. +You should use octal notation only for positive +constants; don't try to get, e.g., $-1$ by saying `\.{@\'777777777777}'. + +\@" [\PAS,T] A hexadecimal constant; `\.{@"D0D0}' tangles to \.{53456} and +weaves to `\O{\^D0D0}'. + +%\@\$ [\PAS] This denotes the string pool check sum. + +%\@\{ [\PAS] The beginning of a ``meta comment,'' i.e., a comment +%that is supposed to appear in the \PASCAL\ code, is indicated by +%\.{@\{} in the \.{WEB} file. +%Such delimiters can be used as +%isolated symbols in macros or modules, but they should be properly nested +%in the final \PASCAL\ program. +%The \.{TANGLE} processor will convert +%`\.{@\{}' into `\.\{' in the \PASCAL\ output file, unless +%the output is already part of a meta-comment; in the latter case +%`\.{@\{}' is converted into `\.[', since +%we don't assume that \PASCAL\ allows +%nested comments. +%Meta-comments +%can be used to put conditional text into an \PASCAL\ program; this helps to +%overcome one of the limitations of \.{WEB}, since the simple macro +%processing routines of \.{TANGLE} do not include the dynamic evaluation of +%boolean expressions. +%\newstuff +%Where is this trick explained, and note that it only works in +%languages whose comments don't end with newline. +%\endnewstuff +% +%\@\} [\PAS] The end of a ``meta comment'' is indicated by `\.{@\}}'; this is +%converted either into `\.\}' or `\.{]}' in the \PASCAL\ output, according +%to the conventions explained for \.{@\{} above. + +\@\& [\PAS] The \.{@\&} operation causes whatever is on its left to be +adjacent to whatever is on its right, in the \PASCAL\ output. +No spaces or +line breaks will separate these two items. +However, the thing on the left +should not be a semicolon, since a line break might occur after a semicolon. + +\@\^ [\PAS,T] The ``control text'' that follows, up to the next +`\.{@>}', will be entered into the index together with the identifiers of +the \PASCAL\ program; this text will appear in roman type. +For example, to +put the phrase ``system dependencies'' into the index, you can type +`\.{@\^system dependencies@>}' in each module +that you want to index as system dependent. +A control text, like a string, +must end on the same line of the \.{WEB} file as it began. +Furthermore, +no \.{WEB} control sequences are allowed in a control text, not even +\.{@@}. +(If you need an \.{@} sign you can get around this restriction by +typing `\.{\\AT!}'.) + +\@. +[\PAS,T] The ``control text'' that follows will be entered into the index +in \.{typewriter} \.{type}; see the rules for `\.{@\^}', which is analogous. + +\@: [\PAS,T] The ``control text'' that follows will be entered into the index +in a format controlled by the \TeX\ macro `\.{\\9}', which the user +should define as desired; see the rules for `\.{@\^}', which is analogous. + +\@t [\PAS] The ``control text'' that follows, up to the next `\.{@>}', will +be put into a \TeX\ \.{\\hbox} and formatted along with the neighboring +\PASCAL\ program. +This text is ignored by \.{TANGLE}, but it can be used +for various purposes within \.{WEAVE}. +For example, you can make comments +that mix \PASCAL\ and classical mathematics, as in `$\\{size}<2^{15}$', by +typing `\.{|size < @t\$2\^\{15\}\$@>|}'. +A control text must end on the +same line of the \.{WEB} file as it began, and it may not contain any +\.{WEB} control codes. + +\@= [\PAS] The ``control text'' that follows, up to the next `\.{@>}', will +be passed verbatim to the \PASCAL\ program. + +%%% \@\\ [\PAS] Force end-of-line here in the \PASCAL\ program file. + +\@! [\PAS,T] The module number in an index entry will be underlined if `\.{@!}' +immediately precedes the identifier or control text being indexed. +This +convention is used to distinguish the modules where an identifier is +defined, or where it is explained in some special way, from the modules +where it is used. +A~reserved word or an identifier of length one will not +be indexed except for underlined entries. +%An `\.{@!}' is implicitly inserted +%by \.{WEAVE} just after the reserved words \&{function}, \&{procedure}, +%\&{program}, and \&{var}, and just after \.{@d} and \.{@f}. +%But you should +%insert your own `\.{@!}' before the definitions of types, constants, +%variables, parameters, and components of records and enumerated types that +%are not covered by this implicit convention, if you want to improve the +%quality of the index that you get. +\newstuff +Some Spidery \.{WEAVE}s will insert implicit `\.{@!}' tokens in places +like function definitions or variable declarations. +The person who built your Spidery \.{WEB} should have documented these +places; if not, they can be discovered by examing the {\tt .spider} +file. +The automatic definitions work well for some languages, but +for the best possible index you should insert your own `\.{@!}' token before +the defining instance of every identifier. +\endnewstuff + +\@? +[\PAS,T] This cancels an implicit (or explicit) `\.{@!}', so that the next +index entry will not be underlined. +\newstuff This is not implemented in the current version of Spidery \.{WEB}. +\endnewstuff + +\@, [\PAS] This control code inserts a thin space in \.{WEAVE}'s output; it is +ignored by \.{TANGLE}. +Sometimes you need this extra space if you are using +macros in an unusual way, e.g., if two identifiers are adjacent. + +\@/ [\PAS] This control code causes a line break to occur within an \PASCAL\ +program formatted by \.{WEAVE}; it is ignored by \.{TANGLE}. +Line breaks +are chosen automatically by \TeX\ according to a scheme that works 99\%\ +of the time, but sometimes you will prefer to force a line break so that +the program is segmented according to logical rather than visual criteria. +\newstuff +The line following such a line break is indented at the same level as +the line broken. +\endnewstuff +Caution: `\.{@/}' should be used only after statements or clauses, not in +the middle of an expression; use \.{@|} in the middle of expressions, in +order to keep \.{WEAVE}'s parser happy. + +\@- [\PAS] \newstuff +This control code makes \.{WEAVE} continue the current +statement on the next line; it is ignored by \.{TANGLE}. +If is just like `\.{@/}', except that the following line is indented, +to show that it is a continuation of the line broken. +\endnewstuff + +\@| [\PAS] This control code specifies an optional line break in the midst of +an expression. +For example, if you have a long condition between \&{if} and +\&{then}, or a long expression on the right-hand side of an assignment +statement, you can use `\.{@|}' to specify breakpoints more logical than +the ones that \TeX\ might choose on visual grounds. + +\@\# [\PAS] This control code forces a line break, like \.{@/} does, +and it also causes a little extra white space to appear between the lines at +this break. +You might use it, for example, between procedure definitions or +between groups of macro definitions that are logically separate but within +the same module. + +\@+ [\PAS] This control code cancels a line break that might otherwise be +inserted by \.{WEAVE}, e.g., before the word `\&{else}', if you want to +put a short if-then-else construction on a single line. +It is ignored by +\.{TANGLE}. + +\@; [\PAS] Usually this control code is treated like a semicolon, for +formatting purposes, except that it is invisible. +\newstuff +The person who built your \.{WEB} can redefine it, though, so check +his documentation to make sure. +\endnewstuff + +You can use it, for example, after +a module name when the \PASCAL\ text represented by that module name ends +with a semicolon. + +\yskip\noindent +The last \newstuff seven \endnewstuff + control codes (namely `\.{@,}', `\.{@/}', `\.{@-}', `\.{@|}', +`\.{@\#}', `\.{@+}', and `\.{@;}') have no effect on the \PASCAL\ +program output by \.{TANGLE}; they merely help to improve the readability +of the \TeX-formatted \PASCAL\ that is output by \.{WEAVE}, in unusual +circumstances. +\.{WEAVE}'s built-in formatting method is fairly good, but +it is incapable of handling all possible cases, because it must deal with +fragments of text involving macros and module names; these fragments do +not necessarily obey \PASCAL's syntax. +Although \.{WEB} allows you to +override the automatic formatting, your best strategy is not to worry +about such things until you have seen what \.{WEAVE} produces automatically, +since you will probably need to make only a few corrections when you are +touching up your documentation. + +Because of the rules by which every module is broken into three parts, +the control codes `\.{@d}', `\.{@f}', and `\.{@u}' are not allowed to occur +once the \PASCAL\ part of a module has begun. + +\section Additional features and caveats. + +%1. +%The character pairs `\.{(*}', `\.{*)}', `\.{(.}', and `\.{.)}' are +%converted automatically in \PASCAL\ text as though they were +%`\.{@\{}', `\.{@\}}', `\.[', and `\.]', respectively, except +%%of course in strings. +%Furthermore in certain installations of \.{WEB} that +%{\def\\#1#2{`{\tentex\char'#1#2}'}% +%have an extended character set, the characters \\32, \\34, \\35, \\30, +%\\36, \\04, \\37, \\05, and \\06} +%can be used as abbreviations for +%`\.{<>}', `\.{<=}', `\.{>=}', `\.{:=}', `\.{==}', `\.{and}', `\.{or}', +%`\.{not}', and `\.{in}', respectively. +%However, the latter abbreviations +%are not used in the standard versions of \.{WEAVE.WEB} and \.{TANGLE.WEB} +%that are distributed to people who are installing \.{WEB} on other +%computers, and the programs are designed to produce only standard ASCII +%characters as output if the input consists entirely of ASCII characters. +% +%2. +%If you have an extended character set, all of the characters listed +%in Appendix C of {\sl The \TeX book\/} can be used in strings. +%But you should +%stick to standard ASCII characters if you want to write programs that will +%be useful to the all the poor souls out there who don't have extended +%character sets. + +3. +The \TeX\ file output by \.{WEAVE} is broken into lines having at most +80 characters each. +The algorithm that does this line breaking is unaware +of \TeX's convention about comments following `\.\%' signs on a line. +When +\TeX\ text is being copied, the existing line breaks are copied as well, +so there is no problem with `\.\%' signs unless the original \.{WEB} file +contains a line more than eighty characters long or a line with \PASCAL\ +text in \pb\ that expands to more than eighty characters long. +Such lines +should not have `\.\%' signs. + +4. +\PASCAL\ text is translated by a ``bottom up'' procedure that +identifies each token as a ``part of speech'' and combines parts of speech +into larger and larger phrases as much as possible according to a special +\newstuff prettyprinting \endnewstuff +grammar. +The grammar and the translation process are explained in the +``Spider User's Guide.'' +It is easy to +learn the translation scheme for simple constructions like single +identifiers and short expressions, just by looking at a few examples of +what \.{WEAVE} does, but the general mechanism is somewhat complex because +it must handle much more than \PASCAL\ itself. +Furthermore the output +contains embedded codes that cause \TeX\ to indent and break lines as +necessary, depending on the fonts used and the desired page width. +For +best results it is wise to adhere to the following restrictions: + +\yskip\itemitem{a)}Comments in \PASCAL\ text should appear only after +statements or clauses; i.e., +\newstuff(if \PASCAL\ were PASCAL) \endnewstuff +after semicolons, after reserved words like +\&{then} and \&{do}, or before reserved words like \&{end} and \&{else}. +Otherwise \.{WEAVE}'s parsing method may well get mixed up. + +\itemitem{b)}Don't enclose long \PASCAL\ texts in \pb, since the +indentation and line breaking codes are omitted when the \pb\ text is +translated from \PASCAL\ to \TeX. +Stick to simple expressions or +statements. + +\yskip +5. +Comments and module names are not permitted in \pb\ text. +After a `\.|' +signals the change from \TeX\ text to \PASCAL\ text, the next `\.|' that is +not part of a string or control text ends the \PASCAL\ text. + +6. +\newstuff +Spidery {\tt WEB} does not handle nested comments. +\endnewstuff +%A comment must have properly nested occurrences of left and right +% braces, otherwise \.{WEAVE} and \.{TANGLE} will not know where the comment +% ends. +%However, the character pairs `\.{\\\{}' and `\.{\\\}}' do not count +%as left and right braces in comments, and the character pair `\.{\\|}' +%does not count as a delimiter that begins \PASCAL\ text. +%(The actual rule +%is that a character after `\.\\' is ignored; hence in `\.{\\\\\{}' the +%left brace {\sl does\/} count.) At present, \.{TANGLE} and \.{WEAVE} treat +%comments in slightly different ways, and it is necessary to satisfy both +%conventions: \.{TANGLE} ignores `\.|' characters entirely, while \.{WEAVE} +%uses them to switch between \TeX\ text and \PASCAL\ text. +%Therefore, a +%comment that includes a brace in a string in \pb---e.g., `\.{\{{ }look at +%this |"\{"| \}}'---will be handled correctly by \.{WEAVE}, but \.{TANGLE} +%will think there is an unmatched left brace. +%In order to satisfy both +%processors, one can write `\.{\{{ }look at this \\leftbrace\\{ }\}}', after +%setting up`\.{\\def\\leftbrace\{|"\{"|\}}'. + +7. +Reserved words of \PASCAL\ must appear entirely in lowercase letters +in the \.{WEB} file; otherwise their special nature will not be recognized +by \.{WEAVE}. +\newstuff +This could be changed, but the author of Spidery {\tt WEB} does not +believe in case-insensitivity for programming languages. +\endnewstuff +You could, for example, have a macro named \\{END} and it +would not be confused with \&{end}. + +However, you may not want to capitalize macro names just to distinguish them +from other identifiers. +Here is a way to unreserve Pascal's reserved word +`\&{type}' and to substitute another word `\&{mtype}' in the \.{WEB} file. +$$\vbox{\halign{\tt #\hfil\cr +@d type(\char'43) = mem[\char'43].t\cr +@d mtype = t \char'100\char'46{} y \char'100\char'46{} p + \char'100\char'46{} e\cr +@f mtype = type\cr +@f type = true\cr}}$$ +In the output of \.{TANGLE}, the macro \.{mtype} now produces `\.{TYPE}' +and the macro \.{type(x)} now produces `\.{MEM[X].T}'. +In the output of +\.{WEAVE}, these same inputs produce \&{mtype} and \\{type}(\|x), +respectively. + +8. +The \.{@f} feature allows you to define one identifier to act like +another, and these format definitions are carried out sequentially, as the +example above indicates. +However, a given identifier has only one printed format +throughout the entire document (and this format will even be used before +the \.{@f} that defines it). +The reason is that \.{WEAVE} operates in two +passes; it processes \.{@f}'s and cross-references on the first pass and +does the output on the second. + +9. +You may want some \.{@f} formatting that doesn't correspond to any +existing reserved word. +In that case, \.{WEAVE} could be extended +\newstuff +by someone who built Spidery {\tt WEB} +\endnewstuff +to include new ``reserved words'' in its vocabulary. +\newstuff +(The ``\/{Spider} User's Guide'' explains how.) +\endnewstuff + +%The identifier `\&{xclause}' has in fact been included already as a +%reserved word, so that it can be used to format the `\&{loop}' macro, +%where `\&{loop}' is defined to be equivalent to `\&{while \\{true} do}'. + +10. +Sometimes it is desirable to insert spacing into \PASCAL\ code that is +more general than the thin space provided by `\.{@,}'. +The \.{@t} feature +can be used for this purpose; e.g., `\.{@t\\hskip 1in@>}' will +leave one inch of blank space. +Furthermore, `\.{@t\\4@>}' can be +used to backspace by one unit of indentation, since the control sequence +\.{\\4} is defined in \.{webmac} to be such a backspace. +(This +control sequence is used, for example, at the beginning of lines that +contain labeled statements, so that the label will stick out a little at +the left.) + +11. +\.{WEAVE} and \.{TANGLE} are designed to work with two input files, +called \\{web\_file} and \\{change\_file}, where \\{change\_file} contains +data that overrides selected portions of \\{web\_file}. +The resulting merged +text is actually what has been called the \.{WEB} file elsewhere in this +report. + +Here's how it works: The change file consists of zero or more ``changes,'' +where a change has the form `\.{@x}$\langle$old lines$\rangle$\.{@y}$\langle$% +new lines$\rangle$\.{@z}'. +The special control codes \.{@x}, \.{@y}, \.{@z}, +which are allowed only in change files, must appear at the beginning of a line; +the remainder of such a line is ignored. +The $\langle$old lines$\rangle$ represent material that exactly matches +consecutive lines of the \\{web\_file}; the $\langle$new lines$\rangle$ +represent zero or more lines that are supposed to replace the old. +Whenever +the first ``old line'' of a change is found to match a line in the +\\{web\_file}, all the other lines in that change must match too. + +Between changes, before the first change, and after the last change, +the change file can have any number of lines that do not begin with +`\.{@x}', `\.{@y}', or~`\.{@z}'. +Such lines are bypassed and not used for +matching purposes. + +This dual-input feature is useful when working with a master \.{WEB} file +that has been received from elsewhere (e.g., \.{TANGLE.WEB} or +\.{WEAVE.WEB} or \.{TEX.WEB}), when changes are desirable to customize the +program for your local computer system. +You will be able to debug your +system-dependent changes without clobbering the master web file; and once +your changes are working, you will be able to incorporate them readily +into new releases of the master web file that you might receive from time +to time. + +\newstuff +There are several multiple-changefile tools in the {\TeX} community; +check back issues of TUGboat for more information. +\endnewstuff + +\section Appendices. +% The basic ideas of \.{WEB} can be understood most easily by looking at +% examples of ``real'' programs. +% Appendix~A shows the \.{WEB} input that +% generated modules 55--59 of the \.{WEAVE} program; Appendix~B shows the +% corresponding \TeX\ code output by \.{WEAVE}; and Appendix~C shows excerpts +% from the corresponding \PASCAL\ code output by \.{TANGLE}. +% +% The complete webs for \.{WEAVE} and \.{TANGLE} appear as the bulk of this +% report, in Appendices D and~E. +% The reader should first compare Appendix~A +% to the corresponding portion of Appendix~D; then the same material should +% be compared to Appendices B and~C. +% Finally, if time permits, the reader may +% enjoy studying the complete programs in Appendices D and~E, since \.{WEAVE} +% and \.{TANGLE} contain several interesting aspects, and since an attempt +% has been made in these appendices to evolve a style of programming that +% makes good use of the \.{WEB} language. +% +% Finally, Appendix F is the `\.{webkernel}' file that sets \TeX\ up to accept +% the output of \.{WEAVE}; Appendix~G discusses how to use some of its macros +% to vary the output formats; and Appendix~H discusses what needs to be done +% when \.{WEAVE} and \.{TANGLE} are installed in a new operating environment. +% +% \section Performance statistics. +% The programs in Appendices D and E will optionally keep statistics on +% how much memory they require. +% Here is what they printed out when +% processing themselves: +% +% \def\pstat#1#2#3 +% #4{\yskip\noindent\.{#1} applied to \.{#2} (cpu time #3 sec)\par +% \halign{\quad\tt##\hfil\cr#4}} +% +% \pstat{TANGLE}{TANGLE}{15} +% {Memory usage statistics:\cr +% 456 names, 215 replacement texts;\cr +% 3396+3361 bytes, 6685+7329+5805 tokens.\cr} +% +% \pstat{TANGLE}{WEAVE}{30} +% {Memory usage statistics:\cr +% 692 names, 339 replacement texts;\cr +% 4576+4294 bytes, 10184+9875+9150 tokens.\cr} +% +% \pstat{WEAVE}{TANGLE}{45} +% {Memory usage statistics: 478 names, 2045 cross references, 4159+3729 bytes;\cr +% parsing required 684 scraps, 1300 texts, 3766 tokens, 119 levels;\cr +% sorting required 34 levels.\cr} +% +% \pstat{WEAVE}{WEAVE}{65} +% {Memory usage statistics: 737 names, 3306 cross references, 4896+4962 bytes;\cr +% parsing required 684 scraps, 1300 texts, 3766 tokens, 119 levels;\cr +% sorting required 73 levels.\cr} +% +% \yskip\noindent The cpu time for \PASCAL\ to process \.{TANGLE.PAS} was +% approximately 13 seconds, and \.{WEAVE.PAS} took approximately 26 seconds; +% thus the tangling time was slightly more than the compiling time. +% The cpu +% time for \TeX\ to process \.{TANGLE.TEX} was approximately 500 seconds, +% and \.{WEAVE.TEX} took approximately 750 seconds (i.e., about 7 +% seconds per printed page, where these pages are substantially larger than +% the pages in a normal book). +% All cpu times quoted are for a DECsystem-10. +% +% \def\K{{\mc K}} +% The file \.{TANGLE.WEB} is about 125\K\ characters long; \.{TANGLE} +% reduces it to a file \.{TANGLE.PAS} whose size is about 42\K\ characters, +% while \.{WEAVE} expands it to a file \.{TANGLE.TEX} of about 185\K\null. +% The corresponding file sizes for \.{WEAVE.WEB}, \.{WEAVE.PAS}, and +% \.{WEAVE.TEX} are 180\K, 89\K, and 265\K. +% +% The much larger file \.{TEX.WEB} led to the following numbers: +% +% \pstat{TANGLE}{TEX}{110} +% {Memory usage statistics:\cr +% 3750 names, 1768 replacement texts;\cr +% 41895+41053 bytes, 42378+45074+41091 tokens.\cr} +% +% \pstat{WEAVE}{TEX}{270} +% {Memory usage statistics: 3412 names, 19699 cross references, +% 37900+40232 bytes;\cr +% parsing required 685 scraps, 1303 texts, 3784 tokens, 104 levels;\cr +% sorting required 52 levels.\cr} +% +% \yskip\noindent +% \PASCAL\ did \.{TEX.PAS} in about 75 seconds; \TeX\ did \.{TEX.TEX} +% in about 3600. +% +% % Here is a quotation that could not really be omitted +% +% \vfill +% +% {\baselineskip9pt +% \halign to\hsize{\hfil\quoteit#\tabskip 0pt plus 100pt& +% \hfil\quoteit#\tabskip 0pt\cr +% O, what a tangled web we weave& +% O, what a tangled WEB we weave\cr +% When first we practise to deceive!& +% When \TeX\ we practise to conceive!\cr +% \noalign{\vskip 2pt} +% \quoterm ---SIR WALTER SCOTT, {\quoteit Marmion} 6:17 (1808)& +% \quoterm ---RICHARD PALAIS (1982)\cr +% }} +% \eject +% +% \def\runninghead{APPENDIX A --- {\tentt WEB} FILE FORMAT} +% \section Appendix A. +% This excerpt from \.{WEAVE.WEB} produced modules 55--59 in Appendix~D. +% Note that some of the lines are indented to show the program structure. +% The indentation is ignored by \.{WEAVE} and \.{TANGLE}, but users find +% that \.{WEB} files are quite readable if they have some such indentation. +% +% \vskip 6pt +% \begingroup \def\tt{\eighttt} \baselineskip9pt +% % Note to myself: I had to remove SAIL characters from the file here! +% % Also tabs replaced by double-space. +% The changes were made in WEAVE source. +% \verbatim +% @* Searching for identifiers. +% The hash table described above is updated by the |id_lookup| procedure, +% which finds a given identifier and returns a pointer to its index in +% |byte_start|. +% The identifier is supposed to match character by character +% and it is also supposed to have a given |ilk| code; the same name may be +% present more than once if it is supposed to appear in the index with +% different typesetting conventions. +% If the identifier was not already present, it is inserted into the table. +% +% Because of the way \.{WEAVE}'s scanning mechanism works, it is most convenient +% to let |id_lookup| search for an identifier that is present in the |buffer| +% array. +% Two other global variables specify its position in the buffer: the +% first character is |buffer[id_first]|, and the last is |buffer[id_loc-1]|. +% +% @<Glob...@>= +% @!id_first:0..long_buf_size; {where the current identifier begins in the buffer} +% @!id_loc:0..long_buf_size; {just after the current identifier in the buffer} +% @# +% @!hash:array [0..hash_size] of sixteen_bits; {heads of hash lists} +% +% @ Initially all the hash lists are empty. +% +% @<Local variables for init...@>= +% @!h:0..hash_size; {index into hash-head array} +% +% @ @<Set init...@>= +% for h:=0 to hash_size-1 do hash[h]:=0; +% +% @ Here now is the main procedure for finding identifiers (and index +% entries). +% The parameter |t| is set to the desired |ilk| code. +% The +% identifier must either have |ilk=t|, or we must have +% |t=normal| and the identifier must be a reserved word. +% +% @p function id_lookup(@!t:eight_bits):name_pointer; {finds current identifier} +% label found; +% var i:0..long_buf_size; {index into |buffer|} +% @!h:0..hash_size; {hash code} +% @!k:0..max_bytes; {index into |byte_mem|} +% @!w:0..ww-1; {row of |byte_mem|} +% @!l:0..long_buf_size; {length of the given identifier} +% @!p:name_pointer; {where the identifier is being sought} +% begin l:=id_loc-id_first; {compute the length} +% @<Compute the hash code |h|@>; +% @<Compute the name location |p|@>; +% if p=name_ptr then @<Enter a new name into the table at position |p|@>; +% id_lookup:=p; +% end; +% +% @ A simple hash code is used: If the sequence of +% ASCII codes is $c_1c_2\ldots c_m$, its hash value will be +% $$(2^{n-1}c_1+2^{n-2}c_2+\cdots+c_n)\,\bmod\,|hash_size|.$$ +% +% @<Compute the hash...@>= +% h:=buffer[id_first]; i:=id_first+1; +% while i<id_loc do +% begin h:=(h+h+buffer[i]) mod hash_size; incr(i); +% end +% ?endgroup % end of verbatim mode +% \endgroup +% \vfill\eject +% +% \def\runninghead{APPENDIX B --- TRANSLATION BY {\tentt WEAVE}} +% \section Appendix B. +% This excerpt from \.{WEAVE.TEX} corresponds to Appendix A. +% +% % I've inserted \vfill's here at the blank lines, to squeeze this on one page! +% \begingroup \def\tt{\eighttt} \baselineskip9pt +% \verbatim +% ?vfill?verbatimgobble +% \N55. +% Searching for identifiers. +% The hash table described above is updated by the \\{id\_lookup} procedure, +% which finds a given identifier and returns a pointer to its index in +% \\{byte\_start}. +% The identifier is supposed to match character by character +% and it is also supposed to have a given \\{ilk} code; the same name may be +% present more than once if it is supposed to appear in the index with +% different typesetting conventions. +% If the identifier was not already present, it is inserted into the table. +% ?vfill?verbatimgobble +% Because of the way \.{WEAVE}'s scanning mechanism works, it is most convenient +% to let \\{id\_lookup} search for an identifier that is present in the % +% \\{buffer} +% array. +% Two other global variables specify its position in the buffer: the +% first character is $\\{buffer}[\\{id\_first}]$, and the last is $\\{buffer}[% +% \\{id\_loc}-1]$. +% ?vfill?verbatimgobble +% \Y\P$\4\X9:Globals in the outer block\X\mathrel{+}\S$\6 +% \4\\{id\_first}: \37$0\to\\{long\_buf\_size}$;\C{where the current identifier +% begins in the buffer}\6 +% \4\\{id\_loc}: \37$0\to\\{long\_buf\_size}$;\C{just after the current +% identifier in the buffer}\7 +% \4\\{hash}: \37\&{array} $[0\to\\{hash\_size}]$ \1\&{of}\5 +% \\{sixteen\_bits};\C{heads of hash lists}\2\par +% \fi +% ?vfill?verbatimgobble +% \M56. +% Initially all the hash lists are empty. +% ?vfill?verbatimgobble +% \Y\P$\4\X16:Local variables for initialization\X\mathrel{+}\S$\6 +% \4\|h: \37$0\to\\{hash\_size}$;\C{index into hash-head array}\par +% \fi +% ?vfill?verbatimgobble +% \M57. +% \P$\X10:Set initial values\X\mathrel{+}\S$\6 +% \&{for} $\|h\K0\mathrel{\&{to}}\\{hash\_size}-1$ \1\&{do}\5 +% $\\{hash}[\|h]\K0$;\2\par +% \fi +% ?vfill?verbatimgobble +% \M58. +% Here now is the main procedure for finding identifiers (and index +% entries). +% The parameter \|t is set to the desired \\{ilk} code. +% The +% identifier must either have $\\{ilk}=\|t$, or we must have +% $\|t=\\{normal}$ and the identifier must be a reserved word. +% ?vfill?verbatimgobble +% \Y\P\4\&{function}\1\ \37$\\{id\_lookup}(\|t:\\{eight\_bits})$: \37\\{name% +% \_pointer};\C{finds current identifier}\6 +% \4\&{label} \37\\{found};\6 +% \4\&{var} \37\|i: \37$0\to\\{long\_buf\_size}$;\C{index into \\{buffer}}\6 +% \|h: \37$0\to\\{hash\_size}$;\C{hash code}\6 +% \|k: \37$0\to\\{max\_bytes}$;\C{index into \\{byte\_mem}}\6 +% \|w: \37$0\to\\{ww}-1$;\C{row of \\{byte\_mem}}\6 +% \|l: \37$0\to\\{long\_buf\_size}$;\C{length of the given identifier}\6 +% \|p: \37\\{name\_pointer};\C{where the identifier is being sought}\2\6 +% \&{begin} \37$\|l\K\\{id\_loc}-\\{id\_first}$;\C{compute the length}\6 +% \X59:Compute the hash code \|h\X;\6 +% \X60:Compute the name location \|p\X;\6 +% \&{if} $\|p=\\{name\_ptr}$ \1\&{then}\5 +% \X62:Enter a new name into the table at position \|p\X;\2\6 +% $\\{id\_lookup}\K\|p$;\6 +% \&{end};\par +% \fi +% ?vfill?verbatimgobble +% \M59. +% A simple hash code is used: If the sequence of +% ASCII codes is $c_1c_2\ldots c_m$, its hash value will be +% $$(2^{n-1}c_1+2^{n-2}c_2+\cdots+c_n)\,\bmod\,\\{hash\_size}.$$ +% ?vfill?verbatimgobble +% \Y\P$\4\X59:Compute the hash code \|h\X\S$\6 +% $\|h\K\\{buffer}[\\{id\_first}]$;\5 +% $\|i\K\\{id\_first}+1$;\6 +% \&{while} $\|i<\\{id\_loc}$ \1\&{do}\6 +% \&{begin} \37$\|h\K(\|h+\|h+\\{buffer}[\|i])\mathbin{\&{mod}}\\{hash\_size}$;\5 +% $\\{incr}(\|i)$;\6 +% \&{end}\2\par +% \U section~58.\fi +% ?endgroup +% \endgroup +% \eject +% +% \def\runninghead{APPENDIX C --- TRANSLATION BY {\tentt TANGLE}} +% \section Appendix C. +% The \.{TANGLE} processor converts \.{WEAVE.WEB} into a syntactically +% correct (but not very pretty) \PASCAL\ program \.{WEAVE.PAS}. +% The first three and last two lines of output are shown here, together with the +% lines of code generated by modules 55--62 and the environments of +% those lines. +% There are 1559 lines in all; the notation +% `\.. \\. +% \\.' stands for portions that are not shown. +% +% Note that, for example, the code corresponding to +% module 55 begins with `\.{\{55:\}}' and ends with `\.{\{:55\}}'; +% the code from modules 59--62 has been tangled into the code from module 58. +% +% \vskip6pt +% \verbatim +% {2:}{4:}{$C-,A+,D-}{[$C+,D+]}{:4} +% PROGRAM WEAVE(WEBFILE,CHANGEFILE,TEXFILE);LABEL 9999;CONST{8:} +% MAXBYTES=45000;MAXNAMES=5000;MAXMODULES=2000;HASHSIZE=353;BUFSIZE=100; +% . +% . . +% TOKPTR:0..MAXTOKS;{MAXTOKPTR,MAXTXTPTR:0..MAXTOKS;}{:53}{55:} +% IDFIRST:0..LONGBUFSIZE;IDLOC:0..LONGBUFSIZE; +% HASH:ARRAY[0..HASHSIZE]OF SIXTEENBITS;{:55}{63:}CURNAME:NAMEPOINTER; +% . +% . . +% PROCEDURE INITIALIZE;VAR{16:}I:0..127;{:16}{40:}WI:0..1;{:40}{56:} +% H:0..HASHSIZE;{:56}{247:}C:ASCIICODE;{:247}BEGIN{10:}HISTORY:=0;{:10} +% . +% . . +% TOKPTR:=1;TEXTPTR:=1;TOKSTART[0]:=1;TOKSTART[1]:=1;{MAXTOKPTR:=1; +% MAXTXTPTR:=1;}{:54}{57:}FOR H:=0 TO HASHSIZE-1 DO HASH[H]:=0;{:57}{94:} +% SCANNINGHEX:=FALSE;{:94}{102:}MODTEXT[0]:=32;{:102}{124:}OUTPTR:=1; +% . +% . . +% IF R=0 THEN XREF[P]:=XREFPTR ELSE XMEM[R].XLINKFIELD:=XREFPTR;END;{:51} +% {58:}FUNCTION IDLOOKUP(T:EIGHTBITS):NAMEPOINTER;LABEL 31; +% VAR I:0..LONGBUFSIZE;H:0..HASHSIZE;K:0..MAXBYTES;W:0..1; +% L:0..LONGBUFSIZE;P:NAMEPOINTER;BEGIN L:=IDLOC-IDFIRST;{59:} +% H:=BUFFER[IDFIRST];I:=IDFIRST+1; +% WHILE I<IDLOC DO BEGIN H:=(H+H+BUFFER[I])MOD HASHSIZE;I:=I+1;END{:59}; +% {60:}P:=HASH[H]; +% WHILE P<>0 DO BEGIN IF(BYTESTART[P+2]-BYTESTART[P]=L)AND((ILK[P]=T)OR((T +% =0)AND(ILK[P]>3)))THEN{61:}BEGIN I:=IDFIRST;K:=BYTESTART[P];W:=P MOD 2; +% WHILE(I<IDLOC)AND(BUFFER[I]=BYTEMEM[W,K])DO BEGIN I:=I+1;K:=K+1;END; +% IF I=IDLOC THEN GOTO 31;END{:61};P:=LINK[P];END;P:=NAMEPTR; +% LINK[P]:=HASH[H];HASH[H]:=P;31:{:60};IF P=NAMEPTR THEN{62:} +% BEGIN W:=NAMEPTR MOD 2; +% IF BYTEPTR[W]+L>MAXBYTES THEN BEGIN WRITELN(TERMOUT); +% WRITE(TERMOUT,'! Sorry, ','byte memory',' capacity exceeded');ERROR; +% HISTORY:=3;JUMPOUT;END; +% IF NAMEPTR+2>MAXNAMES THEN BEGIN WRITELN(TERMOUT); +% WRITE(TERMOUT,'! Sorry, ','name',' capacity exceeded');ERROR;HISTORY:=3; +% JUMPOUT;END;I:=IDFIRST;K:=BYTEPTR[W]; +% WHILE I<IDLOC DO BEGIN BYTEMEM[W,K]:=BUFFER[I];K:=K+1;I:=I+1;END; +% BYTEPTR[W]:=K;BYTESTART[NAMEPTR+2]:=K;NAMEPTR:=NAMEPTR+1;ILK[P]:=T; +% XREF[P]:=0;END{:62};IDLOOKUP:=P;END;{:58}{66:} +% FUNCTION MODLOOKUP(L:SIXTEENBITS):NAMEPOINTER;LABEL 31;VAR C:0..4; +% . +% . . +% WRITE(TERMOUT,'(That was a fatal error, my friend.)');END;END{:263}; +% END.{:261} +% ?endgroup +% \vfill\eject +% +% \pageno=199 % take account of the page numbers for App's D and E. +% +% \def\runninghead{APPENDIX F --- MACROS FOR FORMATTING} +% \section Appendix F: The \.{webmac.tex} file. +% This is the file that extends ``plain \TeX'' format in order to support the +% features needed by the output of \.{WEAVE}. +% +% \vskip6pt +% \verbatim +% % standard macros for WEB listings (in addition to PLAIN.TEX) +% \xdef\fmtversion{\fmtversion+WEBMAC1.3} % identifies current set of macros +% \parskip 0pt % no stretch between paragraphs +% \parindent 1em % for paragraphs and for the first line of Pascal text +% +% \font\eightrm=cmr8 +% \let\sc=\eightrm \let\mainfont=\tenrm +% \font\titlefont=cmr7 scaled\magstep4 % title on the contents page +% \font\ttitlefont=cmtt10 scaled\magstep2 % typewriter type in title +% \font\tentex=cmtex10 % TeX extended character set (used in strings) +% +% \def\\#1{\hbox{\it#1\/\kern.05em}} % italic type for identifiers +% \def\|#1{\hbox{$#1$}} % one-letter identifiers look a bit better this way +% \def\{\hbox{\bf#1\/}} % boldface type for reserved words +% \def\.#1{\hbox{\tentex % typewriter type for strings +% \let\\=\BS % backslash in a string +% \let\'=\RQ % right quote in a string +% \let\`=\LQ % left quote in a string +% \let\{=\LB % left brace in a string +% \let\}=\RB % right brace in a string +% \let\~=\TL % tilde in a string +% \let\ =\SP % space in a string +% \let\_=\UL % underline in a string +% \let\&=\AM % ampersand in a string +% #1}} +% \def\#{\hbox{\tt\char`\#}} % parameter sign +% \def\${\hbox{\tt\char`\$}} % dollar sign +% \def\%{\hbox{\tt\char`\%}} % percent sign +% \def\^{\ifmmode\mathchar"222 \else\char`^ \fi} % pointer or hat +% % circumflex accents can be obtained from \^^D instead of \^ +% \def\AT!{@} % at sign for control text +% +% \chardef\AM=`\& % ampersand character in a string +% \chardef\BS=`\\ % backslash in a string +% \chardef\LB=`\{ % left brace in a string +% \def\LQ{{\tt\char'22}} % left quote in a string +% \chardef\RB=`\} % right brace in a string +% \def\RQ{{\tt\char'23}} % right quote in a string +% \def\SP{{\tt\char`\ }} % (visible) space in a string +% \chardef\TL=`\~ % tilde in a string +% \chardef\UL=`\_ % underline character in a string +% +% \newbox\bak \setbox\bak=\hbox to -1em{} % backspace one em +% \newbox\bakk\setbox\bakk=\hbox to -2em{} % backspace two ems +% +% \newcount\ind % current indentation in ems +% \def\1{\global\advance\ind by1\hangindent\ind em} % indent one more notch +% \def\2{\global\advance\ind by-1} % indent one less notch +% \def\3#1{\hfil\penalty#10\hfilneg} % optional break within a statement +% \def\4{\copy\bak} % backspace one notch +% \def\5{\hfil\penalty-1\hfilneg\kern2.5em\copy\bakk\ignorespaces}% optional break +% \def\6{\ifmmode\else\par % forced break +% \hangindent\ind em\noindent\kern\ind em\copy\bakk\ignorespaces\fi} +% \def\7{\Y\6} % forced break and a little extra space +% +% \let\yskip=\smallskip +% \def\to{\mathrel{.\,.}} % double dot, used only in math mode +% \def\note#1#2.{\Y\noindent{\hangindent2em\baselineskip10pt\eightrm#1 #2.\par}} +% \def\lapstar{\rlap{*}} +% \def\startsection{\Q\noindent{\let\*=\lapstar\bf\modstar.\quad}} +% \def\defin#1{\global\advance\ind by 2 \1\&{#1 }} % begin `define' or `format' +% \def\A{\note{See also}} % cross-reference for multiply defined section names +% \def\B{\mathopen{\.{@\{}}} % begin controlled comment +% \def\C#1{\ifmmode\gdef\XX{\null$\null}\else\gdef\XX{}\fi % Pascal comments +% \XX\hfil\penalty-1\hfilneg\quad$\{\,$#1$\,\}$\XX} +% \def\D{\defin{define}} % macro definition +% \def\E{\cdot10^} % exponent in floating point constant +% \def\F{\defin{format}} % format definition +% \let\G=\ge % greater than or equal sign +% \def\H#1{\hbox{\rm\char"7D\tt#1}} % hexadecimal constant +% \let\I=\ne % unequal sign +% \def\J{\.{@\&}} % TANGLE's join operation +% \let\K=\gets % left arrow +% \let\L=\le % less than or equal sign +% \outer\def\M#1.{\MN#1.\ifon\vfil\penalty-100\vfilneg % beginning of section +% \vskip12ptminus3pt\startsection\ignorespaces} +% \outer\def\N#1.#2.{\MN#1.\vfil\eject % beginning of starred section +% \def\rhead{\uppercase{\ignorespaces#2}} % define running headline +% \message{*\modno} % progress report +% \edef\next{\write\cont{\Z{#2}{\modno}{\the\pageno}}}\next % to contents file +% \ifon\startsection{\bf\ignorespaces#2.\quad}\ignorespaces} +% \def\MN#1.{\par % common code for \M, \N +% {\xdef\modstar{#1}\let\*=\empty\xdef\modno{#1}} +% \ifx\modno\modstar \onmaybe \else\ontrue \fi \mark{\modno}} +% \def\O#1{\hbox{\rm\char'23\kern-.2em\it#1\/\kern.05em}} % octal constant +% \def\P{\rightskip=0pt plus 100pt minus 10pt % go into Pascal mode +% \sfcode`;=3000 +% \pretolerance 10000 +% \hyphenpenalty 10000 \exhyphenpenalty 10000 +% \global\ind=2 \1\ \unskip} +% \def\Q{\rightskip=0pt % get out of Pascal mode +% \sfcode`;=1500 \pretolerance 200 \hyphenpenalty 50 \exhyphenpenalty 50 } +% \let\R=\lnot % logical not +% \let\S=\equiv % equivalence sign +% \def\T{\mathclose{\.{@\}}}} % terminate controlled comment +% \def\U{\note{This code is used in}} % cross-reference for uses of sections +% \let\V=\lor % logical or +% \let\W=\land % logical and +% \def\X#1:#2\X{\ifmmode\gdef\XX{\null$\null}\else\gdef\XX{}\fi % section name +% \XX$\langle\,$#2{\eightrm\kern.5em#1}$\,\rangle$\XX} +% \def\Y{\par\yskip} +% \let\Z=\let % now you can \send the control sequence \Z +% \def\){\hbox{\.{@\$}}} % sign for string pool check sum +% \def\]{\hbox{\.{@\\}}} % sign for forced line break +% \def\=#1{\kern2pt\hbox{\vrule\vtop{\vbox{\hrule +% \hbox{\strut\kern2pt\.{#1}\kern2pt}} +% \hrule}\vrule}\kern2pt} % verbatim string +% \let\~=\ignorespaces +% \let\*=* +% +% \def\onmaybe{\let\ifon=\maybe} \let\maybe=\iftrue +% \newif\ifon \newif\iftitle \newif\ifpagesaved +% \def\lheader{\mainfont\the\pageno\eightrm\qquad\rhead\hfill\title\qquad +% \tensy x\mainfont\topmark} % top line on left-hand pages +% \def\rheader{\tensy x\mainfont\topmark\eightrm\qquad\title\hfill\rhead +% \qquad\mainfont\the\pageno} % top line on right-hand pages +% \def\page{\box255 } +% \def\normaloutput#1#2#3{\ifodd\pageno\hoffset=\pageshift\fi +% \shipout\vbox{ +% \vbox to\fullpageheight{ +% \iftitle\global\titlefalse +% \else\hbox to\pagewidth{\vbox to10pt{}\ifodd\pageno #3\else#2\fi}\fi +% \vfill#1}} % parameter #1 is the page itself +% \global\advance\pageno by1} +% +% \def\rhead{\.{WEB} OUTPUT} % this running head is reset by starred sections +% \def\title{} % an optional title can be set by the user +% \def\topofcontents{\centerline{\titlefont\title} +% \vfill} % this material will start the table of contents page +% \def\botofcontents{\vfill} % this material will end the table of contents page +% \def\contentspagenumber{0} % default page number for table of contents +% \newdimen\pagewidth \pagewidth=6.5in % the width of each page +% \newdimen\pageheight \pageheight=8.7in % the height of each page +% \newdimen\fullpageheight \fullpageheight=9in % page height including headlines +% \newdimen\pageshift \pageshift=0in % shift righthand pages wrt lefthand ones +% \def\magnify#1{\mag=#1\pagewidth=6.5truein\pageheight=8.7truein +% \fullpageheight=9truein\setpage} +% \def\setpage{\hsize\pagewidth\vsize\pageheight} % use after changing page size +% \def\contentsfile{CONTENTS} % file that gets table of contents info +% \def\readcontents{\input CONTENTS} +% +% \newwrite\cont +% \output{\setbox0=\page % the first page is garbage +% \openout\cont=\contentsfile +% \global\output{\normaloutput\page\lheader\rheader}} +% \setpage +% \vbox to \vsize{} % the first \topmark won't be null +% +% \def\ch{\note{The following sections were changed by the change file:} +% \let\*=\relax} +% \newbox\sbox % saved box preceding the index +% \newbox\lbox % lefthand column in the index +% \def\inx{\par\vskip6pt plus 1fil % we are beginning the index +% \write\cont{} % ensure that the contents file isn't empty +% \closeout\cont % the contents information has been fully gathered +% \output{\ifpagesaved\normaloutput{\box\sbox}\lheader\rheader\fi +% \global\setbox\sbox=\page \global\pagesavedtrue} +% \pagesavedfalse \eject % eject the page-so-far and predecessors +% \setbox\sbox\vbox{\unvbox\sbox} % take it out of its box +% \vsize=\pageheight \advance\vsize by -\ht\sbox % the remaining height +% \hsize=.5\pagewidth \advance\hsize by -10pt +% % column width for the index (20pt between cols) +% \parfillskip 0pt plus .6\hsize % try to avoid almost empty lines +% \def\lr{L} % this tells whether the left or right column is next +% \output{\if L\lr\global\setbox\lbox=\page \gdef\lr{R} +% \else\normaloutput{\vbox to\pageheight{\box\sbox\vss +% \hbox to\pagewidth{\box\lbox\hfil\page}}}\lheader\rheader +% \global\vsize\pageheight\gdef\lr{L}\global\pagesavedfalse\fi} +% \message{Index:} +% \parskip 0pt plus .5pt +% \outer\def\:##1, {\par\hangindent2em\noindent##1:\kern1em} % index entry +% \def\[##1]{$\underline{##1}$} % underlined index item +% \rm \rightskip0pt plus 2.5em \tolerance 10000 \let\*=\lapstar +% \hyphenpenalty 10000 \parindent0pt} +% \def\fin{\par\vfill\eject % this is done when we are ending the index +% \ifpagesaved\null\vfill\eject\fi % output a null index column +% \if L\lr\else\null\vfill\eject\fi % finish the current page +% \parfillskip 0pt plus 1fil +% \def\rhead{NAMES OF THE SECTIONS} +% \message{Section names:} +% \output{\normaloutput\page\lheader\rheader} +% \setpage +% \def\note##1##2.{\hfil\penalty-1\hfilneg\quad{\eightrm##1 ##2.}} +% \linepenalty=10 % try to conserve lines +% \def\U{\note{Used in}} % cross-reference for uses of sections +% \def\:{\par\hangindent 2em}\let\*=*} +% \def\con{\par\vfill\eject % finish the section names +% \rightskip 0pt \hyphenpenalty 50 \tolerance 200 +% \setpage +% \output{\normaloutput\page\lheader\rheader} +% \titletrue % prepare to output the table of contents +% \pageno=\contentspagenumber \def\rhead{TABLE OF CONTENTS} +% \message{Table of contents:} +% \topofcontents +% \line{\hfil Section\hbox to3em{\hss Page}} +% \def\Z##1##2##3{\line{\ignorespaces##1 +% \leaders\hbox to .5em{.\hfil}\hfil\ ##2\hbox to3em{\hss##3}}} +% \readcontents\relax % read the contents info +% \botofcontents \end} % print the contents page(s) and terminate +% ?endgroup +% \vfill\eject +% +\def\runninghead{APPENDIX G --- NOTES ON FORMATTING} +\section Appendix G: How to use \.{WEB} macros. +The macros in \.{webkernel} make it possible to produce a variety of formats +without editing the output of \.{WEAVE}, and the purpose of this appendix +is to explain some of the possibilities. + +\def\point#1.{\yskip\indent#1.\quad\ignorespaces} + +\point 1. +Three fonts have been declared in addition to the standard fonts of +\.{PLAIN} format: You can say `\.{\{\\sc stuff\}}' to get {\sc stuff} +in small caps; and you can select the largish fonts \.{\\titlefont} +and \.{\\ttitlefont} in the title of your document, where \.{\\ttitlefont} +is a typewriter style of type. + +\point 2. +When you mention an identifier in \TeX\ text, you normally call +it `\.{|identifier|}'. +But you can also say `\.{\\\\\{identifier\}}'. +The +output will look the same in both cases, but the second alternative +doesn't put \\{identifier} into the index, since +it bypasses \.{WEAVE}'s translation from \PASCAL\ mode. + +\point 3. +To get typewriter-like type, as when referring to `\.{WEB}', you +can use the `\.{\\.}' macro (e.g., `\.{\\.\{WEB\}}'). +In the argument to +this macro you should insert an additional backslash before the symbols +listed as `special string characters' in the index to \.{WEAVE}, i.e., +before backslashes and dollar signs and the like. +A `\.{\\\ }' here will result in the visible space symbol; to get an +invisible space following a control sequence you can say `\.{\{\ \}}'. + +\point 4. +The three control sequences \.{\\pagewidth}, \.{\\pageheight}, +and \.{\\fullpageheight} can be redefined in the limbo section at the +beginning of your \.{WEB} file, to change the dimensions of each page. +The standard settings +$$\lpile{\.{\\pagewidth=6.5in}\cr + \.{\\pageheight=8.7in}\cr + \.{\\fullpageheight=9in}\cr}$$ +were used to prepare the present report; \.{\\fullpageheight} is +\.{\\pageheight} plus room for the additional heading and page numbers at +the top of each page. +If you change any of these quantities, you should +call the macro \.{\\setpage} immediately after making the change. + +\point 5. +The \.{\\pageshift} macro defines an amount by which right-hand +pages (i.e., odd-numbered pages) are shifted right with respect to +left-hand (even-numbered) ones. +By adjusting this amount you may be +able to get two-sided output in which the page numbers line up on +opposite sides of each sheet. + +\point 6. +The \.{\\title} macro will appear at the top of each page +in small caps. +For example, Appendix~D was produced after saying +`\.{\\def\\title\{WEAVE\}}'. +\newstuff +(Appendix~D was omitted from this document; see Don Knuth's original {\tt WEB} +technical report for all the appendices.) +\endnewstuff + +\point 7. +The first page usually is number 1; if you want some other +starting page, just set \.{\\pageno} to the desired number. +For example, +the initial limbo section for Appendix~D included the command +`\.{\\pageno=16}'. + +\point 8. +The macro \.{\\iftitle} will suppress the header line if it is +defined by `\.{\\titletrue}'. +The normal value is \.{\\titlefalse} +except for the table of contents; thus, the contents +page is usually unnumbered. +If your program is so long that the table of +contents doesn't fit on a single page, or if you want a number to appear +on the contents page, you should reset \.{\\pageno} when you begin the +table of contents. + +Two macros are provided to give flexibility to the table of +contents: \.{\\topofcontents} is invoked just before the contents +info is read, and \.{\\botofcontents} is invoked just after. +For example, Appendix~D +was produced with the following definitions: +$$\lpile{\.{\\def\\topofcontents\{\\null\\vfill}\cr + \.{ { }\\titlefalse \% include headline on the contents page}\cr + \.{ { }\\def\\rheader\{\\mainfont Appendix D\\hfil 15\}}\cr + \.{ { }\\centerline\{\\titlefont The \{\\ttitlefont WEAVE\}{ }processor\}}\cr + \.{ { }\\vskip 15pt \\centerline\{(Version 2.5)\}{ }\\vfill\}}\cr}$$ +Redefining \.{\\rheader}, which is the headline for right-hand pages, +suffices in this case to put the desired information at the top of the page. + +\point 9. +Data for the table of contents is written to a file that +is read after the indexes have been \TeX ed; there's one line of data +for every starred module. +For example, when Appendix~D was being generated, +a file +% \.{CONTENTS.TEX} +containing +$$\lpile{\.{\\Z \{{ }Introduction\}\{1\}\{16\}}\cr + \.{\\Z \{{ }The character set\}\{11\}\{19\}}\cr}$$ +and similar lines was created. +The \.{\\topofcontents} macro could +redefine \.{\\Z} so that the information appears in another format. + +\point 10. +Sometimes it is necessary or desirable to divide the output of +\.{WEAVE} into subfiles that can be processed separately. +For example, +the listing of \TeX\ runs to more than 500 pages, and that is enough to +exceed the capacity of many printing devices and/or their software. +When an extremely large job isn't cut into smaller pieces, the entire +process might be spoiled by a single error of some sort, making it +necessary to start everything over. + +Here's a safe way to break a woven file into three parts: +Say the pieces are $\alpha$, +$\beta$, and $\gamma$, where each piece begins with a starred module. +All macros should be defined in the opening limbo section of $\alpha$, +and copies of this \TeX\ code should be placed at the +beginning of $\beta$ and of $\gamma$. +In order to process the parts +separately, we need to take care of two things: The starting page +numbers of $\beta$ and $\gamma$ need to be set up properly, and +the table of contents data from all three runs needs to be +accumulated. + +The \.{webmac} macros include two control sequences \.{\\contentsfile} and +\.{\\readcontents} that facilitate the necessary processing. +We include +`\.{\\def\\contentsfile\{CONT1\}}' in the limbo section of $\alpha$, and +we include `\.{\\def\\contentsfile\{CONT2\}}' in the limbo section of +$\beta$; this causes \TeX\ to write the contents data for $\alpha$ and $\beta$ +into \.{CONT1.TEX} and \.{CONT2.TEX}. +Now in $\gamma$ we say +$$\.{\\def\\readcontents\{\\input CONT1 \\input CONT2 \\input CONTENTS\}};$$ +this brings in the data from all three pieces, in the proper order. + +\newstuff +Warning: life is a little different in Spidery {\tt WEB}. +{\TeX} hackers should go straight to the source. +\endnewstuff + +However, we still need to solve the page-numbering problem. +One way to +do it is to include the following in the limbo material for $\beta$: +$$\lpile{\.{\\message\{Please type the last page number of part 1: \}}\cr + \.{\\read-1to\\\\ \\pageno=\\\\ \\advance\\pageno by 1}\cr}$$ +Then you simply provide the necessary data when \TeX\ requests +it; a similar construction is used at the beginning of $\gamma$. + +This method can, of course, be used to divide a woven file into +any number of pieces. + +\point 11. +Sometimes it is nice to include things in the index that are +typeset in a special way. +For example, we might want to have an +index entry for `\TeX'. +\.{WEAVE} provides only two standard ways to +typeset an index entry (unless the entry is an identifier or a reserved word): +`\.{@\^}' gives roman type, and `\.{@.}' gives typewriter type. +But if we try to typeset `\TeX' in roman type by saying, e.g., +`\.{@\^\\TeX@>}', the backslash character gets in the way, +and this entry wouldn't appear in the index with the T's. + +The solution is to use the `\.{@:}' feature, declaring a macro that +simply removes a sort key as follows: +$$\.{\\def\\9\#1\{\}}$$ +Now you can say, e.g., `\.{@:TeX\}\{\\TeX@>}' in your \.{WEB} file; \.{WEAVE} +puts it into the index alphabetically, based on the sort key, and +produces the macro call `\.{\\9\{TeX\}\{\\TeX\}}' which will ensure that +the sort key isn't printed. + +A similar idea can be used to insert hidden material into module +names so that they are alphabetized in whatever way you might wish. +Some people call these tricks ``special refinements''; others call +them ``kludges''. + +\point 12. +The control sequence \.{\\modno} is set to the number of the +module being typeset. + +\point 13. +If you want to list only the modules that have changed, +together with the index, put the command `\.{\\let\\maybe=\\iffalse}' in +the limbo section before the first module of your \.{WEB} file. +It's +customary to make this the first change in your change file. + +\vfill + +\eject +% +% \def\runninghead{APPENDIX H --- GETTING STARTED} +% \section Appendix H: Installing the \.{WEB} system. +% Suppose you want to use the \.{WEB} programs on your computer, and suppose +% that you can't simply borrow them from somebody else who has the same +% kind of machine. +% Here's what to do: +% +% \yskip +% \def\step(#1){\par\hangindent 2em\noindent\hbox to 2em{\hfil(#1) }\ignorespaces} +% \step(1) Get a tape that contains the files \.{WEAVE.WEB}, \.{TANGLE.WEB}, +% \.{TANGLE.PAS}, and \.{WEBMAC.TEX}. +% The tape will probably also contain an +% example change file \.{TANGLE.CH}. +% \step(2) Look at the sections of \.{TANGLE} that are listed under ``system +% dependencies'' in the index of Appendix~E above, and figure out what changes +% (if any) will be needed for your system. +% \step(3) Make a change file \.{TANGLE.CH} that contains the changes of~(2); +% do not change your copy of \.{TANGLE.WEB}, leave it intact. +% (The +% rules for change files are explained at the end of the manual just before +% the appendices; you may want to look at the example change file that +% arrived with your copy of \.{TANGLE.WEB}. +% It's also a good idea to +% define all the ``switches'' like \&{debug} and \&{gubed} to be null in your +% first change files; then you can sure that your compiler will handle +% all of the code.) +% \step(4) Make the changes of (2) in your copy of \.{TANGLE.PAS}. +% (If these +% changes are extensive, you might be better off finding some computer that +% that already has \.{TANGLE} running, and making the new \.{TANGLE.PAS} +% from \.{TANGLE.WEB} and your \.{TANGLE.CH}.) +% \step(5) Use your \PASCAL\ compiler to convert your copy of \.{TANGLE.PAS} +% to a running program \.{TANGLE}. +% \step(6) Check your changes as follows: Run \.{TANGLE} on \.{TANGLE.WEB} +% and your \.{TANGLE.CH}, yielding $\.{TANGLE.PAS}'$; make a running +% program $\.{TANGLE}'$ by applying \PASCAL\ to +% $\.{TANGLE.PAS}'$; run $\.{TANGLE}'$ on \.{TANGLE.WEB} and +% your \.{TANGLE.CH}, yielding $\.{TANGLE.PAS}''$; and check +% that $\.{TANGLE.PAS}''$ is identical to +% $\.{TANGLE.PAS}'$. +% Once this test has been passed, you have got a +% working \.{TANGLE} program. +% \step(7) Make a change file \.{WEAVE.CH} analogous to (3), but this time +% consider the system-dependent parts of \.{WEAVE} that are listed in +% the index to Appendix~D. +% \step(8) Run \.{TANGLE} on \.{WEAVE.WEB} and your \.{WEAVE.CH}, obtaining +% \.{WEAVE.PAS}. +% \step(9) Use \PASCAL\ on \.{WEAVE.PAS} to make a running \.{WEAVE} program. +% \step(10) Run \.{WEAVE} on \.{TANGLE.WEB} and \.{TANGLE.CH} to produce +% \.{TANGLE.TEX}. +% \step(11) Run \TeX\ on \.{TANGLE.TEX}, obtaining a listing analogous to +% Appendix~E. +% This listing will incorporate your changes. +% \step(12) Run \.{WEAVE} on \.{WEAVE.WEB} and your \.{WEAVE.CH} to produce +% \.{WEAVE.TEX}. +% \step(13) Run \TeX\ on \.{WEAVE.TEX}, obtaining a listing analogous to +% Appendix~D that incorporates your changes. +% +% \yskip\noindent +% This description assumes that you already have a working \TeX82 system. +% But what if you don't have \TeX82? +% Then you start with a tape that also +% contains \.{TEX.WEB} and \.{plain.tex}, and you refer to a hardcopy +% listing of the \TeX82 program corresponding to \.{TEX.WEB}. +% Between steps +% (10) and (11) you do the following: +% +% \yskip +% \def\substep(10.#1){\par\hangindent 4em\noindent +% \hbox to 4em{\hfil(10.#1) }\ignorespaces} +% \substep(10.1) Make a change file \.{TEX.CH} to fix the system dependent +% portions of \.{TEX.WEB}, in a manner analogous to step~(2). +% Since \TeX\ is +% a much more complex program than \.{WEAVE} or \.{TANGLE}, there are more +% system-dependent features to think about, but by now you will be good at +% making such modifications. +% Do not make any changes to \.{TEX.WEB}. +% \substep(10.2) Make an almost-copy of your \.{TEX.CH} called \.{INITEX.CH}; +% this one will have the `\&{init}' and `\&{tini}' macros redefined in order +% to make the initialization version of \TeX. +% It also might have smaller +% font memory and dynamic memory areas, since \.{INITEX} doesn't need as +% much memory for such things; by setting the memory smaller in \.{INITEX}, +% you guarantee that the production system will have a ``cushion.'' +% \substep(10.3) Run \.{TANGLE} on \.{TEX.WEB} and \.{INITEX.CH}, obtaining +% \.{INITEX.PAS} and \.{TEX.POOL}. +% \substep(10.4) Run \PASCAL\ on \.{INITEX.PAS}, obtaining \.{INITEX}. +% \substep(10.5) Run \.{INITEX} on \.{TEX.POOL}, during which run you type +% `\.{plain}' and `\.{\\dump}'. +% This will produce a file \.{plain.fmt} +% containing the data needed to initialize \TeX's memory. +% \substep(10.6) Run \.{TANGLE} on \.{TEX.WEB} and the \.{TEX.CH} of (10.1), +% obtaining \.{TEX.PAS}. +% \substep(10.7) Run \PASCAL\ on \.{TEX.PAS}, obtaining \.{VIRTEX}. +% \substep(10.8) If your operating system supports programs whose core images +% have been saved, run \.{VIRTEX}, type `\.{\&plain}', then save the core image +% and call it \TeX. +% Otherwise, \.{VIRTEX} will be your \TeX, and it will +% read `\.{plain.fmt}' (or some other \.{fmt} file) each time you run. +% +% \yskip +% This 21-step process may seem long, but it is actually an oversimplification, +% since you also need fonts and a way to print the device-independent files +% that \TeX\ spews out. +% On the other hand, the total number of steps is not +% quite so large when you consider that \.{TANGLE}-followed-by-\PASCAL\ and +% \.{WEAVE}-followed-by-\TeX\ may be regarded as single operations. +% +% If you have only the present report, not a tape, you will have to prepare +% files \.{WEAVE.WEB} and \.{TANGLE.WEB} by hand, typing them into the +% computer by following Appendices D and E. +% Then you have to simulate the +% behavior of \.{TANGLE} by converting \.{TANGLE.WEB} manually into +% \.{TANGLE.PAS}; with a good text editor this takes about six hours. +% Then +% you have to correct errors that were made in all this hand work; but still +% the whole project is not impossibly difficult, because in fact the entire +% development of \.{WEAVE} and \.{TANGLE} (including the writing of the +% programs and the manual) took less than two months of work. +% +% \vfill + +\end + diff --git a/web/spiderweb/doc/spiderwebman.toc b/web/spiderweb/doc/spiderwebman.toc new file mode 100644 index 0000000000..66f7f67ff5 --- /dev/null +++ b/web/spiderweb/doc/spiderwebman.toc @@ -0,0 +1 @@ +\catcode`\@=11 |