%==============================================================================%
%                                 Start of Ch0.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.
%
%==============================================================================%

\vbox{\relax}
\vfill

\hrule

\medskip

Copyright \copyright{} 1992 Ross~N.~Williams.
\xn{Ross}{Williams}\xx{copyright}{notice}

Permission is granted to make and distribute verbatim copies of this manual
provided that the copyright notice and this permission notice are preserved
on all copies.\note{This paragraph was copied from the GNU Emacs manual to
avoid my having to get a legal opinion on something I could cook up.}

\medskip

\hrule

\newpage

%==============================================================================

\tableofcontents

\newpage

%==============================================================================

%I am not using LaTeX's figures and tables numbering so these are commented out.
%\pseudochapter{List of Figures}
%\pseudochapter{List of Tables}

%==============================================================================

% No forward.
%\pseudochapter{Foreword}
%\x{foreword}

%==============================================================================

\pseudochapter{Preface}
\x{preface}

When, in 1986, I first read Donald Knuth's\xn{Donald}{Knuth}
technical report on Web\paper{Knuth83},\x{Web} and
tried Web out, I was simultaneously excited by Knuth's idea of literate
programming, and disappointed by his implementation of it. I was excited
because I could sense the potential for
the literate style to transform the state of mind of the programmer, but was
disappointed by Web's rigidity
and lack of practicality, which seemed to betray this potential.
The Web I used was Pascal-specific, \TeX{}-specific, and applied too
many constraints to the programming process.
In particular, it insisted on taking control of the
program text, mangling the code in the Pascal output files,
and imposing its own rather rigid ideas about indenting in the \TeX{} output.
All this, combined with the complexity of the tool, led me
to come to perceive Web as problem rather than solution. 

Despite all this, I was well and truly hooked on the idea of literate
programming. The inevitable result was that I designed and implemented
my own version of Web --- FunnelWeb!

FunnelWeb is not the most sophisticated literate programming tool available,
but it is an extremely \i{practical} tool, striving for simplicity
and portability in all areas. Not only is FunnelWeb language-independent,
and to some extent typesetter independent, but its implementation also
stresses portability, being written in~C, and currently operating on four
major platforms (Sun, Vax, PC, Mac). FunnelWeb allows the
programmer total control over the output file, making it suitable
for use with all sorts of format-sensitive languages. It also allows
control over its own source code, which has been released under a
GNU license.\xx{GNU}{license}
FunnelWeb is quite solid, having to pass
a regression testing suite of over 200 tests
before being released. Finally, FunnelWeb is well documented by this manual
which provides a tutorial, advanced hints, and a language definition.

I would like to dedicate FunnelWeb and this manual to Donald Knuth
and his literate programming tool Web.
Although this manual is somewhat critical of some aspects of
Web, this criticism is really a product of differing design goals.
Knuth designed a paradigm (literate programming) and a tool
(Web) aimed at the highest pitch of program presentation and typesetting.
FunnelWeb aims lower, relaxing constraints, and making compromises
in order to achieve simplicity, flexibility, and portability.
The result is a practical tool which I hope will attract more people to
the literate style.

\bigskip

\leftline{\b{Ross~N.~Williams}}
\leftline{\b{Adelaide, Australia}}
\leftline{\b{May~1992}}

%==============================================================================

\pseudochapter{Acknowledgements}
\x{acknowledgements}

Many thanks to \b{David Hulse}\xn{David}{Hulse}
(\p{dave@cs.adelaide.edu.au}) for
translating the original version of FunnelWeb
(FunnelWeb~V1) from Ada\x{Ada} into~C
and getting it to work on Unix and a PC.
The C code written by David (FunnelWeb~V2) formed
the basis of FunnelWeb~V3, but was
entirely rewritten during the intensive refinement and feature-injection
period leading up to this release (FunnelWeb~V3 is about three times
the size of FunnelWeb~V2).
Nevertheless, without this important first translation step,
I would probably not have found the motivation to develop FunnelWeb to its
present state.

Thanks go to \b{Simon Hackett}\xn{Simon}{Hackett}
(\p{simon@internode.com.au}) of Internode Systems
Pty Ltd for the use of his Sun, Mac, and PC, for assistance in porting
FunnelWeb to the Sun and PC, and for helpful discussions.

Thanks go to \b{Jeremy Begg}\xn{Jeremy}{Begg}
(\p{jeremy@vsm.com.au}) of VSM Software Services
for the use of his VAX, and for assistance with the VMS-specific code.

Thanks to \b{Barry Dwyer}\xn{Barry}{Dwyer} (\p{dwyer@cs.adelaide.edu.au})
and \b{Roger Brissenden}\xn{Roger}{Brissenden} (\p{rjb@koala.harvard.edu})
for trying out FunnelWeb Version~1 in 1987 and providing valuable feedback.

Thanks to Donald Knuth\xn{Donald}{Knuth}
for establishing the idea of literate programming in the first place.

\bigskip

\leftline{\b{Ross~N.~Williams}}
\leftline{\b{Adelaide, Australia}}
\leftline{\b{May~1992}}

%==============================================================================

\pseudochapter{Presentation Notes}
\x{presentation notes}

\thing{References:} All references are set in bold and are
cited in square brackets in the form
\b{[}$<$\i{firstauthor}$><$\i{year}$>$\b{]}.
All references cited in the text appear in the reference list and the index.

\thing{Special terms:} New or important terminology has been set in bold
face and appears in the index. A glossary appears as an appendix.

\thing{Typesetting:} This\x{typesetting}
document was prepared by the author using Andrew
Trevorrow's\xn{Andrew}{Trevorrow} (\p{akt150@cscgpo.anu.edu.au})\checked{}
implementation (OzTeX\x{OzTeX}) of the
\TeX{}/\LaTeX{}\paper{Knuth84}\paper{Lamport86}\x{TeX}\x{LaTeX}
typesetting system running on a Macintosh-SE.\x{Macintosh}

\thing{Graphics:} All diagrams have been constructed out of text using
the \LaTeX{} \p{verbatim} environment so as to allow this document to
be disseminated electronically and printed using \LaTeX{} without access
to the author's drawing tools.

%%%%Put this paragraph back again if I insert any \fix footnotes again.
%\thing{Correction footnotes:} Footnotes\x{footnotes}
%commencing with dots ($\bullet$) are
%notes to remind the author about something in the document that must be
%attended to.\fix{This is an example of such a footnote.} These footnotes
%will be attended to and eliminated in later versions.

\thing{Known typesetting problems:} While every attempt has been made
to give a good presentation within the
time available, some shortcuts have had to be taken. In particular, the author
has
been unable to work out how to get \LaTeX{} to suppress blank pages at the
start of chapters.

%==============================================================================

% No abstract.
%\pseudochapter{Abstract}
%\x{abstract}

%==============================================================================%
%                                End of Ch0.tex                                %
%==============================================================================%
