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


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


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


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


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


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


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

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

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

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


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

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

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


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

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

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

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

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


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

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

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

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

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

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


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

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

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

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

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


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

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

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

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

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


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

%====================== End of FunnelWeb TeX Definitions =======================
EX12: This example gives some simple headings and demonstrates heading name
      inheritance.

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


\fwseca{1}{Feed the Penguins and Save the World}
\fwsecb{1.1}{Feed the Penguins}
\fwsecc{1.1.1}{Feed the little penguins}
\fwsecc{1.1.2}{Feed the big penguins}
\fwsecb{1.2}{Save the World}
\fwsecc{1.2.1}{Save Europe}
\fwsecc{1.2.2}{Save Africa}

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

\fwbeginmacro
\fwmacroname{Save the rest of the world}{2}\fwzero{}\fwequals \fwodef \fwbtx[...]fwetx=%
\fwcdef 
\fwbeginmacronotes
\fwusedin{This macro is NEVER invoked.}
\fwendmacronotes
\fwendmacro

\bye


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