summaryrefslogtreecommitdiff
path: root/web/funnelAC/hackman/h_ch4.tex
diff options
context:
space:
mode:
Diffstat (limited to 'web/funnelAC/hackman/h_ch4.tex')
-rw-r--r--web/funnelAC/hackman/h_ch4.tex401
1 files changed, 401 insertions, 0 deletions
diff --git a/web/funnelAC/hackman/h_ch4.tex b/web/funnelAC/hackman/h_ch4.tex
new file mode 100644
index 0000000000..b4df3706a8
--- /dev/null
+++ b/web/funnelAC/hackman/h_ch4.tex
@@ -0,0 +1,401 @@
+%==============================================================================%
+% Start of Ch4.tex %
+%==============================================================================%
+%
+% Copyright
+% ---------
+% Copyright (C) 1992 Ross N. Williams.
+% This file contains a chapter of the FunnelWeb Hacker's Manual.
+% See the main TeX file for this manual for further information.
+%
+%==============================================================================%
+
+\chapter{FunnelWeb Future}
+\label{chapfuture}\xx{FunnelWeb}{future}
+
+Previous chapters have explained the design of FunnelWeb and given reasons
+for why it is the way it is. This chapter goes through each of the
+aspects of FunnelWeb, and explores their problems, how they can be solved,
+and lists opportunities for improvement.
+
+\section{Documentation}
+\x{documentation}
+
+\thing{An official example:} A official example program written using
+FunnelWeb should be constructed and made available.\xx{official}{example}
+
+\thing{Index program:} In order to typeset the documentation, a portable
+index sorting program is required. One should be written and added to the
+distribution kit.\xx{index}{program} Perhaps this could be the official
+example!
+
+\section{Command Line Interface}
+\xx{command}{interface}
+
+\thing{Buffer length:} Currently the FunnelWeb shell uses the
+\p{COMLINE\_MAX} constant to size its internal command line buffers.
+This is untenable. The maximum length of a shell command line should
+not be machine dependent.
+
+\thing{Antiquated Features:} As the FunnelWeb language develops, it is likely
+that some changes will have to be made that will render one or more
+language constructs obsolete. When this happens, it may be necessary to
+add a command line option that has the power to turn on and off warnings or
+errors flagging antiquated features.\xx{antiquated}{features}
+
+\section{Shell Interpreter}
+\xx{shell}{interpreter}\xx{command}{interpreter}
+
+\thing{SETALL command:} When writing FunnelWeb scripts, it is sometimes
+desirable to set \i{all} of FunnelWeb's options\x{options}
+to some particular value
+so that the script is not vulnerable to changes in FunnelWeb's default
+values which might occur from time to time. To this end, it may be worth
+creating a \dqp{SETALL} command that is identical to the \dqp{SET} command
+except that it will generate an error if the value of an option is not
+specified explicitly.\xx{setall}{command}
+
+\thing{Recursion test:} A test should be added to test for recursive
+invocation in a shellscript.\xx{recursion}{test}
+
+\thing{Diagnostic counting:} The code for counting diagnostics in the
+script interpreter is rather messy and perhaps even buggy. It should be
+cleaned up and commented.\xx{diagnostic}{counting}
+
+\thing{Argument counting:} In the \p{command.c} module, there is a variable
+that counts the arguments to a command. Currently it takes the value of
+the number of parameters including the command verb. This has turned out
+to make the code less readable. It should be changed to be the number of
+arguments to the command verb.
+
+\thing{Make facility:} It may be worth building some sort of make facility
+into the script language so as to support machines such as the Macintosh
+that do not already have this facility.\x{make}
+
+\thing{Signature file:} One problem with using FunnelWeb in conjunction with
+an external \p{Make} facility is that a user might change a FunnelWeb source
+file without making changes that will affect the files that it generates.
+If FunnelWeb is then run and the \dqp{+D} option is on, then the output
+files will be deleted (to avoid further \p{Make} propagations).
+If \p{Make} then has a production linking the \p{.fw} file to its output
+files, then it may conclude that the output files are still out of date.
+To solve the problem, FunnelWeb could be changed to write a \p{.sig} file
+whenever it processes a \p{.fw} file. The \p{Make} production could then
+be wired up to link
+the \p{.fw} file to the \p{.sig} file instead of to the output
+files.\xx{signature}{file}
+
+\section{Language Design}
+\xx{language}{design}
+
+Some proposed changes to FunnelWeb do not correspond to
+any particular component of FunnelWeb
+and are really to do with the design of the input language.
+
+\thing{Output or file?:} The \dqp{@O} special sequence for defining an output
+file is somewhat non-mnemonic and can be confused with zero (\dqp{0}). Perhaps
+it should be replaced by the \dqp{@F} sequence.
+
+\thing{Syntax of section names:} Currently section names use
+the same syntax as macro names. For example \dqp{@<Sloth@>}. It can be
+argued that angle brackets should be reserved only for macro names and that
+some other syntax should be found for delimiting section names. This is not
+a clear issue. It could also be argued that they are both names, and that
+because sections can inherit their names from the macros they contain, that
+the names are of the same \dq{type}.\xx{section}{syntax}
+
+\thing{One macro per section:} One particular style of using FunnelWeb is
+to have at most one macro definition per section. It may be worth adding
+a pragma that instructs FunnelWeb to enforce this.
+
+\thing{Should @\{ suppress EOL?:} When defining a macro in FunnelWeb, it
+seems to be rule rather than the exception that the
+\dqp{@\{} be followed by \dqp{@-}. This suppresses the EOL on the definition
+line, allowing the first line of the macro to be placed immediately
+above and in line with the other
+lines without introducing an EOL at the start of the macro text.
+One option is to introduce a pragma to determine whether to suppress EOLs
+following \dqp{@\{}.
+
+\thing{Pragma syntax:} It is not clear how \dq{loose} the syntax of pragmas
+should be. Perhaps they should be case insensitive.\xx{pragma}{syntax}
+
+\thing{Conditionals:} Depending on demand, it may be worth reintroducing
+some sort of conditional feature into FunnelWeb. However, it would have to
+be very simple to compete with the various ways in which conditionals
+can already be fudged within FunnelWeb as it stands.\x{conditionals}
+
+\thing{File markers:} It might be worth modifying the language so that
+a special syntactical marker is required at the start and end of files.
+This will assist in detecting truncations and other
+corruptions.\xx{file}{markers}
+
+\thing{Formal parameter lists:} It might be worth changing over to a
+syntax for formal parameter lists that does not require the \p{@(} and
+\p{@)}. However, they could be retained as optional for backward
+compatibility.\xx{parameter list}{formal}
+
+\section{Scanner/Mapper}
+\x{scanner}\x{mapper}
+
+\thing{All non-contiguous mappings:} Currently FunnelWeb requires that all
+input files be mapped into a contiguous lump of memory. This caused problems
+for two reasons. First, to do this, one has to allocate the memory first,
+and to do that, you have to know how long the file is, and it turns out that
+finding out the length of a file in a portable manner is very inefficient.
+Second, although IBM PC compatibles may have megabytes of memory, it is
+segmented into blocks of at most 64K. This means that FunnelWeb currently
+cannot read a file longer than 64K on a PC.\xx{contiguous}{memory}
+
+These problems could be avoided if the mapper and scanner were reorganized to
+allow input files to be read in and stored as a linked list of chunks of text
+rather than a contiguous block.
+
+\thing{EOL is unspecifiable:} FunnelWeb uses ASCII character decimal ten (10)
+internally to represent logical end-of-line and is currently organized so that
+if one of these is inserted into the text by the user using a
+\dqp{@\circumflex{}D(10)}, it will be written out as a logical end of line,
+rather than as a single ASCII character 10. This should be
+fixed.\xx{representation}{EOL}
+
+\thing{Allow mnemonics for unprintables:} FunnelWeb allows users to insert
+unprintable characters into the output using the \dqp{@\circumflex{}D(ddd)}
+special sequence. Perhaps it would be changed so that it understands ASCII
+standard mnemonics such as \dqp{LF} as well as ASCII
+numbers.\xx{ASCII}{mnemonics}
+
+\thing{Version pragma:} A \dqp{version} pragma should be added that allows
+the user to specify in the input file the version of FunnelWeb that was
+around when the input file was created. At a later date, such a construct
+would be very useful for determining how an input file should be updated
+if the FunnelWeb language has changed between
+versions.\xx{version}{pragma}
+
+\section{Parser}
+\x{parser}
+
+There are no proposals to change the parser except as a consequence of
+other proposals.
+
+\section{Analyser}
+\x{analyser}
+
+\thing{Recursion detection:} Currently the FunnelWeb analyser flags, with
+an error, all macros with an infinite expansion. This would be best
+changed to flagging all macros that are directly or indirectly recursive.
+To do this, Tarjan's algorithm\paper{Tarjan72}\xn{Robert Endre}{Tarjan}
+for the detection of strong components should
+be installed.\xx{recursion}{detection}
+
+\thing{Once only macros:} By default FunnelWeb prevents a macro from being
+called more than once unless it has a \dqp{@M} associated with it. However,
+FunnelWeb does allow a macro that calls such a macro to be called more
+than once. Perhaps this \dq{loophole} should be plugged somehow.
+
+
+\section{Tangle}
+\x{tangle}
+
+The Tangler is one of the cleanest components of FunnelWeb, as basically all it
+has to do is expand some very well-defined macros.
+
+\thing{Text indentation:} Currently FunnelWeb supports \i{no indentation}
+and \i{blank indentation}. A third form could be added if it was considered
+necessary. \i{Text indentation} is the same as \i{blank indentation} except
+that instead of indenting with blanks, FunnelWeb would indent with the
+text to the left of the called macro. This facility could be useful for
+commenting out large bodies of text in languages that do not have
+multi-line comments (e.g. Ada). A discussion of the pros and cons of this
+form of indentation appears earlier.\xx{text}{indentation}
+
+\section{Weave}
+\x{weave}
+
+Perhaps FunnelWeb's weakest aspect is its typesetting facility.
+
+
+\thing{Align table of contents:} When FunnelWeb generates a table of contents,
+the section numbers are not quite aligned with the start of the controlling
+heading above them.\x{table of contents}
+
+\thing{Typesetting strength:} It should be possible to specify the
+level of typesetting strength for headings so that short documents do not
+look overdone when typeset. A new pragma would be good for
+this.\xx{strength}{typesetting}
+
+\thing{Typeset a portion:} Sometimes it is desirable to typeset just a
+portion of a program. A command line option could be added to do
+this. The option could accept as its argument, a string containing a list
+of section numbers or heading names.
+
+\thing{Generic typesetter option:} In addition to building in a number
+of different versions of Weave, one for each popular typesetter, it would be
+possible to add a special generic format where the typeset output is
+expressed in terms of \i{FunnelWeb macros}. The user could then specify
+macro definitions for a non-supported typesetter and run the output
+through FunnelWeb Tangle to get a typeset file in a format suitable for the
+unsupported typesetter.\xx{typesetter}{generic}
+
+\thing{Suppression of include files:} It should be possible to specify
+in the input file that particular included files not appear in the
+typeset output. Currently, the fact that an inclusion has occurred is
+not even represented in the typeset output. Suppression of inclusions
+is particularly necessary where a library of macros has been included
+at the top of each of a group of source files.\xx{include file}{suppression}
+
+\thing{Cross reference of identifiers:} WEB provides a list of identifiers
+and a list of all the definitions in which they are used. A similar
+feature could be added to FunnelWeb.\xx{cross}{references}
+
+\thing{Support for non-printables:} Currently FunnelWeb does not provide
+support for typesetting the special \dqp{@\circumflex(num)} sequences.
+This should be added.
+
+\thing{Support for @+ sequences:} Currently Weave does not see \dqp{@+}
+sequences as such. Instead it perceives them as ordinary EOLs. However,
+there are arguments for typesetting them specially.
+
+\thing{Typeset text in macro bodies:} One of the much-loved features
+of WEB is the way that it allows the user to switch recursively between
+document and program formats. FunnelWeb does not allow this, but
+should. In FunnelWeb, the delimiters \dqp{@\{} and \dqp{@\}} are already
+used consistently to delimit macro text. The \dqp{@[} and \dqp{@]} sequences
+have been reserved for the delimitation of documentation text.
+
+\thing{Non-tt typesetting:} The current version of FunnelWeb sets all its
+macro text in \p{tt font}. This is both a blessing and a curse. It is a
+blessing because it connects the reader directly to the code, with no
+complicated intermediary. It is a curse because it looks ugly compared to
+the beautifully typeset programs produced by other literate programming
+tools.
+
+The difficulty with adding such beautiful typesetting is that it is
+necessarily language-specific. Keywords and syntax differ from language
+to language and it would not be easy to come up with a set of language
+independent rules.
+
+One approach is to write a set of Weave back-ends, one for each language.
+Another approach is to \i{generate} back ends. This is the approach
+taken in the \i{Spider} system\paper{Ramsey89}.\x{spider}
+In the \i{Spider} system,
+the programmer writes production rules for converting lexical components
+of the program text into typesetter instructions. The \i{Spider} program
+reads these rules and generates a new version of WEB suited for the target
+language.
+
+For FunnelWeb a slightly different system is proposed in which Spider-like
+rules appear in the input file and are used directly by Weave to perform the
+typesetting. An intermediate abstract typesetting language could be used
+so that the productions can be made language specific, but not typesetter
+specific.
+
+\section{Lister}
+\x{lister}
+
+\thing{Glue factor:} A glue factor could be added that determines how many
+lines can be in between two diagnostics in the listing before the two
+groups of lines are joined together in the listing with no intervening
+ellipsis.\xx{glue}{factor}
+
+\section{Diagnostics}
+\x{diagnostics}
+
+\thing{Advisory information:} Some of FunnelWeb's diagnostics provide
+a detailed explanatory paragraph. While this information might be useful the
+first time, it has the capacity to clog up a listing file if the user has
+made the same error many times. To solve this problem, FunnelWeb could be
+modified so that such explanations are only displayed the first time the
+error occurs.
+
+\thing{Abort after n errors:} A facility could be added to prevent
+FunnelWeb's scanning, parsing, and analysing phases from continuing if
+a certain number of errors have already been issued.
+
+
+\section{Speed}
+\x{speed}\x{efficiency}
+
+\thing{Measurement of speed:} Although FunnelWeb can generate a breakdown
+of where it is spending its time, it does not give a final rating in
+lines per minute. This should be added.
+
+\thing{Find the hot spots:} Although FunnelWeb has been designed to allow
+high speed, not much effort has so far been made to make it fast. This should
+be done.
+
+\thing{Change some declarations:} FunnelWeb is full of variable declarations
+where the variables are wider than they need be. Replacing these might speed
+it up.
+
+\section{Correctness}
+\x{correctness}
+
+\thing{Bounds analysis:} Not much effort has gone into the design of
+FunnelWeb's input boundaries. An analysis should be made of FunnelWeb's
+behaviour when the following quantities are stretched:
+
+\begin{itemize}
+\item Input line length.
+\item Input file size.
+\item Number of macros.
+\item Length of macro.
+\end{itemize}
+
+In particular, FunnelWeb's behaviour at 32K and 64K boundaries should be
+observed.
+
+\thing{Stack detection:} Macintosh THINK-C provides just 6K of memory for
+the stack. It might be worth adding checks to make sure that the stack is
+not being blown.
+
+\section{Test Suite}
+\xx{test}{suite}
+
+The following tests should be added to the test suite:
+
+\begin{verbatim}
+Lister
+------
+ LR01: Test with a full listing with no diagnostics.
+ LR02: Test with a full listing with diagnostics.
+ LR03: Test with an abbreviated listing with no diagnostics.
+ LR04: Test with an abbreviated listing with diagnostics.
+ LR05: Test error context system with nearby diagnostics.
+
+Boundary Cases
+--------------
+Static analysis might preclude the need for most of these tests.
+ BC01: Test what happens when memory runs out.
+ BC02: Test on a file with a single line of a megabyte.
+ BC03: Test on a file of a megabyte of EOLs.
+ BC04: Generate an output file with an extremely long line.
+ BC05: Generate an output file with one million lines.
+ BC06: Test on a file with very many macros.
+
+General
+-------
+ GN01: A large legal input file exercising as many features as possible.
+ 1. Test listing file.
+ 2. Test output files.
+ 3. Test typeset file.
+ GN... A selection of ten real-life FunnelWeb files.
+\end{verbatim}
+
+\section{Machine-Specific Changes}
+
+\thing{Icon for the Macintosh:} Currently no icon is supplied for the
+Macintosh version of FunnelWeb. An icon depicting a spider or a funnelled
+web of some kind would seem appropriate.
+
+\section{Summary}
+
+This chapter has describes some of the problems with FunnelWeb and some of the
+opportunities that exist for improving it. The direction and speed in which
+FunnelWeb will develop will depend largely on user feedback. If you have any
+strong feelings on where FunnelWeb should go, please email them to
+Ross Williams (\p{ross@spam.adelaide.edu.au}).
+
+
+%==============================================================================%
+% Start of Ch4.tex %
+%==============================================================================%