%*******************************************************************************
%*                    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 =======================

\fwvskip{40}
\fwcenterline{\fwfonttitle{Powers:}}
\fwcenterline{\fwfonttitle{An Example of}}
\fwcenterline{\fwfonttitle{A Short}}
\fwcenterline{\fwfonttitle{FunnelWeb .fw File}}
\fwvskip{10}
\fwcenterline{\fwfontsmalltitle{by Ross Williams}}
\fwcenterline{\fwfontsmalltitle{26 January 1992}}
\fwvskip{20}

\fwtocstart{}
\fwtoca{1}{FunnelWeb Example Program}
\fwtocb{1.1}{ex16.out}
\fwtocb{1.2}{Pull in packages}
\fwtocb{1.3}{Write out the first p powers of i on a single line}
\fwtocfinish{}


\fwseca{1}{FunnelWeb Example Program}

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

\fwbeginmacro
\fwmacroname{Constants}{1}\fwequals \fwodef \fwbtx[n : constant natural := 10;     -- How many numbers? (Ans: [1,n]).
p : constant natural :=  5;     -- How many powers?  (Ans: [1,p]).]fwetx=%
\fwcdef 
\fwbeginmacronotes
\fwusedin{This macro is invoked in definition 2.}
\fwendmacronotes
\fwendmacro


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

\fwbeginmacro
\fwfilename{ex16.out}{2}\fwequals \fwodef \fwmacroname{Pull in packages}{3}\fwbtx[

procedure example is
   ]fwetx=%
\fwmacroname{Constants}{1}\fwbtx[
begin -- example
   for i in 1..n loop
      ]fwetx=%
\fwmacroname{Write out the first p powers of i on a single line}{4}\fwbtx[
   end loop;
end example;
]fwetx=%
\fwcdef 
\fwbeginmacronotes
\fwisafile{This macro is attached to an output file.}
\fwendmacronotes
\fwendmacro


\fwsecb{1.2}{Pull in packages} 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 (\fwlit{with text\_io}) and then
we need to make all its identifiers visible at the top level (\fwlit{use text\_io}).

\fwbeginmacro
\fwmacroname{Pull in packages}{3}\fwequals \fwodef \fwbtx[with text_io; use text_io;]fwetx=%
\fwcdef 
\fwbeginmacronotes
\fwusedin{This macro is invoked in definition 2.}
\fwendmacronotes
\fwendmacro


\fwsecb{1.3}{Write out the first p powers of i on a single line} Here is  the bit that writes out  the first \fwlit{p} powers of  \fwlit{i}. The power
values  are  calculated  incrementally  in  \fwlit{ip}  to  avoid  the  use  of  the
exponentiation operator.

\fwbeginmacro
\fwmacroname{Write out the first p powers of i on a single line}{4}\fwequals \fwodef \fwbtx[declare
   ip : natural := 1;
begin
   for power in 1..p loop
      ip:=ip*i;
      put(natural'image(ip) & " ");
   end loop;
   new_line;
end;]fwetx=%
\fwcdef 
\fwbeginmacronotes
\fwusedin{This macro is invoked in definition 2.}
\fwendmacronotes
\fwendmacro


\bye


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