summaryrefslogtreecommitdiff
path: root/web/funnelAC/userman/u_ch1.tex
blob: 947fd2326b79c5d22761bc6308955ef489845ed9 (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
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
%==============================================================================%
%                                Start of Ch1.tex                              %
%==============================================================================%
%
% Copyright
% ---------
% Copyright (C) 1992 Ross N. Williams.
% This file contains a chapter of the FunnelWeb User's Manual.
% See the main TeX file for this manual for further information.
%
%==============================================================================%

\chapter{A Tutorial Introduction}
\label{chapintroduction}
\x{tutorial}

\section{What is Literate Programming?}
\x{literate programming}

A traditional computer program consists of a text file containing program
code. Scattered in amongst the program code are comments which describe the
various parts of the code. 

In \newterm{literate programming} the emphasis is reversed. Instead of
writing code containing documentation, the literate programmer writes
documentation containing code. No longer does the English commentary
injected into a program have to be hidden in
comment delimiters at the top of the
file, or under procedure headings, or at the end of lines.
Instead, it is wrenched into the daylight and made the main focus.
The \dq{program} then becomes primarily a document directed at humans,
with the code being herded between \dq{code delimiters} from where it
can be extracted and shuffled out sideways to the language system
by literate programming tools.

The effect of this simple shift of emphasis can be so
profound as to change one's whole approach to programming. Under the
literate programming paradigm, the central activity of programming becomes
that of conveying meaning to other intelligent beings rather than merely
convincing the computer to behave in a particular way. It is the difference
between performing and exposing a magic trick.\x{magic trick}

In order to program in a literate style, particular tools are
required.\xx{tools}{literate programming}
The traditional approach (used in the FunnelWeb system) is to have
some sort of text-file-in/text-file-out utility that reads a
literate program (containing a program commentary peppered with scraps
of program text) and writes out a file containing all the program code and
a file containing typesetter commands representing the entire input document,
documentation, code, and all (\figarchitecture{}).

\begin{figure}[htbp]
\begin{verbatim}

                +-----------------------------------------+
                | File containing the program description |
                | peppered with scraps of program code.   |
                | This is what the programmer works on.   |
                |          (e.g. sloth.web)               |
                +-----------------------------------------+
                                    |
                                    v
                      o---------------------------o
                      | Literate Programming Tool |
                      o---------------------------o
                                    |
                +-------------------+-------------------+
                |                                       |
                v                                       v
       +------------------+           +----------------------------------+
       |   Traditional    |           | Documentation file suitable for  |
       | Computer Program |           | input into a typesetting program |
       |  (e.g. sloth.c)  |           |        (e.g. sloth.tex)          |
       +------------------+           +----------------------------------+

\end{verbatim}
\mylabel{\figarchitecture{}: Traditional architecture of literate programming tools.}{%
%
Literate programming tools could be organized in a number of ways. However,
to fit in with current file and command line based environments, most tools
conform to the traditional architecture shown here in which the user feeds
in a file containing a literate program, and the literate programming
utility generates program files and a documentation file.
%
}
\end{figure}

Given the coming age of hypertext\x{hypertext} systems,
this is probably not the best approach.
However, it does mesh beautifully with current text
files and command line interfaces, the expectation of linear presentations in
the documents we read, and the particular requirements of current programming
languages and typesetting systems. It is certainly not a bad approach.

With this structure in place, the literate programming system can provide
far more than just a reversal of the priority of comments and code.
In its full blown form, a good literate programming facility can provide
total support for the essential thrust of literate programming, which is that
computer programs should be written more for the human reader
than for the compiler. In particular, a literate programming system can
provide:\xs{literate programming}{facilities}

\narrowthing{Re-ordering of code:}{Programming languages often force the
programmer to give the various parts of a computer program in a particular
order.\xx{program}{ordering}
For example, the Pascal\x{Pascal} programming language\paper{BSI82}
imposes the ordering:
constants, types, variables, procedures, code. Pascal also requires that
procedures appear in an order consistent with the partial ordering
imposed by the static call graph (but forward
declarations allow this to be bypassed). In contrast, the literate style
requires that the programmer be free to present the computer program in
any order whatsoever. The facility to do this is implemented in literate
programming tools by providing text \i{macros} that can be defined
and used in any order.}

\narrowthing{Typeset code and documentation:}{Traditionally program
listings are
dull affairs consisting of pages of fan-form paper imprinted with meandering
coastlines of structured text in a boring font. In contrast, literate
programming systems are capable of producing documentation that is
superior in two ways. First, because most of the documentation text is
fed straight to the typesetter, the programmer can make use of all the
power of the underlying typesetter, resulting in documentation that has the
same presentation as an ordinary typeset document. Second, because the
literate programming utility sees all the code, it can use its knowledge
of the programming language and the features of the typesetting language
to typeset the program code as if it were appearing in a
technical journal. It is the difference
between:}

\begin{verbatim}
    while sloth<walrus loop
       sloth:=sloth+1;
    end loop
\end{verbatim}

\narrowtext{and}

\begin{verse}
\b{while} \i{sloth}$<$\i{walrus} \b{loop}\\
\qquad\qquad \i{sloth}$\leftarrow$\i{sloth}$+1$;\\
\b{end} \b{loop}
\end{verse}

\narrowtext{Unfortunately, while FunnelWeb provides full typesetting
of the
documentation, it typesets all of its code in the style of the first of these
two examples. To typeset in the style of the second requires knowledge of
the programming language, and the current version of FunnelWeb is
programming language independent. At a later stage, it is possible that
FunnelWeb will be modified to read in a file containing information
about the target programming language to be used to assist in
typesetting the code properly.}

\narrowthing{Cross referencing:}{Because\x{cross referencing}
the literate tool sees all the
code and documentation, it is able to generate extensive cross referencing
information in the typeset documentation. This makes the printed program
document more easy to navigate and partially compensates for the lack of
an automatic searching facility when reading printed documentation.}

In the end, the details don't matter. The most significant
benefit that literate programming offers
is \i{its capacity to transform the state of mind of the
programmer}.\xs{literate programming}{most significant benefit}
It is now legend that the act of explaining something can transform
one's understanding of it. This is one of the justifications behind the
powerful combination of research and teaching in
universities\paper{Rosovsky90}.\x{universities}
Similarly, by constantly explaining the unfolding program code in English to an
imaginary reader, the programmer transforms his perception of the code,
laying it open, prone, to the critical eye.\xx{explaining}{code}

The result of this exposure is a higher quality of programming.
When exposed to the harsh light of the literate eye,
bugs crawl out, special cases vanish, and sloppy code evaporates.
As a rule literate programs
take longer to write than ordinary programs, but the total
development time\xx{development}{time}
is the same or less because the time taken to write and
document the program carefully is compensated for by a reduced debugging
and maintenance time.
Thus literate programming does not merely assist in the preparation of
documentation, but also makes significant contributes to the process of
programming itself. In practice this has turned out to be a contribution
far more important than the mere capacity to produce typeset documentation.

For more information on literate programming, the reader is directed
to Knuth's early founding work \paper{Knuth83} and \paper{Knuth84}.
For more recent information refer to \paper{Smith91},
which provides a comprehensive bibliography up to 1990.

\section{What is FunnelWeb?}
\xx{FunnelWeb}{overview}

FunnelWeb is a particular literate programming system that is implemented
by a single C program. FunnelWeb takes as input a single \p{.fw}
\newterm{input file}
and writes one or more \newterm{product files}
and a \newterm{documentation file} (\figfunarch{}).

\begin{figure}[htbp]
\begin{verbatim}
                              +-----------+
                              | sloth.fw  |
                              +-----------+
                                    |
                                    v
                          o-------------------o
                          | FUNNELWEB Program |
                          o-------------------o
                                    |
                +-------------------+----------------+
                |                                    |
                v                                    v
  +-----------------------------+    +--------------------------------+
  | Product File (e.g. sloth.c) |    | Documentation File (sloth.tex) |
  +-----------------------------+    +--------------------------------+
\end{verbatim}
\mylabel{\figfunarch{}: Architecture of FunnelWeb.}{%
%
FunnelWeb follows the traditional architecture of literate programming
tools.
%
}
\end{figure}

In literate programming systems, it is usual to refer to the product
file as a \dq{program file}. However, as FunnelWeb is a general tool that
can be used to prepare all sorts of text files that are not computer programs,
the more generic term \dq{product file} was chosen. Product files should
be carefully distinguished from the term \newterm{output files} which refers
to all of the output files produced by FunnelWeb.

FunnelWeb is distinguished by the following characteristics:

\narrowthing{Simplicity:}{A\x{simplicity}
governing design goal of FunnelWeb is to provide
a \i{simple} tool that could be easily learnt and completely mastered.
This manual is thick because it is comprehensive and lingers on the
ways in which FunnelWeb can be used. The tool itself is quite simple.}

\narrowthing{Reliability:}{Another\x{reliability}
design goal is to provide a tool that will
protect the user as much as possible from silly errors. Macro preprocessors
are notorious for causing obscure errors. Every attempt has been made in
FunnelWeb to keep the syntax robust.
For example, in FunnelWeb the syntax of
macro calls has been purposely designed to be highly visible so that the
reader is always aware when the macro facility is being invoked.}

\narrowthing{Language and Typesetter Independence:}{Unlike
Knuth's original\xx{language}{independence}\xx{typesetter}{independence}
Web system which was specific to the Pascal programming language\paper{BSI82}
and the \TeX{} typesetting language\paper{Knuth84}, FunnelWeb strives to
be language and typesetter independent. The current version of FunnelWeb
is completely language independent, but is still somewhat dependent on the
\TeX{}\x{TeX} typesetter language.}

\narrowthing{Portability:}{FunnelWeb\x{portability} has been written in
the~C programming language with great emphasis on portability.
FunnelWeb currently runs on the Sun, VAX, IBM PC, and Mac.}

\narrowthing{Controllable:}{FunnelWeb\x{controllability}
is an extremely controllable tool.
To protect users' investment in source files constructed in the FunnelWeb
macro language, the C source code to FunnelWeb has been released under GNU
license.\xx{GNU}{license}
This means that it will always be available to everyone. Furthermore,
license has been granted for the FunnelWeb User's Manual and FunnelWeb
Hacker's Manual to be copied freely so long as they are not modified. All
this means that FunnelWeb is not going to disappear suddenly.}

\narrowthing{A Production Tool:}{Above\x{production tool}
all, FunnelWeb has been designed to be
a production tool and every effort has been made to ensure that it will
operate effectively in a professional environment. FunnelWeb is \dq{open}
and portable. There is a comprehensive user manual. Its error messages
are comprehensive. It is fast. Finally, it has been designed with the
experience of three years of using FunnelWeb~V1.}

For more information on the history and design of FunnelWeb, see
the \i{FunnelWeb Hacker's Manual}.

\section{The Name FunnelWeb}
\xx{FunnelWeb}{name}

The name \dq{FunnelWeb} was chosen because it contains the name \dq{WEB},
which is the name of Knuth's system. It was also chosen because it
has a distinctly Australian flavour.

Funnel-web spiders\xx{Funnel-web}{spider}
are found in Northern and Eastern Australia. They are
about three to four centimetres long and are very poisonous. The
Sydney\x{Sydney}
Funnel-web spider (\i{Atrax robustus}\x{Atrax robustus}),
common in Sydney,
has caused the most trouble and has been responsible for several deaths.
Funnel-web spiders love to crawl into temporarily discarded shoes where they
later react in a hostile manner to an unsuspecting foot. They are known
to hang on once they sink their fangs in. Funnel-web spiders derive
their name from the shape of their webs which are horizontally-aligned
narrowing tubes, open at one end\paper{ANZE}.

The Funnel-web spider, like the tiger snake\xx{tiger}{snake}
and the white pointer shark,\xx{white pointer}{shark}
is secretly regarded by Australians as a kind of national
treasure.\xn{Edna}{Everage}\xn{Barry}{Humphries}

\begin{verse}
\b{F} is for Funnel-web\\
Our furry-legged foe.\\
He sleeps in your slipper\\
And breakfasts on toe.\\
--- One verse from \i{A Megastar's Mantras: Things that Mean a Lot to Me},\\
\qquad{} by Dame Edna Everage\paper{Humphries91}.\\
\end{verse}

\section{A FunnelWeb Tutorial}
\x{tutorial}\xx{tutorial}{introduction}

The remainder of this chapter consists of an introductory tutorial on
FunnelWeb. Ideally you should have a working version of FunnelWeb in front
of you when reading this chapter so that you can try out the examples
yourself. There is no need to try all the examples so long as you
type in enough to feel comfortable with what you are reading. There
is no harm in reading this chapter offline too, so long as you get to the
computer within a couple of days to reinforce what you have read.

For best effect, you should create a new, temporary, empty directory in
which to experiment with FunnelWeb. That way, it will be more obvious
when FunnelWeb creates an output file. You can either type in the
examples in this chapter directly, or copy and paste them from the \LaTeX{}
source file for this chapter or the FunnelWeb
test suite. The source file for this chapter should be available
in a file such as \p{/fwdir/userman/ch1.tex}. The test suite should be
available in a directory such as \p{/fwdir/tests/}. The
test files called \p{ex01.fw} through \p{ex16.fw} contain the examples in this
chapter. The test files called \p{hi01.fw} through \p{hi10.fw} contain the
examples in the next chapter.

If you do not yet have an installed copy of FunnelWeb, refer to
Chapter~\ref{chapinstall} for full details on how to obtain and install
a copy of FunnelWeb. If you are not sure if you have an installed copy,
try invoking FunnelWeb by giving the command \dqp{fw}. If this yields an error
such as \dq{command not found} then you do not have a properly
installed version of FunnelWeb.

\section{A Hello World Document}
\x{hello world document}

Just as one starts the process of learning a new programming language with a
\dq{Hello World} program, when learning  FunnelWeb, you can start with a
\dq{Hello World} document! And here it is! Edit a text file
called \p{hello.fw} and put the following text in it. (Note: The second
character is the letter \dq{Oh}, not the digit \dq{Zero}).

\begin{verbatim}
@O@<hello.txt@>@{Hello World@+@}
\end{verbatim}

To \dq{run} this \dq{program}, invoke FunnelWeb using the \dqp{fw}
command as follows.\x{invoking FunnelWeb}

\begin{verbatim}
fw hello
\end{verbatim}

\i{If this command doesn't work, then chances are that
FunnelWeb has not been installed on your machine. Refer to
Chapter~\ref{chapinstall} for full details on how to obtain and install
a copy of FunnelWeb.}

There should be no errors. If there are, have a look
at the listing file \p{hello.lis}, which should contain an explanation of the
error, and compare the area in the file where the error occurred with the
text above. If there are no errors, you will find that the following
two files have been created.

\begin{verbatim}
hello.lis   - The LISTING file.
hello.txt   - The PRODUCT file.
\end{verbatim}

Take a look at \p{hello.txt}. It should contain a single line with the
text \p{Hello World}. Let's take another look at the input file.

\begin{verbatim}
@O@<hello.txt@>@{Hello World@+@}
\end{verbatim}

The whole structure of the input file is controlled by \dqp{@},
called the \newterm{special character}, which
introduces \newterm{special sequence}s. A scanner's-eye view of the command
line looks like this:

\begin{verbatim}
@O  @<  "hello.txt"  @>  @{  "Hello World"  @+  @}
\end{verbatim}

The \p{@} character controls everything. In this file we have six different
special sequences that together
form a single macro definition. The \p{@<}\x{@<} and \p{@>}\x{@>}
delimit the name of
the macro. The \p{@O}\x{@O} signals the start of the macro
definition and indicates that the macro is to be connected to a product
file with the same name as the macro (This is is why we got a product file when
we ran FunnelWeb). The \p{@\{} and \p{@\}}\x{@braces}
delimit the body of the macro.
Finally, the \p{@+}\x{@+} instructs that an end of line sequence should be
inserted at that point in the product file.

If you think this syntax looks messy, then you're right.
It \i{is}
messy. FunnelWeb \i{could} have employed a \dq{simpler} notation
in which more of the \p{@} sequences were eliminated. For example:


\begin{verbatim}
Warning: This example is NOT legal FunnelWeb.

#hello.txt{Hello World+}
\end{verbatim}

However, if such a syntax were used, the user (you!) would have to remember
that \p{\#} starts a new macro. You would also have to remember that
the characters \p{\}} and \p{+} cannot be used in a macro body without a fuss.
And so on. FunnelWeb is messier, but provides one simple
rule:\xx{simple}{rule} \i{Nothing special happens
unless the special character \p{@} appears.}

This means that in FunnelWeb, you can look at large blocks of text in the
confidence that (unlike for the C
pre-processor\xx{C}{preprocessor}) there are no macro calls
hidden in there. If there were, there would be an \p{@}
character!\footnote{The only
exception to this rule occurs where the user has explicitly changed the
special character using the \p{@=}\x{@=} special sequence.}

Let's take another look at the hello world program.

\begin{verbatim}
@O@<hello.txt@>@{Hello World@+@}
\end{verbatim}

In its current form, it consists of a single macro definition. This definition,
while completely valid on its own, only represents half the power of
FunnelWeb. In fact you could say that it is a \dq{Hello
Northern Hemisphere Program}.\x{Hello Northern Hemisphere Program}
To turn it into a proper FunnelWeb \dq{Hello
World} program, we need to add some documentation!

A FunnelWeb input file consists of a sequence of macro definitions surrounded
by a sea of documentation which is just ordinary text. Modify your hello
world document so that it looks like this:

\begin{verbatim}
This hello world document was created by -insert your name here-.

@O@<hello.txt@>@{Hello World@+@}

It writes out a file called hello.txt containing the string ``Hello World''.
\end{verbatim}

Now run it through FunnelWeb, but this time, add a \p{+t} to the command line.

\begin{verbatim}
fw hello +t
\end{verbatim}

If all goes well, you should find that you now have

\begin{verbatim}
hello.lis   - A LISTING       file.
hello.tex   - A DOCUMENTATION file (in TeX format).
hello.txt   - A PRODUCT       file.
\end{verbatim}

Take a look at \p{hello.txt}. You will find that it is identical to the
\p{hello.txt} of the previous run. Only macro
definitions affect the product files that FunnelWeb produces (as a result
of \p{@O} macro definitions). The surrounding documentation has \i{no}
effect. In contrast, the new file, \p{hello.tex} (have a look at it now)
which was created as
a result of your adding the \p{+t} option contains a fairly full
representation of the input file. Whereas \p{hello.txt} is the
\i{product file} of FunnelWeb, \p{hello.tex} is the \i{documentation file}.
Try typesetting the documentation file now using
the \TeX{} typesetting program.  Then print it.
The following commands are an example of the
sort of commands you will have to give to do this.

\begin{verbatim}
tex hello                  ! Typeset the documentation.
lpr -Pcslw -d hello.dvi    ! Print the typeset documentation.
\end{verbatim}

The result should be a single page containing the two lines of documentation
along with a typeset representation of the macro.
At this point, you have exercised the two main aspects of
FunnelWeb.\xx{FunnelWeb}{two main aspects}
Starting
with an input file containing macros (or in this case macro) and documentation,
you have successfully generated a product file based on the macros, and
a documentation file, based on the entire document. Congratulations!

The remainder of this tutorial is divided into two parts, which focus on
FunnelWeb's macro facilities and its typesetting facilities. By tradition,
the generation of program files from a literate text is called
\newterm{Tangling}, and the generation of typeset documentation is
called \newterm{Weaving}.\footnote{In FunnelWeb, these two functions
are aspects of a single computer program. However, in Knuth's WEB\x{WEB}
system,
the two functions are embodied in two separate computer programs called
Tangle and Weave, presumably because, as everyone knows, \dq{it takes
two to Tangle}.}

\section{Macro Facilities}
\xx{tutorial}{macro facilities}

The hello world program of the previous section exercised both the macro
expansion (product-file) aspect of FunnelWeb, and the typesetting
(documentation file) aspect
of FunnelWeb. This section contains an exposition of the macro facilities,
and totally ignores the documentation side. This is partly to increase the
focus of the tutorial, and partly because documentation is usually bulky and
would take too long for the reader to type in to make the tutorial effective.

\subsection{Simple Macros}
\xx{tutorial}{simple macros}\xx{tutorial}{macros simple}

The original \dq{Hello World} program consisted of a single macro definition.

\begin{verbatim}
@O@<hello.txt@>@{Hello World@+@}
\end{verbatim}

In fact, this is a rather exceptional macro, as it causes its expansion to
be written to a
product file. The \p{@O}\x{@O} (for \b{O}utput) signals this.
In FunnelWeb, most macros are
defined using \p{@\$}.\x{@dollar}
This  results in a macro that does not generate a product
file, but which can be called in other macros (including \p{@O} macros).
Let us expand the hello world program to include some other macros.

\begin{verbatim}
@O@<hello.txt@>@{@<Greetings@>@+@}

@$@<H@>==@{Hello@}
@$@<W@>==@{World@}

@$@<Greetings@>==@{@<H@> @<W@>@}
\end{verbatim}

Type in the file and run it through FunnelWeb using the command:

\begin{verbatim}
fw hello
\end{verbatim}

The product file (result.out) should look like this:

\begin{verbatim}
Hello World
\end{verbatim}

This short program illustrates some of the features of ordinary macros in
FunnelWeb. Consider the \p{@O} macro. Instead of containing
straight text (\dq{Hello World}), it now contains the macro call
\p{@<Greetings@>}. A FunnelWeb macro can be called from within the body of
another macro just by giving the macro
name delimited in \p{@<} and \p{@>}.

At the bottom of the file is the
definition of the \p{@<Greetings@>}
macro. The definition is similar to the definition of \p{hello.txt} except
that it starts with \p{@\$} to indicate that no product file
is desired from this macro (directly). It also employs the optional
\p{==} syntax which has no semantic impact, but 
can be used to make definitions clearer.
The body of the \p{@<Greetings@>} macro consists of
calls to the \p{H} and \p{W} macros which are defined immediately above.

Note that the macros are not constrained to be
defined in any particular order. One of the main
features of literate programming tools is that
they allow the different parts of the text document being developed (usually
a computer program) to be layed out in any
order.\xx{order}{program}\xx{program}{layout} So long as there is a
definition somewhere in the input file for every macro call, FunnelWeb
will sort it all out.

In fact, FunnelWeb's macro facility is very simple.\xx{macro}{bindings}
Unlike many macro preprocessors which allow macros to define other macros,
FunnelWeb completely
finishes parsing and analysing the macros in the input file before it
starts expanding them into product files. Other preprocessors allow
macros to
be redefined like variables (as in, say, \TeX{}\x{TeX}) taking on
many different values as the macro pre-processor travels through the input
file. In contrast,
FunnelWeb has no concept of \dq{different times} and
treats the input as one huge static orderless, timeless,
collection of definitions.
In FunnelWeb, there is only ever one time, and so there can only ever be
one value/definition for each macro.


\subsection{Number of Times Called}
\x{number of times called}\xx{calls}{number}\xx{invocation}{number}

So far we have seen only tiny, degenerate input files. The next example
moves up to the level of \dq{trivial}, but starts to convey the flavour of
the way FunnelWeb can be used in practice. Normally, there would be
documentation text appearing between the macros, but this has been omitted
so as to keep the focus on the macros themselves. Although the next
example is
much longer than the previous example, the only new construct is \p{@-}
which can appear only at the end of a line,
and suppresses it,\xx{EOL}{suppression}
preventing it from appearing in the text. The \p{@-}\x{@-} construct allows
the text of a macro to be aligned at the left margin, rather than
having the first line hanging at the end of the
\p{@\{}. FunnelWeb could have been set up so that this end of
line marker was suppressed. However, it would have been a special case that
would have broken the very memorable rule \dq{the text of a macro is the
text appearing between the \p{@\{} and \p{@\}}}.

Type the following text into the file \p{hello.fw}
and run it through FunnelWeb. The file contains some intentional errors so
be sure to type it in exactly and worry only if FunnelWeb \i{doesn't}
generate some errors.

\begin{verbatim}
@O@<hello.c@>==@{@-
@<Include Files@>
@<Include Files@>
@<Main Program@>
@}

@$@<Main Program@>==@{@-
main()
{
 doit();
}
@}

@$@<Subroutine@>==@{@-
void doit()
{
 int i;
 for (i=0;i<10;i++)
   {
    @<Print@>
    @<Print@>
   }
}@}

@$@<Print@>==@{@-
printf("Hello World!");
printf("\n");@}

@$@<Scan@>==@{scanf@}

@$@<Include Files@>==@{@-
#include <stdio.h>
#include <stdlib.h>@}
\end{verbatim}

What happened? Well, if you haven't typed the file in properly, you may
get some miscellaneous syntax errors. Fix these before continuing.
If the file has been correctly typed, you should be faced with some error
messages to do with the number of times some of the macros are called.

By default, FunnelWeb insists that each macro defined is invoked
exactly once. However, the file above defines macros that are used
more than once and a macro that is not used at all. Let us examine the
errors.

First, we see that FunnelWeb has alerted us to the fact that
the \p{Include Files} macro has been called twice. Once alerted to this,
a quick look at the program convinces us that calling the macro twice is
a mistake, and that one of the calls should be eliminated.

Second, we note that FunnelWeb has alerted us to the fact that the
\p{@<subroutine@>}
macro is never called. Again, a quick look at the program tells us that this
is a mistake (and a very common one in the use of FunnelWeb), and that
a call to the \p{@<subroutine@>} macro should be inserted just above
the call to the \p{@<Main Program@>} macro
in the definition of \p{@<hello.c@>}.

These two cases demonstrate why these checks have been placed in
FunnelWeb. It is nearly always acceptable for a macro to be called once.
However, if a macro is not called at all, or called more than once,
this is often a sign
that the user has made a mistake.

These checks have a dark side too. In addition to the
errors mentioned above, FunnelWeb has generated two similar
errors that do not help us.

First, we are alerted to the fact that the
\p{@<print@>} macro has been called twice. Clearly, in this case, this is not
a problem, and so here FunnelWeb's fussiness is a nuisance.

Second, we are alerted to the fact that the \p{@<scan@>} macro has never
been called. Like the \p{@<print@>} macro,
this macro was defined as a notational
convenience, and clearly it does not matter here if it is not used. Again,
FunnelWeb is being a nuisance.

The four cases above demonstrate the light and dark side of
FunnelWeb's insistence that each macro be called exactly once. To resolve
the conflict without reducing the strength of the checking, FunnelWeb
provides two special sequences \p{@Z} (for \b{Z}ero) and \p{@M} (for \b{M}any)
that can be attached to macro definitions. Presence of the
\p{@Z}\xx{@Z}{tutorial}
tag allows the designated macro to be called zero times.
Presence of the
\p{@M}\xx{@M}{tutorial}
tag allows the designated macro to be called more than once.
A single macro may carry both tags.
It is always true that all macros are allowed to be called exactly once.

Here is the revised program with the errors fixed,
by eliminating or adding macro calls, or by adding tags.
Try processing the file now. There should be no errors.

\begin{verbatim}
@O@<hello.c@>==@{@-
@<Include Files@>
@<Function@>
@<Main Program@>
@}

@$@<Main Program@>==@{@-
main()
{
 doit();
}
@}

@$@<Function@>==@{@-
void doit()
{
 int i;
 for (i=0;i<10;i++)
   {
    @<Print@>
    @<Print@>
   }
}@}

@$@<Print@>@M==@{@-
printf("Hello World!");
printf("\n");@}

@$@<Scan@>@Z==@{scanf@}

@$@<Include Files@>==@{@-
#include <stdio.h>
#include <stdlib.h>@}
\end{verbatim}

\subsection{Indentation}
\xx{indentation}{macro calls}

The body of the \p{print} macro of the previous example
contains two lines of text.
A literal substitution of this macro's body in its context would result in:

\begin{verbatim}
   {
    printf("Hello World!");
printf("\n");
    printf("Hello World!");
printf("\n");
   }
\end{verbatim}

But instead, it comes out as (have a look at this part of \p{hello.c} now):

\begin{verbatim}
   {
    printf("Hello World!");
    printf("\n");
    printf("Hello World!");
    printf("\n");
   }
\end{verbatim}

The explanation is that FunnelWeb indents each line of multiline macros
by the level of indentation at the point of call.
This means that, as in the case above, program texts, which are usually
highly indented, come out looking \dq{right}.

In other circumstances, where the model of the text is one dimensional,
FunnelWeb's indentation could become an impediment or even a danger.
In these cases, it
can be switched off by including the FunnelWeb \newterm{pragma} line

\begin{verbatim}
@p indentation = none
\end{verbatim}

anywhere in the input file.

One of the design goals of FunnelWeb is to allow the user total control over
the product files. This contrasts with the approach of Knuth's WEB\x{WEB}
system
\paper{Knuth83} (upon which FunnelWeb is based), which mangles the input
text at the Pascal\x{Pascal} program syntax level, truncating identifiers,
converting
the text to upper case, and paragraphing text. Here is an example of part of
a Pascal program produced by WEB\xx{output}{WEB}
(from page~14 of \paper{Knuth83}):

\begin{verbatim}
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};
\end{verbatim}\checked{I can't believe I actually typed this mess in.}

Knuth's theory is that the program generated by a literate programming
system should be
treated as object code and hence should look like object code
too.\x{object code} While this
may be an admirable approach in the long run, the present programming
environment is one of faulty compilers and buggy tools.
The FunnelWeb view is that, in this environment,
the programmer needs all the help he can get
and that therefore he should be allowed total control over
the product file. Another reason for FunnelWeb's providing total
control over the product file, is that FunnelWeb is intended to be
target language independent, and so even if Knuth's view were adopted, it
would not be clear what a legitimate transformation of the text could be.

\subsection{Additive Macros}
\xx{additive}{macros}

Sometimes it is convenient to build up the definition of a macro in
stages throughout the input file. In FunnelWeb, this can be done using
an \newterm{additive macro}.
An additive macro is identical to an ordinary macro except
that\xx{tutorial}{==}\xx{tutorial}{+=}

\begin{enumerate}
\item It has \p{+=} instead of \p{==}.
\item It can be defined in one or more parts throughout the input file.
The definition of the macro is the concatenation of all the parts in the
order in which they appear.
\end{enumerate}

The following example shows how additive macros
can be used to scatter and regroup information, in this
case assisting in the lucid construction of a
data abstraction\xx{data}{abstraction} in a language (Pascal\x{Pascal})
that does not support them explicitly.

\begin{verbatim}
@!******************************

@O@<prog.pas@>==@{@-
program adt(input,output);
@<Types@>
@<Variables@>
@<Procedures@>
begin startproc; end.
@}

@!******************************

@$@<Types@>+=@{@-
type buffer_type =
   record
   length : integer;
   buf : array[1..100] of char;
   end;
@}

@$@<Variables@>+=@{@-
bigbuf : buffer_type;
@}

@$@<Procedures@>+=@{@-
procedure buf_init (var b : buffer_type               ) {Body of buf_init}
procedure buf_add  (var b : buffer_type;     ch : char) {Body of buf_add}
procedure buf_get  (var b : buffer_type; var ch : char) {Body of buf_get}
@}

@!******************************

@$@<Types@>+=@{@-
type complex_type = record r,i : real; end;
@}

@$@<Procedures@>+=@{@-
procedure cm_set (var c: complex_type; a,b: real)         {Body of cm_set}
procedure cm_add (a,b: complex_type; var c: complex_type) {Body of cm_add}
{Other procedures and functions}
@}

@!******************************

{...more pieces of program...}

@!******************************
\end{verbatim}

It is important to remember that the definition of each macro does not change
throughout the input file. FunnelWeb parses the entire input file and
assembles all the macro definitions before it even starts to expand macros.
As a result, each additive macro can only have one definition, and that
definition is the concatenation of all its parts.

The example above shows how additive macros can be used to rearrange the
presentation of a computer program in the order in which the user wishes
to discuss it rather than the order in which the compiler requires that it
be consumed. It is easy, however, to abuse the feature of additive macros.
In many cases, the same effect can be obtained more clearly by replacing
each part of an additive macro in-situ using uniquely named non-additive
macros, and then collect them together as a group at the point where the
additive macro is called. Doing this is more work, and is more error
prone, but can result in a clearer exposition.
The following program illustrates this alternative approach.

\begin{verbatim}
@!******************************

@O@<prog.pas@>==@{@-
program adt(input,output);
@<Types@>
@<Variables@>
@<Procedures@>
begin startproc; end.
@}

@$@<Types@>==@{@-
@<Buffer type@>
@<Complex type@>
@}

@$@<Variables@>==@{@-
@<Buffer variable@>
@}

@$@<Procedures@>==@{@-
@<Buffer procedures@>
@<Complex procedures@>
@}

@!******************************

@$@<Buffer type@>==@{@-
type buffer_type = record
                   length : integer;
                   buf : array[1..100] of char;
                   end;
@}

@$@<Buffer variable@>==@{@-
bigbuf : buffer_type;
@}

@$@<Buffer procedures@>==@{@-
procedure buf_init(var b : buffer_type) {Body of buf_init}
procedure buf_add(var b : buffer_type; ch : char) {Body of buf_add}
procedure buf_get(var b : buffer_type; var ch : char) {Body of buf_get}
@}

@!******************************

@$@<Complex type@>==@{@-
type complex_type = record r,i : real; end;
@}

@$@<Complex procedures@>+=@{@-
procedure cm_set(var c: complex_type; a,b : real)  {Body of cm_set}
procedure cm_add(a,b : complex_type; var c: complex_type) {Body of cm_add}
{Other procedures and functions}
@}

@!******************************

{...more pieces of program...}

@!******************************
\end{verbatim}

One of advantages of FunnelWeb (and literate programming in general) is that
(as shown above) it allows the user to lay out the program in whatever order is
desired\xx{program}{layout}
with near total independence from the ordering requirements of the
target programming language.

Additive macros are allowed to be tagged with \p{@Z} and \p{@M} just as other
macros can, but the tags must appear only on the first definition of the
macro. Additive macros cannot be connected directly to product files.

\subsection{Parameterized Macros}
\xx{parameterized}{macros}

No self-respecting macro preprocessor would be complete without some form
of macro parameterization, and FunnelWeb is no exception. FunnelWeb allows
each macro to have from zero to nine formal parameters\xx{formal}{parameters}
named \p{@1}\x{@1...}, \p{@2},
\p{@3}, \p{@4}, \p{@5}, \p{@6}, \p{@7}, \p{@8}, and \p{@9}.

To define a macro with one or more parameters, insert a formal parameter
list\xx{formal}{parameters}
just after the macro name in the macro definition. Because macro
parameters have fixed names (\p{@1}$\ldots$\p{@9}), there is no need to
specify the names of formal parameters in the formal parameter list.
All that need be conveyed is how many parameters the macro has.
Here is an example of the definition of a macro having three parameters:

\begin{verbatim}
@$@<While loop@>@(@3@)@M==@{@-
@1
while (@2)
  {
   @3
  }
@}
\end{verbatim}

To call a parameterized macro, an actual
parameter\xx{actual}{parameters} list must be supplied
that contains exactly the same number of actual parameters as there are
formal parameters in the definition of the macro being called. An actual
parameter list is delimited by \p{@(}\x{@(}
and \p{@)},\x{@)} and parameters are
\i{separated} by \dqp{@,}.\x{@,} The actual parameters themselves are general
FunnelWeb expressions (see Chapter~\ref{chapdefinition}
for the exact syntax) and can
be inserted into the list directly or can be delimited by \p{@"}\x{@"} so as to
allow some white space to assist in formatting the actual parameters.
Here are some examples of calls of the \p{While loop} macro defined above.

\begin{verbatim}
@! First form of actual parameters without whitespace and double quotes.
@<While loop@>@(x=1;@,x<=10@,printf("X=%u\n",x);@)

@! Second form of actual parameters. The double quotes allow non-active
@! whitespace that helps to lay out the actual parameters neatly.
@! This call is functionally identical to the one above.
@<While loop@>@(
   @"x:=1;@" @,
   @"x<=10@" @,
   @"printf("X=%u\n",x);@" @)

@! The two forms can be mixed in a single call.
@<While loop@>@(x=1;@,x<=10@,
              @"printf("X=%u\n",x);@" @)
\end{verbatim}

A few rules about parameterized macros are worth mentioning.
Macros that do not have any parameters must have no formal or
actual parameter lists.\xs{parameter list}{absent}
Additive macros can have parameters, but the formal parameter list
must appear in the first definition part only.

Here is another example of the use of parameterized macros. This time,
parameters and macro calls are used in a FunnelWeb input file
that constructs an $O(n)$ representation
of a song\x{song}\x{twelve bugs of christmas} whose full size is
$O(n^2)$ in the number $n$ of unique
lines.\x{rec.humor.funny}\xn{Pat}{Scannel}

\begin{verbatim}

@O@<Twelve_bugs.txt@>==@{@-
The Twelve Bugs of Christmas
----------------------------
@<Verse@>@(@"first@"    @,@<1@>@)
@<Verse@>@(@"second@"   @,@<2@>@)
@<Verse@>@(@"third@"    @,@<3@>@)
@<Verse@>@(@"fourth@"   @,@<4@>@)
@<Verse@>@(@"fifth@"    @,@<5@>@)
@<Verse@>@(@"sixth@"    @,@<6@>@)
@<Verse@>@(@"seventh@"  @,@<7@>@)
@<Verse@>@(@"eighth@"   @,@<8@>@)
@<Verse@>@(@"ninth@"    @,@<9@>@)
@<Verse@>@(@"tenth@"    @,@<A@>@)
@<Verse@>@(@"eleventh@" @,@<B@>@)
@<Verse@>@(@"twelfth@"  @,@<C@>@)

This song appeared in the internet newsgroup rec.humor.funny on 24-Dec-1991.
It was contributed by Pat Scannell (scannell@@darkstar.ma30.bull.com).
@}

@$@<Verse@>@(@2@)@M==@{@-
For the @1 bug of Christmas, my manager said to me
     @2
@}

@$@<1@>@M==@{See if they can do it again.@}
@$@<2@>@M==@{Ask them how they did it and@+@<1@>@}
@$@<3@>@M==@{Try to reproduce it@+@<2@>@}
@$@<4@>@M==@{Run with the debugger@+@<3@>@}
@$@<5@>@M==@{Ask for a dump@+@<4@>@}
@$@<6@>@M==@{Reinstall the software@+@<5@>@}
@$@<7@>@M==@{Say they need an upgrade@+@<6@>@}
@$@<8@>@M==@{Find a way around it@+@<7@>@}
@$@<9@>@M==@{Blame it on the hardware@+@<8@>@}
@$@<A@>@M==@{Change the documentation@+@<9@>@}
@$@<B@>@M==@{Say it's not supported@+@<A@>@}
@$@<C@>@M==@{Tell them it's a feature@+@<B@>@}
\end{verbatim}

\subsection{Macro Expansion}
\xx{macro}{expansion}

One of the strengths of FunnelWeb is that, when writing product files, it
does not attempt to evaluate any text expression (\eg{}text block, parameter,
macro call) in memory\xx{memory}{use of}
and then write the result out. Instead, it always
writes out what it is expanding dynamically and directly. This means that
the user need not fear defining macros that expand to huge amounts of text
and then calling those macros in other macros, or passing those huge macros
as parameters to other macros. In all cases, FunnelWeb expands directly to
the product file, and there can be no danger in running out of memory during
expansion (except for running out of stack space and other
marginally used resources in pathological cases).

The only thing to remember in this regard is that FunnelWeb always stores
the entire \i{input} file and all included files, in their entirety in
memory, for the duration of the run.

Here is an example, that illustrates how robust FunnelWeb is:

\begin{verbatim}
@! FunnelWeb copes well with the following macro definitions.
@! (Providing that it has a little over ten megabytes of memory).

@O@<woppa.txt@>==@{@<Quote@>@(@<Humungeous@>@)@+@}

@$@<Quote@>@(@1@)==@{"@1"@}

@$@<Humungeous@>==@{@-
...Ten Megabytes of Text...
@}
\end{verbatim}

\subsection{Include Files}
\xx{include}{files}

FunnelWeb provides a nested include file facility that can be used for a
number of purposes. When FunnelWeb runs into a single line containing the
special sequence \p{@i}\x{@i} followed by a blank, followed by a file name,
it reads in the designated
file and replaces the line containing the command (including the end of
line marker at the end of the line) with the entire contents
of the designated file. For example, if there was a file called
\p{camera.txt} containing the two lines:\xx{poem}{camera}\xx{animal}{poem}

\begin{verbatim}
'Cos I shoot with a camera instead of a gun.
The animals flock to be petted and fed,
\end{verbatim}

and another file called \p{poem.fw}
containing the following four lines\x{shooting}

\begin{verbatim}
I like to go shooting, it's a whole lot of fun,
@i camera.txt
Cos they know my camera isn't loaded with lead.
- RNW, 04-Jan-1991.
\end{verbatim}

Then, if FunnelWeb were to process \p{poem.fw}, the result would be
as if FunnelWeb had read in:

\begin{verbatim}
I like to go shooting, it's a whole lot of fun,
'Cos I shoot with a camera instead of a gun.
The animals flock to be petted and fed,
'Cos they know my camera isn't loaded with lead.
- RNW, 04-Jan-1991.
\end{verbatim}

FunnelWeb expands include files before it starts scanning and parsing the
included text. The result is that include files can contain anything that
can be found in a FunnelWeb file. The following example illustrates
the level at which the include mechanism operates. If \p{main.fw} contains

\begin{verbatim}
@O@<output.dat@>==@{@-
@i inc.fw
This is the text of the sloth macro.
@}
\end{verbatim}

and inc.fw contains

\begin{verbatim}
@<Sloth@>
@}

@$@<Sloth@>==@{@-
\end{verbatim}

Then if FunnelWeb were applied to \p{main.fw}, it would see:

\begin{verbatim}
@O@<output.dat@>==@{@-
@<Sloth@>
@}

@$@<Sloth@>==@{@-
This is the text of the sloth macro.
@}
\end{verbatim}

which it would process in the normal manner. The only special
sequence processing that takes place at a level lower
than include files is the processing of the \p{<special>=<newspecial>}
sequence which changes the special character.\xx{special character}{changing}

A few other facts about include files are worth mentioning here. Include
files inherit the directory specification supplied using the \p{+I} command
line option. The special character is saved at the start of each include
file and restored to its previous value at the end of each include file.
Include files can be nested up to ten levels.
Recursive included files\xx{include files}{recursive}
will always cause an infinite recursion as there
is no bottoming out mechanism available.
Include files
must contain an integer number of lines (\ie{}the last line must be
terminated with an end of line marker). Once FunnelWeb has seen
\dqp{@i\ } at the start of a line, it will grab the rest of the
line raw and treat it as a file name. There is no place on the 
line for things like FunnelWeb comments (see later) or extraneous text.

Include files can be used for many purposes, but are particularly useful for
hauling in macro libraries.\xx{macro}{libraries}

\section{Typesetting Facilities}
\xx{tutorial}{typesetting}

The first half of this tutorial focuses solely on the macro facilities
of FunnelWeb (which it more or less covers completely). As a result,
the example documents you have seen so far have been gross
distortions of \dq{normal} FunnelWeb documents which often contain as much
documentation as
code.\x{documentation vs code}\x{code vs documentation}\footnote{As
an example, the author used
FunnelWeb to develop a largish computer program and found that on average
his style of using FunnelWeb resulted in about 30\% documentation and
70\% macros (code) (measured by numbers of lines).}
While there are applications where FunnelWeb can be used solely
as a macro preprocessor, most applications will use its
typesetting facilities as well.

This section restores the balance in this tutorial
by presenting FunnelWeb's typesetting facilities.

\subsection{Overview}
\xx{overview}{typesetting}

The macro definitions discussed in the macro tutorial completely define
the contents of the product files that FunnelWeb will generate. These macro
definitions can be arranged in any order and nothing external to them
can affect the contents of the product files. The macros
can be thought of as a group of self-contained islands.

Although FunnelWeb will can process the macros all on their own,
the full power of FunnelWeb
is realized only when the macros are surrounded by a sea of documentation.
This sea can take two forms: directives and free text.
Some of the directives control things such as the maximum input line
length. However, most of them are typesetting directives that affect
the printed documentation.
Thus a FunnelWeb document can be viewed as a sequence
of \newterm{macro definitions},
\newterm{directives}, and \newterm{free text}.

Unlike the product files which consist of unscrambled macro calls,
the documentation file is more or less a
direct representation of the input file. Each part of the input file
appears in the documentation file in the order in which it appears in the
input file. However, each different kind of part is
typeset\footnote{Here the term \dq{typeset} is used loosely to refer to
FunnelWeb's generation of typesetter commands for each construct in the
input file. Strictly, the term should be used only to describe the actions
of a typesetter program (\eg{}\TeX{}).} in a different
manner. Macros are typeset in a particular style, with the macro body
appearing in \p{tt font} (see some FunnelWeb printed documentation for
an example). Typesetter directives have specific defined
effects (more later).
Free text is typeset exactly as it is, except that each block of text
between blank lines is filled and justified as a paragraph.

The following example demonstrates how all this works. Type in the following
as \p{example.fw} and run it through FunnelWeb with the
command \dqp{fw~example~+t}. The \dqp{+t} instructs FunnelWeb to generate
a documentation file called \p{example.tex}.
Run the file through \TeX{} and print it.
Examine the files \p{example.out} and \p{example.tex}.

\begin{verbatim}
You are reading some free text before the macro. Free text can consist
of any text (not containing the FunnelWeb special character) including
typesetter commands
such as $, %, #, and \TeX{} which
will be typeset to appear exactly as they do in the input file!
Look out! Here comes a macro!

@O@<example.out@>==@{@-
This text is part of
a macro definition.
@}

This is free text following the macro. This sentence contains
two @{inline@} typesetter @/directives@/.
Now here is a non-inline typesetting directive.

@t new_page

This sentence will appear on the next page.
\end{verbatim}

At the top of the \p{example.tex} documentation file will be a set of \TeX{}
macro definitions. The \TeX{} code corresponding to the input above
appears at the end of the file. It should look something like this.

\begin{verbatim}
You are reading some free text before the macro. Free text can consist
of any text (not containing the FunnelWeb special character) including
typesetter commands
such as \$, \%, \#, and $\backslash$TeX$\{$$\}$ which
will be typeset to appear exactly as they do in the input file!
Look out! Here comes a macro!

\fwbeginmacro
\fwfilename{example.out}{1}\fwequals \fwodef \fwbtx[This text is part of
a macro definition.
]fwetx=%
\fwcdef 
\fwbeginmacronotes
\fwisafile{This macro is attached to an output file.}
\fwendmacronotes
\fwendmacro

This is free text following the macro. This sentence contains
two \fwlit{inline} typesetter \fwemp{directives}.
Now here is a non-inline typesetting directive.

\fwnewpage

This sentence will appear on the next page.
\end{verbatim}

The following points explain the \p{example.tex} file.

\narrowthing{You don't have to know TeX:}{If you don't know
\TeX{}, don't pay too much
attention to this section. You don't need to know \TeX{} to use FunnelWeb.}

\narrowthing{In order:}{FunnelWeb has merely transformed the
input. It hasn't rearranged it.}

\narrowthing{Free text:}{Most of the free text has been simply copied over.
The \TeX{} typesetter justifies and fills all paragraphs fed to it by
default, so most of the text has just been copied verbatim.}

\narrowthing{TeX codes:}{The characters and sequences which
\TeX{} treats as special have been neutralized in the documentation
file. For example, \dqp{\$} has become \dqp{\bs\$}. By
default, FunnelWeb allows the user to write any text as free text and not
have to worry about accidentally invoking typesetter features.}

\narrowthing{fw sequences:}{The \p{fw} sequences (\eg{}\p{\bs{}fwbeginmacro})
invoke \TeX{} macros defined
earlier in the documentation file (and not shown here).}

\narrowthing{The macro:}{The macro is typeset using a set of predefined
\TeX{} macros. See the printed documentation to see what this looks like
on paper.}

\narrowthing{Typesetter directives:}{Unlike the \TeX{}
command sequences (which
were neutralized), the FunnelWeb typesetter directives turn into \TeX{} macro
calls. For example, \dqp{@\{inline@\}} became \dqp{\bs{}fwlit\{inline\}}.}

In summary, FunnelWeb produces typeset documentation that transforms,
but does not reorder, the input file. Macros are typeset in a specific
style. FunnelWeb typesetter directives have particular well-defined effects.
Free text is filled and justified, but will otherwise appear in the
printed documentation exactly as it appears in the input file.

\subsection{Typesetter Independence}
\xx{typesetter}{independence}

Although the current version of FunnelWeb can only generate documentation
files in \TeX{} form,
it encourages typesetter independence
by neutralizing all \TeX{} control sequences before writing them out. The
result is that you don't have worry about upsetting or depending on \TeX{}
by accidentally including some special character or sequence. By default your
input file is \newterm{typesetter independent}.

This scheme differs from other literate programming tools, including
all earlier versions of FunnelWeb, which copy their free text  directly
to the documentation file, the justification being that the programmer
can use the full power of the typesetter language to describe the program.
The disadvantages of doing this are first that the
programmer is required to know the typesetting language and second that
the input file becomes typesetter dependent. FunnelWeb avoids these problems
by knobbling the free text be default.

However, FunnelWeb does provide a trapdoor for those who want their
free text to be fed directly to \TeX{}. To open the trapdoor,
simply include the following pragma somewhere in your input file.

\begin{verbatim}
@p typesetter = tex
\end{verbatim}

See Section~\ref{typesetterpragma} for more information.

FunnelWeb leaves the degree to which
the user wishes to bind a particular document to a particular typesetter
up to the user. In some cases, the extra typesetting power may compensate
for the lack of portability. However, as a rule, it is best to
avoid typesetter-specific commands, so as to allow your input files to
be formatted at a later date for different typesetters.
FunnelWeb includes a number of its own typesetter commands so as to
support typesetter-independent input files.
The following sections describe some of these commands. In particular,
the next section describes the most powerful FunnelWeb typesetting directives
which allow the user to structure the document hierarchically.

\subsection{Hierarchical Structure}
\xx{hierarchical}{structure}

The tree structure is one of the most effective structuring tools that
exists, deriving its power from the principal of divide and conquor.
So effective is it that the internal organization of
most technical books are tree
structures which are concisely summarized in the table of contents.
In contrast, computer programs
are usually presented as flat sequences of text to be consumed by an
anonymous compiler.

In order to bring program documentation up to the structural
sophistication commonplace in technical books, FunnelWeb provides five levels
of section headings\xx{section}{headings}
implemented by the five special sequences \p{@A},\x{@A...} \p{@B},
\p{@C}, \p{@D}, and \p{@E}. These must always appear at the start of a line.
\p{@A} is the highest level section
(\eg{}like \LaTeX{}'s \p{\bs{}chapter}) and \p{@E} is the lowest level
section (\eg{}like \LaTeX{}'s \p{\bs{}subsubsubsection}).
Section headings can appear anywhere in
the free text of a FunnelWeb input file (\ie{}anywhere except inside a
macro definition).

Each section heading\xx{name}{section} in a FunnelWeb document
has an associated name.
The name of a section can be provided explicitly by supplying it
delimited by \p{@<} and \p{@>} immediately after the section sequence
(\eg{}\p{@A}), or implicitly by not providing an explicit name, in which
case the section takes the name of the first macro defined between the
section header in question and the following section header. An error is
generated if a section has not been given an explicit name and does not
contain any macro definitions. Here are some example headings:

\begin{verbatim}
@A@<Feed the Penguins and Save the World@>
@B@<Feed the Penguins@>
@C@<Feed the little penguins@>
@C@<Feed the big penguins@>
@B@<Save the World@>
@C@<Save Europe@>
@C@<Save Africa@>

@C This heading hasn't been given an explicit name, but will inherit the
name \p{Save the rest of the world} from the macro definition below.

@$@<Save the rest of the world@>@Z==@{...@}
\end{verbatim}

The feature of having unnamed sections inherit the name of the first
macro defined within their scope is present because a common style of
writing in FunnelWeb is to have one section per macro definition. Because,
under this style,
each section describes a single macro, it usually turns out that the
macro name makes a good name for the section too. The inheritance mechanism
prevents duplication of the name.\xx{section name}{inheritance}

Apart from the requirement that each section have an explicit or implicit
name and that its special sequence appear at the start of a line, the only
other restriction on section headings is that a section heading at level
$n$ cannot appear immediately after a section heading at level $n-1$ or less.
In other words, the hierarchy cannot be broken. For
example, an \p{@C} cannot appear after an \p{@A} heading unless there
is an intervening \p{@B} heading.

\begin{verbatim}
@A@<The Top Heading@>
@C@<Level C here is not allowed after an A and will cause an error@>
\end{verbatim}

This rule extends to the start of the
file; if there are any headings at all, the first one must be an \p{@A}
heading. The following file, while short, is in error.

\begin{verbatim}
This FunnelWeb input file is in error because its first section heading
is at level C rather than level A.
@C@<2@>
\end{verbatim}

\subsection{Understanding the Printed Documentation}

Type in the following file, and use FunnelWeb and \TeX{} to generate the
corresponding printed
documentation.\xx{programmer's}{cheer}\xx{hacker's}{cheer}
\xx{hacker's}{dictionary}

\begin{verbatim}
@A@<Table of Contents@>

@t table_of_contents

@A@<Macros for Moral Support@>

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

@$@<Programmer's Cheer@>@M==@{
-- Shift to the left!
-- Shift to the right!
-- Pop up, push down!
-- Byte! Byte! Byte!
-- (From "The New Hacker's Dictionary").
@}

The next macro is similar but is distributed throughout the program.
@$@<Hacker's Cheer@>+=@{@+-- Pointer to the left@+@}

@A@<An Extremely Imperative Stack Abstraction@>

@B@<Define the Stack@>
@$@<Hacker's Cheer@>+=@{-- Pointer to the right@+@}
@$@<Stack Type@>@Z==@{type stack = record ... end;@}

@B@<Push the Stack@>
@$@<Hacker's Cheer@>+=@{-- Hack that code@+@}
@$@<Push Procedure@>@Z==@{@-
procedure push(var b:stack; v:value); @<Programmer's Cheer@> {...}@}

@B@<Pop the Stack@>
@$@<Hacker's Cheer@>+=@{-- Tight! Tight! Tight!@+@}
@$@<Pop Procedure@>@Z==@{@-
procedure pop(var b:stack); @<Programmer's Cheer@> {...}@}

@B@<Rough the Stack Up a Bit@>
@$@<Hacker's Cheer@>+=@{-- (RNW, 04-Jan-1991).@+@}
@$@<Rough Procedure@>@Z==@{@-
procedure rough(var b:stack); @<Hacker's Cheer@> {...}@}

@O@<dummy.txt@>==@{dummy@+@}
\end{verbatim}

An examination of the printed documentation reveals a lot about how
FunnelWeb's presentation works.

First, notice how the \p{@t} typesetter directive
at the top of the file has caused a table of contents to appear.
This is one of FunnelWeb's typesetting features and is discussed in a later
section. The table of contents shows that the sections have been
numbered hierarchically.

Now take a look at the typeset macro definitions. Most important are the
numbers in square brackets that follow each macro name. As well as
numbering the headings \i{hierarchically}, FunnelWeb \i{independently}
numbers
the macro definitions \i{sequentially}. The first macro definition
(for \dq{Programmer's Cheer}) is numbered 1.
The second (for \dq{Hacker's Cheer}) is numbered 2 and so on.
Note that it is not macros that are numbered, but macro definitions.
The distinction is necessary because some macros (such as the
\dq{Hacker's Cheer} macro) are additive.
It is important to
realize that there is no relationship between the numbers of the headings
and the numbers of the macro definitions.

Now take a look at the notes beneath the body of each macro definition.
All macro definitions are followed by a note indicating the definitions in
which the macro is called. Additive macros have an additional list, listing
the definitions in which they are defined.

Finally, take a look at the macro \i{call} of \dq{Programmer's Cheer}
in section~3.2 of the printed documentation.
Macro calls are set in slanted roman (so that they can
be distinguished from the \p{tt font} code) and are followed by
the number of the defining macro definition. In this case, the macro
was defined in definition~1. Further down, the call to
the \dq{Hacker's Cheer} macro
indicates that the macro was defined in definition~2. In fact the macro is
additive and definition~2 is just the first of many definitions. To list
all definitions in a call to an additive macro would be unnecessarily messy.

\subsection{Literals and Emphasis}
\x{literal construct}\x{emphasis construct}

When writing about program code, it is often desirable to be able to indicate
that a particular word or phrase be typeset in the same manner as the code
being discussed. For example, one might talk about the variable \p{topval}
or the procedure \p{stack\_pop} and wish for them to be typeset
as they are in this sentence. This, of course,
is simple to do using \TeX{} macros, but use of the
(more general) FunnelWeb typesetting directives to do the same work has the
added benefit of keeping the document portable to other typesetters.

FunnelWeb provides two in-text type modification constructs: \p{@\{...@\}}
and \p{@/...@/}\x{@slash}\x{@braces}
where $\ldots$ is raw text. The \p{@\{...@\}}
construct sets the enclosed
text in the same manner as the text of macro definitions is set. The
\p{@/...@/} construct emphasises its enclosed text in some
typesetter-dependent fashion. Typically the emphasised text is set in
italics.

Here is an example of how these constructs might be used:

\begin{verbatim}
The following procedure @{put_sloth@} writes the @{sloth@} variable to
the output file. Note: @/The output file must be opened for writing
at this point or the program will crash!@/
\end{verbatim}

\subsection{Adding a Header Page}
\x{header page}

FunnelWeb provides a few typesetter-independent typesetting constructs
which are specifically designed for the construction of header pages.
These constructs are usually best placed at the top
of your input file, but can be placed anywhere the document if desired to
create header pages right through. The two main restrictions on these
constructs is that the \p{@t} must start at the start of a line (which
cannot contain comments), and that the constructs cannot appear inside
a macro definition. Here is what the top of an input file might look like:

\begin{verbatim}
@t vskip 40 mm
@t title titlefont centre "Hairy Wombat"
@t title titlefont centre "Simulation"
@t vskip 10 mm
@t title smalltitlefont centre "A Program in Six Parts"
@t title smalltitlefont centre "Simulating the Life of Some Hairy Wombats"
@t vskip 20 mm
@t title normalfont left "By Zqitzypbuswapzra Ypongtatoslrtzz"
@t new_page
@t table_of_contents
@t new_page
\end{verbatim}

The \p{@t} at the start of each line indicates that each entire line is
a typesetter directive.
The \p{vskip}\xx{vskip}{directive}
directive instructs FunnelWeb to skip some vertical space
(measured in millimetres). The \p{title} directive\xx{title}{directive}
instructs FunnelWeb to
position a string of text on a single line of its own. Options are
provided for font and alignment. The first word after \p{title} is the font
which can be one of (in decreasing order of size) \p{titlefont},
\p{smalltitlefont}, and \p{normalfont}. The second word after \p{title} is
the desired alignment of the text. The options here are \p{left}, \p{right},
and \p{centre}. The \p{new\_page}
directive\xx{newpage}{directive}
instructs FunnelWeb to skip to a new page. Finally, the
\p{table\_of\_contents} directive\xx{table of contents}{directive}
instructs FunnelWeb to insert a table of
contents at that point in the text.

\subsection{Comments}
\x{comments}

A FunnelWeb comment commences with the \p{@!}\x{@!} sequence and continues up to,
but not including, the end of line marker at the end of the line that the
comment sequence is on. Comments can be placed on any line except
\p{@i} include, \p{@p} pragma, and \p{@t} typesetter directive lines.

The text following the FunnelWeb comment sequence \p{@!} will not appear
in the product files or the documentation file. It is
only for the eyes of those who bother to look at the original \p{.fw}
input file. Typically FunnelWeb comments are used to describe the way in
which particular FunnelWeb constructs are being used. Example:

\begin{verbatim}
@! This macro is really revolting. Please forgive me. I had to do it!
@$@<Revolt Me@>==@{@-
@#X@(@#Y@(@#Z@,@"@#Z@"@)=6@,Teapot@,@"@#Q@(45@)@"@,Tiger@)@}
\end{verbatim}

\section{A Complete Example}
\xx{complete}{example}\xx{FunnelWeb}{Example}

To finish off the chapter, a complete example of a FunnelWeb input file
is presented. Although unrealistically short, it gives a better
idea of what a typical FunnelWeb \p{.fw} file looks like.

\begin{verbatim}
@!---------------------------------------!
@!  Start of FunnelWeb Example .fw File  !
@!---------------------------------------!

@t vskip 40 mm
@t title titlefont centre "Powers:"
@t title titlefont centre "An Example of"
@t title titlefont centre "A Short"
@t title titlefont centre "FunnelWeb .fw File"
@t vskip 10 mm
@t title smalltitlefont centre "by Ross Williams"
@t title smalltitlefont centre "26 January 1992"
@t vskip 20 mm
@t table_of_contents

@A@<FunnelWeb Example Program@>

This  program writes  out each  of the  first @{p@}  powers of  the first  @{n@}
integers. These  constant parameters are located  here so that they  are easy to
change.

@$@<Constants@>==@{@-
n : constant natural := 10;     -- How many numbers? (Ans: [1,n]).
p : constant natural :=  5;     -- How many powers?  (Ans: [1,p]).@}

@B Here is  the outline of the  program. This FunnelWeb file  generates a single
Ada output file  called @{Power.ada@}. The main program consists  of a loop that
iterates once for each number to be written out.

@O@<Power.ada@>==@{@-
@<Pull in packages@>

procedure example is
   @<Constants@>
begin -- example
   for i in 1..n loop
      @<Write out the first p powers of i on a single line@>
   end loop;
end example;
@}

@B In this section,  we pull in the packages that this program  needs to run. In
fact, all we need is the IO package so that we can write out the results. To use
the IO package, we first of all need  to haul it in (@{with text_io@}) and then
we need to make all its identifiers visible at the top level (@{use text_io@}).

@$@<Pull in packages@>==@{with text_io; use text_io;@}

@B Here is  the bit that writes out  the first @{p@} powers of  @{i@}. The power
values  are  calculated  incrementally  in  @{ip@}  to  avoid  the  use  of  the
exponentiation operator.

@$@<Write out the first p powers of i on a single line@>==@{@-
declare
   ip : natural := 1;
begin
   for power in 1..p loop
      ip:=ip*i;
      put(natural'image(ip) & " ");
   end loop;
   new_line;
end;@}

@!---------------------------------------!
@!   End of FunnelWeb Example .fw File   !
@!---------------------------------------!
\end{verbatim}

\section{Summary}

This chapter has provided an introduction to FunnelWeb and a tutorial
that covers most of its features. FunnelWeb's functionality can be split into
two parts: a macro preprocessor, and support for typesetting.
The reader should be aware that
the examples in this chapter, constructed as they were to demonstrate
particular features of FunnelWeb, do not present a realistic picture
of the best use of the tool. Only the final example of this chapter
comes close.
The reader should study this last example carefully
and then write some real
programs using FunnelWeb before proceeding to Chapter~\ref{chapadvanced}
which provides more advanced information. At this stage it does not
particularly matter exactly how you use Funnelweb, as everyone develops
their own style anyway. The important thing is to try it.

%==============================================================================%
%                               End of Ch1.tex                                 %
%==============================================================================%