~ubuntu-branches/ubuntu/quantal/funnelweb-doc/quantal

@!345678901234567890123456789012345678901234567890123456789012345678901234567890
@!******************************************************************************

@t vskip 50 mm
@t title titlefont centre "FunnelWeb Developer Manual Web"
@t vskip 10 mm
@t title smalltitlefont centre "by Ross N. Williams"
@t title smalltitlefont centre "21 April 1999"
@t vskip 10 mm
@t title smalltitlefont centre "Copyright (c) Ross N. Williams, 1992."
@t new_page
@t vskip 20 mm
@t title titlefont centre "Contents"
@t vskip 10 mm
@t table_of_contents
@t new_page

@!******************************************************************************
@!******************************************************************************

@A@<FunnelWeb Developer Manual Web@>

This document contains the FunnelWeb source for the
FunnelWeb Developer Manual web. When processed by the
FunnelWeb macro preprocessor, this file will generate all
the text files in the web.

@!******************************************************************************

@B@<Copyright Notice@>

This FunnelWeb source file and all works derived from it
(including, but not limited to, the output files and printed
documentation that can be extracted using the FunnelWeb
preprocessor) are copyright as shown below, and the
copyright message in the copyright macro applies to all of
these works. The enclosing macro is called at the start of
each FunnelWeb output file so that the copyright message
appears in each output file as well as in this FunnelWeb
source file.

@$@<Copyright notice/HTML@>@M@{@-
Copyright @<(C)@> Ross N. Williams 1992,1999. All rights reserved.@}

Permission is granted to redistribute and use this manual in
any medium, with or without modification, provided that all
notices (including, without limitation, the copyright
notice, this permission notice, any record of modification,
and all legal notices) are preserved on all copies, that all
modifications are clearly marked, and that modified versions
are not represented as the original version unless all the
modifications since the manual's original release by Ross N.
Williams (www.ross.net) consist of translations or other
transformations that alter only the manual's form, not its
content. THIS MANUAL IS PROVIDED "AS IS" AND WITHOUT ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT
LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND
FITNESS FOR A PARTICULAR PURPOSE. TO THE EXTENT PERMITTED BY
LAW THERE IS ABSOLUTELY NO WARRANTY.

@!******************************************************************************

@p maximum_input_line_length = 500
@p maximum_output_line_length = 500

@!******************************************************************************

@B@<Change Log@>

@$@<Change log@>@Z@{
21-Apr-1999 RNW Converted the original 1992 FunnelWeb hackers manual to this web.
12-May-1999 RNW Added versions page.
29-Dec-1999 RNW compile_compile: Minor fix *.o -> *.c
29-Dec-1999 RNW Added sidebar image strut to stop it collapsing.
30-Dec-1999 RNW Added misc_knownbugs page.
30-Dec-1999 RNW Revised the modify_manuals page.
30-Dec-1999 RNW Changed manual version number scheme.
03-Jan-2000 RNW Changed copyright permission notice.
03-Jan-2000 RNW Added indentation known bug notice.
06-Jan-2000 RNW Added black background table to sidebar to cope with no-images.
09-Jan-2000 RNW Moved main version notice into a macro in the fw include file.
@}

@!******************************************************************************

@B@<General Notes@>

@$@<General Information@>@Z@{
Checking Procedure
------------------
* Spelling check.
* WebLint check.

Shipping Procedure
------------------
* Use FunnelWeb to ENEO *.html
* Run FunnelWeb. Eliminate all warnings.
* Nuke the old web.
* Upload the new web.
* Briefly surf to check.
@}

FORMATTING NOTE: Experimentation has shown that any page containing a
VERBATIM wider than 55 characters must be set to /wide.

@!******************************************************************************

@B@<Things To Do@>

@$@<Things to do@>@Z@{
TTDList
-------

@}

@!******************************************************************************

@B@<Graphic Design Notes@>

These notes record the details of how the graphics in this web were created.
This will enable the graphics to be easily recreated, duplicated, or modified
if necessary.

@$@<Graphic Design Notes@>@Z@{
Sidebar is 50x1200 colour=(0,51,102).

Title
   Bookman Black SSi, 20pt, Antialias

@}

@!******************************************************************************

@B@<Conversion Of Printed Manual@>

The FunnelWeb documentation used to be embodied in a single printed manual
called The FunnelWeb User's Manual. Here's a record of how the material
in the manual ended up in the FunnelWeb documentation webs:

@$@<Printed Manual Conversion@>@Z@{
Printed User Manual Section     Where It Ended Up
---------------------------     -----------------
Preface                         DELETED
Acknowledgements                Copyright page of all FunnelWeb webs.
Presentation Notes              DELETED
1. A Tutorial Introduction      Tut: Chapters 1..4.
2. FunnelWeb Hints.             Tut: Chapter 5..6.
3. FunnelWeb Definition.        Ref: Most of the reference manual.
4. FunnelWeb Installation.      Mainweb,Dev
5. FunnelWeb Administration.    DELETED, but 5.2 => Main: stability
Glossary                        Ref: Glossary.
References                      Ref: References.

Printed Hacker Manual Section   Where It Ended Up
-----------------------------   -----------------
Preface                         Dev: Home page intro.
Acknowledgements                Copyright page of all FunnelWeb webs.
Presentation Notes              DELETED
1. FunnelWeb Design             Dev: Chapter 2.
2. FunnelWeb Implementation     Dev: Chapter 3.
3. FunnelWeb Modification       Dev: Chapter 4.
4. FunnelWeb Future             Dev: Chapter 5.
A. GNU Licence V2               Dev: Chapter 6.
References                      Ref: References.
@}

@!******************************************************************************
@!******************************************************************************

@B@<Parameter Macros@>

@$@<Body@>@M@{@-
<BODY BACKGROUND="@<Bin@>background.gif"
      BGCOLOR=@<White@>
      TEXT="#000000"
      VLINK="#660000"
      LINK="#FF0000"
      ALINK="#CC0000">@}

@$@<FunnelWeb WWW@>@Z@M@{../@}
@$@<FunnelWeb Reference WWW@>@Z@M@{../reference/@}
@$@<FunnelWeb Tutorial WWW@>@Z@M@{../tutorial/@}
@$@<FunnelWeb Developer WWW@>@Z@M@{@}

@!******************************************************************************

@B@<Page Macros@>

The following macros provide macros to set up the top and bottom of pages.

@!------------------------------------------------------------------------------

@$@<SideLink@>@(@2@)@Z@M@{<A HREF="@1"><FONT COLOR="#FFFFFF">@2</FONT></A>@<BR@>@}
@$@<SideLink/bold/target@>@(@3@)@M@{@<WindowLink@>@(@1@,@2@,<FONT COLOR="#FFFFFF"><B>@3</B></FONT>@)@<BR@>@}
@$@<SideLink/bold@>@(@2@)@M@{<A HREF="@1"><FONT COLOR="#FFFFFF"><B>@2</B></FONT></A>@<BR@>@}

@$@<Begin FWDevMan margin@>@M@{
<TABLE WIDTH="490">
<TR>
<TD WIDTH="130" VALIGN="top">
@<HStrut@>@(130@)@<BR@>

@<Sidebar menu@>

</TD>
<TD WIDTH="360" VALIGN="top">
@<Begin size3@>
@}

@$@<Begin FWDevMan margin/wide@>@M@{
<TABLE WIDTH="590">
<TR>
<TD WIDTH="130" VALIGN="top">
@<HStrut@>@(130@)@<BR@>

@<Sidebar menu@>

</TD>
<TD WIDTH="460" VALIGN="top">
@<Begin size3@>
@}

@$@<End FWDevMan margin@>@M@{
@<End size3@>
</TD>
</TR>
@<End table@>
@}

@$@<Sidebar menu@>@M@{@-
@<Begin size2@>
@<BR@>
@<RossNet linklogo IMAGE@>@<BR@>
@<BR@>
@<FunnelWeb linklogo IMAGE@>@<BR@>
@<BR@>
@<Begin tablecolour@>@(#000000@)
@<SideLink/bold/target@>@(@<FunnelWeb Reference WWW@>index.html@,@<FunnelWeb Reference WINDOWNAME@>@,Reference@)
@<BR@>
@<SideLink/bold/target@>@(@<FunnelWeb Tutorial WWW@>index.html@,@<FunnelWeb Tutorial WINDOWNAME@>@,Tutorial@)
@<BR@>
@<SideLink/bold@>@(@<FunnelWeb Developer WWW@>index.html@,Developer@)
@<SideLink@>@(@<Compile FILE@>@,@<Compile HEADING/short@>@)
@<SideLink@>@(@<Design FILE@>@,@<Design HEADING/short@>@)
@<SideLink@>@(@<Implement FILE@>@,@<Implement HEADING/short@>@)
@<SideLink@>@(@<Modify FILE@>@,@<Modify HEADING/short@>@)
@<SideLink@>@(@<Misc FILE@>@,@<Misc HEADING/short@>@)
@<SideLink@>@(@<GPL FILE@>@,@<GPL HEADING/short@>@)

@<BR@>
@<SideLink/bold@>@(@<FunnelWeb_search FILE@>@,SEARCH@)
@<End size2@>
@<End tablecolour@>
@}

@!------------------------------------------------------------------------------

@$@<Begin FWDevMan page/H1@>@(@1@)@Z@M@{@-
@<Doctype@>

<HTML>
@<Header comment@>
<HEAD>
<TITLE>@1</TITLE>
@<Suppress hyperlink underlining@>
</HEAD>
@<Body@>
@<Begin FWDevMan margin@>
@<RunningHeader IMAGE@>
@<FWDevMan heading@>@(@1@)
@}

@$@<Begin FWDevMan page/wide/H1@>@(@1@)@Z@M@{@-
@<Doctype@>

<HTML>
@<Header comment@>
<HEAD>
<TITLE>@1</TITLE>
@<Suppress hyperlink underlining@>
</HEAD>
@<Body@>
@<Begin FWDevMan margin/wide@>
@<RunningHeader IMAGE@>
@<FWDevMan heading@>@(@1@)
@}

@!------------------------------------------------------------------------------

@$@<End FWDevMan page@>@Z@M@{
@<P@>
@<HR@>
@<Begin size2@>
@<Link@>@(mailto:@<Ross webmaster EMAIL@>@,Webmaster@)@<_@>@<_@>@<_@>
<A HREF="@<Copyright FILE@>">@<Copyright notice/HTML@></A><BR>
@<End size2@>
@<End FWDevMan margin@>

</BODY>

@<Trailer comment@>
</HTML>@}

@!******************************************************************************

@B@<Images@>

@$@<RunningHeader IMAGE@>@M@{
<A HREF="@<FunnelWeb Developer WWW@>index.html"><IMG SRC="@<Bin@>title.gif"
 WIDTH="316" HEIGHT="24"
 BORDER="0" ALT="FunnelWeb Developer Manual"
 HSPACE="0" VSPACE="0"></A>@}

@!******************************************************************************

@B@<General Macros@>

@$@<FWDevMan heading@>@(@1@)@M@{@-
@<P@>@<Size5@>@(@1@)@<BR@>@}

@$@<FWDevMan subheading@>@(@1@)@M@{@-
@<P@>@<BR@>@<Size4@>@(@<B@>@(@1@)@)@<BR@>@}

@$@<FWDevMan subsubheading@>@(@1@)@Z@M@{@-
@<P@>@<BR@>@<Size3@>@(@<B@>@(@1@)@)@<BR@>@}

@$@<FWDevMan subsubsubheading@>@(@1@)@Z@M@{@-
@<P@>@<BR@>@<Size3@>@(@<U@>@(@1@)@)@<BR@>@}

@$@<FWDevMan heading/nospace@>@(@1@)@Z@M@{@-
@<Size4@>@(@<B@>@(@1@)@)@<BR@>@}

@$@<FWDevMan heading/center@>@(@1@)@Z@M@{@-
@<P@>@<BR@>
@<Begin center@>
@<Size5@>@(@<B@>@(@1@)@)@<BR@>
@<End center@>@}

@!******************************************************************************

@$@<FWDevMan keywords and decription@>@{
<META NAME="description"
 CONTENT="The FunnelWeb Developer Manual. FunnelWeb is a portable
          free literate programming tool.">

<META NAME="keywords"
 CONTENT="funnelweb,FunnelWeb,funnel,web,
          developer manual,developer,manual,
          literate programming,literate,programming,literate-programming,
          documentation,
          macro,macros,preprocessor,macro preprocessor,
          software,free,freeware,
          open source,open,source,gnu,gpl,copyleft,
          web,development,tool,web tool">
@}

@!******************************************************************************
@!******************************************************************************

@A@<HTML Pages@>

This section contains the HTML pages of the web.

@!******************************************************************************

@$@<Index HEADING@>@M@{FunnelWeb Developer Manual@}
@$@<Index FILE@>@M@{index.html@}
@O@<index.html@>@{@-
@<Doctype@>

<HTML>

<HEAD>
@<FWDevMan keywords and decription@>
@<Suppress hyperlink underlining@>
<TITLE>@<Index HEADING@></TITLE>
</HEAD>

@<Body@>

@<Begin FWDevMan margin@>

@<RunningHeader IMAGE@>

@<FunnelWeb manual version notice@>

@<P@>@<Bigger@>@(T@)HIS DEVELOPER MANUAL is for hackers!
Anyone who wants to bash, diddle, frob, grind, mangle,
patch, poke, toggle, twiddle, zap, or generally hack
FunnelWeb should at least take a look at this manual, as it
explains how to compile FunnelWeb, and contains all kinds of
other useful information about the FunnelWeb source code.

@<P@>
@<Begin size4@>
@<Begin indent@>

@<HeadStyle@>@(@<Compile FILE@>@,@<Compile HEADING@>@)
   @<Compile index@>

@<HeadStyle@>@(@<Design FILE@>@,@<Design HEADING@>@)
   @<Design index@>

@<HeadStyle@>@(@<Implement FILE@>@,@<Implement HEADING@>@)
   @<Implement index@>

@<HeadStyle@>@(@<Modify FILE@>@,@<Modify HEADING@>@)
   @<Modify index@>

@<HeadStyle@>@(@<Misc FILE@>@,@<Misc HEADING@>@)
   @<Misc index@>

@<HeadStyle@>@(@<GPL FILE@>@,@<GPL HEADING@>@)

@<End indent@>
@<End size4@>

@<End FWDevMan page@>
@}

@$@<HeadStyle@>@(@2@)@M@{@<P@><A HREF="@1"><B>@2</B></A><BR>@}

@!******************************************************************************

@$@<Compile HEADING@>@M@{@<SH@>@(1@)How To Compile FunnelWeb@}
@$@<Compile HEADING/short@>@M@{@<SH@>@(1@)Compile@}
@$@<Compile FILE@>@M@{compile.html@}
@O@<compile.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Compile HEADING@>@)

@<P@>

@<Compile index@>

@<Nav/first@>@(@<Index FILE@>@,@<Index FILE@>@,@<Design FILE@>@)

@<End FWDevMan page@>
@}

@$@<Compile index@>@M@{
@<Begin size3@>
@<Begin indent/narrow@>
@<Link@>@(@<Compile_resources FILE@>@,@<Compile_resources HEADING@>@)@<BR@>
@<Link@>@(@<Compile_ftp FILE@>@,@<Compile_ftp HEADING@>@)@<BR@>
@<Link@>@(@<Compile_tree FILE@>@,@<Compile_tree HEADING@>@)@<BR@>
@<Link@>@(@<Compile_compile FILE@>@,@<Compile_compile HEADING@>@)@<BR@>
@<Link@>@(@<Compile_testing FILE@>@,@<Compile_testing HEADING@>@)@<BR@>
@<End indent/narrow@>
@<End size3@>
@}

@!==============================================================================

@$@<Compile_resources HEADING@>@M@{@<SH@>@(1.1@)Resources Required@}
@$@<Compile_resources FILE@>@M@{compile_resources.html@}
@O@<compile_resources.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Compile_resources HEADING@>@)
@<XX@>@(FunnelWeb@,installation@)

@<P@>This chapter describes how to obtain and compile FunnelWeb
from scratch and set up for further development.
In order to compile FunnelWeb, you will need:

@<P@>
@<Begin list@>

@<Item@>FTP access to the internet @<I@>@(OR@) a
FunnelWeb source distribution kit on disk.

@<Item@>A computer running one of the
FunnelWeb-supported operating systems @<I@>@(OR@)
lots of extra time to port FunnelWeb to a new
platform.

@<Item@>About five megabytes of free disk space.

@<Item@>A C compiler.

@<Item@>An acquaintance with the C programming
language and the ability to compile and link C
programs on your machine.

@<Item@>Elementary systems programming knowledege
for your machine.

@<Item@>About an hour.

@<End list@>

@<P@>You will @<I@>@(not@) need any sort of system
privileges to install FunnelWeb, unless you want
the FunnelWeb command @<TT@>@(fw@) to be
automatically available to everyone on your
machine as well as yourself.

@<Nav/first@>@(@<Compile FILE@>@,@<Compile FILE@>@,@<Compile_ftp FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Compile_ftp HEADING@>@M@{@<SH@>@(1.2@)FTP The Source Files@}
@$@<Compile_ftp FILE@>@M@{compile_ftp.html@}
@O@<compile_ftp.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Compile_ftp HEADING@>@)
@<XX@>@(FunnelWeb@,obtaining@)@<XX@>@(ftp@,anonymous@)

@<P@>The first step is to obtain a copy of the FunnelWeb source
code and associated files. You can find FunnelWeb in the RossNet
FTP archive at:

@<P@>
@<Begin indent@>
@<URL@>@(@<FunnelWeb FTP@>@)
@<End indent@>

@<P@>It is not clear at the time of writing whether
FunnelWeb will be presented as a @<DQP@>@(.tar@) file, or as
a directory tree, or both. Just sniff around and use your
common sense.

@<Nav@>@(@<Compile_resources FILE@>@,@<Compile FILE@>@,@<Compile_tree FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Compile_tree HEADING@>@M@{@<SH@>@(1.3@)Establish The Source Tree@}
@$@<Compile_tree FILE@>@M@{compile_tree.html@}
@O@<compile_tree.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Compile_tree HEADING@>@)
@<XX@>@(directory@,tree@)

@<P@>At this stage, we will assume that you have
somehow obtained a set of files that are supposed
to be FunnelWeb, and that they are sitting on a
disk on the machine on which you wish to compile
FunnelWeb.

@<P@>The next thing you have to do is to make
sure that the FunnelWeb directory tree has been
correctly unpacked. The directory tree should look
like this.

@<P@>
@<Begin verbatim@>
   fwdir       - Root FunnelWeb directory.
      admin    - Administrative files.
      answers  - Answers to test suite.
      results  - For test results.
      scripts  - Test scripts.
      sources  - Source code.
      tests    - Test suite.
      web      - The FunnelWeb web.
@<End verbatim@>

@<P@>The following sections describe the contents
of each directory in alphabetical order. Check the
contents to make sure that you have everything. Do
not become fussed if your configuration is not
quite as specified, as it is very easy for
installation guides such as this one to go out of
date.

@<FWDevMan subheading@>@(Admin Directory@)
@<XX@>@(admin@,directory@)

@<P@>The @<TT@>@(admin@) directory contains
administrative files to do with licensing and
such. It is also a catch-all directory for files
that don't belong anywhere else. At the time of
writing, it is not clear exactly what will be in
the @<TT@>@(admin@) directory. Why not take a
look?

@<FWDevMan subheading@>@(Answers Directory@)
@<XX@>@(answers@,directory@)

@<P@>The @<TT@>@(answers@) directory contains the
@<DQ@>@(correct answers@)@<XX@>@(correct@,answers@) to all
the regression testing input files. The regression test
scripts compare these files to the files generated in the
@<TT@>@(results@) directory.

@<P@>
@<Begin verbatim@>
an01.lis ... an04.lis
ex01.lis ... ex16.lis
ex01.out ... ex10.out
ex11.tex ... ex16.tex
generate.lis
hi01.lis ... hi10.lis
hi01.out ... hi05.out
hi06a.out
hi06b.out
hi07a.out
hi07b.out
hi08.out ... hi10.out
pr01.lis ... pr10.lis
sc01.lis ... sc29.lis
tg01.lis ... tg09.lis
tg01.out ... tg09.out
wv01.lis ... wv06.lis
wv01.tex ... wv06.tex
@<End verbatim@>

@<FWDevMan subheading@>@(Results Directory@)
@<XX@>@(results@,directory@)

@<P@>The @<TT@>@(results@) directory exists as a target
directory for the output files generated by FunnelWeb during
regression testing. This directory is distributed empty and
should be empty at the start of regression testing. However,
it is permissible for the @<TT@>@(results@) directory to
contain files generated during a previous test run, as the
regression testing scripts delete specific unwanted files
before each test anyway.

@<FWDevMan subheading@>@(Scripts Directory@)
@<XX@>@(scripts@,directory@)

@<P@>The @<TT@>@(scripts@) directory stores the FunnelWeb
command shell scripts that are used to perform regression
testing.@<XX@>@(regression@,testing@)

@<P@>
@<Begin verbatim@>
master.fws    - The master test script.
test_gen.fws  - Script to generate tricky input files.
test_l.fws    - Test FunnelWeb with +L.
test_ld.fws   - Test FunnelWeb with +L +B...
test_lo.fws   - Test FunnelWeb with +L +O.
test_lo2.fws  - Test FunnelWeb with +L +O (2 outfiles).
test_lot.fws  - Test FunnelWeb with +L +O +T.
test_lt.fws   - Test FunnelWeb with +L +T.
@<End verbatim@>

@<FWDevMan subheading@>@(Sources Directory@)
@<XX@>@(sources@,directory@)

@<P@>The @<TT@>@(sources@) directory contains @<I@>@(all@)
of the C source files required to build a FunnelWeb binary
executable. In the following list, files given without an
extension represent both @<TT@>@(.c@) and @<TT@>@(.h@)
files.

@<Begin verbatim@>
analyse       - The analyser.
as            - Assertions.
clock         - A clock abstraction.
command       - The shell command interpreter.
data          - Shared data structures and global vars.
dump          - Dump internal data structures.
environ.h     - Machine-dependent, program-ind header.
help          - Module to write out help messages.
help_gnu      - Function to write out the GNU license.
help_gnu.txt  - The GNU license in text form.
help_gnu.ctx  - The GNU license in C code form.
list          - A list abstraction.
lister        - Module to manage the listing file.
machin        - Module to hold machine-dependent,
                program-dependent stuff.
main.c        - The main() program.
mapper        - Module to read files into memory.
memory        - Memory management.
misc          - Miscellaneous functions.
option        - Command line option processing.
parser        - The parser.
scanner       - The scanner.
section       - A section number abstraction.
style.h       - A machine-independent,
                program-independent header file.
table         - A table abstraction.
tangle        - The tangler.
texhead       - Module to write out TeX header
                in documentation files.
texhead.ctx   - The TeX header in C code form.
texhead.tex   - The TeX header in TeX form.
weave         - The weaver.
writfile      - Output abstraction.
@<End verbatim@>

@<P@>The @<DQP@>@(.txt@), and @<DQP@>@(.tex@) files do not
participate in the compilation, but are considered part of
the source code as they were used to generate the
@<DQP@>@(.ctx@) files. The @<DQP@>@(.ctx@) files are
included by @<TT@>@(.c@) files of the same name. They do not
need to be compiled themselves.

@<FWDevMan subheading@>@(Tests Directory@)
@<XX@>@(tests@,directory@)

@<P@>The @<TT@>@(tests@) directory stores all the input
files of the regression test suite. These come in two kinds:
FunnelWeb input files with extensions of @<DQP@>@(.fw@), and
FunnelWeb include files with extensions of @<DQP@>@(.fwi@).

@<P@>
@<Begin verbatim@>
FunnelWeb Input Files:
   an01.fw ... an04.fw  - Analyser tests.
   ex01.fw ... ex16.fw  - Examples from the tut man.
   generate.fw          - Generates tricky input files.
   hi01.fw ... hi10.fw  - Examples from hints.
   pr01.fw ... pr10.fw  - Parser tests.
   sc01_note.fw         - Explains absence of sc01.fw
   sc02.fw ... sc29.fw  - Scanner tests.
   tg01.fw ... tg09.fw  - Tangler tests.
   wv01.fw ... wv06.fw  - Weaver tests.

FunnelWeb Include Files:
   ex09a.fwi
   sc13a.fwi ... sc13f.fwi
   sc15a.fwi
   tg08a.fwi
@<End verbatim@>

@<FWDevMan subheading@>@(Web Directory@)
@<XX@>@(web@,directory@)

@<P@>This directory is for the FunnelWeb webs if you want to
keep a copy on your local disk so you can surf it quickly.

@<Nav@>@(@<Compile_ftp FILE@>@,@<Compile FILE@>@,@<Compile_compile FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Compile_compile HEADING@>@M@{@<SH@>@(1.4@)Compiling FunnelWeb@}
@$@<Compile_compile FILE@>@M@{compile_compile.html@}
@O@<compile_compile.html@>@{@-
@<Begin FWDevMan page/wide/H1@>@(@<Compile_compile HEADING@>@)
@<XX@>@(compiling@,FunnelWeb@)

@<P@>The FunnelWeb source code is entirely contained within
the @<TT@>@(sources@) directory. However, some simple script
files and makefiles can be found in the @<TT@>@(admin@)
directory.

@<P@>There should be little difficulty compiling FunnelWeb
for any of the currently supported platforms. If the machine
on which you are compiling FunnelWeb is not one of the ones
listed in the @<TT@>@(environ.h@) file, then choose the
closest one you can. FunnelWeb contains some
machine-dependent components, so if you are compiling for a
currently-unsupported platform, you will probably need to go
into the modules @<TT@>@(environ.h@), @<TT@>@(machin.h@) and
@<TT@>@(machin.c@) and make some changes.

@<P@>Compile
FunnelWeb by pointing your C compiler at all the
@<DQP@>@(.c@) files in the @<TT@>@(sources@) directory. The
@<DQP@>@(.txt@), and @<DQP@>@(.tex@) files do not
participate in the compilation, but appear in the
@<TT@>@(sources@) directory because they were used to
generate the @<DQP@>@(.ctx@) files. The @<DQP@>@(.ctx@)
files are included by @<TT@>@(.c@) files of the same name
and do not need to be compiled separately. Link the results.

@<P@>
@<Begin verbatim@>
   cc -c *.c
   cc -o fw *.o
@<End verbatim@>

@<P@>The result of all this should be a binary executable
called @<TT@>@(fw@), or @<TT@>@(fw.exe@), or
@<TT@>@(fw.xxx@) where @<TT@>@(.xxx@) is whatever file
extension is appropriate on the target machine. Clean up the
@<TT@>@(sources@) directory by deleting all the listing and
object files.

@<P@>If you encounter any difficulties compiling FunnelWeb, you
may wish to refer to the platform-specific notes below.

@<P@>If you port FunnelWeb to a new platform, please @<email me@>
any information that I can incorporate into the next
release, or add here to help others porting to the same
platform.

@<FWDevMan subheading@>@(A Make File@)

@<P@>The FunnelWeb distribution does not provide a makefile
as compilers are so fast now that the risk of omitting a
dependency far exceeds the benefits provided by a makefile
for a program this size.

@<P@>However, some people have complained about the lack of
a makefile, and in fact Dougal Scott
(@<Email@>@(dwagon@@nella9.cc.monash.edu.au@))
actually sent me one which he constructed using the GNU C -MM
option. Here it is:

@<P@>
@<Begin verbatim/size2@>
------------------------SLICE and DICE here---------------------------------
OBJS= analyse.o as.o clock.o command.o data.o dump.o help.o help_gnu.o list.o \
      lister.o machin.o mapper.o memory.o misc.o option.o parser.o scanner.o \
      section.o table.o tangle.o texhead.o weave.o writfile.o main.o
HDRS= analyse.h as.h clock.h command.h data.h dump.h environ.h help.h \
      help_gnu.h list.h lister.h machin.h mapper.h memory.h misc.h option.h \
      parser.h scanner.h section.h style.h table.h tangle.h texhead.h weave.h \
      writfile.h
CC=gcc
CFLAGS=-O -Wall

all: fw

fw: $(OBJS)
        $(CC) -o fw $(OBJS)

analyse.o : analyse.c style.h environ.h analyse.h as.h data.h clock.h list.h \
  table.h option.h machin.h help.h section.h writfile.h lister.h misc.h
as.o : as.c style.h environ.h as.h machin.h
clock.o : clock.c style.h environ.h as.h clock.h machin.h
command.o : command.c style.h environ.h analyse.h as.h command.h machin.h data.h \
  clock.h list.h table.h option.h help.h section.h writfile.h dump.h lister.h \
  memory.h mapper.h misc.h parser.h scanner.h tangle.h weave.h
data.o : data.c data.h style.h environ.h clock.h list.h table.h option.h machin.h \
  help.h section.h writfile.h
dump.o : dump.c style.h environ.h as.h clock.h data.h list.h table.h option.h \
  machin.h help.h section.h writfile.h dump.h misc.h
help.o : help.c style.h environ.h as.h help.h help_gnu.h misc.h data.h clock.h \
  list.h table.h option.h machin.h section.h writfile.h
help_gnu.o : help_gnu.c style.h environ.h help_gnu.h help_gnu.ctx
list.o : list.c style.h environ.h as.h machin.h memory.h list.h
lister.o : lister.c style.h environ.h as.h data.h clock.h list.h table.h option.h \
  machin.h help.h section.h writfile.h lister.h misc.h
machin.o : machin.c style.h environ.h as.h machin.h
main.o : main.c style.h environ.h as.h command.h machin.h data.h clock.h list.h \
  table.h option.h help.h section.h writfile.h memory.h
mapper.o : mapper.c style.h environ.h as.h machin.h mapper.h memory.h
memory.o : memory.c style.h environ.h as.h machin.h memory.h
misc.o : misc.c style.h environ.h as.h data.h clock.h list.h table.h option.h \
  machin.h help.h section.h writfile.h memory.h misc.h
option.o : option.c style.h environ.h as.h data.h clock.h list.h table.h option.h \
  machin.h help.h section.h writfile.h misc.h
parser.o : parser.c style.h environ.h as.h data.h clock.h list.h table.h option.h \
  machin.h help.h section.h writfile.h lister.h mapper.h memory.h misc.h parser.h
scanner.o : scanner.c style.h environ.h as.h clock.h data.h list.h table.h option.h \
  machin.h help.h section.h writfile.h dump.h lister.h mapper.h memory.h misc.h \
  scanner.h
section.o : section.c style.h environ.h as.h section.h
table.o : table.c style.h environ.h as.h machin.h memory.h table.h
tangle.o : tangle.c style.h environ.h as.h data.h clock.h list.h table.h option.h \
  machin.h help.h section.h writfile.h lister.h memory.h misc.h tangle.h
texhead.o : texhead.c style.h environ.h texhead.h writfile.h texhead.ctx
weave.o : weave.c style.h environ.h as.h data.h clock.h list.h table.h option.h \
  machin.h help.h section.h writfile.h lister.h misc.h texhead.h weave.h
writfile.o : writfile.c style.h environ.h as.h machin.h writfile.h
------------------------SLICE and DICE here---------------------------------
@<End verbatim/size2@>

@<FWDevMan subheading@>@(Apollo@)

@<P@>16-Oct-1992: David Barton (@<Email@>@(dlb@@hudson.wash.inmet.com@))
reports that he has managed to compile FunnelWeb on an Apollo running
Domain/OS SR10.2.

@<FWDevMan subheading@>@(HP-UX@)

@<P@>15-Oct-1992: On an HP 9000/s300 running HP-UX 8.0, some
users got FunnelWeb to compile, but found that they were
running up against buffer size limitations. The problem is
the definition of FILENAME_MAX in machin.h. When I wrote
FunnelWeb, I assumed that FILENAME_MAX was the maximum
length of an entire file specification including the path.
However, on many machines, it is defined the be the maximum
length of a filename without the path. The problem can be
fixed by forcing the definition

@<P@>
@<Begin verbatim@>
   #define FILENAME_MAX 300
@<End verbatim@>

@<P@>in machin.h. This is the only known problem encountered
by those who have performed HP ports.

@<FWDevMan subheading@>@(Macintosh MPW C@)

@<P@>09-Aug-1992: Tor Olaussen (@<Email@>@(olaussen@@cc.uib.no@))
of the Nansen Remote Sensing Center, University of Bergen,
Norway reports that he has managed to get FunnelWeb to
compile and run under the Macintosh MPW environment. He
writes:

@<P@>
@<Begin verbatim@>
"If you are interested in my changes, I should be able to generate
diff files, and send them to you together with a makefile. Otherwise
you can use me a reference if you receive questions about FunnelWeb
and MPW."
@<End verbatim@>

@<FWDevMan subheading@>@(Next@)

@<P@>16-Oct-1992: John Dawson (@<Email@>@(avsoft!john@@cs.utexas.edu@))
has installed FunnelWeb on a NeXT machine and has got it to pass
the regression tests. He writes:

@<P@>
@<Begin verbatim@>
   "I had to play with the machin.{h,m} and environ.h files to get
   FunnelWeb to compile correctly.  The problem area was in machin.h
   where you put all those prototypes for the Sun.  They didn't jive
   well with my system.  However, every other default for the Sun was
   ok.  (A NeXT only needs to be aligned on 2^1-byte boundaries, and
   I think 2^0-byte boundaries might even work, but aligning things on
   2^2-byte boundaries doesn't hurt much.)."
@<End verbatim@>

@<P@>The modified header files are available in the file:

@<P@>
@<Begin indent@>
@<URL@>@(@<FunnelWeb FTP@>funnelweb300/funnelweb300_next_patch.c@)
@<End indent@>

@<FWDevMan subheading@>@(MS-DOS@)

@<P@>09-Oct-1992: In the lead up to the release of FunnelWeb 3.0,
the PC that had been
available for me to use to test the port of FW to the PC became
unavailable. Because of this, I took the shortcut of not compiling and
testing the final released version of the code (V3.0) on a PC!!! Worse
still, I did not provide any notes on what compiler flags should be
used.

@<P@>As a result, those who have attempted to compile FunnelWeb on PCs ran
into a few difficulties.

@<P@>If you still want to compile FunnelWeb on the PC, here are
some notes that I have collected:

@<P@>Most people who compile FunnelWeb on a PC seem to be using Borland
C++. If you are using this compiler, you need to do the following:

@<Begin list@>
@<Item@>Insert "#define STDC 1" in environ.h.
@<Item@>Compile with the HUGE memory model.
@<Item@>Turn on the ANSI option.
@<Item@>Turn on the BorlandC++ option.
@<Item@>Increase the run time stack size from 4K (default) to 32K
     by inserting the line:
     @<TT@>@(extern unsigned _stklen = 32768;@)
     just above the minimain() declaration.  Refer to page 608
     of the borland library reference manual (V3.00).
@<End list@>

@<P@>You may run into troubles with MSDOS with the regression
test input file "sc13a" which is a zero length file. It is
just a zero length file so if you run into difficulties,
create it any way you like.

@<Nav@>@(@<Compile_tree FILE@>@,@<Compile FILE@>@,@<Compile_testing FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Compile_testing HEADING@>@M@{@<SH@>@(1.5@)Testing FunnelWeb@}
@$@<Compile_testing FILE@>@M@{compile_testing.html@}
@O@<compile_testing.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Compile_testing HEADING@>@)
@<XX@>@(testing@,FunnelWeb@)

@<P@>Once you have obtained a binary executable, you should
test FunnelWeb before using it or making it available to
users. FunnelWeb comes with a comprehensive regression test
suite. Here's how to use it:

@<P@>
@<Begin list/ordered@>

@<Item@>Set the default directory to be the
@<TT@>@(scripts@) directory.

@<Item@>If you are on a Macintosh, copy the FunnelWeb
executable into the scripts directory.

@<Item@>Edit the script @<TT@>@(master.fws@). Locate the
section called @<DQ@>@(Define Symbol For the Root Test
Directory@) and define the @<TT@>@(R@) symbol to point to
the FunnelWeb root directory @<TT@>@(fwdir@). The examples
in the comments in the script should make it clear what is
required.

@<Item@>Invoke FunnelWeb to execute the master test script
with the command line @<TT@>@(fw +xmaster@)

@<End list/ordered@>

@<P@>The @<TT@>@(master.fws@) script should run for a minute
or two. If all goes well, you will find a differences report
on your screen reporting zero differences. If this happens,
then FunnelWeb has been fully tested and is ready to be made
available to users. You should delete all the files in the
@<TT@>@(results@) directory.

@<P@>If you run into any problems, please write a short
report describing the problem and mail it to me
(@<Ross Williams@> (@<Email@>@(@<Ross personal EMAIL@>@))). I may
not be able to help you with it immediately, but I certainly
want to know that a problem exists, so that it can be
corrected in future releases of FunnelWeb.

@<Nav/last@>@(@<Compile_compile FILE@>@,@<Compile FILE@>@,@<Compile FILE@>@)

@<End FWDevMan page@>
@}

@!******************************************************************************

@$@<Design HEADING@>@M@{@<SH@>@(2@)FunnelWeb Design Notes@}
@$@<Design HEADING/short@>@M@{@<SH@>@(2@)Design@}
@$@<Design FILE@>@M@{design.html@}
@O@<design.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Design HEADING@>@)

@<P@>

@<Design index@>

@<Nav@>@(@<Compile FILE@>@,@<Index FILE@>@,@<Implement FILE@>@)

@<End FWDevMan page@>
@}

@$@<Design index@>@M@{
@<Begin size3@>
@<Begin indent/narrow@>
@<Link@>@(@<Design_introduction FILE@>@,@<Design_introduction HEADING@>@)@<BR@>
@<Link@>@(@<Design_motivation FILE@>@,@<Design_motivation HEADING@>@)@<BR@>
@<Link@>@(@<Design_indentation FILE@>@,@<Design_indentation HEADING@>@)@<BR@>
@<Link@>@(@<Design_syntax FILE@>@,@<Design_syntax HEADING@>@)@<BR@>
@<Link@>@(@<Design_structure FILE@>@,@<Design_structure HEADING@>@)@<BR@>
@<Link@>@(@<Design_testing FILE@>@,@<Design_testing HEADING@>@)@<BR@>
@<Link@>@(@<Design_filenames FILE@>@,@<Design_filenames HEADING@>@)@<BR@>
@<Link@>@(@<Design_numinst FILE@>@,@<Design_numinst HEADING@>@)@<BR@>
@<Link@>@(@<Design_docmac FILE@>@,@<Design_docmac HEADING@>@)@<BR@>
@<Link@>@(@<Design_diagnostics FILE@>@,@<Design_diagnostics HEADING@>@)@<BR@>
@<End indent/narrow@>
@<End size3@>
@}

@!==============================================================================

@$@<Design_introduction HEADING@>@M@{@<SH@>@(2.1@)Introduction@}
@$@<Design_introduction FILE@>@M@{design_introduction.html@}
@O@<design_introduction.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Design_introduction HEADING@>@)
@<XX@>@(FunnelWeb@,design@)

@<P@>This chapter contains notes on the design of FunnelWeb.
These notes are mostly the result of a complete design
review that occurred in late 1991 as part of the process of
preparing FunnelWeb V3.0 for public release.

@<P@>Throughout the FunnelWeb design process I have tried to
stick to the principles of simplicity and clarity. As a
rule, it was considered more important that a feature be
simple, and not allow the user to outsmart himself, than it
was for the feature to be elegant. For example, the
FunnelWeb macro calling syntax is not as clean as the C
preprocessor syntax, but is simpler and more visible, and so
is less likely to cause trouble.

@<Nav/first@>@(@<Design FILE@>@,@<Design FILE@>@,@<Design_motivation FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Design_motivation HEADING@>@M@{@<SH@>@(2.2@)Motivation For FunnelWeb@}
@$@<Design_motivation FILE@>@M@{design_motivation.html@}
@O@<design_motivation.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Design_motivation HEADING@>@)
@<XX@>@(FunnelWeb@,motivation@)

@<P@>During 1986, I discovered Donald
Knuth's@<XN@>@(Donald@,Knuth@) @<TT@>@(WEB@) literate
programming system in the form of Jon
Bentley's@<XN@>@(Jon@,Bentley@) @<I@>@(Programming
Pearls@)@<X@>@(programming pearls@) column in
@<I@>@(Communications@<X@>@(Communications of the ACM@) of
the ACM@) @<Paper@>@(Bentley86@). This  prompted me to
obtain  a copy of the report on the Web
system@<Paper@>@(Knuth83@) and to try out the WEB program.

@<P@>WEB was  the best system that I had seen  for producing
printed and online, inline  documentation. To me the most
extraordinary aspect of the  system was its success despite
the fact that it had been built into the horribly antiquated
file/batch processing systems that we all know  and love
(and use). I had imagined sophisticated documentation
systems before this time, but had always assumed that they
would be parts of complex programming environments. Knuth
showed that, to some extent, it can be done using 1960s
software technology (excluding the 1980s typesetting
technology).

@<P@>The WEB  system was  enticing and promising,  but to me
suffered  from many drawbacks, many of which Knuth had
categorized as advantages. The following highly subjective list
of disadvantages formed  a springboard for the construction
of FunnelWeb.

@<Begin list@>

@<Item@>WEB can only process Pascal@<X@>@(Pascal@) programs.

@<Item@>WEB can produce only one output file. In many
instances it is desirable to generate  more than one output
file.@<XX@>@(number@,output files@)

@<Item@>WEB  enforces  Knuth's  individual style  of
indentation.  WEB  supplies commands to over-ride  the
automatic indentation, but it is  an uphill battle and the
code becomes clogged up with format
directives.@<X@>@(indentation@)

@<Item@>WEB  does not cater for  non-standard Pascal
programs. In  particular, all identifiers are truncated to
about eight characters.

@<Item@>WEB  formats the  program output file  into a form
that is  unreadable to humans.

@<Item@>WEB does  not  provide an include facility. This
was considered a feature essential for supporting macro
libraries.

@<Item@>WEB provides macros with at most one parameter.
Knuth describes a hack that can extract a multiple parameter
macro facility  from a single parameter one, but it is
hardly satisfactory.

@<Item@>WEB does not provide conditionals.

@<End list@>

@<P@>Most  of these  objections boiled  down  to two points:
that WEB  is far  too specialized, and that Knuth's
@<DQ@>@(Occam's Razor@)@<X@>@(Occam's razor@) had cut too
far. What I wanted was a documentation system that employed
all the same principles as WEB but was far more  general.
The  result  was FunnelWeb@<_@>V1 which could process
programs in any language or any combination of languages at
the cost of setting the text in @<TT@>@(tt font@) instead
of typesetting it in a language-specific way, as WEB does.

@<P@>Originally, it  was intended that  FunnelWeb would be
typesetter  independent as well as language independent. It
was intended that a format file consisting of a set of
productions describing how the document file was to be
formatted would be handed to FunnelWeb along with the input
file. However, time pressures forced me to take the back
door and hack up a TeX document file generator. In version
3.2 an HTML generator was added.

@<Nav@>@(@<Design_introduction FILE@>@,@<Design FILE@>@,@<Design_indentation FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Design_indentation HEADING@>@M@{@<SH@>@(2.3@)Indentation@}
@$@<Design_indentation FILE@>@M@{design_indentation.html@}
@O@<design_indentation.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Design_indentation HEADING@>@)
@<X@>@(indentation@)@<XX@>@(indentation@,no@)
@<XX@>@(indentation@,blank@)@<XX@>@(indentation@,text@)

@<P@>How should FunnelWeb insert the text of macros that are
not called in column one? A macro call that does not appear
at the left margin is called an @<NewTerm@>@(indented macro
call@) and suggests three different alternatives for
its expansion: @<NewTerm@>@(no indentation@),
@<NewTerm@>@(blank indentation@), and @<NewTerm@>@(text
indentation@). Here are examples of each kind of
indentation. First the example problem.

@<P@>
@<Begin verbatim@>
@@$@@@<<@>Sloth@@@<>@>==@@{@@-
Aardvark
Walrus@@}

@@O@@@<<@>Output@@@<>@>==@@{@@-
Zebra@@@<<@>Sloth@@@<>@>
Giraffe
@@}
@<End verbatim@>


@<P@>There are three ways that the second line of the
@<TT@>@(Sloth@) macro can be indented in the product file.

@<P@>
@<B@>@(No indentation:@)
@<Begin verbatim@>
     ZebraAardvark
     Walrus
     Giraffe
@<End verbatim@>

@<P@>
@<B@>@(Blank indentation:@)
@<Begin verbatim@>
     ZebraAardvark
          Walrus
     Giraffe
@<End verbatim@>

@<P@>
@<B@>@(Text indentation:@)
@<Begin verbatim@>
     ZebraAardvark
     ZebraWalrus
     Giraffe
@<End verbatim@>

@<P@>No indentation is useful where the user wishes to view
the output as a pure byte stream. Blank
indentation is useful when the user wishes to generate
indented computer programs. Text indentation is useful where
the user wishes to prefix each line of an entire macro
invocation with a string. This can be useful for commenting
out code (@<eg@>in Ada using @<TT@>@(--@)), and for
prepending constructs such as a dollar sign at the start of each
line in an OpenVMS DCL script command file.@<X@>@(DCL@)

@<P@>The design questions are as follows:

@<P@>
@<Begin list/ordered@>
@<Item@>Which of the three kinds of indentation should FunnelWeb support?
@<Item@>What should be the granularity of swapping between indentation modes?
@<Item@>Are particular indentation modes dangerous?
@<Item@>Is the presence of particular combinations of indentation modes
        confusing to the user?
@<Item@>How and when should the choice of indentation be specified?
@<End list/ordered@>

@<P@>After a lot of thought, it was decided that the factor
that should determine the design is the @<I@>@(clarity@) in
the user's mind of the indentation facility, and the
@<I@>@(danger@) associated with misunderstanding it. Here
are two examples that show how easily a misunderstanding about
the indentation model can cause a serious semantic error:

@<P@>
@<Begin verbatim@>
--Misuse of blank (and no) indentation.
--@@@<<@>Sloth@@@<>@>
@<End verbatim@>

@<P@>In this first example, the user has assumed that text
indentation is in action and has placed an Ada comment
symbol @<DQP@>@(--@) before the invocation of the macro
@<TT@>@(@@@<<@>Sloth@@@<>@>@) in the expectation that every
line in the expansion of the macro will be prefixed by
@<DQP@>@(--@). Unfortunately, if no-indentation or
blank-indentation is active, only the first statement of the
expansion of macro @<TT@>@(@@@<<@>Sloth@@@<>@>@) will be
commented out.

@<P@>
@<Begin verbatim@>
--Misuse of text indentation:
a++; @@@<<@>Sloth@@@<>@>
@<End verbatim@>

@<P@>In this second example, the user has assumed
no-indentation or blank-indentation and has placed the call
to @<TT@>@(@@@<<@>Sloth@@@<>@>@) after the incrementing of
variable @<TT@>@(a@). Under a text-indentation mode, this
will result in the statement @<DQP@>@(a++;@) appearing at
the start of each line in the macro expansion!

@<P@>These examples show that confusion about the
indentation model could cause a serious semantic problem in
a program written using FunnelWeb. In particular, the
examples above pose a dilemma because they are symmetric.
One cannot simply pin the blame on one particular
indentation form. A little thought reveals that the greatest
danger lies in @<I@>@(confusion@) in the user's mind. If the
user is confused between text or blank indenting, problems
will arise.

@<P@>There seems to be two ways to solve the problem. The
first is to ban all macro calls that are preceded by
non-blank text. This is not a good option because there are
so many cases where it is desirable to expand more than one
single line macro on the same line. A second option is to
eliminate one of the two forms so as to reduce the potential
for confusion in the user's mind. I choose the latter
option. Of the three forms, the clear choice for elimination
is text indenting for the following reasons:

@<P@>
@<Begin list/ordered@>
@<Item@>It actually introduces extra text which gives it an a priori
        potential for problems.
@<Item@>It is harder to implement and would slow down Tangle.
@<End list/ordered@>

@<P@>The only other decision is the level of granularity of
choice between the remaining options: no indentation and
blank indentation. FunnelWeb@<_@>V1 allowed this choice to
be made in the command line, but this was a bad choice
because it made the user responsible for a portion of the
file's semantics. A better system, used in FunnelWeb@<_@>V3,
is to allow the user to specify the indentation mode in the
input file itself.

@<P@>Again, to avoid confusion, it seems sensible to allow
the user only one indentation mode per FunnelWeb input file.
In most cases, the user will be happy with blank indentation
(the default) and there will be no need for change anyway.

@<Boldthing@>@(Decision:@) Implement only @<DQ@>@(no
indentation@) and @<DQ@>@(blank indentation@). Make the
choice of indentation a static attribute of a particular
FunnelWeb run that is specified in the input file.

@<Nav@>@(@<Design_motivation FILE@>@,@<Design FILE@>@,@<Design_syntax FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Design_syntax HEADING@>@M@{@<SH@>@(2.4@)A Review Of FunnelWeb Syntax@}
@$@<Design_syntax FILE@>@M@{design_syntax.html@}
@O@<design_syntax.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Design_syntax HEADING@>@)
@<XX@>@(FunnelWeb@,syntax@)

@<P@>One of the disadvantages of FunnelWeb is its
clumsy macro definition and calling syntax. Compared to
(say) the C preprocessor, FunnelWeb's macro call syntax is
like a freight train in a china shop. Unfortunately, all
attempts to convert this syntax to something more elgant
have failed, because the existing syntax is the simplest
from a conceptual point of view and is the least likely
to cause semantic confusion. This page discusses and
justifies the FunnelWeb syntax.

@<FWDevMan subheading@>@(Macro Definition Syntax@)
@<XX@>@(macro definition@,syntax@)

@<P@>FunnelWeb's macro definition syntax results in
definitions that look like this:

@<P@>@<Begin verbatim@>
@@$@@@<<@>Put out the cat@@@<>@>==@@{@@-
Open the door
Say out
Close the door@@}
@<End verbatim@>

@<P@>Here's why this syntax was chosen:

@<Narrowthing@>@(Dollars:@,The @<TT@>@(@@$@) is necessary to cue a
definition. Without it, the definition might somehow be
mistaken for an invocation.@)

@<Narrowthing@>@(Name delimiters:@, The @<TT@>@(@@@<<@>@) and
@<TT@>@(@@@<>@>@) are required to delimit the name and to
resonate syntactically with macro calls.@)

@<Narrowthing@>@(Content delimiters:@, The @<TT@>@(@@{@) and
@<TT@>@(@@}@) delimit the content of the macro.@)

@<Narrowthing@>@(EOL suppressor:@,The @<TT@>@(@@-@) is a
result of the simplifying rule that the content of a macro
is @<DQ@>@(exactly the text between the
@<TT@>@(@@{@) and @<TT@>@(@@}@).@)@)

@<P@>The only real target for a syntax purge the
@<DQP@>@(==@) which is optional anyway.

@<P@>An alternative minimalist approach to macro definitions
is:

@<P@>@<Begin verbatim@>
@@@<<@>Put out the cat@@@<>@>
Open the door
Say out
Close the door@@}
@<End verbatim@>

@<P@>but this is too dangerous for my tastes as there
is no syntax surrounding the name of the macro to
indicate that it is a macro definition and not a macro
call.

@<FWDevMan subheading@>@(Parameterized Macro Definition Syntax@)

@<P@>The definitions of parameterized macros are even messier
than the normal definitions.

@<P@>@<Begin verbatim@>
@@$@@@<<@>Put out the cat@@@<>@>@@(@@3@@)==@@{@@-
Open the door
Say out
Close the door@@}
@<End verbatim@>

This is messy, but the @<DQ@>@(natural@) alternative is even worse:

@<P@>@<Begin verbatim@>
@@$@@@<<@>Put out the cat@@@<>@>@@(@@1@@,@@2@@,@@3@@)==@@{@@-
Open the door
Say out
Close the door@@}
@<End verbatim@>

@<P@>Given that the parameters don't have names, it seems cleaner
just to specify the number of parameters.
pecifying the number of parameters seems sensible.

@<FWDevMan subheading@>@(Macro Call Syntax@)
@<XX@>@(macro call@,syntax@)

@<P@>Here are some syntaxes that were considered for
FunnelWeb macro calls.

@<P@>
@<Begin verbatim@>
Open the door
@@@<<@>Say Out@@@<>@>         @@! Current style.
Close the door

Open the door
@@@<<@>Say out@<>@>@@
Close the door

Open the door
@@"Say out@@"
Close the door

Open the door
@@(Say out@@)
Close the door

Open the door
@@@<<@>Say out@<>@>
Close the door
@<End verbatim@>

@<P@>Of these, the first was chosen.

@<FWDevMan subheading@>@(Parameterized Macro Call Syntax@)
@<XX@>@(parameterized macro call@,syntax@)

@<P@>FunnelWeb@<_@>V1 provided a messy parameterized macro
call syntax:

@<P@>@<Begin verbatim@>
@@@<<@>Say Out@@@<>@>@@(@@"firstparam@@"  @@,
   @@"Secondparam@@" @@,
   @@"thirdparam@@" @@)
@<End verbatim@>

@<P@>This syntax was cleaned up considerably in V3.0 by making
the @<TT@>@(@@"@) symbols optional:

@<P@>@<Begin verbatim@>
@@@<<@>Say Out@@@<>@>@@(firstparam@@,@@-
Secondparam@@,thirdparam@@)
@<End verbatim@>

@<Nav@>@(@<Design_indentation FILE@>@,@<Design FILE@>@,@<Design_structure FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Design_structure HEADING@>@M@{@<SH@>@(2.5@)Document Structuring@}
@$@<Design_structure FILE@>@M@{design_structure.html@}
@O@<design_structure.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Design_structure HEADING@>@)

@<P@>Knuth's WEB system provided just two levels of headings,
and this scheme was used in FunnelWeb@<_@>V1. However, experience
showed that there was a need for more levels. Here are some
syntaxes that were considered for implementing this:

@<P@>@<Begin verbatim@>
@@*@@@<<@>Main Program@@@<>@>
@@**@@@<<@>Read the Message@@@<>@>
@@***@@@<<@>Encrypt the Buffer@@@<>@>

@@*@@@<<@>Main Program@@@<>@>
@@*@@*@@@<<@>Read the Message@@@<>@>
@@*@@*@@*@@@<<@>Encrypt the Buffer@@@<>@>

@@s@@@<<@>Main Program@@@<>@>
@@ss@@@<<@>Read the Message@@@<>@>
@@sss@@@<<@>Encrypt the Buffer@@@<>@>

@@s@@@<<@>Main Program@@@<>@>
@@s@@s@@@<<@>Read the Message@@@<>@>
@@s@@s@@s@@@<<@>Encrypt the Buffer@@@<>@>

@@S@@@<<@>Main Program@@@<>@>
@@SS@@@<<@>Read the Message@@@<>@>
@@SSS@@@<<@>Encrypt the Buffer@@@<>@>

@@S@@@<<@>Main Program@@@<>@>
@@S@@S@@@<<@>Read the Message@@@<>@>
@@S@@S@@S@@@<<@>Encrypt the Buffer@@@<>@>

@@1@@@<<@>Main Program@@@<>@>
@@2@@@<<@>Read the Message@@@<>@>
@@3@@@<<@>Encrypt the Buffer@@@<>@>
(using @@A..@@I@@ as macro
 parameters or overload @@1..@@9)

@@*@@1@@@<<@>Main Program@@@<>@>
@@*@@2@@@<<@>Read the Message@@@<>@>
@@*@@3@@@<<@>Encrypt the Buffer@@@<>@>
(using @@A..@@I@@ as macro parameters
 or overload @@1..@@9)

@@A Main Program
@@B Read the Message
@@C Encrypt the Buffer

@@*A Main Program
@@*B Read the Message
@@*C Encrypt the Buffer

The following is the syntax finally chosen.
@@A@@@<<@>Main Program@@@<>@>
@@B@@@<<@>Read the Message@@@<>@>
@@C@@@<<@>Encrypt the Buffer@@@<>@>
@<End verbatim@>

@<P@>Choosing between these alternatives was not easy. The
following thoughts contributed to the decision.

@<P@>
@<Begin list@>

@<Item@>Syntaxes that require visual counting are probably
not a good idea.

@<Item@>Syntaxes that do not delimit the heading name
somehow are likely to cause problems where heading names are
omitted. Users will be tempted to start paragraphs after the
start of heading symbol, and the result is that the first
line of the paragraph will be sucked into the heading.

@<Item@>Overloading the @<TT@>@(@@1@), @<LDots@>,
@<TT@>@(@@9@) sequences is undesirable.

@<End list@>

@<P@>For these reasons, the following syntax was chosen:

@<P@>
@<Begin verbatim@>
@@A@@@<<@>Main Program@@@<>@>
@@B@@@<<@>Read the Message@@@<>@>
@@C@@@<<@>Encrypt the Buffer@@@<>@>
@@D@@@<<@>Encrypt the Buffer@@@<>@>
@@E@@@<<@>Encrypt the Buffer@@@<>@>
@<End verbatim@>

@<P@>A maximum of five levels was chosen because it's
probably sufficient, and @<TT@>@(@@F@) should be reserved
for @<B@>@(F@)ile.

@<Nav@>@(@<Design_syntax FILE@>@,@<Design FILE@>@,@<Design_testing FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Design_testing HEADING@>@M@{@<SH@>@(2.7@)Automated Regression Testing@}
@$@<Design_testing FILE@>@M@{design_testing.html@}
@O@<design_testing.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Design_testing HEADING@>@)
@<XX@>@(regression@,testing@)

@<P@>Automated regression testing is extremely important for
several reasons:

@<P@> @<Begin list/ordered@>

@<Item@>It allows portability problems to be pinpointed
when the program is moved to a new machine.

@<Item@>It provides confidence that changes made to the
program have not introduced bugs.

@<Item@>It provides ongoing confidence in the integrity
of FunnelWeb as a programming tool.

@<Item@>It provides a practical confirmation of the semantics
of FunnelWeb.

@<End list/ordered@>

@<P@>The simplest way to set up automated regression testing
is to construct a suite of test cases, each of which
consists of a test input file and a @<DQ@>@(correct answer@)
output file. To test FunnelWeb, the input files are
processed and the resulting output files compared with the
correct answer output files.

@<P@>To automate such a list of tests, some kind of
scripting language is required. Unfortunately, at the time
of writing FunnelWeb (at least), there was no scripting
language that was available on all the platforms to which
FunnelWeb had to be ported (Macintosh, IBM-PC, Sun, and
OpenVMS). So, after some thought, I decided that the best
solution to the problem was to create a command language
@<I@>@(within FunnelWeb@) that could be used as a framework
for the automation of the testing of the rest of FunnelWeb.

@<P@>The resultant scripting language is described in the
@<FunnelWeb Reference Manual@>.

@<Nav@>@(@<Design_structure FILE@>@,@<Design FILE@>@,@<Design_filenames FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Design_filenames HEADING@>@M@{@<SH@>@(2.8@)File Name Management@}
@$@<Design_filenames FILE@>@M@{design_filenames.html@}
@O@<design_filenames.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Design_filenames HEADING@>@)
@<XX@>@(file@,names@)

@<P@>File names present a host of problems for a program
like FunnelWeb. First, FunnelWeb can generate so many
different kinds of files that conventions must be adopted to
prevent their names from colliding. Second, the
constraints on file names, and even the structure of file
names themselves varies considerably from machine to
machine. These two problems have combined to result in the
sophisticated and rather complicated way in which
FunnelWeb handles filenames.

@<P@>To summarize, the three problems are:

@<P@>
@<Begin list/ordered@>
@<Item@>What filename extensions should be chosen for various kinds of file?
@<Item@>What filename inheritance should take place?
@<Item@>How should FunnelWeb cope with the variations in filename structure
        between platforms?
@<End list/ordered@>

@<P@>These problems are addressed in the following sections.

@<FWDevMan subheading@>@(Filename Extensions@)
@<XX@>@(filename@,extensions@)

@<P@>FunnelWeb is capable of reading and writing a variety
of different kinds of files. In particular, FunnelWeb must
often operate in an environment where the same information
is stored in many forms (@<eg@>prog.fw, prog.c, proc.exe).
File extensions are an essential tool in managing this
situation. The default filename extensions chosen for
FunnelWeb are:

@<P@>
@<Begin verbatim@>
FunnelWeb     : .fw
Product       : None
Documentation : .tex or .html
Listing       : .lis
Journal       : .jrn
@<End verbatim@>

@<P@>Lowercase will be used in systems that are case
sensitive.

@<FWDevMan subheading@>@(Filename Inheritance@)
@<XX@>@(filename@,inheritance@)

@<P@>Inheritance in filenames refers to how input and output
files inherit parts of their name from other filenames and
their environment. For example if the command

@<P@>
@<Begin verbatim@>
   fw sloth +J +L +T
@<End verbatim@>

@<P@>were issued, you would expect to see output files
@<TT@>@(sloth.jrn@), @<TT@>@(sloth.lis@), and
@<TT@>@(sloth.tex@). The output file names have inherited
the @<DQP@>@(sloth@) part of the argument. In fact,
FunnelWeb implements a comprehensive filename inheritance
scheme, which is shown in the following table. Each filename
is built up by starting at the top of its column in the
table and working down the column, inheriting filename
fields (directory, name, extension) that are absent at that
point.

@<P@>
@<Begin center@>
@<Begin table/border@>
@<Row8@>@(@<_@>@, @<B@>@(Script@)     @, @<B@>@(Input@)     @,  @<B@>@(Include@)   @,  @<B@>@(Journal@)   @,  @<B@>@(List@)      @,  @<B@>@(Document@)  @, @<B@>@(Product@) @)
@<Row8@>@(1 @, @<_@>       @, @<_@>      @, @<TT@>@(@@i@)     @, @<_@>       @, @<_@>     @,  @<_@>     @, @<TT@>@(@@o@)  @)
@<Row8@>@(2 @, @<TT@>@(+x@)     @, @<TT@>@(+f@)    @, @<TT@>@(+i@)     @, @<TT@>@(+j@)     @, @<TT@>@(+l@)     @, @<TT@>@(+t@)     @, @<TT@>@(+o@)  @)
@<Row8@>@(3 @, @<DQP@>@(.fws@) @, @<DQP@>@(.fw@) @, @<DQP@>@(.fwi@) @, @<DQP@>@(.jrn@) @, @<DQP@>@(.lis@) @, @<DQP@>@(.tex@) @,  @<_@>    @)
@<Row8@>@(4 @, @<_@>       @,  @<_@>     @, @<TT@>@(+f@)     @, @<TT@>@(+f@)     @, @<TT@>@(+f@)     @, @<TT@>@(+f@)     @,   @<_@>   @)
@<Row8@>@(5 @, DefDir     @, Defdir    @, Defdir     @, Defdir     @, Defdir     @, Defdir     @, Defdir  @)
@<End table@>
@<End center@>

@<P@>The following notes explain the table.

@<P@>@<Begin list/ordered@>

@<Item@>Level@<_@>1 has the highest priority because it is a
direct specification by the user.

@<Item@>Level@<_@>2 comes next because this is also a direct
specification from the user on the command line.

@<Item@>Level@<_@>3 provides the default file extensions.
Product files do not inherit an extension.

@<Item@>Level@<_@>5 is built into most operating systems'
file specification systems. If you specify file
@<DQP@>@(x.y@), it is taken to mean on the default disk in
the default directory.

@<Item@>Level@<_@>4 looks straightforward, but secretly
conceals a difficult design decision. By the time we get
down to this level of inheritance, we know for sure that the
filename has already picked up a file extension. So all that
is left to inherit is the path and the filename proper.
Obviously we have to inherit the filename proper (e.g.
@<TT@>@(sloth@) in @<TT@>@(sloth.tex@)), but should we
inherit the input file path? If we do inherit the input file
path, files will be placed in the same directory as the
input file. If we don't inherit the input file path, files
will be placed in the current directory. The choice made is
to send all the logging type files into the same directory
as the input file. This means, for example, that
@<TT@>@(sloth.lis@) and @<TT@>@(sloth.tex@) will generally
land in the same directory as @<TT@>@(sloth.fw@). However,
product files are sent to the default directory (if not
earlier specified), as this is where the action is. In
normal use, the main output of FunnelWeb will be product
files, and so the user will expect them to appear in the
current directory by default.

@<End list/ordered@>

@<FWDevMan subheading@>@(Portable Structure of File Names@)
@<XX@>@(file@,names@)@<XX@>@(portable@,filenames@)

@<P@>Another problem with file names is the variation of
their structure between environments. Here are examples of
some of the formats that prevail:

@<P@>
@<Begin verbatim@>
   UNIX   /device/dir1/dir2/name
   VMS    node::device:[dir1.dir2]name.ext;vn
   MSDOS  device:\dir1\dir2\name.ext
   MAC    device:dir1:dir2:name
@<End verbatim@>

@<P@>The solution to dealing with these different formats is
to classify them as non-portable and hide the functions that
manipulate them in the machine-specific module of FunnelWeb.
Luckily there are not many such functions.

@<P@>The main problem is coping with file systems that do
not explicitly support file extensions. With so many
possible input and output files, FunnelWeb all but needs
such extensions. Machines that do not support them pose
difficult design decisions. If the user specifies
@<DQP@>@(sloth@) as an input file on such a
non-extension-supporting system, should FunnelWeb look for
@<TT@>@(sloth@) or @<TT@>@(sloth.fw@)? If the user specifies
@<TT@>@(walrus@) as a listing file, should it generate
@<TT@>@(walrus@) or @<TT@>@(walrus.lis@)?

@<P@>Some possible solutions are:

@<Begin list/ordered@>

@<Item@>Regard the filename @<TT@>@(sloth@) as having an
empty extension. It will then default to @<TT@>@(sloth.fw@).

@<Item@>Regard the filename @<TT@>@(sloth@) as having a
blank but full extension. That is, it cannot be overwritten
by inheritance, but it remains blank.

@<Item@>Provide an extra syntactic mechanism to allow the
user to specify one or other of the two options above.

@<End list/ordered@>

@<P@>The solution adopted in FunnelWeb is the first option.
Use of FunnelWeb results in lots of files lying around
(@<eg@>@<TT@>@(sloth.lis@)) and it is hard to see how the
user will cope with them all without some kind of naming
discipline. If a naming discipline has to be used, it might
as well be the FunnelWeb one.

@<P@>Thus the names of all files read and written by
FunnelWeb will have a file extension of from zero to three
letters separated from the rest of the filename by a
@<DQP@>@(.@).

@<P@>The only exception is product files, whose extension is
left undefined. Product files need not contain a
@<DQP@>@(.@) and a file extension.

@<Nav@>@(@<Design_testing FILE@>@,@<Design FILE@>@,@<Design_numinst FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Design_numinst HEADING@>@M@{@<SH@>@(2.9@)Constraints On The Number of Instantiations@}
@$@<Design_numinst FILE@>@M@{design_numinst.html@}
@O@<design_numinst.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Design_numinst HEADING@>@)
@<XX@>@(invocations@,number@)

@<P@>Experience with FunnelWeb@<_@>V1 demonstrated the need
to be able to specify in each macro definitions how many times
the macro was expected to be called. FunnelWeb@<_@>V1
generated an error if a macro is not used, but permited
macros to be called more than once. This caused problems for
macro libraries, many of whose macros were not called.

@<P@>By default, FunnelWeb@<_@>V3.0 requires that each macro
(except for the ones attached to output files) be called
exactly once. However, it also provides syntax that allows
you to specify that a macro be allowed to be called
zero times or many times. This allows a macro to be
specified with the following permissible ranges of numbers
of calls depending on the presence or absence of
@<DQP@>@(@@Z@) and @<DQP@>@(@@M@):

@<P@>
@<Begin verbatim@>
   0..1          @@$@@@<<@>Sloth@@@<>@>@@Z...
      1          @@$@@@<<@>Sloth@@@<>@>...
      1..n       @@$@@@<<@>Sloth@@@<>@>@@M...
   0.....n       @@$@@@<<@>Sloth@@@<>@>@@Z@@M...
@<End verbatim@>

@<P@>The initial proposal for this syntax was to allow the
user to insert zero, one, or both of @<TT@>@(@@?@) and
@<TT@>@(@@M@) just after the @<TT@>@(@@$@) of a macro
definition. Here are some other ideas that were considered
for the syntax of the calling number constraint.

@<P@>
@<Begin verbatim@>
@@?@@M@@$@@@<<@>Slothy dogs@@@<>@>@@(@@5@@)==@@{@@-
This is a short macro.
With only a line or two@@}

@@$@@@<<@>Slothy dogs@@@<>@>@@?@@M@@(@@5@@)==@@{@@-
This is a short macro.
With only a line or two@@}

@@$@@@<<@>Slothy dogs@@@<>@>@@(@@5@@)@@?@@M==@@{@@-
This is a short macro.
With only a line or two@@
@<End verbatim@>

@<P@>The first form was rejected because it is a good visual
rule to start all the macros with @<TT@>@(@@$@). The second
form was rejected because it detaches the macro name from
the parameter list, thus making it look less like a call,
which is a desirable syntactic resonance. The third form is
messy, but was adopted with the change that @<TT@>@(@@?@)
was changed to @<TT@>@(@@M@).

@<P@>After some thought, it was decided that the third
syntax was the best, but that the @<DQP@>@(@@?@) sequence be
reserved for a possible future conditional facility. It was
replaced by @<TT@>@(@@Z@).

@<P@>Example of final syntax:

@<P@>
@<Begin verbatim@>
@@$@@@<<@>Slothy dogs@@@<>@>@@(@@5@@)@@Z@@M+=@@{@@-
This is a short macro.
With only a line or two@@}
@<End verbatim@>

@<Nav@>@(@<Design_filenames FILE@>@,@<Design FILE@>@,@<Design_docmac FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Design_docmac HEADING@>@M@{@<SH@>@(2.10@)Document Structure Vs Macro Structure@}
@$@<Design_docmac FILE@>@M@{design_docmac.html@}
@O@<design_docmac.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Design_docmac HEADING@>@)
@<XX@>@(document structure@,macro structure@)
@<XX@>@(document@,structure@)@<XX@>@(macro@,structure@)
@<XX@>@(hierarchical@,structure@)

@<P@>Once the decision was made to adopt five levels of
headings as a document structure, the next issue was to
decide how this document structure would relate to the macro
structure. The issues to be addressed were as follows:

@<P@>
@<Begin list@>
@<Item@>How should the hierarchical structure connect to the macro structure?
@<Item@>How can backwards compatibility be achieved? Should it?
@<Item@>Should the macros be cross referenced by section or by definition?
@<Item@>Should nameless sections inherit macro names as headings?
@<Item@>Should TeX macros be used to structure the document?
@<End list@>

@<P@>This page contains some thoughts on these issues:

@<FWDevMan subheading@>@(TeX File Document Basis@)

@<P@>One idea is to make the
FunnelWeb input file an actual TeX @<TT@>@(.tex@) file
which is directly typesettable, and use FunnelWeb to
extract code from the TeX file to generate the product files.
This approach was rejected because it is too typesetter
dependent. Instead, the separate FunnelWeb format was adopted.

@<FWDevMan subheading@>@(Hierarchical Heading Numbering@)

@<P@>WEB and FunnelWeb@<_@>V1 used two levels of section
headings, but numbered them all sequentially. This is
unacceptable in a fully hierarchical document which should
have hierarchical section numbers such as 3.2.4. So
FunnelWeb@<_@>V3 uses hierarchical numbering for its
headings in the documentation file.

While hierarchical numbering@<XX@>@(section@,numbering@) is
good for headings, it is messy and confusing when applied to
macro names. In FunnelWeb@<_@>V1's typeset output, each
macro call has appended in square brackets the number of the
section in which the macro is defined. However, hierarchical
numbering would be somewhat messy. For example, in the
typeset documentation, a macro call might look like.

@<P@>@<Begin verbatim@>
   Write out the output[6.7.4.3]
@<End verbatim@>

@<P@>Similarly, cross reference lists would be messy:

@<P@>
@<Begin verbatim@>
   This macro is used in 3.4.5, 1.2, 7.8.9, 7.4, 2.2.1.1.
@<End verbatim@>

@<P@>These problems were solved by numbering headings
hierarchically and numbering the macros sequentially
and independently.

@<FWDevMan subheading@>@(Input Format Matters Most@)

@<P@>In terms of legacy commitment, the critical issue is
not how FunnelWeb formats programs for printing, but how the
FunnelWeb @<TT@>@(.fw@) input file should be formatted. The
typeset output can always be changed simply by fiddling with
FunnelWeb's Weave module. However, as soon as the input
syntax is defined, it will be used in dozens or hundreds of
documents and it will be very difficult indeed to change it.
Therefore, the important thing is to provide as sensible and
expressive a @<TT@>@(.fw@) format as possible.

@<P@>Thus, the issue of how to number headings and macros
in the typeset documentation is not a serious architectural
issue.

@<FWDevMan subheading@>@(Naming Sections@)

@<P@>How should sections be named? In many cases (especially
in the case of high-level sections) the writer will provide
an explicit name for a section. In other cases, provision of
such a name will merely duplicate the name of the macro
contained within the section. It therefore makes sense to
allow the user to omit the name from a section, allowing Weave
to name the section after the first macro definition in the
section. If a macro is unnamed and there is no macro in the
section, an error can be generated.

@<FWDevMan subheading@>@(Summary@)

@<P@>All these thoughts lead to the following scheme:

@<P@>
@<Begin list@>
@<Item@>Documents will be hierarchically structured using @<TT@>@(@@A@), @<TT@>@(@@B@) etc.
@<Item@>Each section can be given a name @<TT@>@(@@@<<@>@<LDots@>@<>@>@).
@<Item@>Sections that do not have names inherit the name of their first macro.
@<Item@>If a section does not have a name or a macro, it is erroneous.
@<Item@>Sections will be numbered hierarchically either by FunnelWeb or by TeX.
@<Item@>Macro body parts will be numbered sequentially by FunnelWeb and cross
  referenced by these numbers.
@<End list@>

@<P@>All this results in a system which:

@<P@>
@<Begin list@>

@<Item@>Provides a hierarchical document structuring capability.
@<Item@>Is typesetter independent.
@<Item@>Does not require duplication between heading and macro names.
@<Item@>Separates the heading and macro systems so that Weave can be configured
  at a later date to cross reference in different ways without requiring
  input files to be reworked.
@<End list@>

@<Nav@>@(@<Design_numinst FILE@>@,@<Design FILE@>@,@<Design_diagnostics FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Design_diagnostics HEADING@>@M@{@<SH@>@(2.11@)Diagnostic Messages@}
@$@<Design_diagnostics FILE@>@M@{design_diagnostics.html@}
@O@<design_diagnostics.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Design_diagnostics HEADING@>@)
@<XX@>@(diagnostic@,messages@)

@<P@>In FunnelWeb, all error messages commence with an
indicator indicating the severity of the error message. Here
are some of the formats that were considered:

@<P@>
@<Begin verbatim@>
W--Error creating sloth.
E--Error opening output file.
S--I'm a teapot.
F--Can't open output file.

W-Error creating sloth.
E-Error opening output file.
S-I'm a teapot.
F-Can't open output file.

W:Error creating sloth.
E:Error opening output file.
S:I'm a teapot.
F:Can't open output file.

W: Error creating sloth.       -- Format chosen.
E: Error opening output file.
S: I'm a teapot.
F: Can't open output file.

War-Error creating sloth.
Err-Error opening output file.
Sev-I'm a teapot.
Fat-Can't open output file.

W-Old fashioned feature.

W-Old fashioned feature.

W--Old fashioned feature.

W: Old fashioned feature.

W:Old fashioned feature.
@<End verbatim@>

@<Nav/last@>@(@<Design_docmac FILE@>@,@<Design FILE@>@,@<Design FILE@>@)

@<End FWDevMan page@>
@}

@!******************************************************************************

@$@<Implement HEADING@>@M@{@<SH@>@(3@)FunnelWeb Implementation Notes@}
@$@<Implement HEADING/short@>@M@{@<SH@>@(3@)Implement@}
@$@<Implement FILE@>@M@{implement.html@}
@O@<implement.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Implement HEADING@>@)

@<P@>This chapter contains some notes on the FunnelWeb C code.

@<Implement index@>

@<Nav@>@(@<Design FILE@>@,@<Index FILE@>@,@<Modify FILE@>@)

@<End FWDevMan page@>
@}

@$@<Implement index@>@M@{
@<Begin size3@>
@<Begin indent/narrow@>
@<Link@>@(@<Implement_history FILE@>@,@<Implement_history HEADING@>@)@<BR@>
@<Link@>@(@<Implement_self FILE@>@,@<Implement_self HEADING@>@)@<BR@>
@<Link@>@(@<Implement_style FILE@>@,@<Implement_style HEADING@>@)@<BR@>
@<Link@>@(@<Implement_memory FILE@>@,@<Implement_memory HEADING@>@)@<BR@>
@<Link@>@(@<Implement_indentation FILE@>@,@<Implement_indentation HEADING@>@)@<BR@>
@<End indent/narrow@>
@<End size3@>
@}

@!==============================================================================

@$@<Implement_history HEADING@>@M@{@<SH@>@(3.1@)History of FunnelWeb Implementations@}
@$@<Implement_history FILE@>@M@{implement_history.html@}
@O@<implement_history.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Implement_history HEADING@>@)
@<XX@>@(FunnelWeb@,history@)
@<X@>@(FunnelWeb version 1@)
@<X@>@(FunnelWeb version 2@)
@<X@>@(FunnelWeb version 3@)

@<FWDevMan subheading@>@(FunnelWeb V1 (1986)@)

@<P@>The first implementation of FunnelWeb was written in
Ada@<X@>@(Ada@)@<Paper@>@(USDOD83@) in December 1986. I used
FunnelWeb as a program to write to help me learn Ada.
FunnelWeb V1 took about one month to write and was fairly
VMS dependent.

@<P@>I used FunnelWeb@<_@>V1 to write all the Ada software
for my Ph.D. project and it was very successful in this
role, helping me to document some complicated code. However
when I finished the Ph.D work in July@<_@>1989, I lost
access to the VAX and hence to FunnelWeb. During my
candidature, at least twenty thousand lines of code were
written using FunnelWeb, but hardly anyone else used
FunnelWeb. After losing access to Ada and the Vax (and hence
to FunnelWeb), I was forced back to programming the
non-literate way. I recognised a need to translate FunnelWeb
into the more portable C programming language, but didn't
have the time or energy to create one.

@<FWDevMan subheading@>@(FunnelWeb V2 (1991)@)

@<P@>About this time (late 1989), David
Hulse,@<XN@>@(David@,Hulse@) at the time a student in
Computer Science at the University of
Adelaide,@<XX@>@(University@,Adelaide@) volunteered to
translate the 4000 line Ada version of FunnelWeb into@<_@>C.
To my knowledge this translation process took about three
weeks (in December 1989). The result was called
FunnelWeb@<_@>V2 and was formally signed into the public
domain on 5@<_@>May 1992. However, it was never publicly
released.

@<P@>I would like to take this opportunity to thank David
Hulse for translating FunnelWeb from Ada to@<_@>C, as this
effort was the basis of later work on FunnelWeb.

@<FWDevMan subheading@>@(FunnelWeb V3.0 (1992)@)

@<P@>Lack of portability of the translated C@<_@>code,
combined with the need for a rather solid design review,
combined with the need to strengthen the program to bring it
up to production standard, resulted in my performing a
complete reworking of the code in late 1991 and early 1992.
The C code was entirely, but incrementally, replaced or
reformatted. The code was also strengthened and new features
were added. This process took about two months (November and
December 1991). A further two months (approx) were spent
writing documentation, constructing a regression test suite,
porting the program to different machines, and sorting out
the legal issues involved in its release. FunnelWeb V3.0 was
publicly released on the Internet under a GNU licence
on 6@<_@>June@<_@>1992.

@<P@>Version 3.0 proved very solid, but had the following
bugs:

@<Begin list@>

@<Item@>Bombs with an assertion error if the input file
is at least 10000 lines long.

@<Blank line@>

@<Item@>Bombs with an assertion error if it's generating
a listing file and an error occurs on a line longer than 200
characters.

@<P@>
@<Begin verbatim/size2@>
   lister.dup: count>=DUPMAX
   An assertion has failed! See the line above.
   Press return to abort FunnelWeb>
@<End verbatim/size2@>

@<Blank line@>

@<Item@>The FunnelWeb shell @<TT@>@(diff@) command bombs
with an assertion error if it can't open the first file:

@<P@>
@<Begin verbatim/size2@>
FunnelWeb>diff deleteme.list vctest01.ans x.x
E: DIFF: Error mapping "deleteme.list".
         Error fopen()ing input file
         (to determine its length).
do_diff: Image comparison succeeded,
         but text comparison failed.
An assertion has failed! See the line above.
Press return to abort FunnelWeb>
@<End verbatim/size2@>

@<Blank line@>

@<Item@>Under VMS FunnelWeb overwrites previous output files
with the newly generated output files, rather than generating a
new version.

@<Blank line@>

@<End list@>

@<FWDevMan subheading@>@(FunnelWeb V3.1 (1993)@)

@<P@>During 1993, the following changes were made, yielding V3.1:

@<Begin verbatim@>
13-Oct-1993:
   lister.c: Increased MAXLINES to one million to
             avoid mes_wri case default bomb.
             Modified bomb message in mes_wri.
   memory.*  Modified package to count blocks
             of various sizes.
   command.c Modified it to call memory to
             write out mem report.
13-Oct-1993
   parser.c  Change ty_name to ty_pname
             to save memory.
   data.h    ?
   weave.c   ?
@<End verbatim@>

@<P@>These changes essentially fixed the "10,000 lines" bug
and performed some memory tuning.

@<FWDevMan subheading@>@(FunnelWeb 3.05AC@)

@<P@>@<Tony Coates@> created a
<A HREF="http://www.ems.uq.edu.au:7007/People/Tony/funnelweb.html">FunnelWeb variant</A>
called FunnelWeb V3.05AC that fixes some bugs, and provides some extra
useful features (including HTML output). This version has been officially
classified as an unofficial version.

@<FWDevMan subheading@>@(FunnelWeb V3.2 (1999)@)

@<P@>In April 1999 I decided to perform extensive housecleaning on
FunnelWeb so as to make it more presentable and useable. This process
involved:

@<P@>
@<Begin list@>
@<Item@>Eliminating all known bugs.
@<Item@>Converting all FunnelWeb documentation to webs.
@<Item@>Porting FunnelWeb to a wider range of platforms.
@<Item@>Providing FunnelWeb executables online.
@<Item@>Reworking the main FunnelWeb web.
@<End list@>

@<P@>The result was FunnelWeb V3.2.

@<Nav/first@>@(@<Implement FILE@>@,@<Implement FILE@>@,@<Implement_self FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Implement_self HEADING@>@M@{@<SH@>@(3.2@)Why FunnelWeb Wasn't Used to Write Itself@}
@$@<Implement_self FILE@>@M@{implement_self.html@}
@O@<implement_self.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Implement_self HEADING@>@)
@<XX@>@(FunnelWeb@,writing itself@)

@<P@>After Knuth created the WEB literate preprocessing
system, he re-wrote it using WEB and distributed the source
code in WEB source form. To allow the WEB source code to be
tangled by users not yet having a copy of WEB, he also
included the tangled Pascal code for the Tangler.

@<P@>While this approach is heroic and serves to convey a
commitment and a confidence in literate programming, it
seemed to me that writing FunnelWeb in FunnelWeb would
simply be asking for trouble.@<XX@>@(trouble@,asking for@)
For a start, it would be very hard to modify any feature of
FunnelWeb that had been used to write FunnelWeb. Also, the
thought of what would happen if the working executable
became inoperative for some reason does not bear thinking
upon.

@<P@>One million billion computer programs were written in
the non-literate style before FunnelWeb was created. Why not
one more?

@<Nav@>@(@<Implement_history FILE@>@,@<Implement FILE@>@,@<Implement_style FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Implement_style HEADING@>@M@{@<SH@>@(3.3@)Coding Style@}
@$@<Implement_style FILE@>@M@{implement_style.html@}
@O@<implement_style.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Implement_style HEADING@>@)
@<XX@>@(coding@,style@)

@<P@>Although FunnelWeb wasn't coded under any formal C
coding standard, it was coded in accordance with a fairly
strict personal style of C which developed during the
development of FunnelWeb. This section aims to describe some
of the more important elements of the coding style.

@<Boldthing@>@(Portability:@) This@<X@>@(portability@) was a major
goal of the FunnelWeb implementation. Two excellent books
guided this move to portability. They were
@<Paper@>@(Rabinowitz90@) (which deals with C code itself)
and @<Paper@>@(Horton90@) (which deals with the portability
of various library calls). Other works such as
@<Paper@>@(Kernighan88@) and @<Paper@>@(ANSI@) were also
helpful.

@<Boldthing@>@(Identifiers:@)
@<Paper@>@(Rabinowitz90@)@<XX@>@(identifier@,length@)
specifies that for wide portability, identifiers of block
and file scope should be unique to eight characters, and
identifiers of program scope should be unique to six
characters. I have gone further in FunnelWeb and actually
made these restrictions actual limits on identifier length.

@<P@>Because names must be so short, a system of
abbreviations was developed to organize the identifiers used
within FunnelWeb. Each abbreviation consists of a letter
pair. Here are most of the abbreviations
used:@<XX@>@(identifier@,abbreviations@)

@<P@>
@<Begin verbatim@>
bp - Body Part.
cm - Compare. Used to prefix comparison
     routines that return [-1,0,1].
dc - Document component.
dm - Dump package.
el - Element.
eq - Equal. Used to prefix comparison
     routines that return a boolean.
ex - Expression.
f  - Global files.
ll - List of lists.
ln - Line record.
ls - List Package.
lr - Lister package.
ma - Macro.
mc - Macro Call.
mn - Macro Name.
op - Options package.
pr - Parser.
ps - Position record.
sc - Scrap record.
sn - Section.
tb - Table package.
ty - Typesetter directive.
wf - Write file package.
wl - Write with EOL (misc.c).
wr - Write          (misc.c).
@<End verbatim@>

@<Boldthing@>@(Pointers:@) Variables or types denoting
pointers@<XX@>@(pointers@,naming@) start with @<DQP@>@(p_@).

@<Boldthing@>@(Types:@) Names denoting types end in
@<DQP@>@(_t@). Thus, a type for a pointer to a table would
be named @<TT@>@(p_tb_t@).@<XX@>@(types@,naming@)

@<Boldthing@>@(File names:@) All FunnelWeb source
files@<XX@>@(filenames@,length@) have file
names that are from one to eight characters long and file
extensions that are from one to three characters long. This
ensures that the FunnelWeb source code can be portably moved
to all kinds of machines, including MSDOS!@<X@>@(MSDOS@)

@<Nav@>@(@<Implement_self FILE@>@,@<Implement FILE@>@,@<Implement_memory FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Implement_memory HEADING@>@M@{@<SH@>@(3.4@)Use of Memory@}
@$@<Implement_memory FILE@>@M@{implement_memory.html@}
@O@<implement_memory.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Implement_memory HEADING@>@)
@<XX@>@(use of@,memory@)

@<P@>FunnelWeb is not a memory-stressed program. However,
during its development, problems with the management of
memory seemed to crop up again and again. This section
documents some of these problems and the solutions
that were adopted.

@<P@>There are three places where memory can be obtained:
the heap, the stack, and from static variables. The
following three sections deal with each of these areas.

@<FWDevMan subheading@>@(The Heap@)
@<XX@>@(heap@,memory@)

@<P@>One of the great frustrations of being a user is to
find that a computer program is complaining about lack of
memory when one knows full well that one has allocated at
least ten times as much memory to the program as it would
ever need to do its job. The reason for such error messages
usually has to do with the programmer setting a fixed
@<DQ@>@(reasonable@) limit to a particular data structure
and then locking it up into an array whose bound is
specified by a constant. This malody is particularly common in
old Pascal programs. While the use of arrays can
increase the speed of a program, it also means that the user
cannot increase the capacity of the program without
obtaining the source code and recompiling it.

@<P@>The alternative is to use the heap for all data
structures that can grow in proportion to the size of the
user's input. This rule has been followed rigorously in
FunnelWeb. This means that as memory spaces increase, users
will be able to hand their version of FunnelWeb more memory
without having to recompile it.

@<P@><HR WIDTH=30%>

@<P@>Some problems arose early on the
Macintosh@<X@>@(Macintosh@) in the use of the heap.
For some obscure reason, many of the heap application
@<TT@>@(malloc@) calls were failing. Whatever
it was, it went away when I replaced direct calls to
@<TT@>@(malloc@)@<X@>@(malloc@) with calls to a mini package
I wrote (called @<TT@>@(memory@)) that allocated large
chunks of memory and then doled out small pieces as required
by the rest of the program.@<XX@>@(memory@,package@)

@<P@>Having a package to manage all the memory allocation
had two other benefits.

@<P@>First, only one check was required in the entire
program to see if memory had run out (in the memory
package), and if that failed, the program could be brought
to a screaming halt. This organization was far preferable to
having each piece of code that needed to allocate memory
having to check to see if @<TT@>@(malloc@) had failed.

@<P@>Second, the decision to construct a mini-shell within
FunnelWeb to support regression testing meant that FunnelWeb
proper (the FunnelWeb @<TT@>@(fw@) shell command)
could be run many times in any given invocation of
FunnelWeb. As a consequence it was necessary to make sure
that there was no memory leakage@<XX@>@(memory@,leakage@)
between invocations of FunnelWeb proper. This was
accomplished by reworking the memory package to operate a
watermark system. The user of the package, when requesting
memory, could request @<DQ@>@(temporary@) or
@<DQ@>@(permanent@). If permanent, the memory package forgot
that it had allocated the memory. If temporary, the memory
package places the allocated block on a list. There was then
a function in the memory package that could be called to
deallocate all the temporary memory. All this meant that
so long as all
requests for memory within FunnelWeb proper were for
temporary memory, and that memory was freed at the end of
every run, one could be sure that there was no memory
leakage.

@<FWDevMan subheading@>@(The Stack@)
@<XX@>@(stack@,memory@)@<XX@>@(stack@,size@)

@<P@>For a while during the development of FunnelWeb a
particularly nasty bug proved extremely hard to find. The
symptom was that FunnelWeb would crash, sometimes at random,
but more often upon entering a particular function. In the
end, about a day of specific debugging was required before
the problem was tracked down to a stack problem. It turned
out that somehow (either the fault of the Macintosh or the
THINK@<_@>C language system), the compiler was allocating
just 6K for stack space!!!!!!!

@<P@>This experience led me immediately to go through the
entire program and eliminate (or remove to the heap) any
automatic variable declarations that used more than one
hundred or so bytes.

@<P@>The lesson is clearly that C@<_@>programs that use more
than a few thousand bytes of stack space are risking their
portability. All large data structures should be placed in
the heap.

@<FWDevMan subheading@>@(Static Variables@)
@<XX@>@(memory@,static@)@<XX@>@(static@,variables@)

@<P@>Static variables also proved a problem on the
Macintosh. It turned out that the Macintosh@<X@>@(Macintosh@)
THINK@<_@>C compiler@<XX@>@(ThinkC@,compiler@) did not allow
more than 32K of statics @<I@>@(in the entire program@). For
a while this restriction was a serious threat to the program
as it was discovered that constant strings were included in
this total! However, some searching revealed a compiler
option that removed the strings from the static category.

@<P@>Nevertheless, the 32K limit is rather severe. Again, it
seems that for portability reasons, C@<_@>programs that use a
lot of static variables are risking their portability. As a
result, the FunnelWeb code avoids static variables where
possible in favour of the heap.

@<Nav@>@(@<Implement_style FILE@>@,@<Implement FILE@>@,@<Implement_indentation FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Implement_indentation HEADING@>@M@{@<SH@>@(3.5@)Implementing Text Indentation@}
@$@<Implement_indentation FILE@>@M@{implement_indentation.html@}
@O@<implement_indentation.html@>@{@-
@<Begin FWDevMan page/wide/H1@>@(@<Implement_indentation HEADING@>@)
@<XX@>@(text@,indentation@)

@<P@>At one point during the development of FunnelWeb, text
indentation was fully implemented. However, it was
subsequently removed because it was considered a dangerous
feature. This section records the way in which text
indentation was implemented so that if the feature ever has
to be put back, this technique can be used again.

@<P@>1. Create a new field in the @<TT@>@(sc_t@) record call
@<TT@>@(sc_postn@).

@<P@>
@<Begin verbatim@>
      char *sc_postn; /* Pointer in the range [sc_first,sc_last+1].           */
                      /* It is the minimum possible value of sc_postn for     */
                      /* which EOL does not appear in *sc_postn..*sc_last.    */
                      /* i.e. Points to the byte following the first EOL in   */
                      /* the scrap or sc_first if EOL does not appear.        */
@<End verbatim@>

@<P@>2. Modify the scanner so that it generates this field.
Sendtext should be modified so that
it accepts an argument for the @<TT@>@(p_postn@) value.

@<P@>
@<Begin verbatim@>
LOCAL void sendtext P_((p_ps_t,char *,char *,char *,bool));
LOCAL void sendtext(p_tkps,p_first,p_last,p_postn,is_white)
/* Appends a text token to the end of the token list.                         */
/* IN: p_ps is a pointer to a position structure giving the position of the   */
/*     first character of the token.                                          */
/* IN: p_first and p_last point to the first and last byte of the text scrap. */
/* IN: p_postn has the same definition as sc_postn (see fwdata.h).            */
/* IN: is_white should be set to TRUE iff scrap is entirely whitespace.       */
p_ps_t p_tkps;
char  *p_first;
char  *p_last;
char  *p_postn;
bool   is_white;
{
 tk_t token;

 /* Empty text scraps should never be generated. */
 assert(p_first@<<@>=p_last,"sendtext: Text scrap bounds are bad.");

 /* If ch=EOL then we should be scanning more text, not shipping it! */
 assert(ch!=EOL,"senttext: Shipping text while still more to scan.");

 /* Check that p_postn is in range. See definition in fwdata.h. */
 assert(p_first@<<@>=p_postn && p_postn@<<@>=p_last+1,
        "sendtext: p_postn is out of range.");

 /* Debug: Check the p_postn field using a brute force check. */
 {
  char *i,*j;
  j=p_first;
  for (i=p_first;i@<<@>=p_last;i++)
     if (*i==EOL)
        j=i+1;
  assert(j==p_postn,"sendtext: sc_postn field is incorrect.");
 }

 /* Load the text token. */
 token.tk_kind        = TK_TEXT;
 ASSIGN(token.tk_ps,*p_tkps);
 token.tk_sc.sc_first = p_first;
 token.tk_sc.sc_last  = p_last;
 token.tk_sc.sc_postn = p_postn;
 token.tk_white       = is_white;
 token.tk_parno       = 0;
 ls_add(token_list,PV &token);
}
@<End verbatim@>

@<P@>Then all the calls to sendtext have to be changed:

@<Begin verbatim@>
/* @@ instructs FunnelWeb to replace the special construct with the */
/* special character. Luckily one appears just before the @@ !!     */
/* Note: FALSE is OK because space is not a legal specialch.       */
/* Note: Setting parameter p_postn to p_ch-1 is OK as EOL is not a */
/*       legal specialch.                                          */
sendtext(ps_spec,p_ch-1,p_ch-1,p_ch-1,FALSE);
break;

/* + instructs FunnelWeb to insert an EOL. We can't look to the end of */
/* the previous line to find an EOL as this might be the first line.   */
/* Running ahead to the end of the line is expensive, and having the   */
/* liner mini-package maintain a variable for it would be extra        */
/* housekeeping. Instead of all this, we just point to a static.       */
{CONST static char stateol = EOL;
 sendtext(&ps_spec,&stateol,&stateol,(&stateol)+1,TRUE);}
break;

/* If we hit something that ends a text token */
/* then we can transmit a white text token.   */
if (ch==specialch || ch==EOFCH)
   {sendtext(&ps_start,p_first,p_ch-1,MAX(p_sol,p_first),TRUE); return;}

/* Otherwise we have some more (non-white) text to scan. */
/* We can then send a non-white text token.              */
while (ch!=specialch && ch!=EOFCH)
   NEXTCH;
sendtext(&ps_start,p_first,p_ch-1,MAX(p_sol,p_first),FALSE);
@<End verbatim@>

The dump code needs to be changed too!

@<Begin verbatim@>
        wf_str(p_wf,"\"");
assert(token-@<>@>tk_sc.sc_first !=NULL,"dm_tkls: NULL ptr1.");
assert(token-@<>@>tk_sc.sc_last  !=NULL,"dm_tkls: NULL ptr2.");
for (i=token-@<>@>tk_sc.sc_first; i@<<@>=token-@<>@>tk_sc.sc_last; i++)
  {
   if (i==token-@<>@>tk_sc.sc_postn)
      wf_str(p_wf,"@<<@>postn@<>@>");
   if (*i=='\n')
      wf_wl(p_wf,"");
   else
      dm_byte(p_wf,*((ubyte_ *) i));
  }
if (i==token-@<>@>tk_sc.sc_postn)
   wf_str(p_wf,"@<<@>postn@<>@>");
wf_str(p_wf,"\"");
}
@<End verbatim@>

@<P@>3. Over in the Tangle module, create a massive array of
pointers to scraps to be used as a stack. Maintain pointers
into the stack called @<TT@>@(current@) and @<I@>@(base@)
(similar to the blank indentation variables). Implement the
following:

@<P@>
@<Begin list@>

@<Item@>To write out a scrap, scan it byte by byte. Output
each byte. When you hit an EOL, pop the stack back to
@<TT@>@(base@). Then write out an EOL followed by the stack
contents but writing each scrap only from @<TT@>@(postn@) to
end end of each scrap. When you have finished the new scrap,
push it on the stack.

@<Item@>When you hit a new macro to expand, save
@<TT@>@(base@). Restore it later.

@<End list@>

@<P@>The @<TT@>@(postn@) field solves the big problem of how
to cope with something like this:

@<P@>
@<Begin verbatim@>
The rain in Spain
falls mainly @@@<<@>on the plain@@@<>@>
@<End verbatim@>

@<P@>The trouble is that we want to text indent the lines in
@<TT@>@(@@@<<@>on the plain@@@<>@>@) with just @<DQP@>@(falls
mainly@<_@>@). However, this string is only part of a scrap. The
solution is to get the scanner to record, in the
@<TT@>@(postn@) field of each scrap, the position of the
first byte with a EOL-free run to the end of the scrap.

@<P@>This scheme is very efficient because all we are doing
is pushing and popping pointers to scraps on a stack array.
The main disadvantage is that the array must necessarily be
finite and would impose a limit on the depth of indentation
nesting.

@<Nav/last@>@(@<Implement_memory FILE@>@,@<Implement FILE@>@,@<Implement FILE@>@)

@<End FWDevMan page@>
@}

@!******************************************************************************

@$@<Modify HEADING@>@M@{@<SH@>@(4@)Modifying FunnelWeb@}
@$@<Modify HEADING/short@>@M@{@<SH@>@(4@)Modify@}
@$@<Modify FILE@>@M@{modify.html@}
@O@<modify.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Modify HEADING@>@)
@<XX@>@(FunnelWeb@,modification@)

@<P@>This chapter deals with modifications to FunnelWeb.
Although the GNU license@<XX@>@(GNU@,license@) under which
FunnelWeb is distributed allows anyone to modify FunnelWeb
and distribute the modified versions, care should be taken
before doing this. This chapter discusses some of the issues
you should think about if you intend to distribute modified
versions of FunnelWeb.

@<Modify index@>

@<Nav@>@(@<Implement FILE@>@,@<Index FILE@>@,@<Misc FILE@>@)

@<End FWDevMan page@>
@}

@$@<Modify index@>@M@{
@<Begin size3@>
@<Begin indent/narrow@>
@<Link@>@(@<Modify_languages FILE@>@,@<Modify_languages HEADING@>@)@<BR@>
@<Link@>@(@<Modify_authority FILE@>@,@<Modify_authority HEADING@>@)@<BR@>
@<Link@>@(@<Modify_protect FILE@>@,@<Modify_protect HEADING@>@)@<BR@>
@<Link@>@(@<Modify_manuals FILE@>@,@<Modify_manuals HEADING@>@)@<BR@>
@<Link@>@(@<Modify_official FILE@>@,@<Modify_official HEADING@>@)@<BR@>
@<End indent/narrow@>
@<End size3@>
@}

@!==============================================================================

@$@<Modify_languages HEADING@>@M@{@<SH@>@(4.1@)The Danger of Modifying Languages@}
@$@<Modify_languages FILE@>@M@{modify_languages.html@}
@O@<modify_languages.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Modify_languages HEADING@>@)
@<XX@>@(changes@,dangers@)@<XX@>@(languages@,dangers@)

@<P@>FunnelWeb is a computer program that implements the
semantics of the FunnelWeb language. As such, you should
take great care when making changes to FunnelWeb that
modify the syntax or semantics of its language:

@<Narrowthing@>@(Removing
features:@,Removal@<XX@>@(removing@,features@) of features
(featurectomy) is extremely difficult once the legacy base
is using the features. If a feature is removed, users will
have to go through all their files and find
a way to simulate the effect of the removed feature with
other features. This is usually unthinkable.@)

@<Narrowthing@>@(Modifying
features:@,Modification@<XX@>@(features@,modification@) of
features has less direct impact than the removal of
features, but can cause more subtle errors. Anyone modifying
features should be sure that they
are not inadvertently laying semantic traps.@)

@<Narrowthing@>@(Adding
features:@,Although@<XX@>@(features@,adding@) the addition
of features is generally the most painless for the user
community, as Hoare points out, it is also the most
dangerous in the long run.@)

@<P@>
@<Begin blockquote@> @<DQ@>@(When any new language
design project is nearing completion, there is always a mad
rush to get new features added before standardization. The
rush is mad indeed, because it leads into a trap from which
there is no escape. A feature which is omitted can always be
added later, when its design and its implications are well
understood. A feature which is included before it is fully
understood can never be removed later.@)@<Paper@>@(Hoare80@)
@<End blockquote@>

@<P@>The benefits of tight control over a language are
enormous.

@<Narrowthing@>@(Universal portability:@,Source files can be
treated as portable.@)

@<Narrowthing@>@(Clear semantics:@,Doubt about the semantics
of the language are minimized.@)

@<P@>For these reasons, I have decided to keep tight control
over the FunnelWeb syntax and semantics. If you develop
a variant of FunnelWeb, please take these issues into account.

@<Nav/first@>@(@<Modify FILE@>@,@<Modify FILE@>@,@<Modify_authority FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Modify_authority HEADING@>@M@{@<SH@>@(4.2@)Authority vs User Security@}
@$@<Modify_authority FILE@>@M@{modify_authority.html@}
@O@<modify_authority.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Modify_authority HEADING@>@)
@<XX@>@(security@,authority@)

@<P@>There are a number of ways of providing the strong
central design authority required to produce the portability
and semantic security desired by users,

@<P@>
@<Begin list@>

@<Item@>Trade mark@<X@>@(trademark@) the name of the
language. Publish a specification of the language under the
trade name. Warn all users not to trust any implementation
that does not guarantee that it implements the language.
Then control implementations by only licensing the trade
mark to conforming implementations.

@<Item@>Create a single implementation of the language. Do
not release the source code to the implementation. Release
only binary executables.

@<Item@>Release the source code to the implementation, but
under a license that prohibits the distribution of modified
versions.

@<End list@>

@<P@>Many other variations on these themes are possible, but
they are all based on the idea of regulating either the
@<DQ@>@(official@) definition of the language or all of its
existing implementations.

@<P@>The solution that I (@<Ross Williams@>
(@<Email@>@(@<Ross personal EMAIL@>@)) have adopted (in 1992)
is to release the FunnelWeb source code under a GNU license
and then to write this chapter in this manual to encourage
programmers to think hard if they make any changes to the
language.

@<Nav@>@(@<Modify_languages FILE@>@,@<Modify FILE@>@,@<Modify_protect FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Modify_protect HEADING@>@M@{@<SH@>@(4.3@)What I Want to Protect@}
@$@<Modify_protect FILE@>@M@{modify_protect.html@}
@O@<modify_protect.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Modify_protect HEADING@>@)
@<XX@>@(protection@,FunnelWeb@)@<XX@>@(protection@,file extension@)

@<P@>The concerns expressed in the previous section about
modifications to the FunnelWeb program do not exclude
modifications. They merely suggest that some conditions be
observed when modifications are made. In the end there are
two things that I want to protect and maintain:

@<P@>
@<Begin list/ordered@>

@<Item@>Restriction of the name @<DQ@>@(FunnelWeb@) only to
computer programs that exactly implement my
@<DQ@>@(official@) definition of the language.

@<Item@>Restriction of the FunnelWeb source file extensions
@<DQP@>@(.fw@) (input files) and @<DQP@>@(.fwi@) (include
files) only to source files that conform exactly to my
@<DQ@>@(official@) definition of the language.

@<End list/ordered@>

@<P@>So long as these conditions hold, @<TT@>@(.fw@) source file
will be universally portable. Here
are my suggestions for how to obey these rules. These
suggestions are in addition to the GNU license rules about
documenting any changes that you make in the source files.

@<Narrowthing@>@(Level 0: Modifications that do not affect
functionality:@,If you change the FunnelWeb program in a
manner that does not affect the functionality of the program
in any way (@<eg@>port it to a new machine, or just speed it
up), then you should modify the program to write out a
message when it starts up saying that it is a modified
version of FunnelWeb. No other actions need be taken.@)

@<Narrowthing@>@(Level 1: Modifications that affect surface
functionality:@,If you make changes to FunnelWeb that affect
its functionality without altering or extending
the syntax or semantics of the FunnelWeb language, you should
augment the name of the program to indicate that it is
a FunnelWeb variant. For example, you could call it
@<DQ@>@(FunnelWeb-Dave@).@)

@<Narrowthing@>@(Level 2: Modifications that affect the language:@,If
you make changes to FunnelWeb that affect the FunnelWeb language
(@<eg@>by adding some new syntax), you should
change the name of the program so that the name no longer
contains the word @<DQ@>@(FunnelWeb@), and should choose
alternative input and include-file file extensions (the
current ones are @<DQP@>@(.fw@) and @<DQP@>@(.fwi@)). For
example, you might call your program @<DQ@>@(BananaWeb@) and
use the file extensions @<DQP@>@(.bw@) and
@<DQP@>@(.bwi@).@)

@<P@>These rules are not very restrictive. Basically you can
do what you like so long as you change the name of the
resulting program. I do not wish to restrict anyone who
might want to use FunnelWeb as a foundation for a more
sophisticated literate programming system. My sole aim here
is to protect the integrity of what already exists.

@<Nav@>@(@<Modify_authority FILE@>@,@<Modify FILE@>@,@<Modify_manuals FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Modify_manuals HEADING@>@M@{@<SH@>@(4.4@)Modifying the Manuals@}
@$@<Modify_manuals FILE@>@M@{modify_manuals.html@}
@O@<modify_manuals.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Modify_manuals HEADING@>@)
@<XX@>@(modifying@,manuals@)

@<P@>The FunnelWeb documentation:

@<P@>
@<Begin indent@>
@<FunnelWeb@>@<BR@>
@<FunnelWeb Reference Manual@>@<BR@>
@<FunnelWeb Tutorial Manual@>@<BR@>
@<FunnelWeb Developer Manual@>@<BR@>
@<End indent@>

@<P@>may be modified and distributed so long as you conform to the
conditions of the licence notice associated with this documentation:

@<Begin blockquote@>
@<FunnelWeb documentation permission notice@>
@<End blockquote@>

@<Nav@>@(@<Modify_protect FILE@>@,@<Modify FILE@>@,@<Modify_official FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Modify_official HEADING@>@M@{@<SH@>@(4.5@)Contributions To The Official FunnelWeb@}
@$@<Modify_official FILE@>@M@{modify_official.html@}
@O@<modify_official.html@>@{@-
@<Begin FWDevMan page/wide/H1@>@(@<Modify_official HEADING@>@)
@<XX@>@(FunnelWeb@,management@)@<XX@>@(FunnelWeb@,official@)

@<P@>Contributions to the official version of FunnelWeb code are welcome,
although it may be some time before I will be able to find the time to
incorporate the changes into the official version. Here are some of
the issues relating to contributions to the official version.

@<FWDevMan subheading@>@(Quality Issues@)

@<P@>Contributions must be of sufficiently high standard to
warrant inclusion in the official version. Whether a
modification will be accepted will depend, amongst other
things, on the following criteria.

@<P@>
@<Begin list@>

@<Item@>Does the modification fit in with the design goals
of FunnelWeb, or is it just a case of creeping featurism?

@<Item@>How well coded is the modification? Would it reduce
the quality of the code?

@<Item@>If the modification changes FunnelWeb's
functionality, is this a desirable change? How will it
impact on existing users? Does it change the semantics
of existing FunnelWeb @<TT@>@(.fw@) files?

@<Item@>Would it be quicker for me to make the modification
myself than to work out how to incorporate the submitted
modification?

@<Item@>Does the change come with a corresponding addition
to the regression test suite?

@<End list@>

@<P@>It is my goal to guard the integrity of the design and
code of the official version of FunnelWeb and so I will
probably be rather fussy about what I regard as a worthwhile
modification.

@<FWDevMan subheading@>@(Legal Issues@)

@<P@>For various reasons, I have decided to maintain
complete copyright over the official version of FunnelWeb,
but release it under a GNU license each time it is updated.
This means that, while you are free to create and distribute
different versions of FunnelWeb, if you want your
modifications to be incorporated into the official version,
you will have to license copyright of the modifications to me
(@<Ross Williams@>). Here's how it works:

@<P@>
@<Begin verbatim@>
+-------@<>@>------+----------@<<@>-------+
|(mods by      |                  |
| me)          V                  |
|     +------------------+        |
+--<--| My Official Copy |        ^
      |   Of FunnelWeb   |        |
      | Copyright (c) Me |        |
      +------------------+        |
 (Periodic GNU |                 / \
  release)     V                /   \  Programmer
      +-------------------+    /Legal\ signs away
      | Official GNU Copy |    \Filte/ copyright on
      +-------------------+     \ r /  modifications
 (Mods made    |                 \ /
  by random    |                  |
  programmer)  |                  ^
               V                  |
             +-----------------------+
             | Modified GNU Version  |
             +-----------------------+

@<End verbatim@>

@<P@>This organization allows me to retain full use of the
source code for any private, public or commercial purpose,
and for the purpose of maintaining the integrity of the
FunnelWeb language, while still assuring contributors that
their contributions will become part of the public GNU
version.

@<P@>This policy is my current policy as at December 1999,
but might change, depending on circumstances.

@<Nav/last@>@(@<Modify_manuals FILE@>@,@<Modify FILE@>@,@<Modify FILE@>@)

@<End FWDevMan page@>
@}

@!******************************************************************************

@$@<Misc HEADING@>@M@{@<SH@>@(5@)Miscellaneous@}
@$@<Misc HEADING/short@>@M@{@<SH@>@(5@)Misc@}
@$@<Misc FILE@>@M@{misc.html@}
@O@<misc.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Misc HEADING@>@)

@<P@>This chapter contains miscellenous development
information.

@<Misc index@>

@<Nav@>@(@<Modify FILE@>@,@<Index FILE@>@,@<GPL FILE@>@)

@<End FWDevMan page@>
@}

@$@<Misc index@>@M@{
@<Begin size3@>
@<Begin indent/narrow@>
@<Link@>@(@<Misc_versions FILE@>@,@<Misc_versions HEADING@>@)@<BR@>
@<Link@>@(@<Misc_wishlist FILE@>@,@<Misc_wishlist HEADING@>@)@<BR@>
@<Link@>@(@<Misc_suggestions FILE@>@,@<Misc_suggestions HEADING@>@)@<BR@>
@<Link@>@(@<Misc_knownbugs FILE@>@,@<Misc_knownbugs HEADING@>@)@<BR@>
@<End indent/narrow@>
@<End size3@>
@}

@!==============================================================================

@$@<Misc_versions HEADING@>@M@{@<SH@>@(5.1@)FunnelWeb Versions@}
@$@<Misc_versions FILE@>@M@{misc_versions.html@}
@O@<misc_versions.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Misc_versions HEADING@>@)
@<XX@>@(FunnelWeb@,versions@)

@<FWDevMan subheading@>@(FunnelWeb V1 (1986)@)

@<P@>FunnelWeb V1 was written in Ada on a VAX in 1986 by
@<Ross Williams@>. FunnelWeb V1 was released as a
VAX/VMS executable for use within the @<University of Adelaide@>,
but was never publicly released.

@<FWDevMan subheading@>@(FunnelWeb V2 (1991)@)

@<P@>In late 1991, @<David Hulse@> translated FunnelWeb V1 from
Ada to C. This C version was designated V2. It was never publicly
released.

@<FWDevMan subheading@>@(FunnelWeb V3.0 (June 1992)@)

@<P@>In early 1992, @<Ross Williams@> rewrote and expanded
V2, creating FunnelWeb V3.0. This version was publicly released
on the Internet on 6 June 1992.

@<P@>Version 3.0 proved very solid. However, the following
bugs were eventually encountered:

@<Begin list@>

@<Item@>Bombs with an assertion error if the input file
is 10000 or more lines long.

@<Blank line@>

@<Item@>Bombs with an assertion error
(@<TT@>@(lister.dup: count@<>@>=DUPMAX@))
if a listing file is being generated, and an error
occurs on a line longer than 200 characters.

@<Blank line@>

@<Item@>The FunnelWeb shell @<TT@>@(diff@) command bombs
with an assertion error if it can't open the first file:

@<Blank line@>

@<Item@>VMS FunnelWeb overwrites previous output files
with the newly generated output files, rather than
generating a new version.

@<End list@>

@<FWDevMan subheading@>@(FunnelWeb 3.05AC@)

@<P@>@<Tony Coates@> created a
<A HREF="http://www.ems.uq.edu.au:7007/People/Tony/funnelweb.html">FunnelWeb variant</A>
called FunnelWeb V3.05AC (a variant of FunnelWeb V3.0) that provides
some additional useful features.
As this is an unofficial version, it's features are not
guaranteed to appear in future official versions of
FunnelWeb.

@<FWDevMan subheading@>@(FunnelWeb V3.1 (October 1993)@)

@<P@>In October 1993, the following changes were made, yielding V3.1:

@<P@>
@<Begin list@>
@<Item@>Lister: Increased MAXLINES to one million to avoid 10000 bug.
@<Item@>Memory:  Modified package to count blocks of various sizes.
@<Item@>Command: Modified it to call memory to write out mem report.
@<Item@>Parser:  Change ty_name to ty_pname to save memory.
@<Item@>Data: Some unrecorded changes.
@<Item@>Weave: Some unrecorded changes.
@<End list@>

@<P@>These changes essentially just fixed the "10,000 lines" bug
and performed some memory tuning. The other bugs in V3.0 remained.
The source code for V3.1 was never released. However, some
executables were.

@<FWDevMan subheading@>@(FunnelWeb 3.2 (May 1999)@)

@<P@>In May 1999, @<Ross Williams@> revised and enhanced
FunnelWeb to produce a new official version: FunnelWeb
Version 3.2. The changes made were as follows:

@<P@>
@<Begin list@>
@<Item@>Fixed the @<>@>=10,000 lines bug.
@<Item@>Fixed the @<TT@>@(DUPMAX@) bug.
@<Item@>Fixed the bug in the @<TT@>@(diff@) command.
@<Item@>Added HTML output using new @<TT@>@(+u@) option.
@<Item@>Added the @<TT@>@(@@L@) library macro feature.
@<Item@>Now executes @<TT@>@(fwinit.fws@) if no command line arguments.
@<Item@>Now gives a line number in @<TT@>@("Expecting @@)"@) error.
@<Item@>Eliminated the 64K input file restriction in the MS-DOS version.
@<Item@>Macintosh version now sets creator of output files to BBEdit.
@<Item@>Ported to more platforms.
@<Item@>Redesigned the main FunnelWeb web.
@<Item@>Converted the user manuals to webs and placed online.
@<End list@>

@<Nav/first@>@(@<Misc FILE@>@,@<Misc FILE@>@,@<Misc_wishlist FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Misc_wishlist HEADING@>@M@{@<SH@>@(5.2@)Wish List@}
@$@<Misc_wishlist FILE@>@M@{misc_wishlist.html@}
@O@<misc_wishlist.html@>@{@-
@<Begin FWDevMan page/H1@>@(@<Misc_wishlist HEADING@>@)
@<XX@>@(FunnelWeb@,future@)

@<P@>This page contains the wish list that was included in
the original 1992 FunnelWeb Hacker's Manual. As hardly any
changes have been made since then, I thought I'd just
include it here verbatim.

@<FWDevMan subheading@>@(Documentation@)

@<Boldthing@>@(An official example:@) A official example
program written using FunnelWeb should be constructed and
made available.@<XX@>@(official@,example@)

@<Boldthing@>@(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!

@<FWDevMan subheading@>@(Command Line Interface@)

@<Boldthing@>@(Buffer length:@) Currently the FunnelWeb
shell uses the @<TT@>@(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.

@<Boldthing@>@(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@)

@<FWDevMan subheading@>@(Shell Interpreter@)

@<Boldthing@>@(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@)

@<Boldthing@>@(Recursion test:@) A test should be added to
test for recursive invocation in a
shellscript.@<XX@>@(recursion@,test@)

@<Boldthing@>@(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@)

@<Boldthing@>@(Argument counting:@) In the
@<TT@>@(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.

@<Boldthing@>@(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@)

@<Boldthing@>@(Signature file:@) One problem with using
FunnelWeb in conjunction with an external @<TT@>@(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 @<TT@>@(Make@) propagations). If
@<TT@>@(Make@) then has a production linking the
@<TT@>@(.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
@<TT@>@(.sig@) file whenever it processes a @<TT@>@(.fw@)
file. The @<TT@>@(Make@) production could then be wired up
to link the @<TT@>@(.fw@) file to the @<TT@>@(.sig@) file
instead of to the output files.@<XX@>@(signature@,file@)

@<FWDevMan subheading@>@(Language Design@)

@<P@>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.

@<Boldthing@>@(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.

@<Boldthing@>@(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@)

@<Boldthing@>@(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.

@<Boldthing@>@(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@>@(@@\{@).

@<Boldthing@>@(Pragma syntax:@) It is not clear how
@<DQ@>@(loose@) the syntax of pragmas should be. Perhaps
they should be case insensitive.@<XX@>@(pragma@,syntax@)

@<Boldthing@>@(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@)

@<Boldthing@>@(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@)

@<Boldthing@>@(Formal parameter lists:@) It might be worth
changing over to a syntax for formal parameter lists that
does not require the @<TT@>@(@@(@) and @<TT@>@(@@)@).
However, they could be retained as optional for backward
compatibility.@<XX@>@(parameter list@,formal@)

@<FWDevMan subheading@>@(Scanner/Mapper@)

@<Boldthing@>@(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.

@<Boldthing@>@(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@>@(@@^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@)

@<Boldthing@>@(Allow mnemonics for unprintables:@) FunnelWeb
allows users to insert unprintable characters into the
output using the @<DQP@>@(@@^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@)

@<Boldthing@>@(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@)

@<FWDevMan subheading@>@(Parser@)

@<P@>There are no proposals to change the parser except as a
consequence of other proposals.

@<FWDevMan subheading@>@(Analyser@)

@<Boldthing@>@(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@)

@<Boldthing@>@(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.

@<FWDevMan subheading@>@(Tangle@)

@<P@>The Tangler is one of the cleanest components of
FunnelWeb, as basically all it has to do is expand some very
well-defined macros.

@<Boldthing@>@(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@)

@<FWDevMan subheading@>@(Weave@)

@<P@>Perhaps FunnelWeb's weakest aspect is its typesetting
facility.

@<Boldthing@>@(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@)

@<Boldthing@>@(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@)

@<Boldthing@>@(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.

@<Boldthing@>@(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@)

@<Boldthing@>@(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@)

@<Boldthing@>@(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@)

@<Boldthing@>@(Support for non-printables:@) Currently
FunnelWeb does not provide support for typesetting the
special @<DQP@>@(@@\circumflex(num)@) sequences. This should
be added.

@<Boldthing@>@(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.

@<Boldthing@>@(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.

@<Boldthing@>@(Non-tt typesetting:@) The current version of
FunnelWeb sets all its macro text in @<TT@>@(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.

@<P@>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.

@<P@>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.

@<P@>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.

@<FWDevMan subheading@>@(Lister@)

@<Boldthing@>@(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@)

@<FWDevMan subheading@>@(Diagnostics@)

@<Boldthing@>@(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.

@<Boldthing@>@(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.

@<FWDevMan subheading@>@(Speed@)

@<Boldthing@>@(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.

@<Boldthing@>@(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.

@<Boldthing@>@(Change some declarations:@) FunnelWeb is full
of variable declarations where the variables are wider than
they need be. Replacing these might speed it up.

@<FWDevMan subheading@>@(Correctness@)

@<Boldthing@>@(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:

@<P@>
@<Begin list@>
@<Item@> Input line length.
@<Item@> Input file size.
@<Item@> Number of macros.
@<Item@> Length of macro.
@<End list@>

@<P@>In particular, FunnelWeb's behaviour at 32K and 64K
boundaries should be observed.

@<Boldthing@>@(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.

@<FWDevMan subheading@>@(Test Suite@)

@<P@>The following tests should be added to the test suite:

@<P@>
@<Begin verbatim@>
Lister
------
   LR01: Test with a full listing with no diagnostics.
   LR02: Test with a full listing with diagnostics.
   LR03: Test abbreviated listing with no diagnostics.
   LR04: Test abbreviated listing with diagnostics.
   LR05: Test error context 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: File with a single line of a megabyte.
   BC03: File of a megabyte of EOLs.
   BC04: Output file with an extremely long line.
   BC05: 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@>

@<FWDevMan subheading@>@(Platform-Specific Changes@)

@<Boldthing@>@(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.

@<Nav@>@(@<Misc_versions FILE@>@,@<Misc FILE@>@,@<Misc_suggestions FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Misc_suggestions HEADING@>@M@{@<SH@>@(5.3@)Suggestions From Users@}
@$@<Misc_suggestions FILE@>@M@{misc_suggestions.html@}
@O@<misc_suggestions.html@>@{@-
@<Begin FWDevMan page/wide/H1@>@(@<Misc_suggestions HEADING@>@)

@<P@>This page contains a list of features that FunnelWeb
users have suggested. The fact that a suggestion has been
made does not automatically mean that I agree with it or
that it will be implemented one day. However, most of the
suggestions are sound.

@<P@>The number in square brackets after each suggestion
indicates the number of users who have suggested the
feature.

@<P@>A quick look at this list suggests that future work on
FunnelWeb should be mainly directed towards improving its
typesetting facilities.

@<P@>
@<Begin verbatim@>
General
-------
S: Integrate FW into the Borland C++ development environment. [1]
S: Add a feature for updating FW source files after the product
   files have been modified. [1]

Documentation
-------------
S: Improve the typesetting of the index. [1]
S: Add more entries to the index. [1]
S: Add a quick reference guide. [1]

Scanner
-------
S: Fix the bug that makes FunnelWeb bomb on excceptionally long input
   lines. [1]
S: If a closing @@} occurs at the start of a line, eliminate the
   preceeding end of line. [1]
S: Allow TABS [1].
S: The syntax is ugly. Redesign it. [2]

Parser
------
S: Add named parameters for macros. [1]
S: Add conditionals. [1]
S: Add a feature that enables the user to specify that all the
   macros called within a particular macros be defined in the order
   in which they are called. [1]

Tangle
------
S: Allow line-oriented substitution and so on rather than stream
   oriented. [1]

Weave
-----
S: Don't typeset non-leaf macros. This will avoid clutter. [1]
S: Teach FW C++ so it can typeset it nicely. [1]
S: Allow both FW text and TeX in the same document (two modes). [1]
S: Include greater support for typesetting a program as a book. [1]
   "What we need is a facility for TANGLING small WEB files
    into small source files, but WEAVING those same small
    WEB files into a single large documentation file, without
    the seams becoming apparent."
S: Add a new format: Microsoft Rich Text Format (RTF). [2]
S: Write a program to convert an RTF file into FunnelWeb source.
   Then people can edit programs in MSWord and run them through
   FunnelWeb. [1]
S: Detailed notes on indexing from one user: [1]
S: Add the ability to include typeset comments within program text. [2]
   R: The @@[..@@] syntax has been reserved for this.
S: Add a new format: LaTeX. [1]
S: Add a new format: Plain ASCII text. [1]
S: Add a GENERIC language typesetting facility: [1]

   "Have you seen the program 'vgrind' (for TeX) or 'psgrind' (for
    PostScript)?  It contains a termcap-like database of programming
    language features, e.g. format of a label, format of a
    producedure/function, keyword listings, character string quoting
    rules, etc.  Perhaps this would be useful for FW?"

S: Automatically generate an index. [1]
S: Allow @@" and @@" in documentation to typeset double quotes properly. [1]
S: Detailed comments from one correspondent:
   "The ability to generate a cross reference of identifiers
   (variables and functions) is essential.

   Constants       are generally defined only in 1 place
                   and so a cross reference to the definition
                   macro is useful.

   Variables       are generally declared in 1 place but
                   refered to and defined in multiple places.
                   A cross reference to the declaration site
                   is generally not useful.

                   A cross reference to the site of use is
                   confusing, since there may be many, equally
                   important sites where the variable is assigned
                   a value.

   functions       are generally unique and so a cross reference
                   to the site of definition (or declaration in
                   the absense of a definition) is useful.

   In FWEB (which I have used extensively recently) each instance
   of use of an identifier contains a subscript which points
   to the site of definition of the identifier (I think this
   is what you refer to in the documents as a feature of the
   original WEB.)  The fact that locating identifiers requires
   knowledge of the programming language is true."

Documentation
-------------
   Page 34, section 1.7.2, paragraph 2, last sentence:
           "free text be default" should be "free text by default".

   Page 34, section 1.7.3, paragraph 1, 1st sentence:
           "divide and conquor" should be "divide and conquer"

   Page 35, section 1.73, paragraph 2 on page 35:
           "section heading at level n cannot....at level (n-1) or less."
           I think this should be:
           "section heading at level n cannot.. at less than level (n-1)"
           Otherwise you are saying that level C cannot occur at B or less.

   Page 50, section 2.11, last paragraph, line 10 of para:
           "excessibly" should be "excessively"

   In the example on p. 21, "... the string ``Hello World''" looks like a TeX
   dependent hangover.

   The caption under Fig. 4, p.111 came out badly spaced on our system.

   Isn't it `holistic' rather than `wholistic?'

   There is often a need to have version dependent documentation as well
   as version dependent code.  It would be nice if there was a special
   kind of macro that could run the output to a file through the
   typesetter, i.e., generate TeX files.  Meanwhile, you can get some
   interesting effects by letting FunnelWeb generate .fw files!  You
   might like to mention this exciting possibility in V2 of the user
   manual.
@<End verbatim@>

@<Nav@>@(@<Misc_wishlist FILE@>@,@<Misc FILE@>@,@<Misc_knownbugs FILE@>@)

@<End FWDevMan page@>
@}

@!==============================================================================

@$@<Misc_knownbugs HEADING@>@M@{@<SH@>@(5.4@)Known Bugs@}
@$@<Misc_knownbugs FILE@>@M@{misc_knownbugs.html@}
@O@<misc_knownbugs.html@>@{@-
@<Begin FWDevMan page/wide/H1@>@(@<Misc_knownbugs HEADING@>@)

@<FWDevMan subheading@>@(FunnelWeb 3.2 (May 1999)@)

@<P@>A bug exists, at least in the Macintosh version, where FunnelWeb V3.2
hangs when fed the following file:

@<P@>
@<Begin verbatim@>
@=#
@O@&lt;X@&gt;@{@&lt;Y@&gt;@}
@$@&lt;Y@&gt;@M@{@&lt;Z@&gt;@(@&lt;Y@&gt;@)@}
@$@&lt;Z@&gt;@(@1@)@{@1@}
#=@
@<End verbatim@>

@<P@>FunnelWeb has always (since V1 in 1986) had macro
recursion detection, but it appears to fail in this case.
You can workaround this bug by eliminating all recursive
macro invocations.

@<P@>
@<HR@>

@<P@>A bug exists in the output line length monitoring of
FunnelWeb V3.2. If you set the pragma @<TT@>@(indentation
= none@), FunnelWeb still counts the output line lengths
as if they are being indented, even though they aren't.
You can workaround this by ignoring the output file line
length errors or by setting:

@<P@>
@<Begin verbatim@>
@@p maximum_output_line_length = infinity
@<End verbatim@>

@<P@>The following source code patch has been proposed, but
not yet tested:

@<P@>
@<Begin verbatim@>
In tangle.c, the code:

     /* Output an EOL with indentation if desired. */
     if (tgindent)
        eolblank(ind_base);
     else
        wf_chr(&f_o,EOL);
     ind_curr=ind_base;

should be changed to:

     /* Output an EOL with indentation if desired. */
     if (tgindent)
       { eolblank(ind_base); ind_curr=ind_base; }
     else
       { wf_chr(&f_o,EOL); ind_curr=0; }
@<End verbatim@>

@<Nav/last@>@(@<Misc_suggestions FILE@>@,@<Misc FILE@>@,@<Misc FILE@>@)

@<End FWDevMan page@>
@}

@!******************************************************************************

@$@<Copyright FILE@>@M@{copyright.html@}
@O@<copyright.html@>@{@-
@<Begin FWDevMan page/H1@>@(Copyright and Credits@)

@<FunnelWeb webs copyright page contents@>

@<End FWDevMan page@>
@}

@!******************************************************************************

@$@<GPL HEADING@>@M@{@<SH@>@(6@)GNU General Public License Version 2@}
@$@<GPL HEADING/short@>@M@{@<SH@>@(6@)Licence@}
@$@<GPL FILE@>@M@{gpl.html@}
@O@<gpl.html@>@{@-
@<Begin FWDevMan page/wide/H1@>@(@<GPL HEADING@>@)

@<P@>This page contains a verbatim copy of Version@<_@>2 of the GNU
General Public License under which the FunnelWeb computer program is
released. Note that the FunnelWeb documentation is released and
under a much simpler license that does not allow modifications.

@<P@>
<HR>

@<P@>
@<Begin verbatim@>
            GNU GENERAL PUBLIC LICENSE
               Version 2, June 1991

 Copyright (C) 1989, 1991 Free Software Foundation, Inc.
                          675 Mass Ave, Cambridge, MA 02139, USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

                 Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

  The precise terms and conditions for copying, distribution and
modification follow.

            GNU GENERAL PUBLIC LICENSE
   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License.  The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language.  (Hereinafter, translation is included without limitation in
the term "modification".)  Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

  1. You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.

You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.

  2. You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

    a) You must cause the modified files to carry prominent notices
    stating that you changed the files and the date of any change.

    b) You must cause any work that you distribute or publish, that in
    whole or in part contains or is derived from the Program or any
    part thereof, to be licensed as a whole at no charge to all third
    parties under the terms of this License.

    c) If the modified program normally reads commands interactively
    when run, you must cause it, when started running for such
    interactive use in the most ordinary way, to print or display an
    announcement including an appropriate copyright notice and a
    notice that there is no warranty (or else, saying that you provide
    a warranty) and that users may redistribute the program under
    these conditions, and telling the user how to view a copy of this
    License.  (Exception: if the Program itself is interactive but
    does not normally print such an announcement, your work based on
    the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.

In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

  3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:

    a) Accompany it with the complete corresponding machine-readable
    source code, which must be distributed under the terms of Sections
    1 and 2 above on a medium customarily used for software interchange; or,

    b) Accompany it with a written offer, valid for at least three
    years, to give any third party, for a charge no more than your
    cost of physically performing source distribution, a complete
    machine-readable copy of the corresponding source code, to be
    distributed under the terms of Sections 1 and 2 above on a medium
    customarily used for software interchange; or,

    c) Accompany it with the information you received as to the offer
    to distribute corresponding source code.  (This alternative is
    allowed only for noncommercial distribution and only if you
    received the program in object code or executable form with such
    an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for
making modifications to it.  For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable.  However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.

If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.

  4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

  5. You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Program or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.

  6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

  7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all.  For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

  8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded.  In such case, this License incorporates
the limitation as if written in the body of this License.

  9. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

Each version is given a distinguishing version number.  If the Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation.  If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.

  10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.

                NO WARRANTY

  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.

          END OF TERMS AND CONDITIONS

   Appendix: How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.

  To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

    @<<@>one line to give the program's name and a brief idea of what it does.@<>@>
    Copyright (C) 19yy  @<<@>name of author@<>@>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

    Gnomovision version 69, Copyright (C) 19yy name of author
    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
    type `show w'.
    This is free software, and you are welcome to redistribute it
    under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License.  Of course, the commands you use may
be called something other than `show w' and `show c'; they could even be
mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary.  Here is a sample; alter the names:

  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
  `Gnomovision' (which makes passes at compilers) written by James Hacker.

  @<<@>signature of Ty Coon@<>@>, 1 April 1989
  Ty Coon, President of Vice

This General Public License does not permit incorporating your program into
proprietary programs.  If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library.  If this is what you want to do, use the GNU Library General
Public License instead of this License.
@<End verbatim@>

@<Nav/last@>@(@<Misc FILE@>@,@<Index FILE@>@,@<Index FILE@>@)

@<End FWDevMan page@>
@}

@!******************************************************************************

@B@<Search Form Section@>

The files in this section are all linked in with the FunnelWeb
include file.

@O@<search.html@>@{@-
@<Begin FWDevMan page/H1@>@(Search FunnelWeb Documentation@)

@<FunnelWeb search form@>@(@,@,@,checked@)

@<End FWDevMan page@>
@}

@!==============================================================================

@O@<search_form.cgi@>@{@-
@<FunnelWeb search CGICODE@>
@}

@!==============================================================================

@O@<search_head.txt@>@{@-
@<Begin FWDevMan page/H1@>@(Search Results@)
@<P@>
@}

@!==============================================================================

@O@<search_tail.txt@>@{@-
@<BR@>
@<P@>@<Back button@>@(Back To The Search Form@)
@<BR@>

@<End FWDevMan page@>
@}

@!==============================================================================

@O@<search_e_nokeywords.txt@>@{@-
@<Begin FWDevMan page/H1@>@(Error: No Keywords Specified@)

@<P@>You must specify one or more keywords to perform a search.

@<P@>@<Back button@>@(Back To The Search Form@)

@<End FWDevMan page@>
@}

@!==============================================================================

@O@<search_e_nomanual.txt@>@{@-
@<Begin FWDevMan page/H1@>@(Error: No Manual Selected@)

@<P@>You must specify one or more manuals (using the checkboxes) to
perform a search.

@<P@>@<Back button@>@(Back To The Search Form@)

@<End FWDevMan page@>
@}

@!******************************************************************************

@O@<0cleanup.vxf@>@{@-
eneo *.html
eneo *.shtml
eneo *.cgi
eneo *.txt
eneo *.lis
eneo *.pl
@}

@!******************************************************************************
@!******************************************************************************

@! Include the FunnelWeb webs master include file.
@! Specify a platform-specific relative (or absolute) path to the include file.
@! Unix    : @i ../0fw_inc.fwi
@! MacOS   : @i ::0fw_inc.fwi
@! OpenVMS : @i [-]0fw_inc.fwi

@i ../0fw_inc.fwi
@i ../0www_style.fwi
@i ../0www_links.fwi
@i ../0www_ross.fwi

@!******************************************************************************
@!******************************************************************************