summaryrefslogtreecommitdiff
path: root/web/funnelAC/results/ex13.tex
blob: 835ae999e623c69b264a88d2146005c5eaf908f8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499

%*******************************************************************************
%*                    START OF AUTOMATICALLY GENERATED TEX FILE                *
%*******************************************************************************
%*                                                                             *
%* This TeX file was automatically generated by the FunnelWeb preprocessor.    *
%* You can typeset this file to produce printed documentation by running it    *
%* through the TeX typesetter using a command such as:                         *
%*    tex thisfilename                                                         *
%* The resultant file thisfilename.dvi can be printed using a command such as: *
%*    lpr -Pcslw -d thisfilename.dvi                                           *
%*                                                                             *
%* FunnelWeb is a preprocessor that allows programmers to weave programs and   *
%* their documentation together in a single document. The FunnelWeb program    *
%* analyses such documents producing both program files and typeset            *
%* documentation such as this TeX file.                                        *
%* FunnelWeb was created by Ross Williams.                                     *
%*                                                                             *
%* For more information on FunnelWeb look in the following FTP archive:        *
%*    Machine  : sirius.itd.adelaide.edu.au [IP=129.127.40.3].                 *
%*    Directory: ~pub/funnelweb/                                               *
%*               (or some other appropriately named directory).                *
%* or email Ross Williams at ross@spam.adelaide.edu.au                         *
%*                                                                             *
%*******************************************************************************


%===================== Start of FunnelWeb TeX Definitions ======================


% Version
% -------
% This is FunnelWeb TeX Macro Library Version 1.0.


% Copyright
% ---------
% This set of FunnelWeb TeX definitions was written by Ross Williams and was
% originally Copyright (C) 1992 Ross N. Williams.  However, I, Ross Williams,
% hereby forego any claim to Copyright in this set of FunnelWeb TeX definitions
% and hereby authorize that the set of TeX definitions pass into the public
% domain. -- Ross N. Williams, 3:41pm 07-May-1992, Adelaide, Australia.


% Modification
% ------------
% Please record all modifications to these TeX definitions here. Unless
% otherwise specified, all modified definitions fall in the public domain too.
%
% Programmers:
%    RNW  Ross N. Williams  ross@spam.adelaide.edu.au
%
% Changes:
%    07-May-1992  RNW  Prepared this work for public domain release.
%


% General Comments
% ----------------
% This set of TeX definitions exists for two reasons:
%
%    1. To shorten and neaten the FunnelWeb TeX output.
%    2. To allow users to fiddle with the output format in their input files
%       (by inserting redefining "\def"s) without having to resort to
%       modifying the FunnelWeb code.
%
% The user is warned that these definitions may be changed from time to time
% (but probably not much). The user should not be too sneaky. In particular,
% users wishing to redefine some of these macros should do so in an explicitly
% defined section at the top of their input file. This will mean that in the
% event of problems, that section can simply be deleted or commented out to
% allow the document to at least be typeset in the default format. Users should
% limit themselves to redefining these macros in such a section and should
% refrain from using the macros throughout their documents.


% Environment Parameters
% ----------------------
% \tolerance tells TeX how tolerant it should be about making bad line and
% page breaks. Here we set it to it's maximum, as
%   1) Computer programs are likely to cause lots of bad breaks.
%   2) In most cases the user would probably rather get the TeX file through
%      TeX without any errors than fiddle with spacings for perfection.
\tolerance=10000

% I don't like indentation as it makes the page look more busy. Instead,
% paragraphs are separated by a little space (see next).
\parindent=0pt

% In many cases, users will produce documents with long runs of paragraphs.
% In order to space out these paragraphs, it is convenient to maintain a
% prevailing non-zero \parskip (end-of-paragaph skip). The only trouble is
% that the skip becomes a problem in macro definitions which require no skip
% and so we have to turn the skip on and off. The following two macros
% simplify this process.
\def\fwparskipon{\parskip=\medskipamount}
\def\fwparskipoff{\parskip=0pt}
\fwparskipon

% Setting raggedbottom allows TeX to leave a bit of space at the bottom of the
% page in order to better vertically align the rest of the page (e.g. skips
% won't stretch as much). It also means that headings are less likely to be
% isolated at the bottom of the page without any following text.
\raggedbottom


% Fonts
% -----
% Most of the typeset output is set in 10pt roman and 10pt tt font.
% The major extra font needs spring from titles and headings.
% For portability's sake we use only the following fonts:
%    cmr10
%    cmbx10
%    cmtt10
% and some enlargements of them. These fonts are all "standard" fonts
% in Plain TeX. See The TeXbook p.350.
\font\fwfontnote=cmr7

\font\fwfontnorm=cmr10
\font\fwfontnorma=cmr10 scaled \magstep1
\font\fwfontnormb=cmr10 scaled \magstep2

\font\fwfontbold=cmbx10
\font\fwfontbolda=cmbx10 scaled \magstep1
\font\fwfontboldb=cmbx10 scaled \magstep2
\font\fwfontboldc=cmbx10 scaled \magstep3
\font\fwfontboldd=cmbx10 scaled \magstep4


% Macros for Stylistic Details
% ----------------------------
% This section contains all the fiddly little macros for setting the details
% of each macro definition.

% Macro definitions are sandwiched by calls to these macros which can be used
% to sort out the spacing before and after the macro definition.
\def\fwbeginmacro{\fwparskipoff\bigskip}
\def\fwendmacro{\fwparskipon\par}

% These macros deal with the macro name and definition line.
\def\fwmacroname#1#2{{\sl #1\/}$\lbrack$#2$\rbrack$}
\def\fwfilename#1#2{{\bf #1}$\lbrack$#2$\rbrack$}
\def\fwzero#1{{\bf Z}}
\def\fwmany#1{{\bf M}}
\def\fwequals{ $\equiv$}
\def\fwplusequals{ $+\equiv$}

% Now for the actual body of the definition. It looks nice to have the tt
% code indented a little. Again, we use macros instead of writing direct TeX,
% so as to allow the user to fiddle this stuff to taste without having to
% modify the FunnelWeb C code.
\def\fwodef{\parindent=15pt\vskip0pt$\lbrace$\parindent=20pt}
\def\fwcdef{$\rbrace$\vskip0pt\parindent=0pt}
\def\fwoquote{`}
\def\fwcquote{'}
\def\fwoparen{$($}
\def\fwcomma{$,$}
\def\fwcparen{$)$}
\def\fwparam#1{$\diamond #1$}
\def\fwparams#1{$(\diamond #1)$}

% These macros deal with the notes that are appended at the end of each
% macro definition. Note that even though \fwisafile,\fwusedin, and \fwseealso
% have the same definition, they are given different names so as to allow the
% user to redefine these macros to typeset each kind of information differently
% if desired.
\def\fwbeginmacronotes{\begingroup\baselineskip=9pt\smallskip}
\def\fwnote#1{{\fwfontnote #1}\par}
\def\fwisafile#1{\fwnote{#1}}
\def\fwusedin#1{\fwnote{#1}}
\def\fwseealso#1{\fwnote{#1}}
\def\fwendmacronotes{\endgroup}


% Macros to Typeset Program Code Verbatim
% ---------------------------------------
% This is by far the hairiest and most difficult part of the typesetting task
% because we have to turn off most of TeX's natural instincts in order to
% typeset the program text exactly as it appears in the input file.
% Two macros are defined to pull this off: \fwbtx and \fwverbatimgobble.
% Their code was inspired by the following sections of "The TeXbook":
%    Appendix D: Dirty Tricks, 3.Verbatim listing, p.380-382.
%    Appendix E: Example Formats, p.421.
% The \fwbtx[ (for "FunnelWeb Begin TeXt") macro does most of the hard work.
% The liberal use of "%" is because I don't understand TeX well enough to
% understand when an end of line will cause trouble, and I am playing it safe.

% Before defining the main \fwbtx macro, we have to stash away some definitions
% in the hidden part of TeX's environment. Let's hope that these "hidden"
% definitions don't affect anything except what is desired to be affected.

% The tt font in which we wish to set the text has two Latin lurking ligatures!
% These are ?` and !`. To disable them, we define the left quote when ACTIVE
% to be defined in such a way as to prevent ligatures. The main TeX text will
% normally not be exposed to this definition because normally the leftquote
% character is not active. The \fwbtx macro temporarily makes the left quote
% character active thus activating the deactivation of left quote ligatures.
% See The TeXbook p.381.
{\catcode`\`=\active \gdef`{\relax\lq}}

% TeX is fairly carefree about spaces and so we have to make it more serious.
% To do so we pull the same trick as above, setting up a definition for active
% space, but only making space active during the span of the verbatim text.
% In Plain TeX the active space is defined to be simply a space, but here we
% define it to be a control space. This ensures that the space cannot
% be gobbled up by one of TeX's mysterious mechanisms when activated.
% See The TeXbook, p.381 and p.352.
{\obeyspaces\global\let =\ }

% Here is the main \fwbtx verbatim text macro.
% Note: The order in which all these pieces of business have to be done is
% still a partial mystery to me. Don't fiddle with this stuff unless you
% think you know what you are doing.
\def\fwbtx[{%
%
% The funnies involved in getting verbatim output are safely housed inside
% this \begingroup, and the \endgroup in \fwverbatimgobble. Groups are used
% instead of curly braces because we have to be able to signal the end of
% this macro with a curly brace.
\begingroup%
%
% \pars at the end of empty lines in the verbatim text won't come out normally
% because TeX is in vertical mode and they get gobbled up. To prevent this,
% we force \par to exit vertical mode first. See The TeXbook p.381.
\def\par{\leavevmode\endgraf}%
%
% Activate the leftquote character so as to avoid ligatures (see above).
\catcode`\`=\active%
%
% The \obeylines macro simply defines end of line (^M) to be \par. This ensures
% that TeX will treat each verbatim line as a new paragraph.
\obeylines%
%
% To get verbatim output, we have to desex all the special characters. This
% is explained in detail in The TeXbook p.380.
\def\do##1{\catcode`##1=12 }\dospecials%
%
% Activate the space character so as to make TeX treat blanks seriously.
% This activation invokes an eralier definition (see above).
\obeyspaces
%
% Interparagraph skips do not help the cause.
% Note: We have to preserve the indentation though, as the code is actually
% indented in the final output. See \fwodef in an earlier section.
\parskip=0pt%
%
% We typeset the verbatim text in tt font (courier on the Macintosh) for a
% number of reasons:
%    - tt font has the same horizontal spacing for each character.
%    - tt font covers the ASCII character set.
%    - tt font doesn't have many surprises (e.g. ligatures).
%    - tt font looks much what you might see on a computer terminal screen.
\tt%
%
% Having set up an environment for verbatim, we are ready to use it.
% By invoking \fwverbatimgobble, this \fwbtx macro gobbles up text verbatim (as
% part of the parameter of \fwverbatimgobble) until it sees the termination
% string "]fwetx=" (the "=" was thrown in to add obscurity as this sequence
% must never occur in the verbatim text).
\fwverbatimgobble}

% The \fwverbatimgobble macro exists to allow \fwbtx to bracket verbatim text.
\def\fwverbatimgobble#1]fwetx={#1\endgroup}


% Table of Contents
% -----------------
% The five levels of table of contents that FunnelWeb supports are identified
% by the five letters [A..E]. These are used throughout the following macros.

% The following macros are utilities to the TOC macros to follow.
\def\fwrule{\medskip\hrule\medskip}
\def\fwqh{\hskip1.5em\relax}
\def\fwbeforesec{\penalty-200\bigskip\medskip\par}

% The following macros are used to typeset the table of contents.
\def\fwtocstart#1{\fwrule\leftline{\fwfontbolda Table of Contents}\fwrule}
\def\fwtoca#1#2{\leftline{{\bf #1 #2}}}
\def\fwtocb#1#2{\leftline{\fwqh #1 #2}}
\def\fwtocc#1#2{\leftline{\fwqh\fwqh #1 #2}}
\def\fwtocd#1#2{\leftline{\fwqh\fwqh\fwqh #1 #2}}
\def\fwtoce#1#2{\leftline{\fwqh\fwqh\fwqh\fwqh #1 #2}}
\def\fwtocfinish#1{\fwrule}

% The following "library" macros define five different strengths of headings
% which can be used later in the section macros.
\def\fwliba#1#2{\vfill\eject{\fwfontboldc #1 #2}\penalty200\smallskip}
\def\fwlibb#1#2{\fwbeforesec{\fwfontboldb #1 #2}\penalty200\smallskip}
\def\fwlibc#1#2{\fwbeforesec{\fwfontnormb #1 #2}\penalty200\smallskip}
\def\fwlibd#1#2{\fwbeforesec{\bf          #1 #2}\penalty200}
\def\fwlibe#1#2{\fwbeforesec{\bf          #1 #2}}

% Here are the macros that actually typeset the section headings throughout
% the document. The fwlib system has been employed so as to easily allow the
% user to redefine the strengths of headings to taste. For example, the
% user could insert in the input document a similar set of definitions to these
% but with the b..e headings set to \fwlibc. This would tone down the output.
\def\fwseca#1#2{\fwliba{#1}{#2}}
\def\fwsecb#1#2{\fwlibb{#1}{#2}}
\def\fwsecc#1#2{\fwlibc{#1}{#2}}
\def\fwsecd#1#2{\fwlibd{#1}{#2}}
\def\fwsece#1#2{\fwlibe{#1}{#2}}


% Support for Explicit Typesetting
% --------------------------------
% FunnelWeb supports pragmas and other constructs that allow
% typesetter-independent typesetting commands to be given. The
% following macros support these features.

% The in-text literal @{sloth@} and emphasise @[walrus@] features.
\def\fwlit#1{{\tt #1}}
\def\fwemp#1{{\it #1}}

% The "@p new_page" pragma.
\def\fwnewpage{\vfill\eject}

% The "@p vskip Nmm" pragma.
\def\fwvskip#1{\null\vskip #1mm}

% The "@p title <font> <align> <text>" pragma.
\def\fwfontnormal#1{{\fwfontnorm {#1}}}
\def\fwfonttitle#1{{\fwfontboldd {#1}}}
\def\fwfontsmalltitle#1{{\fwfontboldb {#1}}}
\def\fwleftline#1{\leftline{#1}}
\def\fwcenterline#1{\centerline{#1}}
\def\fwrightline#1{\rightline{#1}}


% Support for Old FunnelWeb
% -------------------------
% The following macros were used extensively in the first version of
% FunnelWeb and are retained so that these older input files will still
% typeset cleanly.
\def\p#1{{\tt #1}}  % P for Program text.
\def\flagpage#1#2{
   \null
   \vfill
   \centerline{\fwfontboldd #1}
   \vskip 1cm
   \centerline{\fwfontboldd #2}
   \vfill
   \null
   \vfill
}

%====================== End of FunnelWeb TeX Definitions =======================
EX13: This example is used to generate typeset documentation which is
      discussed in the tutorial in the FunnelWeb user's manual.


\fwseca{1}{Table of Contents}


\fwtocstart{}
\fwtoca{1}{Table of Contents}
\fwtoca{2}{Macros for Moral Support}
\fwtoca{3}{An Extremely Imperative Stack Abstraction}
\fwtocb{3.1}{Define the Stack}
\fwtocb{3.2}{Push the Stack}
\fwtocb{3.3}{Pop the Stack}
\fwtocb{3.4}{Rough the Stack Up a Bit}
\fwtocfinish{}


\fwseca{2}{Macros for Moral Support}

The following macro contain comments that provide moral support in the
output code.

\fwbeginmacro
\fwmacroname{Programmer's Cheer}{1}\fwmany{}\fwequals \fwodef \fwbtx[
-- Shift to the left!
-- Shift to the right!
-- Pop up, push down!
-- Byte! Byte! Byte!
-- (From "The New Hacker's Dictionary").
]fwetx=%
\fwcdef 
\fwbeginmacronotes
\fwusedin{This macro is invoked in definitions 6 and 8.}
\fwendmacronotes
\fwendmacro


The next macro is similar but is distributed throughout the program.
\fwbeginmacro
\fwmacroname{Hacker's Cheer}{2}\fwplusequals \fwodef \fwbtx[
-- Pointer to the left
]fwetx=%
\fwcdef 
\fwbeginmacronotes
\fwseealso{This macro is defined in definitions 2, 3, 5, 7, and 9.}
\fwusedin{This macro is invoked in definition 10.}
\fwendmacronotes
\fwendmacro


\fwseca{3}{An Extremely Imperative Stack Abstraction}

\fwsecb{3.1}{Define the Stack}
\fwbeginmacro
\fwmacroname{Hacker's Cheer}{3}\fwplusequals \fwodef \fwbtx[-- Pointer to the right
]fwetx=%
\fwcdef 
\fwbeginmacronotes
\fwseealso{This macro is defined in definitions 2, 3, 5, 7, and 9.}
\fwusedin{This macro is invoked in definition 10.}
\fwendmacronotes
\fwendmacro

\fwbeginmacro
\fwmacroname{Stack Type}{4}\fwzero{}\fwequals \fwodef \fwbtx[type stack = record ... end;]fwetx=%
\fwcdef 
\fwbeginmacronotes
\fwusedin{This macro is NEVER invoked.}
\fwendmacronotes
\fwendmacro


\fwsecb{3.2}{Push the Stack}
\fwbeginmacro
\fwmacroname{Hacker's Cheer}{5}\fwplusequals \fwodef \fwbtx[-- Hack that code
]fwetx=%
\fwcdef 
\fwbeginmacronotes
\fwseealso{This macro is defined in definitions 2, 3, 5, 7, and 9.}
\fwusedin{This macro is invoked in definition 10.}
\fwendmacronotes
\fwendmacro

\fwbeginmacro
\fwmacroname{Push Procedure}{6}\fwzero{}\fwequals \fwodef \fwbtx[procedure push(var b:stack; v:value); ]fwetx=%
\fwmacroname{Programmer's Cheer}{1}\fwbtx[ {...}]fwetx=%
\fwcdef 
\fwbeginmacronotes
\fwusedin{This macro is NEVER invoked.}
\fwendmacronotes
\fwendmacro


\fwsecb{3.3}{Pop the Stack}
\fwbeginmacro
\fwmacroname{Hacker's Cheer}{7}\fwplusequals \fwodef \fwbtx[-- Tight! Tight! Tight!
]fwetx=%
\fwcdef 
\fwbeginmacronotes
\fwseealso{This macro is defined in definitions 2, 3, 5, 7, and 9.}
\fwusedin{This macro is invoked in definition 10.}
\fwendmacronotes
\fwendmacro

\fwbeginmacro
\fwmacroname{Pop Procedure}{8}\fwzero{}\fwequals \fwodef \fwbtx[procedure pop(var b:stack); ]fwetx=%
\fwmacroname{Programmer's Cheer}{1}\fwbtx[ {...}]fwetx=%
\fwcdef 
\fwbeginmacronotes
\fwusedin{This macro is NEVER invoked.}
\fwendmacronotes
\fwendmacro


\fwsecb{3.4}{Rough the Stack Up a Bit}
\fwbeginmacro
\fwmacroname{Hacker's Cheer}{9}\fwplusequals \fwodef \fwbtx[-- (RNW, 04-Jan-1991).
]fwetx=%
\fwcdef 
\fwbeginmacronotes
\fwseealso{This macro is defined in definitions 2, 3, 5, 7, and 9.}
\fwusedin{This macro is invoked in definition 10.}
\fwendmacronotes
\fwendmacro

\fwbeginmacro
\fwmacroname{Rough Procedure}{10}\fwzero{}\fwequals \fwodef \fwbtx[procedure rough(var b:stack); ]fwetx=%
\fwmacroname{Hacker's Cheer}{2}\fwbtx[ {...}]fwetx=%
\fwcdef 
\fwbeginmacronotes
\fwusedin{This macro is NEVER invoked.}
\fwendmacronotes
\fwendmacro


\fwbeginmacro
\fwfilename{dummy.txt}{11}\fwequals \fwodef \fwbtx[dummy
]fwetx=%
\fwcdef 
\fwbeginmacronotes
\fwisafile{This macro is attached to an output file.}
\fwendmacronotes
\fwendmacro

\bye


%*******************************************************************************
%*                    END OF AUTOMATICALLY GENERATED TEX FILE                  *
%*******************************************************************************