1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
2
"http://www.w3.org/TR/REC-html40/loose.dtd">
6
***********************************************************************
7
FUNNELWEB MANUAL WEB PAGE
8
=========================
9
Copyright (c) Ross N. Williams 1992,1999. All rights reserved.
11
Permission is granted to redistribute and use this manual in
12
any medium, with or without modification, provided that all
13
notices (including, without limitation, the copyright
14
notice, this permission notice, any record of modification,
15
and all legal notices) are preserved on all copies, that all
16
modifications are clearly marked, and that modified versions
17
are not represented as the original version unless all the
18
modifications since the manual's original release by Ross N.
19
Williams (www.ross.net) consist of translations or other
20
transformations that alter only the manual's form, not its
21
content. THIS MANUAL IS PROVIDED "AS IS" AND WITHOUT ANY
22
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT
23
LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND
24
FITNESS FOR A PARTICULAR PURPOSE. TO THE EXTENT PERMITTED BY
25
LAW THERE IS ABSOLUTELY NO WARRANTY.
27
***********************************************************************
31
<TITLE>5.2 Wish List</TITLE>
32
<STYLE TYPE="text/css"> <!-- A {text-decoration: none} // --> </STYLE>
34
<BODY BACKGROUND="binary/background.gif"
43
<TD WIDTH="130" VALIGN="top">
44
<IMG SRC="binary/d_clear.gif" ALT="" WIDTH="130" HEIGHT="1"><BR>
49
<A HREF="http://www.ross.net/"
51
onClick="window.open('','rosshome','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
53
<IMG SRC="binary/rossnet_logo.gif"
54
WIDTH="64" HEIGHT="32"
55
BORDER="0" ALT="RossNet"
56
HSPACE="0" VSPACE="1"></A><BR>
59
<A HREF="../index.shtml"
61
onClick="window.open('','funnelweb','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
63
<IMG SRC="binary/linklogo.gif"
64
WIDTH="64" HEIGHT="32"
65
BORDER="0" ALT="FunnelWeb"
66
HSPACE="0" VSPACE="1"></A><BR>
68
<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0><TR><TD BGCOLOR="#000000">
69
<A HREF="../reference/index.html"
70
TARGET="funnelwebreference"
71
onClick="window.open('','funnelwebreference','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
72
><FONT COLOR="#FFFFFF"><B>Reference</B></FONT></A><BR>
74
<A HREF="../tutorial/index.html"
75
TARGET="funnelwebtutorial"
76
onClick="window.open('','funnelwebtutorial','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
77
><FONT COLOR="#FFFFFF"><B>Tutorial</B></FONT></A><BR>
79
<A HREF="index.html"><FONT COLOR="#FFFFFF"><B>Developer</B></FONT></A><BR>
80
<A HREF="compile.html"><FONT COLOR="#FFFFFF">1 Compile</FONT></A><BR>
81
<A HREF="design.html"><FONT COLOR="#FFFFFF">2 Design</FONT></A><BR>
82
<A HREF="implement.html"><FONT COLOR="#FFFFFF">3 Implement</FONT></A><BR>
83
<A HREF="modify.html"><FONT COLOR="#FFFFFF">4 Modify</FONT></A><BR>
84
<A HREF="misc.html"><FONT COLOR="#FFFFFF">5 Misc</FONT></A><BR>
85
<A HREF="gpl.html"><FONT COLOR="#FFFFFF">6 Licence</FONT></A><BR>
88
<A HREF="search.html"><FONT COLOR="#FFFFFF"><B>SEARCH</B></FONT></A><BR>
94
<TD WIDTH="360" VALIGN="top">
98
<A HREF="index.html"><IMG SRC="binary/title.gif"
99
WIDTH="316" HEIGHT="24"
100
BORDER="0" ALT="FunnelWeb Developer Manual"
101
HSPACE="0" VSPACE="0"></A>
102
<P><FONT SIZE="5">5.2 Wish List</FONT><BR>
106
<P>This page contains the wish list that was included in
107
the original 1992 FunnelWeb Hacker's Manual. As hardly any
108
changes have been made since then, I thought I'd just
109
include it here verbatim.
111
<P><BR><FONT SIZE="4"><STRONG>Documentation</STRONG></FONT><BR>
113
<P><B>An official example:</B> A official example
114
program written using FunnelWeb should be constructed and
117
<P><B>Index program:</B> In order to typeset the
118
documentation, a portable index sorting program is required.
119
One should be written and added to the distribution
120
kit. Perhaps this could be the
123
<P><BR><FONT SIZE="4"><STRONG>Command Line Interface</STRONG></FONT><BR>
125
<P><B>Buffer length:</B> Currently the FunnelWeb
126
shell uses the <SAMP>COMLINE_MAX</SAMP> constant to size its
127
internal command line buffers. This is untenable. The
128
maximum length of a shell command line should not be machine
131
<P><B>Antiquated Features:</B> As the FunnelWeb
132
language develops, it is likely that some changes will have
133
to be made that will render one or more language constructs
134
obsolete. When this happens, it may be necessary to add a
135
command line option that has the power to turn on and off
136
warnings or errors flagging antiquated
139
<P><BR><FONT SIZE="4"><STRONG>Shell Interpreter</STRONG></FONT><BR>
141
<P><B>SETALL command:</B> When writing FunnelWeb
142
scripts, it is sometimes desirable to set <I>all</I> of
143
FunnelWeb's options to some particular value
144
so that the script is not vulnerable to changes in
145
FunnelWeb's default values which might occur from time to
146
time. To this end, it may be worth creating a
147
"<TT>SETALL</TT>" command that is identical to the
148
"<TT>SET</TT>" command except that it will generate an error
149
if the value of an option is not specified
152
<P><B>Recursion test:</B> A test should be added to
153
test for recursive invocation in a
156
<P><B>Diagnostic counting:</B> The code for counting
157
diagnostics in the script interpreter is rather messy and
158
perhaps even buggy. It should be cleaned up and
161
<P><B>Argument counting:</B> In the
162
<SAMP>command.c</SAMP> module, there is a variable that counts
163
the arguments to a command. Currently it takes the value of
164
the number of parameters including the command verb. This
165
has turned out to make the code less readable. It should be
166
changed to be the number of arguments to the command verb.
168
<P><B>Make facility:</B> It may be worth building
169
some sort of make facility into the script language so as to
170
support machines such as the Macintosh that do not already
173
<P><B>Signature file:</B> One problem with using
174
FunnelWeb in conjunction with an external <SAMP>Make</SAMP>
175
facility is that a user might change a FunnelWeb source file
176
without making changes that will affect the files that it
177
generates. If FunnelWeb is then run and the "<TT>+D</TT>"
178
option is on, then the output files will be deleted (to
179
avoid further <SAMP>Make</SAMP> propagations). If
180
<SAMP>Make</SAMP> then has a production linking the
181
<SAMP>.fw</SAMP> file to its output files, then it may conclude
182
that the output files are still out of date. To solve the
183
problem, FunnelWeb could be changed to write a
184
<SAMP>.sig</SAMP> file whenever it processes a <SAMP>.fw</SAMP>
185
file. The <SAMP>Make</SAMP> production could then be wired up
186
to link the <SAMP>.fw</SAMP> file to the <SAMP>.sig</SAMP> file
187
instead of to the output files.
189
<P><BR><FONT SIZE="4"><STRONG>Language Design</STRONG></FONT><BR>
191
<P>Some proposed changes to FunnelWeb do not correspond to
192
any particular component of FunnelWeb and are really to do
193
with the design of the input language.
195
<P><B>Output or file?:</B> The "<TT>@O</TT>" special
196
sequence for defining an output file is somewhat
197
non-mnemonic and can be confused with zero ("<TT>0</TT>").
198
Perhaps it should be replaced by the "<TT>@F</TT>"
201
<P><B>Syntax of section names:</B> Currently section
202
names use the same syntax as macro names. For example
203
"<TT>@<Sloth@></TT>". It can be argued that angle brackets
204
should be reserved only for macro names and that some other
205
syntax should be found for delimiting section names. This is
206
not a clear issue. It could also be argued that they are
207
both names, and that because sections can inherit their
208
names from the macros they contain, that the names are of
211
<P><B>One macro per section:</B> One particular style
212
of using FunnelWeb is to have at most one macro definition
213
per section. It may be worth adding a pragma that instructs
214
FunnelWeb to enforce this.
216
<P><B>Should @\{ suppress EOL?:</B> When defining a
217
macro in FunnelWeb, it seems to be rule rather than the
218
exception that the "<TT>@\{</TT>" be followed by
219
"<TT>@-</TT>". This suppresses the EOL on the definition
220
line, allowing the first line of the macro to be placed
221
immediately above and in line with the other lines without
222
introducing an EOL at the start of the macro text. One
223
option is to introduce a pragma to determine whether to
224
suppress EOLs following "<TT>@\{</TT>".
226
<P><B>Pragma syntax:</B> It is not clear how
227
"loose" the syntax of pragmas should be. Perhaps
228
they should be case insensitive.
230
<P><B>Conditionals:</B> Depending on demand, it may
231
be worth reintroducing some sort of conditional feature into
232
FunnelWeb. However, it would have to be very simple to
233
compete with the various ways in which conditionals can
234
already be fudged within FunnelWeb as it
237
<P><B>File markers:</B> It might be worth modifying
238
the language so that a special syntactical marker is
239
required at the start and end of files. This will assist in
240
detecting truncations and other
243
<P><B>Formal parameter lists:</B> It might be worth
244
changing over to a syntax for formal parameter lists that
245
does not require the <SAMP>@(</SAMP> and <SAMP>@)</SAMP>.
246
However, they could be retained as optional for backward
249
<P><BR><FONT SIZE="4"><STRONG>Scanner/Mapper</STRONG></FONT><BR>
251
<P><B>All non-contiguous mappings:</B> Currently
252
FunnelWeb requires that all input files be mapped into a
253
contiguous lump of memory. This caused problems for two
254
reasons. First, to do this, one has to allocate the memory
255
first, and to do that, you have to know how long the file
256
is, and it turns out that finding out the length of a file
257
in a portable manner is very inefficient. Second, although
258
IBM PC compatibles may have megabytes of memory, it is
259
segmented into blocks of at most 64K. This means that
260
FunnelWeb currently cannot read a file longer than 64K on a
263
These problems could be avoided if the mapper and scanner
264
were reorganized to allow input files to be read in and
265
stored as a linked list of chunks of text rather than a
268
<P><B>EOL is unspecifiable:</B> FunnelWeb uses ASCII
269
character decimal ten (10) internally to represent logical
270
end-of-line and is currently organized so that if one of
271
these is inserted into the text by the user using a
272
"<TT>@^D(10)</TT>", it will be written out as
273
a logical end of line, rather than as a single ASCII
274
character 10. This should be
277
<P><B>Allow mnemonics for unprintables:</B> FunnelWeb
278
allows users to insert unprintable characters into the
279
output using the "<TT>@^D(ddd)</TT>" special
280
sequence. Perhaps it would be changed so that it understands
281
ASCII standard mnemonics such as "<TT>LF</TT>" as well as
284
<P><B>Version pragma:</B> A "<TT>version</TT>" pragma
285
should be added that allows the user to specify in the input
286
file the version of FunnelWeb that was around when the input
287
file was created. At a later date, such a construct would be
288
very useful for determining how an input file should be
289
updated if the FunnelWeb language has changed between
292
<P><BR><FONT SIZE="4"><STRONG>Parser</STRONG></FONT><BR>
294
<P>There are no proposals to change the parser except as a
295
consequence of other proposals.
297
<P><BR><FONT SIZE="4"><STRONG>Analyser</STRONG></FONT><BR>
299
<P><B>Recursion detection:</B> Currently the
300
FunnelWeb analyser flags, with an error, all macros with an
301
infinite expansion. This would be best changed to flagging
302
all macros that are directly or indirectly recursive. To do
303
this, Tarjan's algorithm<STRONG>[Tarjan72]</STRONG> for the detection of strong components
306
<P><B>Once only macros:</B> By default FunnelWeb
307
prevents a macro from being called more than once unless it
308
has a "<TT>@M</TT>" associated with it. However, FunnelWeb
309
does allow a macro that calls such a macro to be called more
310
than once. Perhaps this "loophole" should be plugged
313
<P><BR><FONT SIZE="4"><STRONG>Tangle</STRONG></FONT><BR>
315
<P>The Tangler is one of the cleanest components of
316
FunnelWeb, as basically all it has to do is expand some very
319
<P><B>Text indentation:</B> Currently FunnelWeb
320
supports <I>no indentation</I> and <I>blank
321
indentation</I> . A third form could be added if it was
322
considered necessary. <I>Text indentation</I> is the same
323
as <I>blank indentation</I> except that instead of
324
indenting with blanks, FunnelWeb would indent with the text
325
to the left of the called macro. This facility could be
326
useful for commenting out large bodies of text in languages
327
that do not have multi-line comments (e.g. Ada). A
328
discussion of the pros and cons of this form of indentation
331
<P><BR><FONT SIZE="4"><STRONG>Weave</STRONG></FONT><BR>
333
<P>Perhaps FunnelWeb's weakest aspect is its typesetting
336
<P><B>Align table of contents:</B> When FunnelWeb
337
generates a table of contents, the section numbers are not
338
quite aligned with the start of the controlling heading
341
<P><B>Typesetting strength:</B> It should be possible
342
to specify the level of typesetting strength for headings so
343
that short documents do not look overdone when typeset. A
344
new pragma would be good for
347
<P><B>Typeset a portion:</B> Sometimes it is
348
desirable to typeset just a portion of a program. A command
349
line option could be added to do this. The option could
350
accept as its argument, a string containing a list of
351
section numbers or heading names.
353
<P><B>Generic typesetter option:</B> In addition to
354
building in a number of different versions of Weave, one for
355
each popular typesetter, it would be possible to add a
356
special generic format where the typeset output is expressed
357
in terms of <I>FunnelWeb macros</I> . The user could then
358
specify macro definitions for a non-supported typesetter and
359
run the output through FunnelWeb Tangle to get a typeset
360
file in a format suitable for the unsupported
363
<P><B>Suppression of include files:</B> It should be
364
possible to specify in the input file that particular
365
included files not appear in the typeset output. Currently,
366
the fact that an inclusion has occurred is not even
367
represented in the typeset output. Suppression of inclusions
368
is particularly necessary where a library of macros has been
369
included at the top of each of a group of source
372
<P><B>Cross reference of identifiers:</B> WEB
373
provides a list of identifiers and a list of all the
374
definitions in which they are used. A similar feature could
375
be added to FunnelWeb.
377
<P><B>Support for non-printables:</B> Currently
378
FunnelWeb does not provide support for typesetting the
379
special "<TT>@\circumflex(num)</TT>" sequences. This should
382
<P><B>Support for @+ sequences:</B> Currently Weave
383
does not see "<TT>@+</TT>" sequences as such. Instead it
384
perceives them as ordinary EOLs. However, there are
385
arguments for typesetting them specially.
387
<P><B>Typeset text in macro bodies:</B> One of the
388
much-loved features of WEB is the way that it allows the
389
user to switch recursively between document and program
390
formats. FunnelWeb does not allow this, but should. In
391
FunnelWeb, the delimiters "<TT>@{</TT>" and
392
"<TT>@}</TT>" are already used consistently to delimit
393
macro text. The "<TT>@[</TT>" and "<TT>@]</TT>" sequences
394
have been reserved for the delimitation of documentation
397
<P><B>Non-tt typesetting:</B> The current version of
398
FunnelWeb sets all its macro text in <SAMP>tt font</SAMP>. This
399
is both a blessing and a curse. It is a blessing because it
400
connects the reader directly to the code, with no
401
complicated intermediary. It is a curse because it looks
402
ugly compared to the beautifully typeset programs produced
403
by other literate programming tools.
405
<P>The difficulty with adding such beautiful typesetting is
406
that it is necessarily language-specific. Keywords and
407
syntax differ from language to language and it would not be
408
easy to come up with a set of language independent rules.
410
<P>One approach is to write a set of Weave back-ends, one for
411
each language. Another approach is to <I>generate</I> back
412
ends. This is the approach taken in the <I>Spider</I>
413
system<STRONG>[Ramsey89]</STRONG>. In the
414
<I>Spider</I> system, the programmer writes production
415
rules for converting lexical components of the program text
416
into typesetter instructions. The <I>Spider</I> program
417
reads these rules and generates a new version of WEB suited
418
for the target language.
420
<P>For FunnelWeb a slightly different system is proposed in
421
which Spider-like rules appear in the input file and are
422
used directly by Weave to perform the typesetting. An
423
intermediate abstract typesetting language could be used so
424
that the productions can be made language specific, but not
427
<P><BR><FONT SIZE="4"><STRONG>Lister</STRONG></FONT><BR>
429
<P><B>Glue factor:</B> A glue factor could be added
430
that determines how many lines can be in between two
431
diagnostics in the listing before the two groups of lines
432
are joined together in the listing with no intervening
435
<P><BR><FONT SIZE="4"><STRONG>Diagnostics</STRONG></FONT><BR>
437
<P><B>Advisory information:</B> Some of FunnelWeb's
438
diagnostics provide a detailed explanatory paragraph. While
439
this information might be useful the first time, it has the
440
capacity to clog up a listing file if the user has made the
441
same error many times. To solve this problem, FunnelWeb
442
could be modified so that such explanations are only
443
displayed the first time the error occurs.
445
<P><B>Abort after n errors:</B> A facility could be
446
added to prevent FunnelWeb's scanning, parsing, and
447
analysing phases from continuing if a certain number of
448
errors have already been issued.
450
<P><BR><FONT SIZE="4"><STRONG>Speed</STRONG></FONT><BR>
452
<P><B>Measurement of speed:</B> Although FunnelWeb
453
can generate a breakdown of where it is spending its time,
454
it does not give a final rating in lines per minute. This
457
<P><B>Find the hot spots:</B> Although FunnelWeb has
458
been designed to allow high speed, not much effort has so
459
far been made to make it fast. This should be done.
461
<P><B>Change some declarations:</B> FunnelWeb is full
462
of variable declarations where the variables are wider than
463
they need be. Replacing these might speed it up.
465
<P><BR><FONT SIZE="4"><STRONG>Correctness</STRONG></FONT><BR>
467
<P><B>Bounds analysis:</B> Not much effort has gone
468
into the design of FunnelWeb's input boundaries. An analysis
469
should be made of FunnelWeb's behaviour when the following
470
quantities are stretched:
474
<LI> Input line length.
475
<LI> Input file size.
476
<LI> Number of macros.
477
<LI> Length of macro.
480
<P>In particular, FunnelWeb's behaviour at 32K and 64K
481
boundaries should be observed.
483
<P><B>Stack detection:</B> Macintosh THINK-C provides
484
just 6K of memory for the stack. It might be worth adding
485
checks to make sure that the stack is not being blown.
487
<P><BR><FONT SIZE="4"><STRONG>Test Suite</STRONG></FONT><BR>
489
<P>The following tests should be added to the test suite:
495
LR01: Test with a full listing with no diagnostics.
496
LR02: Test with a full listing with diagnostics.
497
LR03: Test abbreviated listing with no diagnostics.
498
LR04: Test abbreviated listing with diagnostics.
499
LR05: Test error context with nearby diagnostics.
503
Static analysis might preclude the need for
505
BC01: Test what happens when memory runs out.
506
BC02: File with a single line of a megabyte.
507
BC03: File of a megabyte of EOLs.
508
BC04: Output file with an extremely long line.
509
BC05: Output file with one million lines.
510
BC06: Test on a file with very many macros.
514
GN01: A large legal input file exercising
515
as many features as possible.
516
1. Test listing file.
517
2. Test output files.
518
3. Test typeset file.
519
GN... A selection of ten real-life FunnelWeb files.
522
<P><BR><FONT SIZE="4"><STRONG>Platform-Specific Changes</STRONG></FONT><BR>
524
<P><B>Icon for the Macintosh:</B> Currently no icon
525
is supplied for the Macintosh version of FunnelWeb. An icon
526
depicting a spider or a funnelled web of some kind would
533
<TD ALIGN="left" VALIGN="bottom"><A HREF="misc_versions.html"><IMG SRC="binary/fw_left.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Prev"></A></TD>
534
<TD ALIGN="center" VALIGN="bottom"><A HREF="misc.html"><IMG SRC="binary/fw_up.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Up"></A></TD>
535
<TD ALIGN="right" VALIGN="bottom"><A HREF="misc_suggestions.html"><IMG SRC="binary/fw_right.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Next"></A></TD>
544
<A HREF="mailto:webmaster@ross.net">Webmaster</A>
545
<A HREF="copyright.html">Copyright © Ross N. Williams 1992,1999. All rights reserved.</A><BR>
556
<!-- *********************************************************************** -->
557
<!-- End Of A FunnelWeb Manual Web Page (www.ross.net/funnelweb/) -->
558
<!-- *********************************************************************** -->