File: 0fw_tut.fw

package info (click to toggle)
funnelweb-doc 3.2d-4.2
links: PTS
area: main
in suites: forky, sid, trixie
size: 3,744 kB
sloc: perl: 241; makefile: 23
file content (6445 lines) | stat: -rw-r--r-- 224,800 bytes
parent folder | download | duplicates (5)
@!345678901234567890123456789012345678901234567890123456789012345678901234567890
@!******************************************************************************

@t vskip 50 mm
@t title titlefont centre "FunnelWeb Tutorial Manual Web"
@t vskip 10 mm
@t title smalltitlefont centre "by Ross N. Williams"
@t title smalltitlefont centre "18 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 Tutorial Manual Web@>

This document contains the FunnelWeb source for the
FunnelWeb tutorial 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@{
18-Apr-1999 RNW Converted original 1992 FunnelWeb manual to this web (+ref web).
08-May-1999 RNW Documented new HTML +u option.
12-May-1999 RNW Documented @@L library feature.
13-May-1999 RNW Added the chapter on webmaking.
29-Dec-1999 RNW Added sidebar image strut to stop it collapsing.
30-Dec-1999 RNW Added the HTML style page.
30-Dec-1999 RNW Added the emacs mode page.
30-Dec-1999 RNW Changed manual version number scheme.
31-Dec-1999 RNW Tweaked the wholistic debugging page.
03-Jan-2000 RNW Changed copyright permission 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@<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@<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,0,0).

Title
   Bookman Black SSi, 20pt, Antialias


@}

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

@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 Tutorial WWW@>@Z@M@{@}
@$@<FunnelWeb Reference WWW@>@Z@M@{../reference/@}
@$@<FunnelWeb Developer WWW@>@Z@M@{../developer/@}

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

@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 FWTutMan 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 FWTutMan 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 FWTutMan 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 Developer WWW@>index.html@,@<FunnelWeb Developer WINDOWNAME@>@,Developer@)
@<BR@>
@<SideLink/bold@>@(@<FunnelWeb Tutorial WWW@>index.html@,Tutorial@)
@<SideLink@>@(@<Intro FILE@>@,@<Intro HEADING/short@>@)
@<SideLink@>@(@<Macro FILE@>@,@<Macro HEADING/short@>@)
@<SideLink@>@(@<Type FILE@>@,@<Type HEADING/short@>@)
@<SideLink@>@(@<Example FILE@>@,@<Example HEADING/short@>@)
@<SideLink@>@(@<Hints FILE@>@,@<Hints HEADING/short@>@)
@<SideLink@>@(@<Examples FILE@>@,@<Examples HEADING/short@>@)
@<SideLink@>@(@<Web FILE@>@,@<Web HEADING/short@>@)

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

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

@$@<Begin FWTutMan page/H1@>@(@1@)@Z@M@{
<HTML>
@<Header comment@>
<HEAD>
<TITLE>@1</TITLE>
@<Suppress hyperlink underlining@>
</HEAD>
@<Body@>
@<Begin FWTutMan margin@>
@<RunningHeader IMAGE@>
@<FWTutMan heading@>@(@1@)
@}

@$@<Begin FWTutMan page/wide/H1@>@(@1@)@Z@M@{
<HTML>
@<Header comment@>
<HEAD>
<TITLE>@1</TITLE>
@<Suppress hyperlink underlining@>
</HEAD>
@<Body@>
@<Begin FWTutMan margin/wide@>
@<RunningHeader IMAGE@>
@<FWTutMan heading@>@(@1@)
@}

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

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

</BODY>

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

@$@<Page title prefix@>@Z@M@{@}

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

@B@<Images@>

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

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

@B@<General Macros@>

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

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

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

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

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

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


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

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

<META NAME="keywords"
 CONTENT="funnelweb,FunnelWeb,funnel,web,
          tutorial,manual,tutorial 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 Tutorial Manual@}
@$@<Index FILE@>@M@{index.html@}
@O@<index.html@>@{@-
<HTML>

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

@<Body@>

@<Begin FWTutMan margin@>

@<RunningHeader IMAGE@>

@<FunnelWeb manual version notice@>

@<P@>@<Bigger@>@(T@)HIS TUTORIAL MANUAL provides a friendly
introduction to the FunnelWeb literate programming
preprocessor

@<P@>This Tutorial Manual does not provide a definitive
description of FunnelWeb, so if you have a specific technical
question, you should refer to the @<FunnelWeb Reference Manual@>,
which is definitive. To perform a keyword search
of the Reference Manual and/or this Tutorial manual, click
on SEARCH in the margin.

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

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

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

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

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

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

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

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

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

@<End FWTutMan page@>
@}

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

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

@$@<Intro HEADING@>@M@{@<SH@>@(1@)Introduction@}
@$@<Intro HEADING/short@>@M@{@<SH@>@(1@)Introduction@}
@$@<Intro FILE@>@M@{intro.html@}
@O@<intro.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Intro HEADING@>@)

@<P@>

@<Intro index@>

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

@<End FWTutMan page@>
@}

@$@<Intro index@>@M@{
@<Begin size3@>
@<Begin indent/narrow@>
@<Link@>@(@<Intro_what FILE@>@,@<Intro_what HEADING@>@)@<BR@>
@<Link@>@(@<Intro_whatfw FILE@>@,@<Intro_whatfw HEADING@>@)@<BR@>
@<Link@>@(@<Intro_name FILE@>@,@<Intro_name HEADING@>@)@<BR@>
@<Link@>@(@<Intro_tutorial FILE@>@,@<Intro_tutorial HEADING@>@)@<BR@>
@<Link@>@(@<Intro_hello FILE@>@,@<Intro_hello HEADING@>@)@<BR@>
@<End indent/narrow@>
@<End size3@>
@}

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

@$@<Intro_what HEADING@>@M@{@<SH@>@(1.1@)What Is Literate Programming?@}
@$@<Intro_what FILE@>@M@{intro_what.html@}
@O@<intro_what.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Intro_what HEADING@>@)
@<X@>@(literate programming@)

@<P@>A traditional computer program consists of a text file
containing program code. Scattered in amongst the program
code are comments which describe the various parts of the
code.

@<P@>In @<NewTerm@>@(literate programming@) the emphasis is
reversed. Instead of writing code containing documentation,
the literate programmer writes documentation containing
code. No longer does the English commentary injected into a
program have to be hidden in comment delimiters at the top
of the file, or under procedure headings, or at the end of
lines. Instead, it is wrenched into the daylight and made
the main focus. The @<DQ@>@(program@) then becomes primarily
a document directed at humans, with the code being herded
between @<DQ@>@(code delimiters@) from where it can be
extracted and shuffled out sideways to the language system
by literate programming tools.

@<P@>The effect of this simple shift of emphasis can be so
profound as to change one's whole approach to programming.
Under the literate programming paradigm, the central
activity of programming becomes that of conveying meaning to
other intelligent beings rather than merely convincing the
computer to behave in a particular way. It is the difference
between performing and exposing a magic trick.@<X@>@(magic
trick@)

@<P@>In order to program in a literate style, particular
tools are required.@<XX@>@(tools@,literate programming@) The
traditional approach (used in the FunnelWeb system) is to
have some sort of text-file-in/text-file-out utility that
reads a literate program (containing a program commentary
peppered with scraps of program text) and writes out a file
containing all the program code and a file containing
typesetter commands representing the entire input document,
documentation, code, and all. See the diagram below.

@<P@>
@<Begin verbatim@>
      +-----------------------------------------+
      | File containing the program description |
      | peppered with scraps of program code.   |
      | This is what the programmer works on.   |
      |          (e.g. sloth.web)               |
      +-----------------------------------------+
                         |
                         v
           o---------------------------o
           | Literate Programming Tool |
           o---------------------------o
                         |
            +------------+-------------+
            |                          |
            v                          v
   +------------------+   +--------------------------+
   |   Traditional    |   | Documentation file       |
   | Computer Program |   | (e.g. sloth.tex)         |
   |  (e.g. sloth.c)  |   | (e.g. sloth.html)        |
   +------------------+   +--------------------------+

@<End verbatim@>
@<CaptionTitle@>@(Traditional architecture of literate programming tools.@)
@<Begin blockquote@>
@<Begin size2@>
Literate programming tools could be organized in a number of
ways. However, to fit in with current file and command line
based environments, most tools conform to the traditional
architecture shown here in which the user feeds in a file
containing a literate program, and the literate programming
utility generates program files and a documentation file.
@<End size2@>
@<End blockquote@>

@<P@>Given the coming age of hypertext@<X@>@(hypertext@)
systems, this is probably not the best approach. However, it
does mesh beautifully with current text files and command
line interfaces, the expectation of linear presentations in
the documents we read, and the particular requirements of
current programming languages and typesetting systems. It is
certainly not a bad approach.

@<P@>With this structure in place, the literate programming
system can provide far more than just a reversal of the
priority of comments and code. In its full blown form, a
good literate programming facility can provide total support
for the essential thrust of literate programming, which is
that computer programs should be written more for the human
reader than for the compiler. In particular, a literate
programming system can provide:@<XS@>@(literate
programming@,facilities@)

@<Narrowthing@>@(Re-ordering of code:@,Programming languages
often force the programmer to give the various parts of a
computer program in a particular
order.@<XX@>@(program@,ordering@) For example, the
Pascal@<X@>@(Pascal@) programming language@<Paper@>@(BSI82@)
imposes the ordering: constants, types, variables,
procedures, code. Pascal also requires that procedures
appear in an order consistent with the partial ordering
imposed by the static call graph (but forward declarations
allow this to be bypassed). In contrast, the literate style
requires that the programmer be free to present the computer
program in any order whatsoever. The facility to do this is
implemented in literate programming tools by providing text
@<I@>@(macros@) that can be defined and used in any order.@)

@<Narrowthing@>@(Typeset code and
documentation:@,Traditionally program listings are dull
affairs consisting of pages of fan-form paper imprinted with
meandering coastlines of structured text in a boring font.
In contrast, literate programming systems are capable of
producing documentation that is superior in two ways. First,
because most of the documentation text is fed straight to
the typesetter, the programmer can make use of all the power
of the underlying typesetter, resulting in documentation
that has the same presentation as an ordinary typeset
document. Second, because the literate programming utility
sees all the code, it can use its knowledge of the
programming language and the features of the typesetting
language to typeset the program code as if it were appearing
in a technical journal. It is the difference between:@)

@<P@>
@<Begin verbatim@>
    while sloth@<<@>walrus loop
       sloth:=sloth+1;
    end loop
@<End verbatim@>

and

@<Begin indent@>
@<B@>@(while@) @<I@>@(sloth@)@<<@>@<I@>@(walrus@) @<B@>@(loop@)@<BR@>
@<_@>@<_@>@<_@>@<_@>@<_@>@<_@>@<I@>@(sloth@)=@<I@>@(sloth@)+1;@<BR@>
@<B@>@(end@) @<B@>@(loop@)
@<End indent@>

@<P@>Unfortunately, while FunnelWeb provides full
typesetting of the documentation, it typesets all of its
code in the style of the first of these two examples. To
typeset in the style of the second requires knowledge of the
programming language, and the current version of FunnelWeb
is programming language independent. At a later stage, it is
possible that FunnelWeb will be modified to read in a file
containing information about the target programming language
to be used to assist in typesetting the code properly.

@<Narrowthing@>@(Cross referencing:@,Because@<X@>@(cross
referencing@) the literate tool sees all the code and
documentation, it is able to generate extensive cross
referencing information in the typeset documentation. This
makes the printed program document more easy to navigate and
partially compensates for the lack of an automatic searching
facility when reading printed documentation.@)

@<P@>In the end, the details don't matter. The most
significant benefit that literate programming offers is
@<I@>@(its capacity to transform the state of mind of the
programmer@).@<XS@>@(literate programming@,most significant
benefit@) It is well known that the act of explaining
something can transform one's understanding of it. This is
one of the justifications behind the powerful combination of
research and teaching in
universities @<Paper@>@(Rosovsky90@).@<X@>@(universities@)
Similarly, by constantly explaining the unfolding program
code in English to an imaginary reader, the programmer
transforms his perception of the code, laying it open,
prone, to the critical eye.@<XX@>@(explaining@,code@)

@<P@>The result of this exposure is a higher quality of
programming. When exposed to the harsh light of the literate
eye, bugs crawl out, special cases vanish, and sloppy code
evaporates. As a rule, literate programs take longer to write
than ordinary programs, but the total development
time@<XX@>@(development@,time@) is the same or less because
the time taken to write and document the program carefully
is compensated for by a reduced debugging and maintenance
time. Thus literate programming does not merely assist in
the preparation of documentation, but also makes significant
contributes to the process of programming itself. In
practice this has turned out to be a contribution far more
important than the mere capacity to produce typeset
documentation.

@<P@>For more information on literate programming, the
reader is directed to Knuth's early founding work
@<Paper@>@(Knuth83@) and @<Paper@>@(Knuth84@). For more
recent information refer to @<Paper@>@(Smith91@), which
provides a comprehensive bibliography up to 1990.


@<Nav/first@>@(@<Intro FILE@>@,@<Intro FILE@>@,@<Intro_whatfw FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Intro_whatfw HEADING@>@M@{@<SH@>@(1.2@)What Is FunnelWeb?@}
@$@<Intro_whatfw FILE@>@M@{intro_whatfw.html@}
@O@<intro_whatfw.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Intro_whatfw HEADING@>@)
@<XX@>@(FunnelWeb@,overview@)

@<P@>FunnelWeb is a particular literate programming system
that is implemented by a single C program. FunnelWeb takes
as input a single @<TT@>@(.fw@) @<NewTerm@>@(input file@)
and writes one or more @<NewTerm@>@(product files@) and a
@<NewTerm@>@(documentation file@) (see below).

@<P@>
@<Begin verbatim@>
                   +-----------+
                   | sloth.fw  |
                   +-----------+
                         |
                         v
               o-------------------o
               | FUNNELWEB Program |
               o-------------------o
                         |
             +-----------+-----------+
             |                       |
             v                       v
     +----------------+    +--------------------+
     |  Product File  |    | Documentation File |
     | (e.g. sloth.c) |    | (e.g. sloth.html)  |
     |                |    | (e.g. sloth.tex)   |
     +----------------+    +--------------------+

@<End verbatim@>
@<CaptionTitle@>@(Architecture of FunnelWeb.@)

@<P@>In literate programming systems, it is usual to refer
to the product file as a @<DQ@>@(program file@). However, as
FunnelWeb is a general tool that can be used to prepare all
sorts of text files that are not computer programs, the more
generic term @<DQ@>@(product file@) was chosen. Product
files should be carefully distinguished from the term
@<NewTerm@>@(output files@) which refers to all of the
output files produced by FunnelWeb.

@<P@>FunnelWeb is distinguished by the following
characteristics:

@<Narrowthing@>@(Simplicity:@,A@<X@>@(simplicity@) governing
design goal of FunnelWeb is to provide a @<I@>@(simple@)
tool that could be easily learnt and completely mastered.
This manual is thick because it is comprehensive and lingers
on the ways in which FunnelWeb can be used. The tool itself
is quite simple.@)

@<Narrowthing@>@(Reliability:@,Another@<X@>@(reliability@)
design goal is to provide a tool that will protect the user
as much as possible from silly errors. Macro preprocessors
are notorious for causing obscure errors. Every attempt has
been made in FunnelWeb to keep the syntax robust. For
example, in FunnelWeb the syntax of macro calls has been
purposely designed to be highly visible so that the reader
is always aware when the macro facility is being invoked.@)

@<Narrowthing@>@(Language and Typesetter
Independence:@,Unlike Knuth's
original@<XX@>@(language@,independence@)@<XX@>@(typesetter@,independence@)
Web system which was specific to the Pascal programming
language@<Paper@>@(BSI82@) and the TeX typesetting
language@<Paper@>@(Knuth84@), FunnelWeb strives to be
language and typesetter independent.
FunnelWeb is completely language independent. FunnelWeb
input files can be typesetter independent too, and
FunnelWeb can generate documentation in TeX and HTML formats.@)

@<Narrowthing@>@(Portability:@,FunnelWeb@<X@>@(portability@)
has been written in the C programming language with great
emphasis on portability. FunnelWeb currently runs on the
Sun, OpenVMS, IBM PC, and Mac.@)

@<Narrowthing@>@(Controllable:@,FunnelWeb@<X@>@(controllability@)
is an extremely controllable tool. To protect users'
investment in source files constructed in the FunnelWeb
macro language, the C source code to FunnelWeb has been
released under a GNU General Public License
(GPL).@<XX@>@(GNU@,license@) This means
that it will always be available to everyone. Furthermore,
license has been granted for the FunnelWeb User's Manual to
be copied freely so long as they are not modified. All this
means that FunnelWeb is not going to disappear suddenly.@)

@<Narrowthing@>@(A Production Tool:@,Above@<X@>@(production
tool@) all, FunnelWeb has been designed to be a production
tool and every effort has been made to ensure that it will
operate effectively in a professional environment. FunnelWeb
is @<DQ@>@(open@) and portable. There is a comprehensive
user manual. Its error messages are comprehensive. It is
fast. Finally, it has been designed with the experience of
three years of using FunnelWeb@<_@>V1.@)

@<Nav@>@(@<Intro_what FILE@>@,@<Intro FILE@>@,@<Intro_name FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Intro_name HEADING@>@M@{@<SH@>@(1.3@)The Name FunnelWeb@}
@$@<Intro_name FILE@>@M@{intro_name.html@}
@O@<intro_name.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Intro_name HEADING@>@)
@<XX@>@(FunnelWeb@,name@)

@<P@>The name @<DQ@>@(FunnelWeb@) was chosen because it
contains the name @<DQ@>@(WEB@), which is the name of
Knuth's system. It was also chosen because it has a
distinctly Australian flavour.

@<P@>Funnel-web spiders@<XX@>@(Funnel-web@,spider@) are
found in Northern and Eastern Australia. They are about
three to four centimetres long and are very poisonous. The
Sydney@<X@>@(Sydney@) Funnel-web spider (@<I@>@(Atrax
robustus@)@<X@>@(Atrax robustus@)), common in Sydney, has
caused the most trouble and has been responsible for several
deaths. Funnel-web spiders love to crawl into temporarily
discarded shoes where they later react in a hostile manner
to an unsuspecting foot. They are known to hang on once they
sink their fangs in. Funnel-web spiders derive their name
from the shape of their webs which are horizontally-aligned
narrowing tubes, open at one end@<Paper@>@(ANZE@).

@<P@>The Funnel-web spider, like the tiger
snake@<XX@>@(tiger@,snake@) and the white pointer
shark,@<XX@>@(white pointer@,shark@) is secretly regarded by
Australians as a kind of national
treasure.@<XN@>@(Edna@,Everage@)@<XN@>@(Barry@,Humphries@)

@<P@>
@<Begin indent@>
@<B@>@(F@) is for Funnel-web@<BR@>
Our furry-legged foe.@<BR@>
He sleeps in your slipper@<BR@>
And breakfasts on toe.@<BR@>
--- One verse from @<I@>@(A Megastar's Mantras: Things that Mean a Lot to Me@),@<BR@>
@<_@>@<_@>@<_@>@<_@>@<_@>@<_@>@<_@>by Dame Edna Everage@<Paper@>@(Humphries91@).@<BR@>
@<End indent@>

@<Nav@>@(@<Intro_whatfw FILE@>@,@<Intro FILE@>@,@<Intro_tutorial FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Intro_tutorial HEADING@>@M@{@<SH@>@(1.4@)Using These Tutorials@}
@$@<Intro_tutorial FILE@>@M@{intro_tutorial.html@}
@O@<intro_tutorial.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Intro_tutorial HEADING@>@)
@<X@>@(tutorial@)@<XX@>@(tutorial@,introduction@)

@<P@>Much of the rest of this manual consists of
introductory tutorials on FunnelWeb. Ideally you should have
a working version of FunnelWeb in front of you so that you
can try out the examples yourself. There is no need to try
all the examples, so long as you type in enough to feel
comfortable with what you are reading.

@<P@>For best effect, you should create a new, temporary,
empty directory in which to experiment with FunnelWeb. That
way, it will be more obvious when FunnelWeb creates an
output file. You can either type in the examples in this
chapter directly, or copy and paste them directly from
this manual or the FunnelWeb test suite. The test files called
@<TT@>@(ex01.fw@) through @<TT@>@(ex16.fw@) and
@<TT@>@(hi01.fw@) through @<TT@>@(hi10.fw@) contain the
examples in the manual.

@<P@>If you do not yet have an installed copy of FunnelWeb,
refer to the main @<FunnelWeb@> web for full details on how
to obtain and install a copy of FunnelWeb. If you are not
sure if you have an installed copy, try invoking FunnelWeb
by giving the command @<DQP@>@(fw@). If this yields an error
such as @<DQ@>@(command not found@) then you do not have a
properly installed version of FunnelWeb.

@<Nav@>@(@<Intro_name FILE@>@,@<Intro FILE@>@,@<Intro_hello FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Intro_hello HEADING@>@M@{@<SH@>@(1.5@)A Hello World Document@}
@$@<Intro_hello FILE@>@M@{intro_hello.html@}
@O@<intro_hello.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Intro_hello HEADING@>@)
@<X@>@(hello world document@)

@<P@>Just as one starts the process of learning a new
programming language with a @<DQ@>@(Hello World@) program,
when learning  FunnelWeb, you can start with a @<DQ@>@(Hello
World@) document. And here it is! Edit a text file called
@<TT@>@(hello.fw@) and put the following text in it. (Note:
The second character is the letter @<DQ@>@(Oh@), not the
digit @<DQ@>@(Zero@)).

@<P@>
@<Begin verbatim@>
@@O@@@<<@>hello.txt@@@<>@>@@{Hello World@@+@@}
@<End verbatim@>

@<P@>To @<DQ@>@(run@) this @<DQ@>@(program@), invoke
FunnelWeb using the @<DQP@>@(fw@) command as
follows.@<X@>@(invoking FunnelWeb@)

@<P@>
@<Begin verbatim@>
fw hello
@<End verbatim@>

@<P@>@<I@>@(If this command doesn't work, then chances are
that FunnelWeb has not been installed on your machine. Refer
to the main @<FunnelWeb@> web for full details on how to
obtain and install a copy of FunnelWeb.@)

@<P@>There should be no errors. If there are, have a look at
the listing file @<TT@>@(hello.lis@), which should contain
an explanation of the error, and compare the area in the
file where the error occurred with the text above. If there
are no errors, you will find that the following two files
have been created.

@<P@>
@<Begin verbatim@>
hello.lis   - The LISTING file.
hello.txt   - The PRODUCT file.
@<End verbatim@>

@<P@>Take a look at @<TT@>@(hello.txt@). It should contain a
single line with the text @<TT@>@(Hello World@). Let's take
another look at the input file.

@<P@>
@<Begin verbatim@>
@@O@@@<<@>hello.txt@@@<>@>@@{Hello World@@+@@}
@<End verbatim@>

@<P@>The whole structure of the input file is controlled by
@<DQP@>@(@@@), called the @<NewTerm@>@(special character@),
which introduces @<NewTerm@>@(special sequence@)s. A
scanner's-eye view of the command line looks like this:

@<P@>
@<Begin verbatim@>
@@O  @@@<<@>  "hello.txt"  @@@<>@>
@@{  "Hello World"  @@+  @@}
@<End verbatim@>

@<P@>The @<TT@>@(@@@) character controls everything. In this
file we have six different special sequences that together
form a single macro definition. The
@<TT@>@(@@@<<@>@)@<X@>@(@@@<<@>@) and
@<TT@>@(@@@<>@>@)@<X@>@(@@@<>@>@) delimit the name of the
macro. The @<TT@>@(@@O@)@<X@>@(@@O@) signals the start of
the macro definition and indicates that the macro is to be
connected to a product file with the same name as the macro
(This is is why we got a product file when we ran
FunnelWeb). The @<TT@>@(@@{@) and
@<TT@>@(@@}@)@<X@>@(@@braces@) delimit the body of the
macro. Finally, the @<TT@>@(@@+@)@<X@>@(@@+@) instructs that
an end of line sequence should be inserted at that point in
the product file.

@<P@>If you think this syntax looks messy, then you're
right. It @<I@>@(is@) messy. FunnelWeb @<I@>@(could@) have
employed a @<DQ@>@(simpler@) notation in which more of the
@<TT@>@(@@@) sequences were eliminated. For example:

@<P@>
@<Begin verbatim@>
Warning: This example is NOT legal FunnelWeb.

#hello.txt{Hello World+}
@<End verbatim@>

@<P@>However, if such a syntax were used, the user (you!)
would have to remember that @<TT@>@(#@) starts a new macro.
You would also have to remember that the characters
@<TT@>@(}@) and @<TT@>@(+@) cannot be used in a macro body
without a fuss. And so on. FunnelWeb is messier, but
provides one simple rule:@<XX@>@(simple@,rule@)
@<I@>@(Nothing special happens unless the special character
@<TT@>@(@@@) appears.@)

@<P@>This means that in FunnelWeb, you can look at large
blocks of text in the confidence that (unlike for the C
pre-processor@<XX@>@(C@,preprocessor@)) there are no macro
calls hidden in there. If there were, there would be an
@<TT@>@(@@@) character! (The only exception to this
rule occurs where the user has explicitly changed the
special character using the @<TT@>@(@@=@)@<X@>@(@@=@)
special sequence).

@<P@>Let's take another look at the hello world program.

@<P@>
@<Begin verbatim@>
@@O@@@<<@>hello.txt@@@<>@>@@{Hello World@@+@@}
@<End verbatim@>

@<P@>In its current form, it consists of a single macro
definition. This definition, while completely valid on its
own, only represents half the power of FunnelWeb. In fact
you could say that it is a @<DQ@>@(Hello Northern Hemisphere
Program@).@<X@>@(Hello Northern Hemisphere Program@) To turn
it into a proper FunnelWeb @<DQ@>@(Hello World@) program, we
need to add some documentation.

@<P@>A FunnelWeb input file consists of a sequence of macro
definitions surrounded by a sea of documentation which is
just ordinary text. Modify your hello world document so that
it looks like this:

@<P@>
@<Begin verbatim@>
This hello world document was
created by -insert your name here-.

@@O@@@<<@>hello.txt@@@<>@>@@{Hello World@@+@@}

It writes out a file called hello.txt
containing the string ``Hello World''.
@<End verbatim@>

@<P@>Now run it through FunnelWeb, but this time, add a
@<TT@>@(+t@) to the command line.

@<P@>
@<Begin verbatim@>
fw hello +t
@<End verbatim@>

@<P@>If all goes well, you should find that you now have

@<P@>
@<Begin verbatim@>
hello.lis   - A LISTING       file.
hello.tex   - A DOCUMENTATION file (in TeX format).
hello.txt   - A PRODUCT       file.
@<End verbatim@>

@<P@>Take a look at @<TT@>@(hello.txt@). You will find that
it is identical to the @<TT@>@(hello.txt@) of the previous
run. Only macro definitions affect the product files that
FunnelWeb produces (as a result of @<TT@>@(@@O@) macro
definitions). The surrounding documentation has @<I@>@(no@)
effect. In contrast, the new file, @<TT@>@(hello.tex@) (have
a look at it now) which was created as a result of your
adding the @<TT@>@(+t@) option contains a fairly full
representation of the input file. Whereas
@<TT@>@(hello.txt@) is the @<I@>@(product file@) of
FunnelWeb, @<TT@>@(hello.tex@) is the @<I@>@(documentation
file@).

@<P@>Try typesetting the documentation file now using the
TeX typesetting program.  Then print it. The following
commands are an example of the sort of commands you will
have to give to do this.

@<P@>
@<Begin verbatim@>
tex hello               ! Typeset the doc.
lpr -Pcslw -d hello.dvi ! Print the typeset doc.
@<End verbatim@>

@<P@>If you don't have TeX, you can generate an
HTML documentation file instead. Here's how:

@<P@>
@<Begin verbatim@>
fw hello +u
@<End verbatim@>

@<P@>The documentation should consist of single page containing
the two lines of documentation along with a typeset representation
of the macro. At this point, you have exercised the two main
aspects of FunnelWeb.@<XX@>@(FunnelWeb@,two main aspects@)
Starting with an input file containing macros (or in this
case macro) and documentation, you have successfully
generated a product file based on the macros, and a
documentation file, based on the entire document.

@<P@>The next two sections focus on FunnelWeb's macro
facilities and its typesetting facilities. By tradition, the
generation of program files from a literate text is called
@<NewTerm@>@(Tangling@), and the generation of typeset
documentation is called @<NewTerm@>@(Weaving@). In
FunnelWeb, these two functions are aspects of a single
computer program. However, in Knuth's WEB@<X@>@(WEB@)
system, the two functions are embodied in two separate
computer programs called Tangle and Weave, presumably
because, as everyone knows, @<DQ@>@(it takes two to
Tangle@).

@<Nav/last@>@(@<Intro_tutorial FILE@>@,@<Intro FILE@>@,@<Intro FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Macro HEADING@>@M@{@<SH@>@(2@)Macro Facilities Tutorial@}
@$@<Macro HEADING/short@>@M@{@<SH@>@(2@)Macros@}
@$@<Macro FILE@>@M@{macro.html@}
@O@<macro.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Macro HEADING@>@)
@<XX@>@(tutorial@,macro facilities@)

@<P@>
@<Macro index@>

@<Nav@>@(@<Intro FILE@>@,@<Index FILE@>@,@<Type FILE@>@)

@<End FWTutMan page@>
@}

@$@<Macro index@>@M@{
@<Begin size3@>
@<Begin indent/narrow@>
@<Link@>@(@<Macro_simple FILE@>@,@<Macro_simple HEADING@>@)@<BR@>
@<Link@>@(@<Macro_times FILE@>@,@<Macro_times HEADING@>@)@<BR@>
@<Link@>@(@<Macro_indent FILE@>@,@<Macro_indent HEADING@>@)@<BR@>
@<Link@>@(@<Macro_additive FILE@>@,@<Macro_additive HEADING@>@)@<BR@>
@<Link@>@(@<Macro_param FILE@>@,@<Macro_param HEADING@>@)@<BR@>
@<Link@>@(@<Macro_library FILE@>@,@<Macro_library HEADING@>@)@<BR@>
@<Link@>@(@<Macro_expansion FILE@>@,@<Macro_expansion HEADING@>@)@<BR@>
@<Link@>@(@<Macro_include FILE@>@,@<Macro_include HEADING@>@)@<BR@>
@<End indent/narrow@>
@<End size3@>
@}

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

@$@<Macro_simple HEADING@>@M@{@<SH@>@(2.1@)Simple Macros@}
@$@<Macro_simple FILE@>@M@{macro_simple.html@}
@O@<macro_simple.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Macro_simple HEADING@>@)
@<XX@>@(tutorial@,simple macros@)@<XX@>@(tutorial@,macros simple@)

@<P@>The original @<DQ@>@(Hello World@) program consisted of
a single macro definition.

@<P@>
@<Begin verbatim@>
@@O@@@<<@>hello.txt@@@<>@>@@{Hello World@@+@@}
@<End verbatim@>

@<P@>In fact, this is a rather exceptional macro, as it
causes its expansion to be written to a product file. The
@<TT@>@(@@O@)@<X@>@(@@O@) (for @<B@>@(O@)utput) signals this. In
FunnelWeb, most macros are defined using
@<TT@>@(@@$@).@<X@>@(@@dollar@) This  results in a macro
that does not generate a product file, but which can be
called in other macros (including @<TT@>@(@@O@) macros). Let
us expand the hello world program to include some other
macros.

@<P@>
@<Begin verbatim@>
@@O@@@<<@>hello.txt@@@<>@>@@{@@@<<@>Greetings@@@<>@>@@+@@}

@@$@@@<<@>H@@@<>@>==@@{Hello@@}
@@$@@@<<@>W@@@<>@>==@@{World@@}

@@$@@@<<@>Greetings@@@<>@>==@@{@@@<<@>H@@@<>@> @@@<<@>W@@@<>@>@@}
@<End verbatim@>

@<P@>Type in the file and run it through FunnelWeb using the command:

@<P@>
@<Begin verbatim@>
fw hello
@<End verbatim@>

@<P@>The product file (result.out) should look like this:

@<P@>
@<Begin verbatim@>
Hello World
@<End verbatim@>

@<P@>This short program illustrates some of the features of
ordinary macros in FunnelWeb. Consider the @<TT@>@(@@O@)
macro. Instead of containing straight text (@<DQ@>@(Hello
World@)), it now contains the macro call
@<TT@>@(@@@<<@>Greetings@@@<>@>@). A FunnelWeb macro can
be called from within the body of another macro just by
giving the macro name delimited in @<TT@>@(@@@<<@>@) and
@<TT@>@(@@@<>@>@).

@<P@>At the bottom of the file is the definition of the
@<TT@>@(@@@<<@>Greetings@@@<>@>@) macro. The definition
is similar to the definition of @<TT@>@(hello.txt@) except
that it starts with @<TT@>@(@@$@) to indicate that no
product file is desired from this macro (directly). It also
employs the optional @<TT@>@(==@) syntax which has no
semantic impact, but can be used to make definitions
clearer. The body of the
@<TT@>@(@@@<<@>Greetings@@@<>@>@) macro consists of
calls to the @<TT@>@(H@) and @<TT@>@(W@) macros which are
defined immediately above.

@<P@>Note that the macros are not constrained to be defined
in any particular order. One of the main features of
literate programming tools is that they allow the different
parts of the text document being developed (usually a
computer program) to be layed out in any
order.@<XX@>@(order@,program@)@<XX@>@(program@,layout@) So
long as there is a definition somewhere in the input file
for every macro call, FunnelWeb will sort it all out.

@<P@>In fact, FunnelWeb's macro facility is very
simple.@<XX@>@(macro@,bindings@) Unlike many macro
preprocessors which allow macros to define other macros,
FunnelWeb completely finishes parsing and analysing the
macros in the input file before it starts expanding them
into product files. Other preprocessors allow macros to be
redefined like variables (as in, say, TeX@<X@>@(TeX@))
taking on many different values as the macro pre-processor
travels through the input file. In contrast, FunnelWeb has
no concept of @<DQ@>@(different times@) and treats the input
as one huge static orderless, timeless, collection of
definitions. In FunnelWeb, there is only ever one time, and
so there can only ever be one value/definition for each
macro.

@<Nav@>@(@<Macro FILE@>@,@<Macro FILE@>@,@<Macro_times FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Macro_times HEADING@>@M@{@<SH@>@(2.2@)Number of Times Called@}
@$@<Macro_times FILE@>@M@{macro_times.html@}
@O@<macro_times.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Macro_times HEADING@>@)
@<X@>@(number of times called@)@<XX@>@(calls@,number@)@<XX@>@(invocation@,number@)

@<P@>So far we have seen only tiny, degenerate input files.
The next example moves up to the level of @<DQ@>@(trivial@),
but starts to convey the flavour of the way FunnelWeb can be
used in practice. Normally, there would be documentation
text appearing between the macros, but this has been omitted
so as to keep the focus on the macros themselves. Although
the next example is much longer than the previous example,
the only new construct is @<TT@>@(@@-@) which can appear
only at the end of a line, and suppresses
it,@<XX@>@(EOL@,suppression@) preventing it from appearing
in the text. The @<TT@>@(@@-@)@<X@>@(@@-@) construct allows
the text of a macro to be aligned at the left margin, rather
than having the first line hanging at the end of the
@<TT@>@(@@{@). FunnelWeb could have been set up so that
this end of line marker was suppressed. However, it would
have been a special case that would have broken the very
memorable rule @<DQ@>@(the text of a macro is the text
appearing between the @<TT@>@(@@{@) and @<TT@>@(@@}@)@).

@<P@>Type the following text into the file
@<TT@>@(hello.fw@) and run it through FunnelWeb. The file
contains some intentional errors so be sure to type it in
exactly and worry only if FunnelWeb @<I@>@(doesn't@)
generate some errors.

@<P@>
@<Begin verbatim@>
@@O@@@<<@>hello.c@@@<>@>==@@{@@-
@@@<<@>Include Files@@@<>@>
@@@<<@>Include Files@@@<>@>
@@@<<@>Main Program@@@<>@>
@@}

@@$@@@<<@>Main Program@@@<>@>==@@{@@-
main()
{
 doit();
}
@@}

@@$@@@<<@>Subroutine@@@<>@>==@@{@@-
void doit()
{
 int i;
 for (i=0;i@<<@>10;i++)
   {
    @@@<<@>Print@@@<>@>
    @@@<<@>Print@@@<>@>
   }
}@@}

@@$@@@<<@>Print@@@<>@>==@@{@@-
printf("Hello World!");
printf("\n");@@}

@@$@@@<<@>Scan@@@<>@>==@@{scanf@@}

@@$@@@<<@>Include Files@@@<>@>==@@{@@-
#include @<<@>stdio.h@<>@>
#include @<<@>stdlib.h@<>@>@@}
@<End verbatim@>

@<P@>What happened? Well, if you haven't typed the file in
properly, you may get some miscellaneous syntax errors. Fix
these before continuing. If the file has been correctly
typed, you should be faced with some error messages to do
with the number of times some of the macros are called.

@<P@>By default, FunnelWeb insists that each macro defined
is invoked exactly once. However, the file above defines
macros that are used more than once and a macro that is not
used at all. Let us examine the errors.

@<P@>First, we see that FunnelWeb has alerted us to the fact
that the @<TT@>@(Include Files@) macro has been called
twice. Once alerted to this, a quick look at the program
convinces us that calling the macro twice is a mistake, and
that one of the calls should be deleted.

@<P@>Second, we note that FunnelWeb has alerted us to the
fact that the @<TT@>@(@@@<<@>subroutine@@@<>@>@) macro
is never called. Again, a quick look at the program tells us
that this is a mistake (and a very common one in the use of
FunnelWeb), and that a call to the
@<TT@>@(@@@<<@>subroutine@@@<>@>@) macro should be
inserted just above the call to the @<TT@>@(@@@<<@>Main
Program@@@<>@>@) macro in the definition of
@<TT@>@(@@@<<@>hello.c@@@<>@>@).

@<P@>These two cases demonstrate why these checks have been
placed in FunnelWeb. It is nearly always acceptable for a
macro to be called once. However, if a macro is not called
at all, or called more than once, this is often a sign that
the user has made a mistake.

@<P@>These checks have a dark side too. In addition to the
errors mentioned above, FunnelWeb has generated two similar
errors that do not help us.

@<P@>First, we are alerted to the fact that the
@<TT@>@(@@@<<@>print@@@<>@>@) macro has been called
twice. Clearly, in this case, this is not a problem, and so
here FunnelWeb's fussiness is a nuisance.

@<P@>Second, we are alerted to the fact that the
@<TT@>@(@@@<<@>scan@@@<>@>@) macro has never been
called. Like the @<TT@>@(@@@<<@>print@@@<>@>@) macro,
this macro was defined as a notational convenience, and
clearly it does not matter here if it is not used. Again,
FunnelWeb is being a nuisance.

@<P@>The four cases above demonstrate the light and dark
side of FunnelWeb's insistence that each macro be called
exactly once. To resolve the conflict without reducing the
strength of the checking, FunnelWeb provides two special
sequences @<TT@>@(@@Z@) (for @<B@>@(Z@)ero) and @<TT@>@(@@M@)
(for @<B@>@(M@)any) that can be attached to macro definitions.
Presence of the @<TT@>@(@@Z@)@<XX@>@(@@Z@,tutorial@) tag
allows the designated macro to be called zero times.
Presence of the @<TT@>@(@@M@)@<XX@>@(@@M@,tutorial@) tag
allows the designated macro to be called more than once. A
single macro may carry both tags. It is always true that all
macros are allowed to be called exactly once.

@<P@>Here is the revised program with the errors fixed, by
eliminating or adding macro calls, or by adding tags. Try
processing the file now. There should be no errors.

@<P@>
@<Begin verbatim@>
@@O@@@<<@>hello.c@@@<>@>==@@{@@-
@@@<<@>Include Files@@@<>@>
@@@<<@>Function@@@<>@>
@@@<<@>Main Program@@@<>@>
@@}

@@$@@@<<@>Main Program@@@<>@>==@@{@@-
main()
{
 doit();
}
@@}

@@$@@@<<@>Function@@@<>@>==@@{@@-
void doit()
{
 int i;
 for (i=0;i@<<@>10;i++)
   {
    @@@<<@>Print@@@<>@>
    @@@<<@>Print@@@<>@>
   }
}@@}

@@$@@@<<@>Print@@@<>@>@@M==@@{@@-
printf("Hello World!");
printf("\n");@@}

@@$@@@<<@>Scan@@@<>@>@@Z==@@{scanf@@}

@@$@@@<<@>Include Files@@@<>@>==@@{@@-
#include @<<@>stdio.h@<>@>
#include @<<@>stdlib.h@<>@>@@}
@<End verbatim@>

@<Nav@>@(@<Macro_simple FILE@>@,@<Macro FILE@>@,@<Macro_indent FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Macro_indent HEADING@>@M@{@<SH@>@(2.3@)Indentation@}
@$@<Macro_indent FILE@>@M@{macro_indent.html@}
@O@<macro_indent.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Macro_indent HEADING@>@)
@<XX@>@(indentation@,macro calls@)

@<P@>The body of the @<TT@>@(print@) macro of the previous
example contains two lines of text. A literal substitution
of this macro's body in its context would result in:

@<P@>
@<Begin verbatim@>
   {
    printf("Hello World!");
printf("\n");
    printf("Hello World!");
printf("\n");
   }
@<End verbatim@>

@<P@>But instead, it comes out as (have a look at this part
of @<TT@>@(hello.c@) now):

@<P@>
@<Begin verbatim@>
   {
    printf("Hello World!");
    printf("\n");
    printf("Hello World!");
    printf("\n");
   }
@<End verbatim@>

@<P@>The explanation is that FunnelWeb indents each line of
multiline macros by the level of indentation at the point of
call. This means that, as in the case above, program texts,
which are usually highly indented, come out looking
@<DQ@>@(right@).

@<P@>In other circumstances, where the model of the text is
one dimensional, FunnelWeb's indentation could become an
impediment or even a danger. In these cases, it can be
switched off by including the FunnelWeb
@<NewTerm@>@(pragma@) line

@<P@>
@<Begin verbatim@>
@@p indentation = none
@<End verbatim@>

@<P@>anywhere in the input file.

@<P@>One of the design goals of FunnelWeb is to allow the
user total control over the product files. This contrasts
with the approach of Knuth's WEB@<X@>@(WEB@) system
@<Paper@>@(Knuth83@) (upon which FunnelWeb is based), which
mangles the input text at the Pascal@<X@>@(Pascal@) program
syntax level, truncating identifiers, converting the text to
upper case, and paragraphing text. Here is an example of
part of a Pascal program produced by
WEB@<XX@>@(output@,WEB@) (from page@<_@>14 of
@<Paper@>@(Knuth83@)):

@<P@>
@<Begin verbatim@>
IF R=0 THEN XREF[P]:=XREFPTR ELSE
XMEM[R].XLINKFIELD:=XREFPTR;END;{:51}
{58:}FUNCTION IDLOOKUP(T:EIGHTBITS):NAMEPOINTER;
LABEL 31;
VAR I:0..LONGBUFSIZE;H:0..HASHSIZE;K:0..MAXBYTES;
W:0..1;
L:0..LONGBUFSIZE;P:NAMEPOINTER;BEGIN
L:=IDLOC-IDFIRST;{59:}
H:=BUFFER[IDFIRST];I=IDFIRST+1;
WHILE I@<<@>IDLOC DO BEGIN H:=(H+H+BUFFER[I])MOD
HASHSIZE;I=I+1;END{:59};
@<End verbatim@>
@! CHECKED: I can't believe I actually typed this mess in.
@! Had to add in some line breaks to make it fit in web page.

@<P@>Knuth's theory is that the program generated by a
literate programming system should be treated as object code
and hence should look like object code too.@<X@>@(object
code@) While this may be an admirable approach in the long
run, the present programming environment is one of faulty
compilers and buggy tools. The FunnelWeb view is that, in
this environment, the programmer needs all the help he can
get and that therefore he should be allowed total control
over the product file. Another reason for FunnelWeb's
providing total control over the product file, is that
FunnelWeb is intended to be target language independent, and
so even if Knuth's view were adopted, it would not be clear
what a legitimate transformation of the text could be.

@<Nav@>@(@<Macro_times FILE@>@,@<Macro FILE@>@,@<Macro_additive FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Macro_additive HEADING@>@M@{@<SH@>@(2.4@)Additive Macros@}
@$@<Macro_additive FILE@>@M@{macro_additive.html@}
@O@<macro_additive.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Macro_additive HEADING@>@)
@<XX@>@(additive@,macros@)

@<P@>Sometimes it is convenient to build up the definition
of a macro in stages throughout the input file. In
FunnelWeb, this can be done using an @<NewTerm@>@(additive
macro@). An additive macro is identical to an ordinary macro
except that@<XX@>@(tutorial@,==@)@<XX@>@(tutorial@,+=@)

@<P@>
@<Begin list/ordered@>
@<Item@> It has @<TT@>@(+=@) instead of @<TT@>@(==@).
@<Item@> It can be defined in one or more parts throughout the input file.
The definition of the macro is the concatenation of all the parts in the
order in which they appear.
@<End list/ordered@>

@<P@>The following example shows how additive macros can be
used to scatter and regroup information, in this case
assisting in the lucid construction of a data
abstraction@<XX@>@(data@,abstraction@) in a language
(Pascal@<X@>@(Pascal@)) that does not support them
explicitly.

@<P@>
@<Begin verbatim@>
@@!******************************

@@O@@@<<@>prog.pas@@@<>@>==@@{@@-
program adt(input,output);
@@@<<@>Types@@@<>@>
@@@<<@>Variables@@@<>@>
@@@<<@>Procedures@@@<>@>
begin startproc; end.
@@}

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

@@$@@@<<@>Types@@@<>@>+=@@{@@-
type buffer_type =
   record
   length : integer;
   buf : array[1..100] of char;
   end;
@@}

@@$@@@<<@>Variables@@@<>@>+=@@{@@-
bigbuf : buffer_type;
@@}

@@$@@@<<@>Procedures@@@<>@>+=@@{@@-
procedure buf_init (var b : buffer_type               )
   {Body of buf_init}
procedure buf_add  (var b : buffer_type;     ch : char)
   {Body of buf_add}
procedure buf_get  (var b : buffer_type; var ch : char)
   {Body of buf_get}
@@}

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

@@$@@@<<@>Types@@@<>@>+=@@{@@-
type complex_type = record r,i : real; end;
@@}

@@$@@@<<@>Procedures@@@<>@>+=@@{@@-
procedure cm_set (var c: complex_type; a,b: real)
   {Body of cm_set}
procedure cm_add (a,b: complex_type; var c: complex_type)
   {Body of cm_add}
{Other procedures and functions}
@@}

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

{...more pieces of program...}

@@!******************************
@<End verbatim@>

@<P@>It is important to remember that the definition of each
macro does not change throughout the input file. FunnelWeb
parses the entire input file and assembles all the macro
definitions before it even starts to expand macros. As a
result, each additive macro can only have one definition,
and that definition is the concatenation of all its parts.

@<P@>The example above shows how additive macros can be used
to rearrange the presentation of a computer program in the
order in which the user wishes to discuss it rather than the
order in which the compiler requires that it be consumed. It
is easy, however, to abuse the feature of additive macros.
In many cases, the same effect can be obtained more clearly
by replacing each part of an additive macro in-situ using
uniquely named non-additive macros, and then collect them
together as a group at the point where the additive macro is
called. Doing this is more work, and is more error prone,
but can result in a clearer exposition. The following
program illustrates this alternative approach.

@<P@>
@<Begin verbatim@>
@@!******************************

@@O@@@<<@>prog.pas@@@<>@>==@@{@@-
program adt(input,output);
@@@<<@>Types@@@<>@>
@@@<<@>Variables@@@<>@>
@@@<<@>Procedures@@@<>@>
begin startproc; end.
@@}

@@$@@@<<@>Types@@@<>@>==@@{@@-
@@@<<@>Buffer type@@@<>@>
@@@<<@>Complex type@@@<>@>
@@}

@@$@@@<<@>Variables@@@<>@>==@@{@@-
@@@<<@>Buffer variable@@@<>@>
@@}

@@$@@@<<@>Procedures@@@<>@>==@@{@@-
@@@<<@>Buffer procedures@@@<>@>
@@@<<@>Complex procedures@@@<>@>
@@}

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

@@$@@@<<@>Buffer type@@@<>@>==@@{@@-
type buffer_type = record
                   length : integer;
                   buf : array[1..100] of char;
                   end;
@@}

@@$@@@<<@>Buffer variable@@@<>@>==@@{@@-
bigbuf : buffer_type;
@@}

@@$@@@<<@>Buffer procedures@@@<>@>==@@{@@-
procedure buf_init(var b : buffer_type)
   {Body of buf_init}
procedure buf_add(var b : buffer_type; ch : char)
   {Body of buf_add}
procedure buf_get(var b : buffer_type; var ch : char)
   {Body of buf_get}
@@}

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

@@$@@@<<@>Complex type@@@<>@>==@@{@@-
type complex_type = record r,i : real; end;
@@}

@@$@@@<<@>Complex procedures@@@<>@>+=@@{@@-
procedure cm_set(var c: complex_type; a,b : real)
   {Body of cm_set}
procedure cm_add(a,b : complex_type; var c: complex_type)
   {Body of cm_add}
{Other procedures and functions}
@@}

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

{...more pieces of program...}

@@!******************************
@<End verbatim@>

@<P@>One of advantages of FunnelWeb (and literate
programming in general) is that (as shown above) it allows
the user to lay out the program in whatever order is
desired@<XX@>@(program@,layout@) with near total
independence from the ordering requirements of the target
programming language.

@<P@>Additive macros are allowed to be tagged with
@<TT@>@(@@Z@) and @<TT@>@(@@M@) just as other macros can,
but the tags must appear only on the first definition of the
macro. Additive macros cannot be connected directly to
product files.

@<Nav@>@(@<Macro_indent FILE@>@,@<Macro FILE@>@,@<Macro_param FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Macro_param HEADING@>@M@{@<SH@>@(2.5@)Parameterized Macros@}
@$@<Macro_param FILE@>@M@{macro_param.html@}
@O@<macro_param.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Macro_param HEADING@>@)
@<XX@>@(parameterized@,macros@)

@<P@>No self-respecting macro preprocessor would be complete
without some form of macro parameterization, and FunnelWeb
is no exception. FunnelWeb allows each macro to have from
zero to nine formal parameters@<XX@>@(formal@,parameters@)
named @<TT@>@(@@1@)@<X@>@(@@1...@), @<TT@>@(@@2@),
@<TT@>@(@@3@), @<TT@>@(@@4@), @<TT@>@(@@5@), @<TT@>@(@@6@),
@<TT@>@(@@7@), @<TT@>@(@@8@), and @<TT@>@(@@9@).

@<P@>To define a macro with one or more parameters, insert a
formal parameter list@<XX@>@(formal@,parameters@) just after
the macro name in the macro definition. Because macro
parameters have fixed names
(@<TT@>@(@@1@)@<LDots@>@<TT@>@(@@9@)), there is no need to
specify the names of formal parameters in the formal
parameter list. All that need be conveyed is how many
parameters the macro has. Here is an example of the
definition of a macro having three parameters:

@<P@>
@<Begin verbatim@>
@@$@@@<<@>While loop@@@<>@>@@(@@3@@)@@M==@@{@@-
@@1
while (@@2)
  {
   @@3
  }
@@}
@<End verbatim@>

@<P@>To call a parameterized macro, an actual
parameter@<XX@>@(actual@,parameters@) list must be supplied
that contains exactly the same number of actual parameters
as there are formal parameters in the definition of the
macro being called. An actual parameter list is delimited by
@<TT@>@(@@(@)@<X@>@(@@(@) and @<TT@>@(@@)@),@<X@>@(@@}@) and
parameters are @<I@>@(separated@) by
@<TT@>@(@@,@).@<X@>@(@@,@) The actual parameters themselves
are general FunnelWeb expressions (see the
@<FunnelWeb Reference Manual@> for the exact syntax) and can
be inserted into the list directly or can be delimited by
@<TT@>@(@@"@)@<X@>@(@@"@) so as to allow some white space to
assist in formatting the actual parameters. Here are some
examples of calls of the @<TT@>@(While loop@) macro defined
above.

@<P@>
@<Begin verbatim@>
@@! First form of actual parameters
@@! without whitespace and double quotes.
@@@<<@>While loop@@@<>@>@@(@@-
x=1;@@,x@<<@>=10@@,printf("X=%u\n",x);@@)

@@! Second form of actual parameters. The double
@@! quotes allow non-active whitespace that helps
@@! to lay out the actual parameters neatly. This
@@! call is functionally identical to the one above.
@@@<<@>While loop@@@<>@>@@(
   @@"x:=1;@@" @@,
   @@"x@<<@>=10@@" @@,
   @@"printf("X=%u\n",x);@@" @@)

@@! The two forms can be mixed in a single call.
@@@<<@>While loop@@@<>@>@@(x=1;@@,x@<<@>=10@@,
              @@"printf("X=%u\n",x);@@" @@)
@<End verbatim@>

@<P@>A few rules about parameterized macros are worth
mentioning. Macros that do not have any parameters must have
no formal or actual parameter lists.@<XS@>@(parameter
list@,absent@) Additive macros can have parameters, but the
formal parameter list must appear in the first definition
part only.

@<P@>Here is another example of the use of parameterized
macros. This time, parameters and macro calls are used in a
FunnelWeb input file that constructs an O(n)
representation of a song@<X@>@(song@)@<X@>@(twelve bugs of
christmas@) whose full size is O(n^2) in the number n of
unique lines.@<X@>@(rec.humor.funny@)@<XN@>@(Pat@,Scannel@)

@<P@>
@<Begin verbatim@>
@@O@@@<<@>Twelve_bugs.txt@@@<>@>==@@{@@-
The Twelve Bugs of Christmas
----------------------------
@@@<<@>Verse@@@<>@>@@(@@"first@@"    @@,@@@<<@>1@@@<>@>@@)
@@@<<@>Verse@@@<>@>@@(@@"second@@"   @@,@@@<<@>2@@@<>@>@@)
@@@<<@>Verse@@@<>@>@@(@@"third@@"    @@,@@@<<@>3@@@<>@>@@)
@@@<<@>Verse@@@<>@>@@(@@"fourth@@"   @@,@@@<<@>4@@@<>@>@@)
@@@<<@>Verse@@@<>@>@@(@@"fifth@@"    @@,@@@<<@>5@@@<>@>@@)
@@@<<@>Verse@@@<>@>@@(@@"sixth@@"    @@,@@@<<@>6@@@<>@>@@)
@@@<<@>Verse@@@<>@>@@(@@"seventh@@"  @@,@@@<<@>7@@@<>@>@@)
@@@<<@>Verse@@@<>@>@@(@@"eighth@@"   @@,@@@<<@>8@@@<>@>@@)
@@@<<@>Verse@@@<>@>@@(@@"ninth@@"    @@,@@@<<@>9@@@<>@>@@)
@@@<<@>Verse@@@<>@>@@(@@"tenth@@"    @@,@@@<<@>A@@@<>@>@@)
@@@<<@>Verse@@@<>@>@@(@@"eleventh@@" @@,@@@<<@>B@@@<>@>@@)
@@@<<@>Verse@@@<>@>@@(@@"twelfth@@"  @@,@@@<<@>C@@@<>@>@@)

This song appeared in the internet newsgroup
rec.humor.funny on 24-Dec-1991. It was contributed
by Pat Scannell (scannell@@@@darkstar.ma30.bull.com).
@@}

@@$@@@<<@>Verse@@@<>@>@@(@@2@@)@@M==@@{@@-
For the @@1 bug of Christmas, my manager said to me
     @@2
@@}

@@$@@@<<@>1@@@<>@>@@M==@@{@@-
See if they can do it again.@@}
@@$@@@<<@>2@@@<>@>@@M==@@{@@-
Ask them how they did it and@@+@@@<<@>1@@@<>@>@@}
@@$@@@<<@>3@@@<>@>@@M==@@{@@-
Try to reproduce it@@+@@@<<@>2@@@<>@>@@}
@@$@@@<<@>4@@@<>@>@@M==@@{@@-
Run with the debugger@@+@@@<<@>3@@@<>@>@@}
@@$@@@<<@>5@@@<>@>@@M==@@{@@-
Ask for a dump@@+@@@<<@>4@@@<>@>@@}
@@$@@@<<@>6@@@<>@>@@M==@@{@@-
Reinstall the software@@+@@@<<@>5@@@<>@>@@}
@@$@@@<<@>7@@@<>@>@@M==@@{@@-
Say they need an upgrade@@+@@@<<@>6@@@<>@>@@}
@@$@@@<<@>8@@@<>@>@@M==@@{@@-
Find a way around it@@+@@@<<@>7@@@<>@>@@}
@@$@@@<<@>9@@@<>@>@@M==@@{@@-
Blame it on the hardware@@+@@@<<@>8@@@<>@>@@}
@@$@@@<<@>A@@@<>@>@@M==@@{@@-
Change the documentation@@+@@@<<@>9@@@<>@>@@}
@@$@@@<<@>B@@@<>@>@@M==@@{@@-
Say it's not supported@@+@@@<<@>A@@@<>@>@@}
@@$@@@<<@>C@@@<>@>@@M==@@{@@-
Tell them it's a feature@@+@@@<<@>B@@@<>@>@@}
@<End verbatim@>

@<Nav@>@(@<Macro_additive FILE@>@,@<Macro FILE@>@,@<Macro_library FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Macro_library HEADING@>@M@{@<SH@>@(2.6@)Library Macros@}
@$@<Macro_library FILE@>@M@{macro_library.html@}
@O@<macro_library.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Macro_library HEADING@>@)
@<XX@>@(library@,macros@)

@<P@>FunnelWeb provides a library macro feature that allows
you to redefine macros. Normally, FunnelWeb will generate an
error if you attempt to define a macro of a particular name
more than once. However, if you attach a different number of
@<TT@>@(@@L@) markers (up to five) to each definition,
FunnelWeb accepts the multiple definitions, and at tangle time
uses the definition with the least number of @<TT@>@(@@L@)s.
For example:

@<P@>
@<Begin verbatim@>
@@$@@@<<@>ugly duckling@@@<>@>@@L@@L@@{egg@@}
@@$@@@<<@>ugly duckling@@@<>@>@@{swan@@}
@@$@@@<<@>ugly duckling@@@<>@>@@L@@{signet@@}
@<End verbatim@>

@<P@>In this example, the ugly duckling macro will expand
to @<TT@>@(swan@) because the swan definition has the least
number of @<TT@>@(@@L@) markers (@<ie@>the lowest library level).

@<P@>No two definitions may have the same name and level, but
definitions having the same name, but differing levels, are
independent of each other and can have different call number
constraints. They can even be defined additively,
with their multipart definitions interlaced. For example:

@<P@>
@<Begin verbatim@>
@@$@@@<<@>ugly duckling@@@<>@>@@L@@L+=@@{eg@@}
@@$@@@<<@>ugly duckling@@@<>@>@@L+=@@{sig@@}
@@$@@@<<@>ugly duckling@@@<>@>@@L@@L+=@@{g@@}
@@$@@@<<@>ugly duckling@@@<>@>@@L+=@@{net@@}
@<End verbatim@>

@<P@>Here, two macros having the same
name (@<TT@>@(ugly duckling@)) are defined at library
levels one and two. Each of these macros is defined in
two additive parts. The first macro is at level two
and has the value @<TT@>@(egg@). The second macro is
at level one and has the value @<TT@>@(signet@).
If this macro name were referenced by another macro, it
would be expanded to @<TT@>@(signet@), as this is the
value of the definition with the lowest library level.

@<FWTutMan subheading@>@(Uses Of Library Macros@)

@<P@>When using FunnelWeb as a macro preprocessor (@<eg@>for
the generation of HTML webs), it's convenient to be able to
define include files that contain large numbers of commonly
used macro definitions. However, sometimes, some macros must
be redefined. By tagging such macros in the include file
using @<TT@>@(@@L@), such redefinition is made possible.

@<Nav@>@(@<Macro_param FILE@>@,@<Macro FILE@>@,@<Macro_expansion FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Macro_expansion HEADING@>@M@{@<SH@>@(2.7@)Macro Expansion@}
@$@<Macro_expansion FILE@>@M@{macro_expansion.html@}
@O@<macro_expansion.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Macro_expansion HEADING@>@)
@<XX@>@(macro@,expansion@)

@<P@>One of the strengths of FunnelWeb is that, when writing
product files, it does not attempt to evaluate any text
expression (@<eg@>text block, parameter, macro call) in
memory@<XX@>@(memory@,use of@) and then write the result
out. Instead, it always writes out what it is expanding
dynamically and directly. This means that you need not
fear defining macros that expand to huge amounts of text and
then calling those macros in other macros, or passing those
huge macros as parameters to other macros. In all cases,
FunnelWeb expands directly to the product file, and there
can be no danger in running out of memory during expansion
(except for running out of stack space and other marginally
used resources in pathological cases).

@<P@>The only thing to remember in this regard is that
FunnelWeb always stores the entire @<I@>@(input@) file and
all included files, in their entirety in memory, for the
duration of the run.

@<P@>Here is an example, that illustrates how robust
FunnelWeb is:

@<P@>
@<Begin verbatim@>
@@! FunnelWeb copes well with the following
@@! macro definitions. (Providing that it has
@@! a little over ten megabytes of memory).

@@O@@@<<@>woppa.txt@@@<>@>==@@{@@-
@@@<<@>Quote@@@<>@>@@(@@@<<@>Humungeous@@@<>@>@@)@@+@@}

@@$@@@<<@>Quote@@@<>@>@@(@@1@@)==@@{"@@1"@@}

@@$@@@<<@>Humungeous@@@<>@>==@@{@@-
...Ten Megabytes of Text...
@@}
@<End verbatim@>

@<Nav@>@(@<Macro_library FILE@>@,@<Macro FILE@>@,@<Macro_include FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Macro_include HEADING@>@M@{@<SH@>@(2.8@)Include Files@}
@$@<Macro_include FILE@>@M@{macro_include.html@}
@O@<macro_include.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Macro_include HEADING@>@)
@<XX@>@(include@,files@)

@<P@>FunnelWeb provides a nested include file facility that
can be used for a number of purposes. When FunnelWeb runs
into a single line containing the special sequence
@<TT@>@(@@i@)@<X@>@(@@i@) followed by a blank, followed by a
file name, it reads in the designated file and replaces the
line containing the command (including the end of line
marker at the end of the line) with the entire contents of
the designated file. For example, if there was a file called
@<TT@>@(camera.txt@) containing the two
lines:@<XX@>@(poem@,camera@)@<XX@>@(animal@,poem@)

@<P@>
@<Begin verbatim@>
'Cos I shoot with a camera instead of a gun.
The animals flock to be petted and fed,
@<End verbatim@>

@<P@>and another file called @<TT@>@(poem.fw@)
containing the following four lines@<X@>@(shooting@)

@<P@>
@<Begin verbatim@>
I like to go shooting, it's a whole lot of fun,
@@i camera.txt
Cos they know my camera isn't loaded with lead.
- RNW, 04-Jan-1991.
@<End verbatim@>

@<P@>Then, if FunnelWeb were to process @<TT@>@(poem.fw@),
the result would be as if FunnelWeb had read in:

@<P@>
@<Begin verbatim@>
I like to go shooting, it's a whole lot of fun,
'Cos I shoot with a camera instead of a gun.
The animals flock to be petted and fed,
'Cos they know my camera isn't loaded with lead.
- RNW, 04-Jan-1991.
@<End verbatim@>

@<P@>FunnelWeb expands include files before it starts
scanning and parsing the included text. The result is that
include files can contain anything that can be found in a
FunnelWeb file. The following example illustrates the level
at which the include mechanism operates. If
@<TT@>@(main.fw@) contains

@<P@>
@<Begin verbatim@>
@@O@@@<<@>output.dat@@@<>@>==@@{@@-
@@i inc.fw
This is the text of the sloth macro.
@@}
@<End verbatim@>

@<P@>and inc.fw contains

@<P@>
@<Begin verbatim@>
@@@<<@>Sloth@@@<>@>
@@}

@@$@@@<<@>Sloth@@@<>@>==@@{@@-
@<End verbatim@>

@<P@>Then if FunnelWeb were applied to @<TT@>@(main.fw@), it would see:

@<P@>
@<Begin verbatim@>
@@O@@@<<@>output.dat@@@<>@>==@@{@@-
@@@<<@>Sloth@@@<>@>
@@}

@@$@@@<<@>Sloth@@@<>@>==@@{@@-
This is the text of the sloth macro.
@@}
@<End verbatim@>

@<P@>which it would process in the normal manner. The only
special sequence processing that takes place at a level
lower than include files is the processing of the
@<TT@>@(@<<@>special@<>@>=@<<@>newspecial@<>@>@)
sequence which changes the special character.@<XX@>@(special
character@,changing@)

@<P@>A few other facts about include files are worth
mentioning here. Include files inherit the directory
specification supplied using the @<TT@>@(+I@) command line
option. The special character is saved at the start of each
include file and restored to its previous value at the end
of each include file. Include files can be nested up to ten
levels. Recursive included files@<XX@>@(include
files@,recursive@) will always cause an infinite recursion
as there is no bottoming out mechanism available. Include
files must contain an integer number of lines (@<ie@>the
last line must be terminated with an end of line marker).
Once FunnelWeb has seen @<DQP@>@(@@i@<_@>@) at the start of a
line, it will grab the rest of the line raw and treat it as
a file name. There is no place on the line for things like
FunnelWeb comments (see later) or extraneous text.

@<P@>Include files can be used for many purposes, but are
particularly useful for hauling in macro
libraries.@<XX@>@(macro@,libraries@)

@<Nav/last@>@(@<Macro_expansion FILE@>@,@<Macro FILE@>@,@<Macro FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Type HEADING@>@M@{@<SH@>@(3@)Typesetting Facilities Tutorial@}
@$@<Type HEADING/short@>@M@{@<SH@>@(3@)Typesetting@}
@$@<Type FILE@>@M@{type.html@}
@O@<type.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Type HEADING@>@)

@<P@>
@<Type index@>

@<Nav@>@(@<Macro FILE@>@,@<Index FILE@>@,@<Example FILE@>@)

@<End FWTutMan page@>
@}

@$@<Type index@>@M@{
@<Begin size3@>
@<Begin indent/narrow@>
@<Link@>@(@<Type_overview FILE@>@,@<Type_overview HEADING@>@)@<BR@>
@<Link@>@(@<Type_independence FILE@>@,@<Type_independence HEADING@>@)@<BR@>
@<Link@>@(@<Type_hierarchy FILE@>@,@<Type_hierarchy HEADING@>@)@<BR@>
@<Link@>@(@<Type_printed FILE@>@,@<Type_printed HEADING@>@)@<BR@>
@<Link@>@(@<Type_literals FILE@>@,@<Type_literals HEADING@>@)@<BR@>
@<Link@>@(@<Type_header FILE@>@,@<Type_header HEADING@>@)@<BR@>
@<Link@>@(@<Type_comments FILE@>@,@<Type_comments HEADING@>@)@<BR@>
@<End indent/narrow@>
@<End size3@>
@}

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

@$@<Type_overview HEADING@>@M@{@<SH@>@(3.1@)Overview@}
@$@<Type_overview FILE@>@M@{type_overview.html@}
@O@<type_overview.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Type_overview HEADING@>@)
@<XX@>@(overview@,typesetting@)

@<P@>The previous sections of this manual have focused solely on the
macro facilities of FunnelWeb (which are more or less covered
completely). As a result, the example documents you have
seen so far have been gross distortions of @<DQ@>@(normal@)
FunnelWeb documents. Normal FunnelWeb documents
often contain as much
documentation as code.@<X@>@(documentation vs
code@)@<X@>@(code vs documentation@) While there
are applications where FunnelWeb can be used solely as a
macro preprocessor, many applications will use its
typesetting facilities as well.

@<P@>The macro definitions discussed in the macro tutorial
completely define the contents of the product files that
FunnelWeb will generate. These macro definitions can be
arranged in any order, and nothing external to them can
affect the contents of the product files. The macros can be
thought of as a group of self-contained islands.

@<P@>Although FunnelWeb will can process the macros all on
their own, the full power of FunnelWeb is realized only when
the macros are surrounded by a sea of documentation. This
sea can take two forms: directives and free text. Some of
the directives control things such as the maximum input line
length. However, most of them are typesetting directives
that affect the printed documentation. Thus a FunnelWeb
document can be viewed as a sequence of @<NewTerm@>@(macro
definitions@), @<NewTerm@>@(directives@), and
@<NewTerm@>@(free text@).

@<P@>Unlike the product files which consist of unscrambled
macro calls, the documentation file is more or less a direct
representation of the input file. Each part of the input
file appears in the documentation file in the order in which
it appears in the input file. However, each different kind
of part is typeset [Note: Here the term @<DQ@>@(typeset@)
is used loosely to refer to FunnelWeb's generation of
typesetter commands for each construct in the input file.
Strictly, the term should be used only to describe the
actions of a typesetter program (@<eg@>TeX).] in a
different manner. Macros are typeset in a particular style,
with the macro body appearing in @<TT@>@(tt font@) (see some
FunnelWeb printed documentation for an example). Typesetter
directives have specific defined effects (more later). Free
text is typeset exactly as it is, except that each block of
text between blank lines is filled and justified as a
paragraph.

@<P@>The following example demonstrates how all this works.
Type in the following as @<TT@>@(example.fw@) and run it
through FunnelWeb with the command @<DQP@>@(fw@<_@>example@<_@>+t@).
The @<DQP@>@(+t@) instructs FunnelWeb to generate a
documentation file called @<TT@>@(example.tex@). Run the
file through TeX and print it. Examine the files
@<TT@>@(example.out@) and @<TT@>@(example.tex@).

@<P@>
@<Begin verbatim@>
You are reading some free text before the
macro. Free text can consist of any text
(not containing the FunnelWeb special
character) including typesetter commands
such as $, %, #, and TeX which
will be typeset to appear exactly as
they do in the input file!
Look out! Here comes a macro!

@@O@@@<<@>example.out@@@<>@>==@@{@@-
This text is part of
a macro definition.
@@}

This is free text following the macro. This
sentence contains two @@{inline@@} typesetter
@@/directives@@/. Now here is a non-inline
typesetting directive.

@@t new_page

This sentence will appear on the next page.
@<End verbatim@>

@<P@>At the top of the @<TT@>@(example.tex@) documentation
file will be a set of TeX macro definitions. The TeX code
corresponding to the input above appears at the end of the
file. It should look something like this.

@<P@>
@<Begin verbatim@>
You are reading some free text before the
macro. Free text can consist of any text
(not containing the FunnelWeb special
character) including typesetter commands
such as \$, \%, \#, and \TeX{} which
will be typeset to appear exactly as
they do in the input file!
Look out! Here comes a macro!

\fwbeginmacro
\fwfilename{example.out,1}\fwequals
\fwodef \fwbtx[This text is part of
a macro definition.
]fwetx=%
\fwcdef
\fwbeginmacronotes
\fwisafile{This macro is attached to an output file.}
\fwendmacronotes
\fwendmacro

This is free text following the macro. This sentence contains
two \fwlit{inline} typesetter \fwemp{directives}.
Now here is a non-inline typesetting directive.

\fwnewpage

This sentence will appear on the next page.
@<End verbatim@>

@<P@>The following points explain the @<TT@>@(example.tex@)
file.

@<Narrowthing@>@(You don't have to know TeX:@,If you don't
know TeX, don't pay too much attention to this section. You
don't need to know TeX to use FunnelWeb.@)

@<Narrowthing@>@(In order:@,FunnelWeb has merely transformed
the input. It hasn't rearranged it.@)

@<Narrowthing@>@(Free text:@,Most of the free text has been
simply copied over. The TeX typesetter justifies and fills
all paragraphs fed to it by default, so most of the text has
just been copied verbatim.@)

@<Narrowthing@>@(TeX codes:@,The characters and sequences
which TeX treats as special have been neutralized in the
documentation file. For example, @<DQP@>@($@) has become
@<DQP@>@(\$@). By default, FunnelWeb allows the user to
write any text as free text and not have to worry about
accidentally invoking typesetter features.@)

@<Narrowthing@>@(fw sequences:@,The @<TT@>@(fw@) sequences
(@<eg@>@<TT@>@(\fwbeginmacro@)) invoke TeX macros
defined earlier in the documentation file (and not shown
here).@)

@<Narrowthing@>@(The macro:@,The macro is typeset using a
set of predefined TeX macros. See the printed documentation
to see what this looks like on paper.@)

@<Narrowthing@>@(Typesetter directives:@,Unlike the TeX
command sequences (which were neutralized), the FunnelWeb
typesetter directives turn into TeX macro calls. For
example, @<DQP@>@(@@{inline@@}@) became
@<DQP@>@(\fwlit{inline}@).@)

@<P@>FunnelWeb can also generate documentation in HTML form.
Just replace the @<TT@>@(+t@) option with the @<TT@>@(+u@) option.

@<P@>In summary, FunnelWeb produces typeset documentation
that transforms, but does not reorder, the input file.
Macros are typeset in a specific style. FunnelWeb typesetter
directives have particular well-defined effects. Free text
is filled and justified, but will otherwise appear in the
printed documentation exactly as it appears in the input
file.

@<Nav/first@>@(@<Type FILE@>@,@<Type FILE@>@,@<Type_independence FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Type_independence HEADING@>@M@{@<SH@>@(3.2@)Typesetter Independence@}
@$@<Type_independence FILE@>@M@{type_independence.html@}
@O@<type_independence.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Type_independence HEADING@>@)
@<XX@>@(typesetter@,independence@)

@<P@>FunnelWeb encourages
typesetter independence by neutralizing all TeX (or HTML) control
sequences before writing them out. The result is that you
don't have worry about upsetting or depending on TeX by
accidentally including some special character or sequence.
By default your input file is @<NewTerm@>@(typesetter
independent@).

@<P@>This scheme differs from other literate programming
tools (including very early versions of FunnelWeb) which
copy their free text  directly to the documentation file,
the justification being that the programmer can use the full
power of the typesetter language to describe the program.
The disadvantages of doing this are first that the
programmer is required to know the typesetting language and
second that the input file becomes typesetter dependent.
FunnelWeb avoids these problems by nobbling the free text
be default.

@<P@>However, FunnelWeb does provide a trapdoor for those
who want their free text to be fed directly to TeX. To open
the trapdoor, simply include one of the following pragmas
somewhere in your input file.

@<P@>
@<Begin verbatim@>
@@p typesetter = tex
@@p typesetter = html
@<End verbatim@>

@<P@>See the @<FunnelWeb Reference Manual@> for more information.

@<P@>FunnelWeb leaves the degree to which the user wishes to
bind a particular document to a particular typesetter up to
the user. In some cases, the extra typesetting power may
compensate for the lack of portability. However, as a rule,
it is best to avoid typesetter-specific commands, so as to
allow your input files to be formatted at a later date for
different typesetters. FunnelWeb includes a number of its
own typesetter commands so as to support
typesetter-independent input files. The following sections
describe some of these commands. In particular, the next
section describes the most powerful FunnelWeb typesetting
directives which allow the user to structure the document
hierarchically.

@<Nav@>@(@<Type_overview FILE@>@,@<Type FILE@>@,@<Type_hierarchy FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Type_hierarchy HEADING@>@M@{@<SH@>@(3.3@)Hierarchical Structure@}
@$@<Type_hierarchy FILE@>@M@{type_hierarchy.html@}
@O@<type_hierarchy.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Type_hierarchy HEADING@>@)
@<XX@>@(hierarchical@,structure@)

@<P@>The tree structure is one of the most effective
structuring tools that exists, deriving its power from the
principal of divide and conquor. So effective is it that the
internal organization of most technical books are tree
structures which are concisely summarized in the table of
contents. In contrast, computer programs are usually
presented as flat sequences of text to be consumed by an
anonymous compiler.

@<P@>In order to bring program documentation up to the
structural sophistication commonplace in technical books,
FunnelWeb provides five levels of section
headings@<XX@>@(section@,headings@) implemented by the five
special sequences @<TT@>@(@@A@),@<X@>@(@@A...@)
@<TT@>@(@@B@), @<TT@>@(@@C@), @<TT@>@(@@D@), and
@<TT@>@(@@E@). These must always appear at the start of a
line. @<TT@>@(@@A@) is the highest level section (@<eg@>like
LaTeX's @<TT@>@(\chapter@)) and @<TT@>@(@@E@) is the
lowest level section (@<eg@>like LaTeX's
@<TT@>@(\subsubsubsection@)). Section headings can
appear anywhere in the free text of a FunnelWeb input file
(@<ie@>anywhere except inside a macro definition).

@<P@>Each section heading@<XX@>@(name@,section@) in a
FunnelWeb document has an associated name. The name of a
section can be provided explicitly by supplying it delimited
by @<TT@>@(@@@<<@>@) and @<TT@>@(@@@<>@>@) immediately
after the section sequence (@<eg@>@<TT@>@(@@A@)), or
implicitly by not providing an explicit name, in which case
the section takes the name of the first macro defined
between the section header in question and the following
section header. An error is generated if a section has not
been given an explicit name and does not contain any macro
definitions. Here are some example headings:

@<P@>
@<Begin verbatim@>
@@A@@@<<@>Feed the Penguins and Save the World@@@<>@>
@@B@@@<<@>Feed the Penguins@@@<>@>
@@C@@@<<@>Feed the little penguins@@@<>@>
@@C@@@<<@>Feed the big penguins@@@<>@>
@@B@@@<<@>Save the World@@@<>@>
@@C@@@<<@>Save Europe@@@<>@>
@@C@@@<<@>Save Africa@@@<>@>

@@C This heading hasn't been given an
explicit name, but will inherit the name
@<TT@>@(Save the rest of the world@)
from the macro definition below.

@@$@@@<<@>Save the rest of the world@@@<>@>@@Z==@@{...@@}
@<End verbatim@>

@<P@>The feature of having unnamed sections inherit the name
of the first macro defined within their scope is present
because a common style of writing in FunnelWeb is to have
one section per macro definition. Because, under this style,
each section describes a single macro, it usually turns out
that the macro name makes a good name for the section too.
The inheritance mechanism prevents duplication of the
name.@<XX@>@(section name@,inheritance@)

@<P@>Apart from the requirement that each section have an
explicit or implicit name and that its special sequence
appear at the start of a line, the only other restriction on
section headings is that a section heading at level n
cannot appear immediately after a section heading at level
n-1 or less. In other words, the hierarchy cannot be
broken. For example, an @<TT@>@(@@C@) cannot appear after an
@<TT@>@(@@A@) heading unless there is an intervening
@<TT@>@(@@B@) heading.

@<P@>
@<Begin verbatim@>
@@A@@@<<@>The Top Heading@@@<>@>
@@C@@@<<@>Level C here is not allowed after an A@@@<>@>
@<End verbatim@>

@<P@>This rule extends to the start of the file; if there
are any headings at all, the first one must be an
@<TT@>@(@@A@) heading. The following file, while short, is
in error.

@<P@>
@<Begin verbatim@>
This FunnelWeb input file is in error
because its first section heading
is at level C rather than level A.
@@C@@@<<@>2@@@<>@>
@<End verbatim@>

@<Nav@>@(@<Type_independence FILE@>@,@<Type FILE@>@,@<Type_printed FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Type_printed HEADING@>@M@{@<SH@>@(3.4@)Understanding the Printed Documentation@}
@$@<Type_printed FILE@>@M@{type_printed.html@}
@O@<type_printed.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Type_printed HEADING@>@)

@<P@>Type in the following file, and use FunnelWeb and TeX
to generate the corresponding printed
documentation.@<XX@>@(programmer's@,cheer@)@<XX@>@(hacker's@,cheer@)
@<XX@>@(hacker's@,dictionary@)

@<P@>
@<Begin verbatim@>
@@A@@@<<@>Table of Contents@@@<>@>

@@t table_of_contents

@@A@@@<<@>Macros for Moral Support@@@<>@>

The following macro contain comments that provide moral
support.

@@$@@@<<@>Programmer's Cheer@@@<>@>@@M==@@{
-- Shift to the left!
-- Shift to the right!
-- Pop up, push down!
-- Byte! Byte! Byte!
-- (From "The New Hacker's Dictionary").
@@}

The next macro is similar but is
distributed throughout the program.

@@$@@@<<@>Hacker's Cheer@@@<>@>+=@@{
-- Pointer to the left@@+@@}

@@A@@@<<@>An Extremely Imperative Stack Abstraction@@@<>@>

@@B@@@<<@>Define the Stack@@@<>@>

@@$@@@<<@>Hacker's Cheer@@@<>@>+=@@{@@-
-- Pointer to the right@@+@@}

@@$@@@<<@>Stack Type@@@<>@>@@Z==@@{@@-
type stack = record ... end;@@}

@@B@@@<<@>Push the Stack@@@<>@>

@@$@@@<<@>Hacker's Cheer@@@<>@>+=@@{@@-
-- Hack that code@@+@@}

@@$@@@<<@>Push Procedure@@@<>@>@@Z==@@{@@-
procedure push(var b:stack; v:value);
@@@<<@>Programmer's Cheer@@@<>@> {...}@@}

@@B@@@<<@>Pop the Stack@@@<>@>

@@$@@@<<@>Hacker's Cheer@@@<>@>+=@@{@@-
-- Tight! Tight! Tight!@@+@@}

@@$@@@<<@>Pop Procedure@@@<>@>@@Z==@@{@@-
procedure pop(var b:stack);

@@@<<@>Programmer's Cheer@@@<>@> {...}@@}

@@B@@@<<@>Rough the Stack Up a Bit@@@<>@>

@@$@@@<<@>Hacker's Cheer@@@<>@>+=@@{@@-
-- (RNW, 04-Jan-1991).@@+@@}

@@$@@@<<@>Rough Procedure@@@<>@>@@Z==@@{@@-
procedure rough(var b:stack);
@@@<<@>Hacker's Cheer@@@<>@> {...}@@}

@@O@@@<<@>dummy.txt@@@<>@>==@@{dummy@@+@@}
@<End verbatim@>

@<P@>An examination of the printed documentation reveals a
lot about how FunnelWeb's presentation works.

@<P@>First, notice how the @<TT@>@(@@t@) typesetter
directive at the top of the file has caused a table of
contents to appear. This is one of FunnelWeb's typesetting
features and is discussed in a later section. The table of
contents shows that the sections have been numbered
hierarchically.

@<P@>Now take a look at the typeset macro definitions. Most
important are the numbers in square brackets that follow
each macro name. As well as numbering the headings
@<I@>@(hierarchically@), FunnelWeb @<I@>@(independently@)
numbers the macro definitions @<I@>@(sequentially@). The
first macro definition (for @<DQ@>@(Programmer's Cheer@)) is
numbered 1. The second (for @<DQ@>@(Hacker's Cheer@)) is
numbered 2 and so on. Note that it is not macros that are
numbered, but macro definitions. The distinction is
necessary because some macros (such as the @<DQ@>@(Hacker's
Cheer@) macro) are additive. It is important to realize that
there is no relationship between the numbers of the headings
and the numbers of the macro definitions.

@<P@>Now take a look at the notes beneath the body of each
macro definition. All macro definitions are followed by a
note indicating the definitions in which the macro is
called. Additive macros have an additional list, listing the
definitions in which they are defined.

@<P@>Finally, take a look at the macro @<I@>@(call@) of
@<DQ@>@(Programmer's Cheer@) in section@<_@>3.2 of the printed
documentation. Macro calls are set in slanted roman (so that
they can be distinguished from the @<TT@>@(tt font@) code)
and are followed by the number of the defining macro
definition. In this case, the macro was defined in
definition@<_@>1. Further down, the call to the @<DQ@>@(Hacker's
Cheer@) macro indicates that the macro was defined in
definition@<_@>2. In fact the macro is additive and definition@<_@>2
is just the first of many definitions. To list all
definitions in a call to an additive macro would be
unnecessarily messy.

@<Nav@>@(@<Type_hierarchy FILE@>@,@<Type FILE@>@,@<Type_literals FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Type_literals HEADING@>@M@{@<SH@>@(3.5@)Literals and Emphasis@}
@$@<Type_literals FILE@>@M@{type_literals.html@}
@O@<type_literals.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Type_literals HEADING@>@)
@<X@>@(literal construct@)@<X@>@(emphasis construct@)

@<P@>When writing about program code, it is often desirable
to be able to indicate that a particular word or phrase be
typeset in the same manner as the code being discussed. For
example, one might talk about the variable @<TT@>@(topval@)
or the procedure @<TT@>@(stack_pop@) and wish for them to
be typeset as they are in this sentence. This, of course, is
simple to do using TeX macros, but use of the (more general)
FunnelWeb typesetting directives to do the same work has the
added benefit of keeping the document portable to other
typesetters.

@<P@>FunnelWeb provides two in-text type modification
constructs: @<TT@>@(@@{...@@}@) and
@<TT@>@(@@/...@@/@)@<X@>@(@@slash@)@<X@>@(@@braces@) where
@<LDots@> is raw text. The @<TT@>@(@@{...@@}@) construct
sets the enclosed text in the same manner as the text of
macro definitions is set. The @<TT@>@(@@/...@@/@) construct
emphasises its enclosed text in some typesetter-dependent
fashion. Typically the emphasised text is set in italics.

@<P@>Here is an example of how these constructs might be
used:

@<P@>
@<Begin verbatim@>
The following procedure @@{put_sloth@@} writes the
@@{sloth@@} variable to the output file. Note: @@/The output
file must be opened for writing at this point or the program
will crash!@@/
@<End verbatim@>

@<Nav@>@(@<Type_printed FILE@>@,@<Type FILE@>@,@<Type_header FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Type_header HEADING@>@M@{@<SH@>@(3.6@)Adding A Header Page@}
@$@<Type_header FILE@>@M@{type_header.html@}
@O@<type_header.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Type_header HEADING@>@)
@<X@>@(header page@)

@<P@>FunnelWeb provides a few typesetter-independent
typesetting constructs which are specifically designed for
the construction of header pages. These constructs are
usually best placed at the top of your input file, but can
be placed anywhere the document if desired to create header
pages right through. The two main restrictions on these
constructs is that the @<TT@>@(@@t@) must start at the start
of a line (which cannot contain comments), and that the
constructs cannot appear inside a macro definition. Here is
what the top of an input file might look like:

@<P@>
@<Begin verbatim@>
@@t vskip 40 mm
@@t title titlefont centre "Hairy Wombat"
@@t title titlefont centre "Simulation"
@@t vskip 10 mm
@@t title smalltitlefont centre "A Program in Six Parts"
@@t title smalltitlefont centre "Simulating the Life of"
@@t title smalltitlefont centre "Some Hairy Wombats"
@@t vskip 20 mm
@@t title normalfont left "By Zqitzypba Ypongslrzz"
@@t new_page
@@t table_of_contents
@@t new_page
@<End verbatim@>

@<P@>The @<TT@>@(@@t@) at the start of each line indicates
that each entire line is a typesetter directive. The
@<TT@>@(vskip@)@<XX@>@(vskip@,directive@) directive
instructs FunnelWeb to skip some vertical space (measured in
millimetres). The @<TT@>@(title@)
directive@<XX@>@(title@,directive@) instructs FunnelWeb to
position a string of text on a single line of its own.
Options are provided for font and alignment. The first word
after @<TT@>@(title@) is the font which can be one of (in
decreasing order of size) @<TT@>@(titlefont@),
@<TT@>@(smalltitlefont@), and @<TT@>@(normalfont@). The
second word after @<TT@>@(title@) is the desired alignment
of the text. The options here are @<TT@>@(left@),
@<TT@>@(right@), and @<TT@>@(centre@). The
@<TT@>@(new_page@) directive@<XX@>@(newpage@,directive@)
instructs FunnelWeb to skip to a new page. Finally, the
@<TT@>@(table_of_contents@) directive@<XX@>@(table of
contents@,directive@) instructs FunnelWeb to insert a table
of contents at that point in the text.

@<Nav@>@(@<Type_literals FILE@>@,@<Type FILE@>@,@<Type_comments FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Type_comments HEADING@>@M@{@<SH@>@(3.7@)Comments@}
@$@<Type_comments FILE@>@M@{type_comments.html@}
@O@<type_comments.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Type_comments HEADING@>@)
@<X@>@(comments@)

@<P@>A FunnelWeb comment commences with the
@<TT@>@(@@!@)@<X@>@(@@!@) sequence and continues up to, but
not including, the end of line marker at the end of the line
that the comment sequence is on. Comments can be placed on
any line except @<TT@>@(@@i@) include, @<TT@>@(@@p@) pragma,
and @<TT@>@(@@t@) typesetter directive lines.

@<P@>The text following the FunnelWeb comment sequence
@<TT@>@(@@!@) will not appear in the product files or the
documentation file. It is only for the eyes of those who
bother to look at the original @<TT@>@(.fw@) input file.
Typically FunnelWeb comments are used to describe the way in
which particular FunnelWeb constructs are being used.
Example:

@<P@>
@<Begin verbatim@>
@@! This macro is really revolting.
@@! Please forgive me. I had to do it!
@@$@@@<<@>Revolt Me@@@<>@>==@@{@@-
@@#X@@(@@#Y@@(@@#Z@@,@@"@@#Z@@"@@)=
6@@,Teapot@@,@@"@@#Q@@(45@@)@@"@@,Tiger@@)@@}
@<End verbatim@>

@<Nav/last@>@(@<Type_header FILE@>@,@<Type FILE@>@,@<Type FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Example HEADING@>@M@{@<SH@>@(4@)A Complete Example@}
@$@<Example HEADING/short@>@M@{@<SH@>@(4@)Example@}
@$@<Example FILE@>@M@{example.html@}
@O@<example.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Example HEADING@>@)
@<XX@>@(complete@,example@)@<XX@>@(FunnelWeb@,Example@)

@<P@>To finish off the chapter, a complete example of a
FunnelWeb input file is presented. Although unrealistically
short, it gives a better idea of what a typical FunnelWeb
@<TT@>@(.fw@) file looks like.

@<P@>
@<Begin verbatim@>
@@!---------------------------------------!
@@!  Start of FunnelWeb Example .fw File  !
@@!---------------------------------------!

@@t vskip 40 mm
@@t title titlefont centre "Powers:"
@@t title titlefont centre "An Example of"
@@t title titlefont centre "A Short"
@@t title titlefont centre "FunnelWeb .fw File"
@@t vskip 10 mm
@@t title smalltitlefont centre "by Ross Williams"
@@t title smalltitlefont centre "26 January 1992"
@@t vskip 20 mm
@@t table_of_contents

@@A@@@<<@>FunnelWeb Example Program@@@<>@>

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

@@$@@@<<@>Constants@@@<>@>==@@{@@-
n : constant natural := 10;   -- [1,n] numbers?
p : constant natural :=  5;   -- [1,p]) powers?@@}

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

@@O@@@<<@>Power.ada@@@<>@>==@@{@@-
@@@<<@>Pull in packages@@@<>@>

procedure example is
   @@@<<@>Constants@@@<>@>
begin -- example
   for i in 1..n loop
      @@@<<@>Write out the first p powers@@@<>@>
   end loop;
end example;
@@}

@@B In this section,  we pull in the packages that this
program  needs to run. In fact, all we need is the IO
package so that we can write out the results. To use the IO
package, we first of all need  to haul it in (@@{with
text_io@@}) and then we need to make all its identifiers
visible at the top level (@@{use text_io@@}).

@@$@@@<<@>Pull in packages@@@<>@>@@{@-
with text_io; use text_io;@@}

@@B Here is  the bit that writes out  the first @@{p@@}
powers of  @@{i@@}. The power values  are  calculated
incrementally  in  @@{ip@@}  to  avoid  the  use  of  the
exponentiation operator.

@@$@@@<<@>Write out the first p powers@@@<>@>@@{@@-
declare
   ip : natural := 1;
begin
   for power in 1..p loop
      ip:=ip*i;
      put(natural'image(ip) & " ");
   end loop;
   new_line;
end;@@}

@@!---------------------------------------!
@@!   End of FunnelWeb Example .fw File   !
@@!---------------------------------------!
@<End verbatim@>

@<FWTutMan subheading@>@(Summary@)

@<P@>FunnelWeb's functionality can be split into two parts:
a macro preprocessor, and support for typesetting. The
reader should be aware that the examples in this manual,
constructed as they have been to demonstrate particular
features of FunnelWeb, do not present a realistic picture of
the best use of the tool. Only the example above comes
close.

@<Nav@>@(@<Type FILE@>@,@<Index FILE@>@,@<Hints FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Hints HEADING@>@M@{@<SH@>@(5@)FunnelWeb Hints@}
@$@<Hints HEADING/short@>@M@{@<SH@>@(5@)Hints@}
@$@<Hints FILE@>@M@{hints.html@}
@O@<hints.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Hints HEADING@>@)

@<P@>This section contains a grab bag of hints about how
FunnelWeb can be used. This chapter probably should not be
read until you have commenced using FunnelWeb, or at the
very least, tried out some of the examples in earlier
chapters. Those who find themselves using FunnelWeb
frequently should read this chapter at some stage so as to
ensure that they are getting the most out of it.

@<P@>Most of the examples in this chapter have been placed in the
FunnelWeb regression test suite. The files to
examine are @<TT@>@(hi01.fw@) through @<TT@>@(hi10.fw@).

@<P@>
@<Hints index@>

@<Nav@>@(@<Example FILE@>@,@<Index FILE@>@,@<Examples FILE@>@)

@<End FWTutMan page@>
@}

@$@<Hints index@>@M@{
@<Begin size3@>
@<Begin indent/narrow@>
@<Link@>@(@<Hints_names FILE@>@,@<Hints_names HEADING@>@)@<BR@>
@<Link@>@(@<Hints_qnames FILE@>@,@<Hints_qnames HEADING@>@)@<BR@>
@<Link@>@(@<Hints_martinet FILE@>@,@<Hints_martinet HEADING@>@)@<BR@>
@<Link@>@(@<Hints_eols FILE@>@,@<Hints_eols HEADING@>@)@<BR@>
@<Link@>@(@<Hints_conditionals FILE@>@,@<Hints_conditionals HEADING@>@)@<BR@>
@<Link@>@(@<Hints_headings FILE@>@,@<Hints_headings HEADING@>@)@<BR@>
@<Link@>@(@<Hints_efficiency FILE@>@,@<Hints_efficiency HEADING@>@)@<BR@>
@<Link@>@(@<Hints_interactive FILE@>@,@<Hints_interactive HEADING@>@)@<BR@>
@<Link@>@(@<Hints_default FILE@>@,@<Hints_default HEADING@>@)@<BR@>
@<Link@>@(@<Hints_make FILE@>@,@<Hints_make HEADING@>@)@<BR@>
@<Link@>@(@<Hints_dangers FILE@>@,@<Hints_dangers HEADING@>@)@<BR@>
@<Link@>@(@<Hints_debugging FILE@>@,@<Hints_debugging HEADING@>@)@<BR@>
@<Link@>@(@<Hints_tabs FILE@>@,@<Hints_tabs HEADING@>@)@<BR@>
@<Link@>@(@<Hints_htmlstyle FILE@>@,@<Hints_htmlstyle HEADING@>@)@<BR@>
@<Link@>@(@<Hints_emacs FILE@>@,@<Hints_emacs HEADING@>@)@<BR@>
@<End indent/narrow@>
@<End size3@>
@}

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

@$@<Hints_names HEADING@>@M@{@<SH@>@(5.1@)Macro Names@}
@$@<Hints_names FILE@>@M@{hints_names.html@}
@O@<hints_names.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Hints_names HEADING@>@)
@<XX@>@(macro@,names@)@<XX@>@(macro@,identifiers@)

@<P@>When using FunnelWeb, the choice of macro names can be
as important to the readability of a program as the choice
of program identifiers, and it is important that you
know the range of options available.

@<Narrowthing@>@(Names are case sensitive and exact
matching:@,Macro names are case sensitive and are matched
exactly. The strings used as a macro name at the point of
definition and call must be @<I@>@(identical@) for the
connection to be made.@)

@<Narrowthing@>@(Names can contain any printable
character:@,FunnelWeb is less restrictive about its macro
names than most programming languages are about their
identifiers. A FunnelWeb macro name can contain any sequence
of printable characters, including blanks and punctuation.
Names can start and end with any character. However, names cannot
cross line boundaries. The following are all legal macro
names:@)

@<Begin verbatim@>
        @@@<<@>This macro expands to some really bad code@@@<>@>
        @@@<<@>@@@<>@>
        @@@<<@>453 #$ %&# --===~~1"@<>@>@<>@>@<>@>@@@<>@>
        @@@<<@>@<<@>@@@<>@>
        @@@<<@>@<<@>@<>@>@@@<>@>
        @@@<<@>a b c d e f g@@@<>@>
        @@@<<@>       !     @@@<>@>
        @@@<<@>?? ...@@@<>@>
        @@@<<@>"Who's been hacking MY program" said Father Bear.@@@<>@>
        @@@<<@>Update the maximum and return for more data@@@<>@>
@<End verbatim@>

@<Narrowthing@>@(Names must be no more than a maximum limit
in length:@,Names can be no longer than a predefined maximum
length (80). Currently this length cannot be modified without
recompiling FunnelWeb.@)

@<P@>Typically, macro names will consist of a short English
phrase or sentence that describes the contents of the macro.

@<Nav/first@>@(@<Hints FILE@>@,@<Hints FILE@>@,@<Hints_qnames FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Hints_qnames HEADING@>@M@{@<SH@>@(5.2@)Quick Names@}
@$@<Hints_qnames FILE@>@M@{hints_qnames.html@}
@O@<hints_qnames.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Hints_qnames HEADING@>@)
@<XX@>@(quick@,names@)

@<P@>Sometimes a particular macro must be used extremely
often. When this happens, it is desirable to make the macro's
name as short as possible. The shortest ordinary FunnelWeb
macro name is the empty name@<XX@>@(empty@,name@)
@<DQP@>@(@@@<<@>@@@<>@>@), which is four characters long.
Single-character names are five characters long.

@<P@>To cater for the cases where really short names are
needed, FunnelWeb provides a @<NewTerm@>@(quick name@)
syntax that allows one-character macro names to be specified
in two less characters. Quick names take the form of the
special character, followed by a hash (@<TT@>@(#@)) followed
by a single character. Examples:

@<P@>
@<Begin verbatim@>
   @@#A     @@#|     @@#&     @@#m
@<End verbatim@>

@<P@>This form of macro name has the same syntactic
functionality as an ordinary name and can be substituted
wherever an ordinary name can be. In fact quick names live
in the same namespace as ordinary macro names. For example
the quickname @<TT@>@(@@#A@) is the @<I@>@(same name@)
(refers to the same macro) as the ordinary name
@<TT@>@(@@@<<@>A@@@<>@>@).

@<P@>Because quick names look syntactically @<DQ@>@(open@)
(@<ie@>they do not have a closing@<TT@>@(@@@<>@>@) as
ordinary names do), it is best to avoid them except where a
macro must be called very often.

@<Nav@>@(@<Hints_names FILE@>@,@<Hints FILE@>@,@<Hints_martinet FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Hints_martinet HEADING@>@M@{@<SH@>@(5.3@)FunnelWeb the Martinet@}
@$@<Hints_martinet FILE@>@M@{hints_martinet.html@}
@O@<hints_martinet.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Hints_martinet HEADING@>@)
@<XX@>@(FunnelWeb@,rules@)@<XX@>@(FunnelWeb@,martinet@)

@<P@>There are many ways in which a macro preprocessor can
cause unexpected difficulties. FunnelWeb seeks to avoid many
of these problems by performing a number of checks. This
section describes some of the checks that FunnelWeb
performs.

@<Narrowthing@>@(Trailing blanks in the input
file:@,Trailing blanks@<XX@>@(trailing@,blanks@) are usually
not dangerous, but FunnelWeb disallows them anyway. All
trailing blanks in the @<I@>@(input@) (@<TT@>@(.fw@) file)
are flagged as errors by FunnelWeb. FunnelWeb does not flag
trailing blanks in any of its output files.@)

@<Narrowthing@>@(Input line length:@,FunnelWeb has a maximum
input line length.@<XX@>@(input line@,length@) If FunnelWeb
reads an input line longer than this length, it flags the
line with an error message. The maximum length can be
changed using a pragma (see the @<FunnelWeb Reference Manual@>).@)

@<Narrowthing@>@(Product file line length:@,FunnelWeb
watches the length of output lines@<XX@>@(output
line@,length@) and all output lines longer than the limit
are flagged with error messages. The maximum length can be
changed using a pragma. That FunnelWeb polices output lines
is very important. Some programs can behave very strangely
if they get an input line that is too long (@<eg@>Fortran
compilers@<XX@>@(Fortran@,compilers@) can simply ignore text
past a certain column!) and once FunnelWeb starts expanding
macros using indentation, it is sometimes not obvious how
wide the product file will be.@)

@<Narrowthing@>@(Control characters:@,The presence of
control characters@<XX@>@(control@,characters@) in a text
file can result in some confusing behaviour downstream when
the file is presented to various programs. Unfortunately,
some text editors@<XX@>@(text@,editors@) allow control
characters to be inserted into the text rather too easily,
and it is all too easy to be tripped up. FunnelWeb prevents
these problems by flagging with diagnostics all
non-end-of-line control characters detected in the input
(@<TT@>@(.fw@)) file (even TABs@<X@>@(tabs@)). The result is
that the user is guaranteed that product files generated
from FunnelWeb contain no unintentional control characters.
This said, FunnelWeb does allow the insertion of control
characters in the output file by explicitly specifying them
in the text using a @<TT@>@(@@^@) control sequence.@)

@<Narrowthing@>@(Number of invocations:@,FunnelWeb checks
the number of times that@<XX@>@(invocations@,number@) each
macro is called and issues an error if the total is not one.
The @<TT@>@(@@Z@) (for zero) and @<TT@>@(@@M@) (for many)
macro attributes can be used to bypass these checks.@)

@<Narrowthing@>@(Recursion:@,Because@<XX@>@(recursion@,macro@)
FunnelWeb does not provide any conditional constructs, all
recursively defined macros must, by definition, expand
infinitely*, and are therefore unacceptable. FunnelWeb
performs @<I@>@(static@) checks to detect recursion,
detecting it before macro expansion commences. The user need
not fear that FunnelWeb will lock up or spew forth if a
recursive macro is accidentally specified.
(* Note: A special case exists where there is
recursion but no content. In this case, the expansion is
finite (the empty string) even though the operation of
expanding is infinite. FunnelWeb does not treat this case
specially).@)

@<Nav@>@(@<Hints_qnames FILE@>@,@<Hints FILE@>@,@<Hints_eols FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Hints_eols HEADING@>@M@{@<SH@>@(5.4@)Fiddling With End of Lines@}
@$@<Hints_eols FILE@>@M@{hints_eols.html@}
@O@<hints_eols.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Hints_eols HEADING@>@)
@<XX@>@(EOL@,fiddling with@)@<XX@>@(end-of-line@,fiddling with@)@<X@>@(spacing@)

@<P@>One of the  fiddly aspects of programming  with
FunnelWeb is coping  with end of lines. If  you want  your
product file to be  well indented without multiple blank
lines  or code run-ons,  you have to spend a  little time
working out how the end of line markers get moved around.

@<P@>The rule  to remember is that, disregarding the
effects of  special sequences within a macro body,
@<I@>@(the body of a macro consists of exactly the text
between the opening @<TT@>@(@@{@) and the  closing
@<TT@>@(@@}@)@). This text includes end of line markers.

@<P@>If for example you call a macro in a sequence of
code@<LDots@>

@<P@>
@<Begin verbatim@>
while the_walrus_is_sleepy do
   begin
   writeln('zzzzzzz');
   @@@<<@>Wake up the walrus@@@<>@>
   writeln('Umpharumpha...');
   end;
@<End verbatim@>

@<P@>where @<TT@>@(@<<@>wake up the walrus@<>@>@) is defined
as follows

@<P@>
@<Begin verbatim@>
@@$@@@<<@>Wake up the walrus@@@<>@>==@@{
wake_up_the_walrus(the_walrus);
@@}
@<End verbatim@>

@<P@>then when @<TT@>@(@<<@>Wake up the walrus@<>@>@) is
expanded you will get

@<P@>
@<Begin verbatim@>
while the_walrus_is_sleepy do
   begin
   writeln("zzzzzzz");

   wake_up_the_walrus(the_walrus);

   writeln("Umpharumpha...");
   end;
@<End verbatim@>

@<P@>The blank  lines were  introduced by  the end  on line
markers included  in the definition of @<TT@>@(@<<@>Wake up
the walrus@<>@>@). A  good solution to this  problem is to
suppress the end of line markers by defining the macro as
follows

@<P@>
@<Begin verbatim@>
@@$@@@<<@>Wake up the walrus@@@<>@>==@@{@@-
wake_up_the_walrus(the_walrus);@@}
@<End verbatim@>

@<P@>This is the usual form of macro definitions in
FunnelWeb files.

@<P@>In additive macros, this format  does not work properly
because the end of line that is suppressed by the trailing
@<TT@>@(@@}@) does not get replaced by the end of line at
the end of the macro invocation. For example the definition

@<P@>
@<Begin verbatim@>
@@$@@@<<@>Wake up the walrus@@@<>@>+=@@{@@-
wake_up_the_walrus_once(the_walrus);@@}
@<End verbatim@>

@<P@>later followed by

@<P@>
@<Begin verbatim@>
@@$@@@<<@>Wake up the walrus@@@<>@>+=@@{@@-
wake_up_the_walrus_again(the_walrus);@@}
@<End verbatim@>

@<P@>is equivalent to the single definition

@<P@>
@<Begin verbatim@>
@@$@@@<<@>Wake up the walrus@@@<>@>==@@{@@-
wake_up_the_walrus_once(the_walrus);@@-
wake_up_the_walrus_again(the_walrus);@@}
@<End verbatim@>

@<P@>Putting the trailing @<TT@>@(@@}@)  on a new line at
the end of  the macro (except for the last definition part)
solves the problem.

@<P@>
@<Begin verbatim@>
@@$@@@<<@>Wake up the walrus@@@<>@>+=@@{@@-
wake_up_the_walrus_once(the_walrus);
@@}
@<End verbatim@>

@<P@>later followed by

@<P@>
@<Begin verbatim@>
@@$@@@<<@>Wake up the walrus@@@<>@>+=@@{@@-
wake_up_the_walrus_again(the_walrus);@@}
@<End verbatim@>

@<P@>is equivalent to the single definition

@<P@>
@<Begin verbatim@>
@@$@@@<<@>Wake up the walrus@@@<>@>==@@{@@-
wake_up_the_walrus_once(the_walrus);
wake_up_the_walrus_again(the_walrus);@@}
@<End verbatim@>

@<P@>Managing end of line markers is tricky, but once you
establish  a convention for coping with them, the problem
disappears into the background.

@<Nav@>@(@<Hints_martinet FILE@>@,@<Hints FILE@>@,@<Hints_conditionals FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Hints_conditionals HEADING@>@M@{@<SH@>@(5.5@)Fudging Conditionals@}
@$@<Hints_conditionals FILE@>@M@{hints_conditionals.html@}
@O@<hints_conditionals.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Hints_conditionals HEADING@>@)
@<XX@>@(fudging@,conditionals@)

@<P@>As a macro preprocessor, one facility that FunnelWeb
lacks is a conditional facility (such as C's
@<TT@>@(#ifdef@)). It might, therefore, come as a surprise
to know that the FunnelWeb V1 actually had a
built in conditional facility. The facility allowed the
programmer to specify a construct that would select from one
of a number of macro expressions depending on the value of a
controlling macro expression.

@<P@>In three years the construct was never used.

@<P@>The reason was that conditional constructs could be
fudged nearly as easily as they could be used. Because of
this, the inbuilt conditional feature was removed in the
FunnelWeb V2. Not only did this simplify the
program, but is also allowed recursive macros to be detected
through static analysis rather than during macro expansion.

@<P@>There are two basic ways to fudge a conditional. First,
the comment facility of the target programming language may
be employed. For example, in Ada,@<X@>@(Ada@) comments
commence with @<DQP@>@(--@) and terminate at the end of the
line. Using this fact, it is easy to construct macros that
can be called at the start of each target line and which
turn on and off the lines so marked by defining the macro to
be the empty string (ON) or the comment symbol
(@<TT@>@(--@)) (OFF). For example:

@<P@>@<Begin verbatim@>
@@A@@@<<@>Debug Macro@@@<>@>

The following macro determines whether debug code
will be included in the program. All lines of
debug code commence with a call to this macro and
so we can turn all that code on or off here by
defining this macro to be either empty or the
single-line comment symbol (@<TT@>@(--@)). Note
the use of a quick macro name.

@@$@@#D@@M==@@{@@}  @@! Turns the debug code ON.
@@! Use this definition to turn
@@! the debug code OFF: @@$@@#D==@@{--@@}

... then later in the file...

@@$@@@<<@>Sloth incrementing loop@@@<>@>==@@{@@-
while sloth@<<@>walrus loop
   @@#D assert(sloth@<<@>walrus,"Sloth bomb.");
   @@#D assert(timer@<<@>timermax,"Timer bomb.");
   inc(sloth);
end loop@@}
@<End verbatim@>

@<P@>The other way to fudge a conditional is to
define a macro with a single parameter. A call to
the macro is then wrapped around all the
conditional code in the program. The macro can
then be defined to present or ignore the code of
its argument. For example:

@<P@>
@<Begin verbatim@>
@@A@@@<<@>Debug Macro@@@<>@>

The following macro determines whether debug code
will be included in the program. All debug code is
wrapped by a call to this macro and so we can turn
all the debug code on or off here by defining this
macro to be either empty or its parameter.

@@$@@#D@@(@@1@@)@@M==@@{@@1@@}  @@! Debug code ON.
@@! Use this definition to turn the
@@! debug code OFF: @@$@@#D@@(@@1@@)==@@{@@}

... then later in the file...

@@$@@@<<@>Sloth incrementing loop@@@<>@>==@@{@@-
while sloth@<<@>walrus loop
   @@#D@@(assert(sloth@<<@>walrus,"Sloth bomb.");
        assert(timer@<<@>timermax,"Timer bomb");@@)
   inc(sloth);
end loop@@}
@<End verbatim@>

@<P@>In languages that allow multi-line comments (@<eg@>C
with @<TT@>@(/*@) and @<TT@>@(*/@)), comments can be used to
eliminate the conditioned code rather than absence.  For
example:

@<P@>
@<Begin verbatim@>
@@! Comments out the debug code
@@$@@#D@@(@@1@@)@@M==@@{/* @@1 */@@}
@<End verbatim@>

@<P@>(Note: If this example were ever actually used, the
programmer would have to be careful not to place comments in
the argument code. Nested comments in C are non-portable.)

@<P@>The parameterized macro idea can be generalized to
support the choice of more than one mutually exclusive
alternative. For example:

@<P@>
@<Begin verbatim@>
@@A This module contains non-portable code that
must execute on Hewlett Packard, Sun, and DEC
workstations. The following FunnelWeb macro is
defined to choose between these three. The first
parameter is the HP code, the second is the Sun
code, and the third is the DEC code. Whichever
parameter constitutes the body of this macro
determines which machine the code is being
targeted for.

@@$@@@<<@>Machine specific code@@@<>@>@@(@@3@@)@@M==@@{@@-
@@1@@}  @@! Configure for HP.

...then later in the file...

@@@<<@>Machine specific code@@@<>@>@@(
@@"get_command_line(comline)@@"           @@, @@! HP.
@@"scan_command_line(128,comline);@@"     @@, @@! Sun.
@@"dcl_get_command_line(comline,256);@@"  @@) @@! DEC.
@<End verbatim@>

@<P@>Of course, this could also be performed using three
separate macros. The main advantage of using a single macro
is that the mutual exclusivity is enforced. Also, because
FunnelWeb ensures that the number of formal and actual
parameters are the same, this method lessens the chance that
a machine will be forgotten in some places.

@<Nav@>@(@<Hints_eols FILE@>@,@<Hints FILE@>@,@<Hints_headings FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Hints_headings HEADING@>@M@{@<SH@>@(5.6@)Changing the Strength of Headings@}
@$@<Hints_headings FILE@>@M@{hints_headings.html@}
@O@<hints_headings.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Hints_headings HEADING@>@)
@<XX@>@(headings@,strength@)@<XX@>@(typesetting@,strength@)
@<XX@>@(section@,strength@)@<XX@>@(font@,size@)

@<P@>FunnelWeb provides five heading levels: @<TT@>@(@@A@),
@<TT@>@(@@B@), @<TT@>@(@@C@), @<TT@>@(@@D@), and
@<TT@>@(@@E@) to which it binds five different typographical
strengths. These bindings are static; a level @<TT@>@(@@A@)
heading will always be typeset in a particular font size
regardless of the size of the document. The font sizes have
been preset to be @<DQ@>@(reasonable@) for a range of
document sizes, but may be inappropriate for very small or
large documents.

@<P@>FunnelWeb does not currently provide an
@<DQ@>@(official@) way (@<eg@>a pragma) to change the
typesetting strength of headings. This feature might be
added in later versions. Meanwhile, a hack is available that
will do the job, providing that you do not mind the hack
being TeX-specific and probably FunnelWeb-version specific.

@<P@>Inside the set of TeX macro definitions that FunnelWeb
writes at the top of every documentation file are five
@<DQ@>@(library@) definitions
@<TT@>@(fwliba@)@<LDots@>@<TT@>@(fwlibe@) which provide five
different typesetting strengths for headings. Near the end
of the set of definitions, FunnelWeb binds these macros to
five other macros @<TT@>@(fwseca@)@<LDots@>@<TT@>@(fwsece@)
which are invoked directly in the generated TeX code to
typeset the headings.

@<P@>
@<Begin verbatim@>
\def\fwseca#1#2{\fwliba{#1@@,#2}}
\def\fwsecb#1#2{\fwlibb{#1@@,#2}}
\def\fwsecc#1#2{\fwlibc{#1@@,#2}}
\def\fwsecd#1#2{\fwlibd{#1@@,#2}}
\def\fwsece#1#2{\fwlibe{#1@@,#2}}
@<End verbatim@>

@<P@>This means that the typesetting strength of the
headings in a FunnelWeb document can be changed by
redefining these macros at the top of a FunnelWeb document.
For example:

@<P@>
@<Begin verbatim@>
@@p typesetter = tex
\def\fwseca#1#2{\fwlibc{#1@@,#2}}
@<End verbatim@>

@<P@>would set @<TT@>@(@@A@) headings at the same strength
as the default strength of @<TT@>@(@@C@) headings. The
@<TT@>@(typesetter@) directive is necessary to ensure that
the TeX control sequences get through to the documentation
file unfiltered.

@<P@>The following will tone down all headings by two levels
(with the @<TT@>@(@@D@) and @<TT@>@(@@E@) levels being
allocated the default @<TT@>@(@@E@) typesetting strength
because there is nothing weaker).

@<P@>
@<Begin verbatim@>
@@p typesetter = tex
\def\fwseca#1#2{\fwlibc{#1@@,#2}}
\def\fwsecb#1#2{\fwlibd{#1@@,#2}}
\def\fwsecc#1#2{\fwlibe{#1@@,#2}}
\def\fwsecd#1#2{\fwlibe{#1@@,#2}}
\def\fwsece#1#2{\fwlibe{#1@@,#2}}
@<End verbatim@>

@<P@>These definitions affect only the headings that follow
them, and so they should be placed at the top of the
FunnelWeb input file.

@<P@>To change the style of headings in HTML output, just
modify the style settings near the top of the HTML file.

@<Nav@>@(@<Hints_conditionals FILE@>@,@<Hints FILE@>@,@<Hints_efficiency FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Hints_efficiency HEADING@>@M@{@<SH@>@(5.7@)Efficiency Notes@}
@$@<Hints_efficiency FILE@>@M@{hints_efficiency.html@}
@O@<hints_efficiency.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Hints_efficiency HEADING@>@)
@<XX@>@(FunnelWeb@,efficiency@)@<XX@>@(efficiency@,notes@)

@<P@>The following notes are worth keeping in mind when
using FunnelWeb.

@<Narrowthing@>@(Memory:@,When@<X@>@(memory@)@<XX@>@(input@,files@)
FunnelWeb processes an input file, it reads the entire input
file, and all the included files into memory. (Note: If a
file is included n times, FunnelWeb keeps n copies in
memory). This organization does not pose a constraint on
machines with large memories, but could present a problem on
the smaller machines such as the PC.@)

@<Narrowthing@>@(Speed:@,FunnelWeb@<X@>@(speed@) is not a
slow program. However, it is not particularly fast either.
If the speed at which FunnelWeb runs is important to you,
then the thing to keep in mind is that FunnelWeb has been
optimized to deal efficiently with large slabs of text.
FunnelWeb treats input files as a sequence of text slabs and
special sequences (@<eg@>@<TT@>@(@@+@)) and whenever it hits
a special sequence, it has to stop and think. Thus, while a
ten megabyte text slab would be manipulated as a single
token, in a few milliseconds, a similar ten megabyte chunk
filled with special sequences would take a lot longer. If
FunnelWeb is running slowly, look to see if the input
contains a high density of special sequences. This can
sometimes happen if FunnelWeb is being used as a backend
macro processor and its input is being generated
automatically by some other program.@)

@<Narrowthing@>@(Macro
expansion:@,When@<XX@>@(macro@,expansion@) tangling
(expanding macros), FunnelWeb never expands a macro
expression into memory; it always writes it to the product
file as it goes. This is a powerful fact, because it means
that you can write macros containing an unlimited amount of
text, and pass such macros as parameters to other macros
without becoming concerned about overflowing some kind of
buffer memory. In short, FunnelWeb does not impose any
limits on the size of macro bodies or their expansions.@)

@<Nav@>@(@<Hints_headings FILE@>@,@<Hints FILE@>@,@<Hints_interactive FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Hints_interactive HEADING@>@M@{@<SH@>@(5.8@)Interactive Mode@}
@$@<Hints_interactive FILE@>@M@{hints_interactive.html@}
@O@<hints_interactive.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Hints_interactive HEADING@>@)
@<X@>@(interactive mode@)@<X@>@(keyboard mode@)

@<P@>As well as having a command line interface with lots of
options, FunnelWeb also provides a command language and a
mode (@<DQ@>@(interactive mode@)) in which commands in the
language can be typed interactively. The FunnelWeb command
interpreter was created primarily to support regression
testing,@<XX@>@(regression@,testing@) but can also be useful
to FunnelWeb users.

@<P@>FunnelWeb's command
interpreter@<XX@>@(command@,interpreter@) reads one command
per line and can read a stream of commands either from a
text file, or from the console. The interpreter can
understand over twenty commands. See the
@<FunnelWeb Reference Manual@> for a full list. However,
most of them
were designed to support regression testing and will not be
of use to the casual user.

@<P@>The commands that are of greatest use to the casual
user are:@<XX@>@(useful@,commands@)

@<P@>
@<Begin verbatim@>
     !               - Ignores the whole line.
     EXECUTE fn      - Execute the specified file.
     FW options      - Invoke FunnelWeb-proper once.
     SET options     - Sets options.
     SHOW            - Displays current options.
     TRACE ON        - Turns command tracing ON.
     QUIT            - Quits FunnelWeb.
@<End verbatim@>

@<P@>To distinguish here between invocations of the
FunnelWeb program and FunnelWeb runs inside the shell, we
call the latter @<NewTerm@>@(FunnelWeb proper@). The
@<DQP@>@(FW@) command invokes FunnelWeb proper with the
specified options which take the same syntax as they do on
the command line. The only restriction is that none of the
action options can be turned on except @<DQP@>@(+F@) which
must be turned on.

@<P@>The @<DQP@>@(SET@) command@<XX@>@(set@,command@) has
the same syntax as the @<DQP@>@(FW@) command except that it
does not allow @<I@>@(any@) action options to be specified.
It's sole effect is to set default option values for the
rest of the run.

@<P@>The @<DQP@>@(SHOW@)@<XX@>@(show@,command@) command
displays the current default options.

@<P@>By default, FunnelWeb does not echo the commands that
it processes in a script. The @<DQP@>@(TRACE
ON@)@<XX@>@(trace on@,command@) command turns on such
tracing.

@<P@>These commands can be combined to streamline the use of
FunnelWeb. For example, you might wish to create a script
called @<TT@>@(typeset.fws@) to process a whole group of
files.

@<P@>
@<Begin verbatim@>
trace on
!This script typesets the whole program.
! Set no listing file, no product files,
! but specify a documentation file
! and specify the directory into which
! it should be placed.
set -L -O +T/usr/ross/typeset/
fw prog1
fw prog2
fw prog3
fw prog4
@<End verbatim@>

@<P@>There are a few ways in which this script can be run.
The simplest is simply to specify it in the @<DQP@>@(+X@)
option of a FunnelWeb invocation. FunnelWeb shellscripts
default to @<DQP@>@(@<<@>current_directory@<>@>@) and
@<DQP@>@(.fws@).

@<P@>
@<Begin verbatim@>
fw +xtypeset
@<End verbatim@>

@<P@>The second alternative is
to enter interactive mode.

@<P@>
@<Begin verbatim@>
fw +k
@<End verbatim@>

@<P@>From there, you can execute
the script using:

@<P@>
@<Begin verbatim@>
execute typeset
@<End verbatim@>

@<P@>Interactive mode could be very useful to those with
multiple-window workstations.@<X@>@(workstations@) The user
could create a window containing an interactive session of
FunnelWeb, and then switch between windows, editing, and
executing FunnelWeb proper and other programs.

@<P@>If you find yourself using the command interpreter a
lot, be sure to read about the other commands that are
available in the @<FunnelWeb Reference Manual@>.

@<Nav@>@(@<Hints_efficiency FILE@>@,@<Hints FILE@>@,@<Hints_default FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Hints_default HEADING@>@M@{@<SH@>@(5.9@)Setting Up Default Options@}
@$@<Hints_default FILE@>@M@{hints_default.html@}
@O@<hints_default.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Hints_default HEADING@>@)
@<XX@>@(options@,setting defaults@)@<XX@>@(default@,options@)

@<P@>If you do not like FunnelWeb's default settings for its
command line options, there are a number of ways in which
you can change them.

@<Narrowthing@>@(Define an @<DQ@>@(alias@):@,Use your
operating system @<DQP@>@(alias@)@<X@>@(alias@) facility to
create an alias for FunnelWeb containing the desired
options. FunnelWeb processes options from left to right, so
you can override these defaults later if you wish.@)

@<Narrowthing@>@(Create a script called
@<DQP@>@(fwinit.fws@):@,When FunnelWeb starts up, it
executes a script called
@<DQP@>@(fwinit.fws@)@<X@>@(fwinit.fws@)
if@<XX@>@(startup@,script@)@<XX@>@(initialization@,script@)
such a script exists in the current directory. You can use
this fact to set options before the run of FunnelWeb proper
by creating such a script and placing a single
@<DQP@>@(set@) command in it containing the desired options.
The main trouble with this approach is that the options in
the @<TT@>@(set@) command will be processed @<I@>@(after@)
the command line options, which means that you won't be able
to override them on the command line.@)

@<P@>For example, you might be involved more with presenting
programs than with running them, and want FunnelWeb to
generate a documentation file by default, but not to produce
listing or product files by default. In Unix you could do
this with:

@<P@>
@<Begin verbatim@>
alias fw fw -L -O +T
@<End verbatim@>

@<Nav@>@(@<Hints_interactive FILE@>@,@<Hints FILE@>@,@<Hints_make FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Hints_make HEADING@>@M@{@<SH@>@(5.10@)FunnelWeb and Make@}
@$@<Hints_make FILE@>@M@{hints_make.html@}
@O@<hints_make.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Hints_make HEADING@>@)
@<X@>@(make utility@)@<XX@>@(file@,dependencies@)

@<P@>The Unix @<TT@>@(Make@) program allows a set of
dependencies between a set of files to be described, and
then uses these dependencies to control the way in which the
files are created and updated. Typically, @<TT@>@(Make@) is
used to control the process of transforming a collection of
source code files to one or more executable files. As the
use of FunnelWeb implies an extra stage to this process, it
is natural to include the transformation of @<TT@>@(.fw@)
files to source code files as part of the @<TT@>@(Make@)
process. This is easy to do, but the user should be aware of
one aspect of FunnelWeb which can cause problems.

@<P@>It is often useful, when using FunnelWeb, to create a
FunnelWeb @<TT@>@(.fw@) file that generates more than one
product file. That is, a single @<TT@>@(.fw@) file may have
many macro definitions connected to product files so that
when the FunnelWeb @<TT@>@(.fw@) file is processed by
FunnelWeb, several files are created. For example, this
facility is convenient for placing a single package's
@<TT@>@(.h@) and @<TT@>@(.c@) files within the same
FunnelWeb @<TT@>@(.fw@) file.

@<P@>The use of multiple product files, however, provokes a
problem with dependencies. Suppose for example that a
FunnelWeb @<TT@>@(prog.fw@) produces two product files
@<TT@>@(proc.spec@) (a package specification) and
@<TT@>@(prog.body@) (a package body). If the package is
accessed in the way that packages normally are, it will be
quite common for the programmer to want to modify the
package body without modifying the program specification. So
the programmer will edit the @<TT@>@(prog.fw@) file to
change the package body. The result of running this through
FunnelWeb will be the desired new package body file.
However, FunnelWeb will also produce a new package
specification product file @<I@>@(even though it may be
identical to the previous version!@) The result is that the
newly created (with a recent file date) specification
package file could provoke a huge remake of much of the
program in which it resides.

@<P@>To solve the problem, FunnelWeb includes a command line
option (@<TT@>@(D@) for
Delete),@<XX@>@(D@,option@)@<XX@>@(delete@,output files@)
which when turned on (using @<DQP@>@(+D@)) causes FunnelWeb
to suppress@<XX@>@(suppression@,file@) product and
documentation files that are identical to the previously
existing versions of the same files. For example, if, during
a FunnelWeb  run, a macro was connected to a product file
called @<TT@>@(x.dat@), and the macro expanded to
@<I@>@(exactly@) the same text as is contained in
@<TT@>@(x.dat@) then FunnelWeb would simply @<I@>@(never
write the product file@), the file @<TT@>@(x.dat@) would be
untouched and, as a result, no further @<TT@>@(Make@)
propagations would take place.

@<P@>FunnelWeb implements this feature by writing each
product file to a temporary file with a temporary file name.
It then compares the temporary file with the target file. If
the two are identical, it deletes the temporary file. If the
two are different it deletes the target file and renames the
temporary file to the target file.

@<P@>Use of the @<TT@>@(D@) facility means that the
programmer need not be punished (by extra @<TT@>@(Make@)
propagations) for describing more than one product file in
the same FunnelWeb file.

@<Nav@>@(@<Hints_default FILE@>@,@<Hints FILE@>@,@<Hints_dangers FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Hints_dangers HEADING@>@M@{@<SH@>@(5.11@)The Dangers Of FunnelWeb@}
@$@<Hints_dangers FILE@>@M@{hints_dangers.html@}
@O@<hints_dangers.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Hints_dangers HEADING@>@)
@<XX@>@(FunnelWeb@,dangers@)@<XX@>@(FunnelWeb@,pitfalls@)

@<P@>Like many tools that are general and flexible,
FunnelWeb can be used in a variety of ways, both good and
bad. One of the original appeals of the literate approach to
programming for Knuth,@<XN@>@(Donald@,Knuth@) the inventor
of literate programming,@<XX@>@(literate@,programming@) was
that it allows the programmer to describe the target program
bottom up, top down, size to side, or chaotically if
desired.

@<P@>The flexibility that the literate style of
programming leaves much room for bad documentation
as well as good documentation. Years of experience
with FunnelWeb has revealed the following
stylistic pitfalls which the experienced FunnelWeb
user should take care to avoid. (Note: The fact that
these faults are listed here does not mean that
the author has eliminated them in his own work.
Rather, it is mainly the author's own mistakes
that have resulted in this list being compiled.
The author immediately confesses to several of the
faults listed here, most notably that of Pavlov
documentation).

@<Narrowthing@>@(Spaghetti
organization:@,By@<XX@>@(spaghetti@,organization@) far the
worst problem that arises in connection with the literate
style occurs where the programmer has used the literate tool
to completely scramble the program so that the program is
described and layed out in an unordered, undisciplined
@<DQ@>@(stream of consciousness@).@<X@>@(stream of
consciousness@) In such cases the programmer may be using
the literate style as a crutch to avoid having to think
about structuring the presentation.@)

@<Narrowthing@>@(Boring
organization:@,At@<XX@>@(boring@,organization@) the other
extreme, a program may be organized in such a strict way
that it is essentially laid out in the order most
@<DQ@>@(desired@) by the target programming language. For
example, each macro might contain a single procedure, with
all the macros being called by a macro connected to a file
at the top. In many cases a boring structure may be entirely
appropriate, but the programmer should be warned that it is
easy to slip into such a normative style, largely forgetting
the descriptive structural power that FunnelWeb provides.@)

@<Narrowthing@>@(Poor random
access:@,Using@<XX@>@(random@,access@) FunnelWeb, it is
quite possible to write programs like novels@<X@>@(novels@)
--- to be read from cover to cover. Sometimes the story is
very exciting, with data structures making dashing triumphs
and optimized code bringing the story to a satisfying
conclusion. These programs can be works of art.
Unfortunately, without careful construction, such
@<DQ@>@(novel-programs@) can become very hard to access
randomly by (say) a maintenance
programmer@<XX@>@(maintenance@,programmer@) who wishes only
to dive in and fix a specific problem. If the entire program
is scrambled for sequential exposition, it can be hard to
find the parts relating to a single function. Somehow a
balance must be struck in the document between the needs of
the sequential and of the random-access reader. This balance
will depend on the intended use of the program.@)

@<Narrowthing@>@(Too-interdependent
documentation:@,Sometimes,
when@<XX@>@(documentation@,interdependent@) editing a
program written using FunnelWeb, one knows how to modify the
program, but one is unsure of how to update the surrounding
documentation! The documentation may be woven into such a
network of facts that it seems that changing a small piece
of code could invalidate many pieces of documentation
scattered throughout the document. The documentation becomes
a big tar pit in which movement is impossible. For example,
if you have talked about a particular data structure
invariant throughout a document, changing that invariant in
a small way could mean having to update all the
documentation without touching much code. In such cases, the
documentation is too interdependent. This could be
symptomatic of an excessibly interconnected program, or of
an excessively verbose or redundant documenting style. In
any case, a balance must be struck between the
conversational style that encourages redundancy (by
mentioning things many times) and the normalized database
approach where each fact is given at only one point, and the
reader is left to figure out the implications throughout the
document.@)

@<Narrowthing@>@(Pavlov
documentation:@,By@<XX@>@(pavlov@,documentation@) placing so
much emphasis on the documentation, FunnelWeb naturally
provides slots where documentation @<DQ@>@(should@) go. For
example, a FunnelWeb user may feel that there may be a
rather unpleasant gap between a @<TT@>@(@@C@) marker and the
following macro. In many cases @<I@>@(no@) commentary is
needed, and the zone is better left blank rather than being
filled with the kind of uninformative waffle one often finds
filling the slots of structured documentation written
according to a military standards
(@<eg@>MIL-STD-2167A).@<X@>@(MIL-STD-2167A@)@<X@>@(2167A@) (Note:
This is not a criticism of 2167A, only of the way it is
sometimes used). The lesson is to add documentation only
when it adds something. The lesson in Strunk and
White@<Paper@>@(Strunk79@) (p.@<_@>23) holds for program
documentation as it does for other writing: @<DQ@>@(Vigorous
writing is concise. A sentence should contain no unnecessary
words, a paragraph no unnecessary sentences, for the same
reason that a drawing should have no unnecessary lines and a
machine no unnecessary parts. This requires not that the
writer make all his sentences short, or that he avoid all
detail and treat his subjects only in outline, but that
every word tell.@).@)

@<Narrowthing@>@(Duplicate
documentation:@,Where@<XX@>@(duplicate@,documentation@) the
programmer is generating product files that must exist on
their own within the entire programming environment
(@<eg@>the case of a programmer in a team who is using
FunnelWeb for his own benefit but must generate (say)
commented Ada@<X@>@(Ada@) specification package files) there
is a tendency for the comments in the target code to
duplicate the commentary in the FunnelWeb text. This may or
may not be a problem, depending on the situation.
However, if this is happening, it is certainly worth the
programmer spending some time deciding if one or other of
the FunnelWeb or inline-comment documentation should be
discarded. In many cases, a mixture can be used, with the
FunnelWeb documentation referring the reader to the inline
comments where they are present. For example:@)

@<P@>
@<Begin verbatim@>
@@A Here is the header comment for the list package
specification. The reader should read these comments
carefully as they define a list. There is no need to
duplicate the comments in this text.

@@$@@@<<@>Specification package comments@@@<>@>==@@{@@-
-- LIST PACKAGE
-- ============
-- * A LIST consists of zero or more ITEMS.
-- * The items are numbered 1 to N where N
--   is the number of items in the list.
-- * If the list is non-empty, item 1
--   is called the HEAD of the list.
-- * If the list is non-empty, item N
--   is called the TAIL of the list.
-- ...
@@}
@<End verbatim@>

@<Narrowthing@>@(Overdocumenting:@,Another@<XX@>@(over@,documentation@)
evil that can arise when using FunnelWeb is to over-document
the target program. In some of Knuth's earlier (@<eg@>1984)
examples of literate programming, each variable is given its
own description and each piece of code has a detailed
explanation. This level of analysis, while justified for
tricky tracts of code, is probably not warranted for most of
the code that constitutes most programs. Such
over-commenting can even have the detrimental affect of
obscuring the code, making it hard to understand because it
is so scattered (see @<DQ@>@(spaghetti organization@)
earlier). It is up to the user to decide when a stretch of
just a few lines of code should be pulled to bits and
analysed and when it is clearer to leave it alone.@)

@<Narrowthing@>@(@,In the case where there are a few rather tricky
lines of code, a detailed explanation may be appropriate.
The following example contains a solution to a problem
outlined in section 16.3 of the book @<DQ@>@(The Science of
Programming@) by David Gries@<Paper@>@(Gries81@).@)

@<P@>
@<Begin verbatim@>
@@C@@@<<@>Calculation of the longest plateau in b@@@<>@>

This section contains a solution to a problem
outlined in section 16.3 of the book @@/The
Science of Programming@@/ by David Gries[Gries81].

@@D Given a sorted array @@{b[1..N]@@} of
integers, we wish to determine the @@/length@@/ of
the longest run of identically valued elements in
the array. This problem is defined by the
following precondition and postcondition.

@@$@@@<<@>Precondition@@@<>@>==@@{/* Pre: sorted(b). */@@}
@@$@@@<<@>Postcondition@@@<>@>==@@{@@-
/* Post: sorted(b) and p is the length */
/* of the longest run in b[1..N].      */@@}

@@D We approach a solution to the problem by
deciding to try the approach of scanning through
the array one element at a time maintaining a
useful invariant through each iteration. A loop
variable array index @@{i@@} is created for this
purpose. The bound function is @@{N-i@@}. Here is
the invariant.

@@$@@@<<@>Invariant@@@<>@>==@@{@@-
/* Invariant: sorted(b) and 1@<<@>=i@<<@>=N and   */
/*            p is len of longest run in b[1..i]. */@@}

@@D Establishing the invariant above in the
initial, degenerate case is easy.

@@$@@@<<@>Establish plateau loop invariant@@@<>@>@@{@-
i=1; p=1;@@}

@@D At this stage, we have the following loop
structure. Note that when both the invariant and
@@{i == N@@} are true, the postcondition holds and
the loop can terminate.

@@$@@@<<@>p=len(longest run in sorted b[1..N])@@@<>@>@@{@@-
@@@<<@>Precondition@@@<>@>
@@@<<@>Establish plateau loop invariant@@@<>@>
while (i != N)
  {
   @@@<<@>Invariant@@@<>@>
   @@@<<@>Loop body@@@<>@>
  }
@@@<<@>Postcondition@@@<>@>
@@}

@@D Now there remains only the loop body whose
sole task is to increase @@{i@@} (and so decrease
the value of the bound function) while maintaining
the invariant. If @@{p@@} is the length of the
longest run seen so far (i.e. in b[1..i]), then,
because the array is sorted, the extension of our
array range to @@{b[1..i+1]@@} can only result in
an increase in @@{p@@} if the new element
terminates a run of length @@{p+1@@}. The increase
can be at most 1. Because the array is sorted, we
need only compare the endpoints of this possible
run to see if it exists. This is performed as
shown below.

@@$@@@<<@>Loop body@@@<>@>==@@{@-
i++; if (b[i] != b[i-p]) p++;@@}
@<End verbatim@>

@<P@>Where the code is more obvious,
it is often better to let the code speak for itself.

@<P@>
@<Begin verbatim@>
@@C The following function compares two C
strings and returns TRUE iff they are identical.

@@$@@@<<@>Function comp@@@<>@>==@@{@@-
bool comp(p,q)
char *p,*q;
{
 while (TRUE)
   {
    if (*p != *q  ) return FALSE;
    if (*p == '\0') return TRUE;
    p++; q++;
   }
}
@@}
@<End verbatim@>

@<Nav@>@(@<Hints_make FILE@>@,@<Hints FILE@>@,@<Hints_debugging FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Hints_debugging HEADING@>@M@{@<SH@>@(5.12@)Wholistic Debugging@}
@$@<Hints_debugging FILE@>@M@{hints_debugging.html@}
@O@<hints_debugging.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Hints_debugging HEADING@>@)

@<P@>Surprising though it may be, FunnelWeb has a role
to play in the @<B@>@(debugging@) of programs. My
experience in programming has led me to the concept of
@<NewTerm@>@(wholistic debugging@). When many programmers
detect a bug, their first reaction seems to be to jump into
the debugger@<X@>@(debugger@) where they often spend many
hours stepping through endless stretches of code and
generally wasting a lot of time.

@<P@>In contrast, my first reaction when I detect a bug is
to realize that @<B@>@(the code must not be in good enough
shape if such a bug can arise!@) The presence of the bug is
taken as symptomatic of the lack of general health of the
code. If that bug occurred, why not another? In response to
this realization, my reaction is not to enter the debugger,
but rather to return to the original code and tend it like a
garden,@<XX@>@(code@,gardening@) adding more comments,
reworking the weaker parts, adding assertions, and looking
for faults. In many cases, the search for faults does not
even centre on the specific bug that arose, but does tend to
focus on the area of code where the bug is likely to be.

@<P@>The result is often that the original bug is located
more quickly than it would have been had the debugger been
involved. But even if it isn't, there are other benefits. A
programmer who enters the debugger may stay there for hours
and still not find the bug. The result is frustration and no
positive gain at all. In contrast, by tending to the code,
the programmer is making forward progress at all times (the
code is constantly improving) even if the bug is not
immediately found. At the end of ten hours, the programmer
can at least feel that the code is @<DQ@>@(ten hours
better@), whereas the debugger freak will likely feel
defeated. All this makes code tending better psychologically
as well as a more efficient approach to debugging.

@<P@>I call this technique wholistic debugging, for it is
like the difference between conventional and wholistic
medicine.@<XX@>@(wholistic@,medicine@) Go to a conventional
doctor with a headache and he might send off for head
X-rays, perform allergy tests and perform many other
debugging activities. Go to a wholistic doctor with the same
problem and he might look to see if you are fit, assess your
mental health, and ask you if your marriage is working. Both
approaches are appropriate at different times, but I believe
that, on balance, in programming the wholistic approach is
not used enough.

@<Nav@>@(@<Hints_dangers FILE@>@,@<Hints FILE@>@,@<Hints_tabs FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Hints_tabs HEADING@>@M@{@<SH@>@(5.13@)TABs@}
@$@<Hints_tabs FILE@>@M@{hints_tabs.html@}
@O@<hints_tabs.html@>@{@-
@<Begin FWTutMan page/wide/H1@>@(@<Hints_tabs HEADING@>@)

@<P@>FunnelWeb is designed to protect its user from spurious
non-printable characters that might creep into a source file,
and so it classifies any occurrence of such a character as
an error.

@<P@>FunnelWeb's idea of printable is any character in the
range ASCII [32..126]. A number of people have complained
about this, saying that they want to include 8-bit
characters in their FunnelWeb input files. Currently there
is no fix for this except to insert characters explicitly
into the output using a @<TT@>@(@@^@) sequence (see the
@<FunnelWeb Reference Manual@> for more details).

@<P@>In particular, FunnelWeb flags TAB characters in its
input file as errors because TABs are essentially invisible
control characters with very poorly-defined semantics; it's
FunnelWeb's job to keep an eye on the input file to ensure
that the programmer doesn't get any nasty surprises and as
TABs can cause several kinds of surprises, they are excluded.

@<P@>A lot of people have complained about this aspect of
FunnelWeb. Unfortunately, this issue has not yet been
resolved. If you actually @<I@>@(need@) TABs in the output
file (@<eg@>for a makefile), then you should insert TABs
explicitly using a @<TT@>@(@@^D(009)@) sequence (see the
@<FunnelWeb Reference Manual@> for more details).

@<P@>The following C program removes TABs. The program was
kindly donated by John Skaller. Warning: This program
doesn't have any error checking.

@<Begin verbatim@>
/* UNTAB Program                                            */
/* =============                                            */
/* Author       : John Skaller (maxtal@@extro.ucc.su.oz.au) */
/* Organization : MAXTAL P/L 6 Mackay St ASHFIELD 2131.     */
/* Usage        : untab 2 <infile >outfile                  */
/* Status       : Public domain.                            */

#include <stdio.h>

int main(int argv, char **argc)
{
        int n=2;
        if(argv==2)sscanf(argc[1],"%d",&n);
        int ch=getchar();
        int column=0;
        while(ch!=-1){
                if(ch=='\n'){putchar('\n'); column=0;}
                else if(ch==9){
                        putchar(' '); column++;
                        while(column % n){putchar(' '); column++;}
                }
                else { putchar(ch); column++;}
                ch=getchar();
        }
}
@<End verbatim@>

@<Nav@>@(@<Hints_debugging FILE@>@,@<Hints FILE@>@,@<Hints_htmlstyle FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Hints_htmlstyle HEADING@>@M@{@<SH@>@(5.14@)HTML Style@}
@$@<Hints_htmlstyle FILE@>@M@{hints_htmlstyle.html@}
@O@<hints_htmlstyle.html@>@{@-
@<Begin FWTutMan page/wide/H1@>@(@<Hints_htmlstyle HEADING@>@)

@<P@>If you specify the @<TT@>@(+U@) command line option,
FunnelWeb will generate a @<TT@>@(.html@) documentation file
containing HTML. In the @<TT@>@(@<<@>HEAD@<>@>@) section of
this file, FunnelWeb defines the style of the file by including
a style directive similar to the following:

@<P@>
@<Begin verbatim@>
   @<<@>STYLE TYPE="text/css"@<>@>
   @<<@>!--
   A {text-decoration: none}
   H1 { font-family: sans-serif; font-size: large }
   H2 { font-family: sans-serif; font-size: medium;
        font-weight: bold }
   H3 { font-family: sans-serif; font-size: medium }
   H4 { font-family: sans-serif; font-size: small }
   H5 { font-family: sans-serif; font-size: small }
   // --@<>@>
   @<<@>/STYLE@<>@>
@<End verbatim@>

@<P@>If you do not like this style, you can change it simply by
editing the @<TT@>@(.html@) file and changing the style directive in
the @<TT@>@(@<<@>HEAD@<>@>@) section. However, this change will be
overwritten the next time you regenerate the HTML file.

@<P@>Another way to define your own style is to turn off FunnelWeb's
automatic @<DQ@>@(escaping@) of special characters with:

@<P@>
@<Begin verbatim@>
@@p typesetter = html
@<End verbatim@>

@<P@>You can then include a style directive in one one of the very
early comment parts of your FunnelWeb source file, where it will
override the one written by FunnelWeb in the @<TT@>@(@<<@>HEAD@<>@>@)
section. The disadvantage is that your FunnelWeb source file becomes
typesetter-dependent.


@<Nav@>@(@<Hints_tabs FILE@>@,@<Hints FILE@>@,@<Hints_emacs FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Hints_emacs HEADING@>@M@{@<SH@>@(5.15@)A FunnelWeb Mode For Emacs@}
@$@<Hints_emacs FILE@>@M@{hints_emacs.html@}
@O@<hints_emacs.html@>@{@-
@<Begin FWTutMan page/wide/H1@>@(@<Hints_emacs HEADING@>@)

@<P@>@<Tony Coates@> has created a FunnelWeb Emacs mode, which he has
made generally available. The mode is written as a FunnelWeb file. To
use the mode, click on the link below. A new window should appear
containing a plain text file which is the FunnelWeb source for the
mode. Save the plain text file on your disk as @<TT@>@(fwmode.fw@) and
then invoke FunnelWeb  using @<TT@>@(fw fwmode@) to generate the emacs
mode files @<TT@>@(fw-mode.el@) and @<TT@>@(switch-mode.el@).

@<P@>
@<Begin indent@>
   @<Size4@>@(@<Link/blank@>@(fwmode.txt@,FunnelWeb Emacs Mode FunnelWeb Source File@)@)
@<End indent@>

@<Nav/last@>@(@<Hints_htmlstyle FILE@>@,@<Hints FILE@>@,@<Hints FILE@>@)

@<End FWTutMan page@>
@}

@O@<fwmode.txt@>@{@-
@i 0fwmode
@}

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

@$@<Examples HEADING@>@M@{@<SH@>@(6@)Examples of FunnelWeb Applications@}
@$@<Examples HEADING/short@>@M@{@<SH@>@(6@)Examples@}
@$@<Examples FILE@>@M@{examples.html@}
@O@<examples.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Examples HEADING@>@)
@<XX@>@(FunnelWeb@,example applications@)@<XX@>@(FunnelWeb@,applications@)

@<P@>Despite (or perhaps because of) its flexibility and
simplicity, FunnelWeb can be applied to quite a number of
different text processing and documenting problems. This
section gives some examples of some of the more interesting
real problems that FunnelWeb has solved.

@<P@>
@<Examples index@>

@<Nav@>@(@<Hints FILE@>@,@<Index FILE@>@,@<Web FILE@>@)

@<End FWTutMan page@>
@}

@$@<Examples index@>@M@{
@<Begin size3@>
@<Begin indent/narrow@>
@<Link@>@(@<Examples_postscript FILE@>@,@<Examples_postscript HEADING@>@)@<BR@>
@<Link@>@(@<Examples_adt FILE@>@,@<Examples_adt HEADING@>@)@<BR@>
@<Link@>@(@<Examples_languages FILE@>@,@<Examples_languages HEADING@>@)@<BR@>
@<Link@>@(@<Examples_function FILE@>@,@<Examples_function HEADING@>@)@<BR@>
@<Link@>@(@<Examples_comments FILE@>@,@<Examples_comments HEADING@>@)@<BR@>
@<Link@>@(@<Examples_sharing FILE@>@,@<Examples_sharing HEADING@>@)@<BR@>
@<Link@>@(@<Examples_generics FILE@>@,@<Examples_generics HEADING@>@)@<BR@>
@<End indent/narrow@>
@<End size3@>
@}

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

@$@<Examples_postscript HEADING@>@M@{@<SH@>@(6.1@)Analyzing the Monster Postscript Header File@}
@$@<Examples_postscript FILE@>@M@{examples_postscript.html@}
@O@<examples_postscript.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Examples_postscript HEADING@>@)
@<XX@>@(macro@,names@)@<XX@>@(macro@,identifiers@)
@<XX@>@(monster file@,postscript@)

@<P@>During my Ph.D. candidature, I determined at one point
that it would be very desirable to automatically insert
diagrams from the @<I@>@(MacDraw@)@<X@>@(MacDraw@) program
on my Macintosh into TeX@<X@>@(TeX@) @<TT@>@(insert@)ions in
my thesis.@<XX@>@(PhD@,thesis@) This would allow diagrams to
float around with the text and be printed automatically
rather than having to be printed separately and stuck in
with real glue. On the face of it, the problem seemed
inherently solvable, as the Macintosh@<X@>@(Macintosh@) could
generate PostScript@<X@>@(PostScript@) for each diagram and
this PostScript could presumably be inserted into the
PostScript generated using TeX.

@<P@>The only trouble was that the Macintosh PostScript code
for the diagrams relied on an Apple PostScript header
file.@<XX@>@(postscript@,header file@) This meant that the
header file had to be included at the start of the TeX
PostScript if the inserted PostScript for the diagrams was
to work. Unfortunately, merely including the header file at
the top didn't work, and it turned out that a rather
detailed analysis of some parts of the Apple header file was
required in order to perform the necessary surgery on the
header file to make it work. This analysis was severely
aggravated by the fact that the PostScript header file was
virtually unreadable. Basically it was about 50K of
interwoven definitions, that looked as if it had been run
through a word processor. There was no way that the code
could be understood clearly without some kind of
reformatting. Two other aspects of the problem further
complicated the analysis:

@<P@>
@<Begin list@>

@<Item@>The definitions of interest (@<ie@>the ones causing
the problems) were scattered throughout the heaeder file.

@<Item@>Many definitions could not be moved within the
header file. For one or more
reasons (@<eg@>to keep a definition within the activation of
a particular dictionary @<TT@>@(begin@) and @<TT@>@(end@))
it would have been unwise to move the definitions of
interest to the same point in the file.

@<End list@>

@<P@>In fact the file was so messy and complicated that, as
a rule, it had to be handled with kid gloves. It would have
been unwise to re-arrange the definitions or to insert
comments.

@<P@>To my surprise, FunnelWeb provided an unexpected
solution to the problem. First I replaced all occurrences of
the @<TT@>@(@@@) in the header file with @<TT@>@(@@@@@).
Second, I placed the entire header file in a FunnelWeb macro
definition connected to a product file. I then processed the
file and checked to make sure that the product file was
identical to the original file. By doing all this I had
placed the header file under FunnelWeb control. I then left
the macro definition largely untouched, but replaced the
PostScript definitions of interest with FunnelWeb macro
calls, moving the actual PostScript definitions into
FunnelWeb macro definitions at the end of the FunnelWeb
file.

@<P@>
@<Begin verbatim@>
@@O@@@<<@>LaserHeader.ps@@@<>@>==@@{@@-
Unreadable Postscript code
@@@<<@>Print routine@@@<>@>
Unreadable Postscript code
@@@<<@>Zap routine@@@<>@>
Unreadable Postscript code
@@}

@@A This routine looks as if it does this, but really is
does that, blah, blah blah.

@@$@@@<<@>Print routine@@@<>@>==@@{@@-
/print { push pop pop push turn around
         and jump up and down and print it} def
@@}

@@A This routine zaps the...

@@$@@@<<@>Zap routine@@@<>@>==@@{@@-
/zap { push pop pop push turn around and
       jump up and down and print it} def
@@}
@<End verbatim@>

@<P@>Use of FunnelWeb meant that I was able to pluck out the
definitions of interest (a very small part of the whole
file) and collect them as a group at the end of the file
where they could be studied. Because each definition was
safely contained in a macro, it was possible to write a
detailed commentary of each routine without fear of
affecting the final PostScript code in any way at all. Once
this analysis was completed, it was possible to perform
surgery on the offending PostScript definitions in an
extremely controlled way. In particular, the FunnelWeb input
file served as a repository for all the different versions
of particular routines that were tried in order to get the
definitions to work. A new (@<B@>@(Z@)ero) macro was created for
each version of each definition, and a commentary of how it
performed added above it.

@<P@>This case demonstrates that FunnelWeb is an extremely
powerful tool for dissecting and documenting cryptic text
files.@<XX@>@(cryptic@,text files@) Through the use of
macros, particular parts of the file can be isolated and
discussed without affecting the final product file in any
way. In the example above, only a small part of the file was
analysed, the rest being left as a blob, but in the general
case, a cryptic text file could be inserted into FunnelWeb
and then incrementally dissected (and possibly modified)
until the result is a fully documented literate program.
That this can be done without affecting the actual product
file demonstrates the high degree of descriptive control
that FunnelWeb provides.

@<Nav/first@>@(@<Examples FILE@>@,@<Examples FILE@>@,@<Examples_adt FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Examples_adt HEADING@>@M@{@<SH@>@(6.2@)Making Ada ADTs More Abstract@}
@$@<Examples_adt FILE@>@M@{examples_adt.html@}
@O@<examples_adt.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Examples_adt HEADING@>@)
@<X@>@(Ada@)@<X@>@(abstract data type@)@<X@>@(ADT@)

@<P@>Like many modern programming languages, Ada provides
mechanisms for hiding information and structure. In
particular, Ada provides a @<NewTerm@>@(package@) facility
that allows the programmer to declare objects in a package
definition and define them in a corresponding package body.
This works well for functions and procedures. However, in
the case of types, implementation issues (in particular, the
need to know the size of exported types) have led the
designers of Ada to force the placement of private type
definitions in the definition package rather than the
implementation package. This means that some implementation
details are present in the package definition for all to
see. While not actually dangerous (the user of the package
cannot make use of the information without recourse to
@<DQ@>@(Chapter@<_@>13@) of the Ada Language Reference
Manual@<Paper@>@(DOD83@)), this aspect of Ada is certainly
unpleasant.

@<P@>During the development of some Ada programs, FunnelWeb
was used to solve this problem. Instead of creating a
separate file for the package specification and package
body, a single FunnelWeb file was created containing two
sections, one for the each package part. The
@<DQ@>@(private@) part of the package specification was then
moved (using a FunnelWeb macro definition) to the section
describing the package body. Readers who wished only to read
the package specification could read only the first part,
which contained a fully documented description not
containing the private definition.

@<Nav@>@(@<Examples_postscript FILE@>@,@<Examples FILE@>@,@<Examples_languages FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Examples_languages HEADING@>@M@{@<SH@>@(6.3@)Multiple Language Systems@}
@$@<Examples_languages FILE@>@M@{examples_languages.html@}
@O@<examples_languages.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Examples_languages HEADING@>@)
@<XX@>@(multiple@,languages@)

@<P@>With the prevalence of open systems@<X@>@(open
systems@) and multi-vendor computing, it is often necessary
to construct systems consisting of programs written in a
number of different programming languages for a number of
different systems. For example, a particular functionality
might be implemented by a shellscript (invoked by the user)
that calls a C@<_@>program that makes a network connection to a
Pascal program that queries a database. Quite often all
these programs must conspire closely to execute their
function. In the normal case, they must be written
separately. FunnelWeb allows them to be written as a whole.

@<P@>By creating a single FunnelWeb file that creates many
product files in different languages, the programmer can
describe the interaction between the different programs in
any manner desired. Furthermore, because the different
product files  are all created in the same @<DQ@>@(text
space@) (@<ie@>in a single FunnelWeb file), it is easy for
them to share information.

@<P@>For example, in one real application FunnelWeb was used
to create a system for printing
files@<XX@>@(printing@,system@) on a laser
printer@<XX@>@(laser@,printer@) connected to a remote Vax
Unix machine from a local Vax VMS machine. The system
consisted of two files: a VMS DCL command procedure to run
on the local node, and a Unix shellscript to run on the
remote node. The user, by giving the print command, invoked
the local VMS command procedure, which in turn fired up the
remote Unix shellscript. The two scripts then cooperated to
transfer the files to be printed and print them.

@<P@>In addition to its usual documentation powers,
FunnelWeb assisted in the creation of this system in two
special ways. First, it allowed pieces of code from the two
different command procedures to be partially interwoven in a
description of their interaction. This is just not possible
with comments. Second, it facilitated the use of shared
information. For example, under some conditions, each file
to be printed would be renamed and copied to the remote
system using a particular constant filename
(@<eg@>@<DQP@>@(printfile.tmp@)). FunnelWeb allowed this
constant filename to be included in a single macro
definition which was invoked in the definition of each of
the scripts. This ensured that the two scripts used the same
name.

@<P@>
@<Begin verbatim@>
@@A The following macro contains the temporary
file name used to allow the two shellscripts to
transfer each file to be printed.

@@$@@@<<@>printfile@@@<>@>@@M==@@{printme.txt@@}

@@A Here are the scripts for the local VMS node
and the remote UNIX node.

@@O@@@<<@>vmscommandprocedure.com@@@<>@>==@@{@@-
DCL commands
copy @@@<<@>printfile@@@<>@> unixnode::
DCL commands
@@}

@@O@@@<<@>unixshellscript@@@<>@>==@@{@@-
unix commands
print @@@<<@>printfile@@@<>@>
unix commands
@@}
@<End verbatim@>

@<P@>In the case of the printing system, the entire system
was described and defined in a single FunnelWeb
@<TT@>@(.fw@) file. In larger systems containing many
FunnelWeb @<TT@>@(.fw@) files for many different modules in
many different languages, the same trick can be pulled by
placing FunnelWeb macro definitions for shared values into
FunnelWeb include files. For example, a suite of
implementations of network nodes, with each implementation
being in a different programming language for a different
target machine, could all share a table of configuration
constants defined in macros in a FunnelWeb include file.

@<P@>In summary, FunnelWeb's macro and include file
mechanisms provide a simple way for programs written in
different languages to share information. This reduces
redundancy between the systems and hence the chance of
inconsistencies arising.@<X@>@(sharing information@)

@<Nav@>@(@<Examples_adt FILE@>@,@<Examples FILE@>@,@<Examples_function FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Examples_function HEADING@>@M@{@<SH@>@(6.4@)The Case of the Small Function@}
@$@<Examples_function FILE@>@M@{examples_function.html@}
@O@<examples_function.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Examples_function HEADING@>@)
@<XX@>@(small@,functions@)

@<P@>Often, when programming, there is a need for a code
abstraction@<XX@>@(code@,abstraction@) facility that
operates at the text level. If the statement
@<DQP@>@(a:=3;@) occurs often, it may be best simply to
repeat it verbatim. If a sequence of one hundred statements
is repeated often, it is normal to remove the code to a
function and replace the occurrences by a function call.
However, in between these two extremes are cases where a
particular sequence of code is long enough and appears often
enough to be troublesome, but which is bound so messily to
its environment as to make a function call cumbersome.

@<P@>For example, the following line of statements
(referring to five variables declared @<I@>@(local@) to a
function) might appear ten times in a function:

@<P@>
@<Begin verbatim@>
a=b*3.14159; c=d % 256; e=e+1;
@<End verbatim@>

@<P@>Now the @<DQ@>@(normal@) rule of programming says that
these statements should be placed in a procedure (also
called a @<DQ@>@(function@) in the C programming language
used in this example), but here five local variables are
used. Use of a procedure (function) would result in a
procedure definition looking something like:

@<P@>
@<Begin verbatim@>
void frobit(a,b,c,d,e)
float *a,b;
int *c,d;
unsigned *e;
{*a=b @<<@>@<<@> 8; *c=d % 256; *e=*e+1;}
@<End verbatim@>

@<P@>and a procedure call something like

@<P@>
@<Begin verbatim@>
frobit(&a,b,&c,d,&e);
@<End verbatim@>

@<P@>This might be workable in a language that allowed
formal parameters to be specified to be bound only to
particular variables. Similarly, it might be possible to
avoid the parameter list in languages that support local
procedures that can access non-local variables (such as
Pascal@<X@>@(Pascal@)). However, in our example here, in the
C programming language, these options are not available, and
so we must either create a function with five parameters, or
use the C macro preprocessor@<XX@>@(preprocessor@,C@) (the
best solution). FunnelWeb provides the same macro facility
for languages that do not have a built-in preprocessor.

@<P@>In particularly speed-stressed applications, the
programmer may be reluctant to remove code to a procedure
because of the procedure-call overhead.@<XX@>@(procedure
call@,overhead@) FunnelWeb macros can help there too.

@<P@>In summary, there sometimes arises in programming
situations where the cost of defining a procedure is higher
than the benefits it will bestow. Common reasons for this
are the run-time procedure overhead and the messy binding
problems@<XX@>@(binding@,problems@) caused by removing
target code from its target context. FunnelWeb can help in
these situations by allowing the programmer to define a text
macro. This avoids all the problems and provides an
additional incentive for the programmer to describe the
piece of code so isolated.

@<Nav@>@(@<Examples_languages FILE@>@,@<Examples FILE@>@,@<Examples_comments FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Examples_comments HEADING@>@M@{@<SH@>@(6.5@)When Comments are Bad@}
@$@<Examples_comments FILE@>@M@{examples_comments.html@}
@O@<examples_comments.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Examples_comments HEADING@>@)
@<XX@>@(comments@,abuse@)@<XX@>@(eliminating@,comments@)

@<P@>In the @<DQ@>@(good old days@)@<X@>@(good old days@) of
small machine memories and interpreted BASIC,@<X@>@(BASIC@)
programmers would eliminate the @<DQP@>@(REM@)
statements@<XX@>@(REM@,statement@) (comments) from their
BASIC programs so as to save space and increase execution
speed. Whilst this was obviously an appalling programming
practice, the small memories and slow microprocessors often
made this tempting, if not necessary.

@<P@>Thankfully, times have changed since then, and most
code is now compiled rather than interpreted. However, from
time to time one still runs into an environment or
situation, or special-purpose language, where comments are
either unavailable (no comment feature) or undesirable. Here
FunnelWeb can be used to fully document the code without
resulting in any comments in the final code at all. For
example:@<XX@>@(header@,files@)

@<P@> @<Begin list@>

@<Item@>Comments in frequently used @<TT@>@(.h@) header
files in C programs@<XX@>@(C@,header@) can have a
significant impact on compilation speed. Often such header
files are fairly cryptic and really ought to be well
commented, but their authors are reluctant to.

@<Item@>Comments are undesirable in
PostScript@<X@>@(postscript@) header files that must be
transferred repeatedly along communications channels
(@<eg@>the Apple Macintosh LaserWriter header file).

@<Item@>Interpreted programs in embedded systems.

@<Item@>Hand written machine code in hex dump form could be
commented.

@<Item@>A programmer may wish to annotate a text data file
containing lists of numbers that is to be fed into a
statistical program that does not provide any comment
facility for its input file.

@<End list@>

@<P@>In all these situations, FunnelWeb allows full
integrated documentation without any impact on the final
code.

@<Nav@>@(@<Examples_function FILE@>@,@<Examples FILE@>@,@<Examples_sharing FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Examples_sharing HEADING@>@M@{@<SH@>@(6.6@)Documents That Share Text@}
@$@<Examples_sharing FILE@>@M@{examples_sharing.html@}
@O@<examples_sharing.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Examples_sharing HEADING@>@)
@<XX@>@(sharing@,text@)

@<P@>FunnelWeb is very useful when preparing multiple
documents that must share large slabs of identical text that
are being constantly modified.

@<P@>For example someone preparing two slightly different
user manuals for two slightly different audiences might want
the manuals to share large slabs of text, while still
allowing differences between them. The following example
shows how this can be done. The code is cluttered, but this
clutter would not be a problem if the lumps of text were
moderately large.

@<P@>
@<Begin verbatim@>
@@O@@@<<@>manual1.txt@@@<>@>==@@{@@@<<@>M1@@@<>@>@@+@@}
@@O@@@<<@>manual2.txt@@@<>@>==@@{@@@<<@>M2@@@<>@>@@+@@}

@@$@@@<<@>M1@@@<>@>+=@@{@@@<<@>T1@@@<>@>@@}
@@$@@@<<@>M2@@@<>@>+=@@{@@@<<@>T1@@@<>@>@@}
@@$@@@<<@>T1@@@<>@>@@M==@@{@@-
First lump of text shared by both documents.@@+@@}

@@$@@@<<@>M1@@@<>@>+=@@{Text for first document@@+@@}
@@$@@@<<@>M2@@@<>@>+=@@{Text for second document@@+@@}

@@$@@@<<@>M1@@@<>@>+=@@{@@@<<@>T2@@@<>@>@@}
@@$@@@<<@>M2@@@<>@>+=@@{@@@<<@>T2@@@<>@>@@}
@@$@@@<<@>T2@@@<>@>@@M==@@{@@-
Second lump of text shared by both documents.@@+@@}
@<End verbatim@>

@<P@>An alternative approach, which might work better in
situations where there are many small differences between
the two documents rather than a few large ones, is to define
a macro with two arguments, one for each product file
document. Write the document from top to bottom, but place
all stretches that differ between the two documents in a
macro call.@<XX@>@(annual@,report@)

@<P@>
@<Begin verbatim@>
@@! Set the definition of @@#D to
@@!    @@1 to create the shareholders report.
@@!    @@2 to create the customers report.
@@$@@#D@@(@@2@@)@@M==@@{@@1@@}

@@O@@@<<@>report.txt@@@<>@>==@@{@@-
ANNUAL REPORT TO @@#D@@(Shareholders@@,Customers@@)
=================@@#D@@(============@@,=========@@)
This has been a very good year for The Very Big
Corporation of America. With your help, we have
been able to successfully
@@#D@@(@@"screw the customers
          for every cent they have@@"@@,
     @@"knock the shareholders into
        submission to bring you lower prices@@"@@).
With gross earnings approaching six trillion
dollars, we have been able to
@@#D@@(@@"increase dividends@@"@@,
     @@"lower prices@@"@@).
We expect to have an even better year next year.
@@}
@<End verbatim@>

@<P@>One application where text sharing can be particularly
useful is in the preparation of computer
documentation@<XX@>@(examples@,documentation@) containing
examples. For example, a book describing a new programming
language might be full of examples of small programs written
in the language which the user might want to try without
having to type them all in. The @<DQ@>@(default@) approach
of keeping a copy of the examples in the text of the book
and another copy in separate files is cumbersome and error
prone, because both files have to be updated whenever an
example is changed. A more sophisticated approach is to
store each example in a separate file, and then use the
@<DQ@>@(include file@) facility of the word processor to
include each example in the text. This is a better solution,
but suffers from a few drawbacks. First, when editing the
book in a word processor, the examples in the book will not
be directly accessible or visible. To see an example, the
writer would have to open the file containing the example in
a separate window. This could become tedious if the text
contained many examples, as many texts do. Furthermore,
there is a risk that some example files will be included in
the wrong place. Second, because the book is dependent on
the included files, the book will end up consisting of a
directory of a hundred or more files instead of just a few.

@<P@>An alternative solution is to construct a single
FunnelWeb @<TT@>@(.fw@) file that, when processed, produces
both the book file and the example files. This solution
assumes that the book consists of a text file containing
commands for a typesetter such as TeX.

@<Begin verbatim@>
@@O@@@<<@>Book.tex@@@<>@>==@@{@@#B@@}

@@$@@#B+=@@{@@-
The first step to learning the object oriented
AdaCgol++ language is to examine a hello world
program.

\start{verbatim}
@@@<<@>Ex1@@@<>@>
\finish{verbatim}
@@}

@@$@@@<<@>Ex1@@@<>@>==@@{@@-
read iopack@@+Enter !World~! !Hello~! ex pr flu X[1]@@}
@@O@@@<<@>Ex1.c@@@<>@>==@@{@@@<<@>Ex1@@@<>@>@@}

@@$@@#B+=@@{@@-
To understand the program, think of the execution
state as a plate of cheese...
@@}
@<End verbatim@>

@<P@>Most of the file will consist of part
definitions of the additive macro @<TT@>@(@@#B@).
The definition is @<DQ@>@(broken@) to allow a
macro definition, wherever an example appears.

@<P@>The example above is a little messy because
FunnelWeb does not allow macros connected to
product files to be called, and it does not have
text expressions that write to an product file as
well as evaluating to text. Nevertheless, it
presents a fairly clean solution to the problem of
keeping the example programs in a computing text
up to date.

@<Nav@>@(@<Examples_comments FILE@>@,@<Examples FILE@>@,@<Examples_generics FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Examples_generics HEADING@>@M@{@<SH@>@(6.7@)Generics@}
@$@<Examples_generics FILE@>@M@{examples_generics.html@}
@O@<examples_generics.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Examples_generics HEADING@>@)
@<XX@>@(generics@,fudging@)

@<P@>It is well known that generics in programming languages
are closely aligned with textual substitution. In fact, a
good way to understand the generic facility of a new
programming language is to ask oneself the question
@<DQ@>@(In what way does this generic facility differ from
simple text substitution?@) The differences, if any,
typically have to do with the difference in scoping between
textual and intelligent substitution and whether the generic
code is shared or copied by the implementation. In most
cases the differences are quite minor.

@<P@>Because generic facilities are so closely aligned with
text substitution, it is possible to use FunnelWeb's
parameterized macros to provide generics in programming
languages that do not support generics. Simply write a
FunnelWeb macro whose parameters are the parameters of the
generic and whose body is the generic object.

@<P@>The following FunnelWeb file gives an example of a
fully worked Vax Pascal@<X@>@(Pascal@) generic set package
implemented using FunnelWeb parameterized macros. The
package was written by Barry Dwyer@<XN@>@(Barry@,Dwyer@) of
the Computer Science Department of the University of
Adelaide@<XX@>@(University@,Adelaide@) in 1987 and was
emailed to me on 11@<_@>November 1987. The generic package
provides a set abstraction@<XX@>@(set@,abstraction@)
implemented using linked lists. Note the clever use of the
instantiation parameters in type, function, and procedure
names.

@<P@>
@<Begin verbatim@>
@@$@@@<<@>Generic Set Module@@@<>@>@@(@@2@@)==@@{@@-
@@! @@1 is the base type, @@2 is the set type.
[inherit ('@@1'), environment ('@@2')]

module @@2;

type  @@2 = ^@@2Record;
      @@2Record = record
         Member: @@1;
         Next: @@2;
         end;

procedure Null@@2 (var Result: @@2);
begin new (Result);
Result^.Member := (- MaxInt)::@@1;
Result^.Next := nil end;

function IsNull@@2 (S: @@2): boolean;
begin
IsNull@@2 := S^.Member::integer = - MaxInt
end;

procedure ForEach@@1 (S: @@2; procedure DoIt (i: @@1));
var   ThisS, NextS: @@2;
begin ThisS := S;
while ThisS^.Member::integer @<<@>@<>@> - MaxInt do
   begin NextS := ThisS^.Next;
   DoIt (ThisS^.Member);
   ThisS := NextS end;
end;

function First@@1 (S: @@2): @@1;
begin First@@1 := S^.Member end;

function Is@@1InSet (i: @@1; S: @@2): boolean;
   procedure TestEquals (j: @@1);
   begin if Equal@@1 (i, j) then Is@@1InSet := true; end;
begin
Is@@1InSet := false;
ForEach@@1 (S, TestEquals);
end;

function Includes@@2 (S1, S2: @@2): boolean;
var Result: boolean;
   procedure TestIfInS1 (i: @@1);
   begin
   if Result then
      if not Is@@1InSet (i, S1) then
         Result := false;
   end;
begin Result := true;
ForEach@@1 (S2, TestIfInS1);
Includes@@2 := Result end;

function Disjoint@@2s (S1, S2: @@2): boolean;
var Result: boolean;
   procedure TestIfInS1 (i: @@1);
   begin
   if Result then
      if Is@@1InSet (i, S1) then
         Result := false;
   end;
begin Result := true;
ForEach@@1 (S2, TestIfInS1);
Disjoint@@2s := Result end;

function Equal@@2 (S1, S2: @@2): boolean;
begin
Equal@@2 := Includes@@2 (S1, S2) and
           Includes@@2 (S2, S1);
end;

procedure Insert@@1 (i: @@1; var S: @@2);
var   This, Pred, Succ: @@2;
begin
if not Is@@1InSet (i, S) then
   begin
   Pred := nil; Succ := S;
   while Succ^.Member::integer @<>@> i::integer do
      begin Pred := Succ; Succ := Succ^.Next end;
   if Succ^.Member::integer @<<@> i::integer then
      begin
      new (This);
      This^.Next := Succ;
      This^.Member := i;
      if Pred @<<@>@<>@> nil then
         Pred^.Next := This
      else
         S := This;
      end;
   end;
end;

procedure Insert@@1s (S1: @@2; var S2: @@2);
var   This, Pred, Succ: @@2;
   procedure Add@@1 (i: @@1);
   begin Insert@@1 (i, S2) end;
begin
ForEach@@1 (S1, Add@@1);
end;

procedure Remove@@1 (i: @@1; var S: @@2);
var   Pred, This: @@2;
begin
Pred := nil; This := S;
while not Equal@@1 (This^.Member, i) do begin
   Pred := This; This := This^.Next end;
if Pred @<<@>@<>@> nil then
   Pred^.Next := This^.Next
else
   S := This^.Next;
Dispose (This);
end;

procedure Dispose@@2 (var S: @@2);
var   Old: @@2;
begin
while S @<<@>@<>@> nil do
   begin
   Old := S;
   S := S^.Next;
   Dispose (Old)
   end;
end;

end.
@@}

@@O@@@<<@>NaryTreeSet.pas@@@<>@>==@@{@@-
  @@@<<@>Generic Set Module@@@<>@>@@-
@@(@@"NaryTree@@"@@,@@"NaryTreeSet@@"@@)@@}
@@O@@@<<@>NaryTreeSetSet.pas@@@<>@>==@@{@@-
  @@@<<@>Generic Set Module@@@<>@>@@-
@@(@@"NaryTreeSet@@"@@,@@"NaryTreeSetSet@@"@@)@@}
@<End verbatim@>

@<P@>A great advantage of the approach reflected in the
above example is that it allows the programmer to construct
a generic object in a language that does not supply
generics, @<I@>@(with complete
typesafety.@)@<XX@>@(typesafe@,generics@) This contrasts to
the approach that might be used in a language such as C
where the programmer might choose to construct a
@<DQ@>@(generic@) package by parameterizing a package with
pointers to @<TT@>@(void@). The resulting package is
powerful but extremely untypesafe. Such a generic list
package is used in the code of FunnelWeb itself and caused
no end of problems, as the compiler had no way of telling if
pointers to the correctly typed object were being handed to
the correct list-object/function combination.

@<P@>The major disadvantage of the text generic approach is
that it causes the code of the generic object to be
duplicated once for each instantiation. Depending on the
number and size of the instantiations, this may or may not
be acceptable.

@<P@>Where the duplication of code is unacceptable, a hybrid
approach may be taken. As in the C@<_@>example, the programmer
could write a single generic package using pointers to
@<TT@>@(void@) or some other untypesafe mechanism. Then the
programmer creates a FunnelWeb generic package whose
functions do nothing more than call the functions of the
untypesafe package, and whose types do nothing more than
contain the types of the untypesafe package. This solution
involves the use of untypesafe programming, but this is a
one-off and if done carefully and correctly, the result can
be a typesafe generic package involving minimal code
duplication.

@<Nav/last@>@(@<Examples_sharing FILE@>@,@<Examples FILE@>@,@<Examples FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Web HEADING@>@M@{@<SH@>@(7@)Making Webs With FunnelWeb@}
@$@<Web HEADING/short@>@M@{@<SH@>@(7@)Webmaking@}
@$@<Web FILE@>@M@{web.html@}
@O@<web.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Web HEADING@>@)

@<P@>FunnelWeb was designed for the purposes of literate
programming and was first created in 1986, long before the
internet's World Wide Web appeared. So it came as a pleasant
surprise to discover that FunnelWeb is an excellent tool for
the preparation of websites! All the FunnelWeb webs,
including the web you are reading right now, were created
using FunnelWeb itself. This chapter explains how you can
use FunnelWeb to make websites.

@<P@>
@<Web index@>

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

@<End FWTutMan page@>
@}

@$@<Web index@>@M@{
@<Begin size3@>
@<Begin indent/narrow@>
@<Link@>@(@<Web_introduction FILE@>@,@<Web_introduction HEADING@>@)@<BR@>
@<Link@>@(@<Web_start FILE@>@,@<Web_start HEADING@>@)@<BR@>
@<Link@>@(@<Web_messy FILE@>@,@<Web_messy HEADING@>@)@<BR@>
@<Link@>@(@<Web_errors FILE@>@,@<Web_errors HEADING@>@)@<BR@>
@<Link@>@(@<Web_style FILE@>@,@<Web_style HEADING@>@)@<BR@>
@<Link@>@(@<Web_libraries FILE@>@,@<Web_libraries HEADING@>@)@<BR@>
@<Link@>@(@<Web_param FILE@>@,@<Web_param HEADING@>@)@<BR@>
@<Link@>@(@<Web_conventions FILE@>@,@<Web_conventions HEADING@>@)@<BR@>
@<End indent/narrow@>
@<End size3@>
@}

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

@$@<Web_introduction HEADING@>@M@{@<SH@>@(7.1@)Introduction@}
@$@<Web_introduction FILE@>@M@{web_introduction.html@}
@O@<web_introduction.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Web_introduction HEADING@>@)

@<P@>How can FunnelWeb be used to make webs? Easy!
Here's how it works. You create a single file called (say)
@<TT@>@(daves_web.fw@) containing a Funnelweb output
file macro (@<TT@>@(@@O@)) for each page in the the web
that you want to create. The @<TT@>@(daves_web.fw@) file
contains the entire web. When you feed it through FunnelWeb,
FunnelWeb generates all the HTML files in your web.

@<P@>
@<Begin verbatim@>
                 +--------------+
                 | daves_web.fw |
                 +--------------+
                        |
                        V
               o-------------------o
               | FunnelWeb Program |
               o-------------------o
                        |
                        V
       +----------------+----------------+
       |                |                |
+--------------+  +------------+  +------------+
| contact.html |  | index.html |  | links.html |
+--------------+  +------------+  +------------+
@<End verbatim@>

@<P@>Here are some key points about this application:

@<P@>
@<Begin list@>

@<Item@>First, FunnelWeb can only generate the text files in
your web (such as the @<TT@>@(.html@) files). You will still
need to create the image files using the image manipulation
tools you usually use; FunnelWeb does not help with the
graphics, nor does it provide a GUI. You have to write raw
HTML. However, FunnelWeb provides power tools for writing
the HTML.

@<Blank line@>

@<Item@>Second, this is not a literate-programming
application of webs. Here, FunnelWeb is being used purely as
a macro preprocessor, and there will never be any cause to
use FunnelWeb to generate documentation files (weaving). The
files generated as above are FunnelWeb @<I@>@(output@)
files, not FunnelWeb HTML documentation produced by the
FunnelWeb weaver. This is a raw macro preprocessor
application.

@<End list@>

@<P@>So what benefit is there in converting one's web to a
single FunnelWeb file? If you have just a small number of
pages in your web (as in the above diagram), there is
probably not much benefit. However, if you have several
pages in your web, FunnelWeb can provide huge benefits by
enabling you to control the relationships between the
various parts of your web and to parameterize it in whatever
ways you want to. The result is a consistent style, a
reduction of errors, and the power to execute broad ranging
changes to the web with very little fuss. For example,
FunnelWeb makes it easy to change the background of each
page in your web, or to add a copyright notice at the bottom
of every page.

@<P@>

@<P@>The advantages of using FunnelWeb to make webs are as follows:

@<P@>
@<Begin list@>
@<Item@>Web is represented by a single file.
@<Item@>No more multiple-file replace operations!
@<Item@>Define a consistent style for the web.
@<Item@>Parameterize the web. Make global changes easily.
@<Item@>Use the power of HTML without the messy HTML syntax.
@<Item@>Eliminates many syntax and spelling errors.
@<Item@>Eliminates bad (internal) links.
@<Item@>Eliminates form/CGI cross reference errors.
@<Item@>A flexible text power tool always available.
@<End list@>

@<P@>The disadvantages of using FunnelWeb to make webs are as
follows:

@<P@>
@<Begin list@>
@<Item@>No GUI interface. You have to write your web directly.
@<Item@>It is more difficult to position graphics precisely.
@<Item@>FunnelWeb files can look cryptic and messy.
@<Item@>You have to run FunnelWeb between changing your web and
viewing the changed pages.
@<End list@>

@<P@>Thus, if you make webs that are highly graphics
intensive, or if you are uncertain about writing HTML, you
should probably not use FunnelWeb. However, if you are
generating large webs with many similar pages, FunnelWeb
will eliminate much of the hassle in managing the whole
complex. For large webs, this management capability is
invaluable.

@<P@>Whatever its advantages and disadvantages, FunnelWeb is
certainly a @<B@>@(practical@) production-quality webmaking tool.
It has been used to make all of the webs in the following
web spaces (each of which contains several subwebs):

@<P@>
@<Begin indent@>
@<Ross Williams@>@<BR@>
@<Rocksoft@>@<BR@>
@<Veracity@>@<BR@>
@<End indent@>

@<Nav/first@>@(@<Web FILE@>@,@<Web FILE@>@,@<Web_start FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Web_start HEADING@>@M@{@<SH@>@(7.2@)Getting Started@}
@$@<Web_start FILE@>@M@{web_start.html@}
@O@<web_start.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Web_start HEADING@>@)

@<P@>This page contains a brief hands-on tutorial to get you started
in using FunnelWeb to make webs.

@<FWTutMan subheading@>@(Hello Web@)

@<P@>The best way to understand how FunnelWeb can help you make webs
is to work through a simple example. Here is one:

@<P@>
@<Begin verbatim@>@=#
@!************************************************

@O@#<<#>index.html@>@{
##<HTML##>

##<HEAD##>
##<TITLE##>Dave's Home Page##</TITLE##>
##</HEAD##>

##<BODY BGCOLOR=#@FFFFFF##>
##<P##>Welcome to my home page. Check out my
##<A HREF="links.html"##>links page##</A##>.
##</BODY##>

##</HTML##>
@}

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

@O@##<links.html@##>@{
##<HTML##>

##<HEAD##>
##<TITLE##>Dave's Links##</TITLE##>
##</HEAD##>

##<BODY BGCOLOR=#@FFFFFF##>
##<P##>Here are my links:

##<P##>
##<A HREF="http://www.yahoo.com/"##>Yahoo##</A##>##<BR##>
##<A HREF="http://www.dilbert.com/"##>Dilbert##</A##>##<BR##>
##</BODY##>

##</HTML##>
@}

@!************************************************
#=@@<End verbatim@>

@<P@>Cut and paste the above text into a file called @<TT@>@(dave.fw@)
and run FunnelWeb on it by giving the command:

@<P@>
@<Begin verbatim@>
   fw dave
@<End verbatim@>

@<P@>
@<Begin blockquote@>
@<Begin size2@>
@<B@>@(Note:@) On my computer, when you cut and paste text
from a web page, the pasted text contains a block of blanks
before each line; you will have to delete these to make the
example work, as FunnelWeb requires the first line of macro
definitions to be in column one.
@<End size2@>
@<End blockquote@>

@<P@>If all goes well, FunnelWeb should write out two files
@<TT@>@(index.html@) and @<TT@>@(links.html@). That's the
generated web, and you should be able to browse it using your
favorite web browser.

@<FWTutMan subheading@>@(First Glimmers Of Usefulness@)

@<P@>The sole benefit we have obtained so far is that the web
is represented as a single file. This confers quite a few benefits
on its own for medium-sized webs, such as the elimination of
the need to perform multiple-file search and replace operations,
but it's really only a start.

@<P@>The next step is to recognise that the two pages above share
quite a lot of text and that that text can be removed into FunnelWeb
macros.

@<P@>
@<Begin verbatim@>@=#
@!************************************************

@$@##<Begin page@>@(@1@)@M@{
##<HTML##>
##<HEAD##>
##<TITLE##>@1##</TITLE##>
##</HEAD##>
##<BODY BGCOLOR=#@FFFFFF##>
@}

@$@##<End page@##>@M@{
##</BODY##>
##</HTML##>
@}

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

@O@##<index.html@##>@{

@##<Begin page@##>@(Dave's Home Page@)

##<P##>Welcome to my home page. Check out my
##<A HREF="links.html"##>links page##</A##>.

@##<End page@##>
@}

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

@O@##<links.html@##>@{
@##<Begin page@##>@(Dave's Links@)

##<P##>Here are my links:

##<P##>
##<A HREF="http://www.yahoo.com/"##>Yahoo##</A##>##<BR##>
##<A HREF="http://www.dilbert.com/"##>Dilbert##</A##>##<BR##>

@##<End page@##>
@}

@!************************************************
#=@@<End verbatim@>

@<P@>Now, although the file has actually got a little longer and
looks far more complicated than it did, we've actually managed
to extract two significant benefits from this reorganization.

@<Narrowthing@>@(Page style:@,First, almost without even
trying, we've created a page style. For example, to change
the colour of all the pages in the web, we need just change
the single body definition in the begin page macro.
Similarly, if we wanted to add a copyright notice at the
bottom of each page, we need change only the end page
macro.@)

@<Narrowthing@>@(Page overhead:@,Second, we've reduced the
amount of text required to define each page. Instead of
requiring ten lines of HTML to set up each page, we need
just two FunnelWeb calls (two lines); the rest is text
particular to the page being defined.@)

@<P@>These advantages may seem minor, but when scaled up to a
web containing a dozen or more pages, they become very significant.

@<P@>The newfound power, in the case of the example, can be demonstrated
by changing the web from black on white to blue on white, and by adding
another page:

@<P@>
@<Begin verbatim@>@=#
@!************************************************

@$@##<Begin page@##>@(@1@)@M@{
##<HTML##>
##<HEAD##>
##<TITLE##>@1##</TITLE##>
##</HEAD##>
##<BODY BGCOLOR=#@FFFFFF TEXT=#@000033##>
@}

@$@##<End page@##>@m@{
##</BODY##>
##</HTML##>
@}

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

@O@##<index.html@##>@{
@##<Begin page@##>@(Dave's Home Page@)

##<P##>Welcome to my home page. Check out my
##<A HREF="links.html"##>links page##</A##> and my
##<A HREF="hobbies.html"##>hobbies page##</A##>.

@##<End page@##>
@}

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

@O@##<links.html@##>@{
@##<Begin page@##>@(Dave's Links@)

##<P##>Here are my links:

##<P##>
##<A HREF="http://www.yahoo.com/"##>Yahoo##</A##>##<BR##>
##<A HREF="http://www.dilbert.com/"##>Dilbert##</A##>##<BR##>

@##<End page@##>
@}

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

@O@##<hobbies.html@##>@{
@##<Begin page@##>@(Dave's Hobbies@)

##<P##>This page is under construction!

@##<End page@##>
@}

@!************************************************
#=@@<End verbatim@>

@<P@>Now that you have a Hello World file to play with, the remaining
sections of this chapter will discuss the ways in which you can
use the macro power now at your fingertips.

@<Nav@>@(@<Web_introduction FILE@>@,@<Web FILE@>@,@<Web_messy FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Web_messy HEADING@>@M@{@<SH@>@(7.3@)Replacing Messy HTML Constructs@}
@$@<Web_messy FILE@>@M@{web_messy.html@}
@O@<web_messy.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Web_messy HEADING@>@)

@<P@>One of the greatest benefits of using FunnelWeb is its ability
to replace messy slabs of HTML with a simple macro call. This page
provides lots of examples of this.

@<FWTutMan subheading@>@(Hyperlinks@)

@<P@>Hyperlinks are messy and you can eliminate their messiness
from your FunnelWeb web source by defining a macro for each link
you want to use. For example:

@<P@>
@<Begin verbatim@>@=#
@$@##<Dilbert@##>@Z@M@{@-
##<A HREF="http://www.dilbert.com/"##>Dilbert##</A##>@}
@$@##<Yahoo@##>@Z@M@{@-
##<A HREF="http://www.yahoo.com/"##>Yahoo##</A##>@}
#=@@<End verbatim@>

@<P@>While the definitions themselves are certainly messy,
having made them, we are now free to refer to Dilbert and
Yahoo within our webs in a very clean manner indeed. For
example, the links page of the previous example now becomes
just:

@<P@>
@<Begin verbatim@>@=#
@O@##<links.html@##>@{
@##<Begin page@##>@(Dave's Links@)

##<P##>Check out @##<Dilbert@##> and @##<Yahoo@##>!

@##<End page@##>
@}
#=@@<End verbatim@>

@<FWTutMan subheading@>@(Images@)

@<P@>Suppose we want to include a small image of a checkmark
at various points without a web page. Here's the HTML that
has to be included at each point:

@<P@>
@<Begin verbatim@>@=#
##<IMG SRC="bin/tick_red_12.gif"
WIDTH="12" HEIGHT="12"
HSPACE=4 VSPACE=0
ALT="*" BORDER="0"##>
#=@@<End verbatim@>

@<P@>Yuk! To eliminate this mess in our FunnelWeb/HTML, we
can define a macro for a tick mark as follows:

@<P@>
@<Begin verbatim@>@=#
@$@##<Tick@##>@M@{
##<IMG SRC="bin/tick_red_12.gif"
WIDTH="12" HEIGHT="12"
HSPACE=4 VSPACE=0
ALT="*" BORDER="0"##>@}
#=@@<End verbatim@>

@<P@>Now, using tick marks without your text is easy.
Here's an example:

@<P@>
@<Begin verbatim@>@=#
@##<Tick@##>Low cost.##<BR##>
@##<Tick@##>Easy installation.##<BR##>
@##<Tick@##>Available now!##<BR##>
#=@@<End verbatim@>

@<FWTutMan subheading@>@(Large Form Fields@)

@<P@>Another example is where you have form fields
with lots of options. Here's an example of a commonly
occurring form field that goes on for a couple of
hundred lines!

@<P@>
@<Begin verbatim@>@=#
##<SELECT NAME="Country"##>
##<OPTION##>United States
##<OPTION##>Afghanistan
##<OPTION##>Albania
...
##<OPTION##>Zambia
##<OPTION##>Zimbabwe
##</SELECT##>
#=@@<End verbatim@>

@<P@>Using FunnelWeb, you can move all this to a single macro
definition as follows:

@<P@>
@<Begin verbatim@>@=#
@$@##<Country form field@##>@M@(
##<SELECT NAME="Country"##>
##<OPTION##>United States
##<OPTION##>Afghanistan
##<OPTION##>Albania
...
##<OPTION##>Zambia
##<OPTION##>Zimbabwe
##</SELECT##>
#=@@<End verbatim@>

@<P@>Now, whenever you want a country field in a form, you can
just write:

@<P@>
@<Begin verbatim@>@=#
@##<Country form field@##>
#=@@<End verbatim@>

@<FWTutMan subheading@>@(Navigation Buttons@)

@<P@>Sometimes the navigation constructs that appear
within pages can become rather messy. Here's an example
where we have three buttons at the bottom of each page.

@<P@>
@<Begin verbatim@>@=#
##<TABLE WIDTH="100%"##>
##<TR##>
##<TD ALIGN="left"   VALIGN="bottom"##>##<
 A HREF="links.html"##>##<IMG SRC="bin/left.gif"##>##</A##>##</TD##>
##<TD ALIGN="center" VALIGN="bottom"##>##<
 A HREF="home.html"##>##<IMG SRC="bin/up.gif"##>##</A##>##</TD##>
##<TD ALIGN="right"  VALIGN="bottom"##>##<
 A HREF="hobbies.html"##>##<
 IMG SRC="bin/right.gif"##>##</A##>##</TD##>
##</TR##>
##</TABLE##>
#=@@<End verbatim@>

@<P@>We can move all this to a single macro definition
that has three parameters, one for each target page.

@<P@>
@<Begin verbatim@>@=#
@$@##<Nav@##>@(@3@)@Z@M@{
@##<P@##>
##<TABLE WIDTH="100%"##>
##<TR##>
##<TD ALIGN="left"   VALIGN="bottom"##>##<
 A HREF="@1"##>##<IMG SRC="bin/left.gif"##>##</A##>##</TD##>
##<TD ALIGN="center" VALIGN="bottom"##>##<
 A HREF="@2"##>##<IMG SRC="bin/up.gif"##>##</A##>##</TD##>
##<TD ALIGN="right"  VALIGN="bottom"##>##<
 A HREF="@3"##>##<IMG SRC="bin/right.gif"##>##</A##>##</TD##>
##</TR##>
##</TABLE##>
@}
#=@@<End verbatim@>

@<P@>Now, to add navigation buttons to a page,
we can just write (near the end of the page).

@<P@>
@<Begin verbatim@>@=#
@##<Nav@##>@(links.html@,home.html@,hobbies.html@)
#=@@<End verbatim@>

@<P@>If you wanted to, you could build the navigation
buttons into the @<TT@>@(@@@<<@>End page@@@<>@>@) macro
and set it up with three parameters instead.

@<Nav@>@(@<Web_start FILE@>@,@<Web FILE@>@,@<Web_errors FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Web_errors HEADING@>@M@{@<SH@>@(7.4@)Avoiding Errors And Inconsistencies@}
@$@<Web_errors FILE@>@M@{web_errors.html@}
@O@<web_errors.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Web_errors HEADING@>@)

@<P@>FunnelWeb provides the opportunity to eliminate all kinds of
errors and inconsistencies by replacing text names with FunnelWeb
macro names that cannot be misspelt without being detected by FunnelWeb.
This page provides some examples of this.

@<FWTutMan subheading@>@(Minor Style Elements@)

@<P@>Have you ever done this:

@<P@>
@<Begin verbatim@>@=#
This is ##<B Very Important##</B##>!
#=@@<End verbatim@>

@<P@>These kinds of errors can be eliminated by replacing HTML
constructs, even simple ones, by FunnelWeb macros:

@<P@>
@<Begin verbatim@>@=#
@$@##<B@##>@(@1@)@M@{##<B##>@1##</B##>@}
...
This is @##<B@##>@(Very Important@)!
#=@@<End verbatim@>

@<P@>While this is a bit messier, it eliminates the chance of an
error because if you get the syntax wrong, FunnelWeb will generate
an error at "compile time", which is a lot better than receiving
email from some random web visitor. It's true that the same level
of checking can be obtained by running an HTML syntax checker
over your web. However, if you're using FunnelWeb for all its
other benefits, you might as well use this aspect too.

@<FWTutMan subheading@>@(File Names In Hyperlinks@)

@<P@>Another source of error in webs is bad internal links.
This can occur when you rename a file and forget to "fix up"
all the links to it, and when you make a typing error when
typing in a filename in a hyperlink.

@<P@>You can use FunnelWeb to eliminate both of these kinds
of error, by defining a macro for each output file. This is
easier to do than explain:

@<P@>
@<Begin verbatim@>@=#
@!************************************************

@$@##<Begin page@##>@(@1@)@M@{
##<HTML##>
##<HEAD##>
##<TITLE##>@1##</TITLE##>
##</HEAD##>
##<BODY BGCOLOR=#@FFFFFF TEXT=#@000033##>
@}

@$@##<End page@##>@M@{
##</BODY##>
##</HTML##>
@}

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

@O@##<index.html@##>@{
@##<Begin page@##>@(Dave's Home Page@)

##<P##>Welcome to my home page. Check out my
##<A HREF="@##<Links FILE@##>"##>links page##</A##> and my
##<A HREF="@##<Hobbies FILE@##>"##>hobbies page##</A##>.

@##<End page@##>
@}

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

@$@##<Links FILE@##>@M@{links.html@}
@O@##<links.html@##>@{
@##<Begin page@##>@(Dave's Links@)

##<P##>Here are my links:

##<P##>
##<A HREF="http://www.yahoo.com/"##>Yahoo##</A##>##<BR##>
##<A HREF="http://www.dilbert.com/"##>Dilbert##</A##>##<BR##>

@##<End page@##>
@}

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

@$@##<Hobbies FILE@##>@M@{hobbies.html@}
@O@##<hobbies.html@##>@{
@##<Begin page@##>@(Dave's Hobbies@)

##<P##>This page is under construction!

@##<End page@##>
@}

@!************************************************
#=@@<End verbatim@>

@<P@>Again, this technique introduces a little messiness, but
the benefits it brings are significant. Once you have deployed
this technique throughout your web source file, you will then
be free to change the names of any of your files without ever
having to worry about fixing up any links - they will all be
fixed automatically! Furthermore, if you delete an output
file from your FunnelWeb source file, FunnelWeb will alert
you to any "dangling links" because the references to the
deleted page take the form of calls to a macro that is no
longer defined! Of course, this only works if you don't mark
your filename macros with @<TT@>@(@@Z@).

@<P@>The only thing you have to get right is to ensure that
the filename of the output macro is the same as the value
of the corresponding naming macro. This isn't too hard to
do because they are always on adjacent lines.

@<P@>The benefit of eliminating all bad links from one's
web is a benefit that can be obtained by running an external
web analysis tool over your web. However, by using FunnelWeb
file naming macros, you can be SURE that the web can never
be generated with a bad link, whereas the web analysis tool
only works if you remember to run it!

@<FWTutMan subheading@>@(People's Names@)

@<P@>Sometimes you might have to create a web that contains lots
of long names that are hard to remember or spell. FunnelWeb
can help here by eliminating the chance of error. Just define
each name as macro and always call the macro when using the
name. The benefit of doing this is that FunnelWeb will always
detect a spelling error because if you make a spelling error
in the macro name, FunnelWeb will generate a "macro not defined"
error.

@<P@>
@<Begin verbatim@>@=#
@$@##<Marvin Hylrzbvwryvitz@##>@M@{Marvin Hylrzbvwryvitz@}
#=@@<End verbatim@>

@<P@>If you want to, you could used a shortened form. For example:

@<P@>
@<Begin verbatim@>@=#
@$@##<Marvin@##>@M@{Marvin Hylrzbvwryvitz@}
#=@@<End verbatim@>

@<FWTutMan subheading@>@(CGI Form Fields@)

@<P@>One of the organizational challenges of implementing
CGI form processing is getting all the field names right.
Because (normally) the form is in one file, and the CGI
script that processes it is in another file, it's very
easy to accidentally use different names for the same
field. For example, you might use @<TT@>@(email_adr@) in
one and @<TT@>@(email-adr@) in the other.

@<P@>FunnelWeb can be used to completely eliminate this
problem as follows:

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

@<Item@>Put both the HTML file containing the form and the
CGI file that processes it within the @<TT@>@(.fw@) file
that embodies your web.

@<Blank line@>

@<Item@>Define a macro for the name of each field and use
the macro in both the form and the CGI script.

@<End list/ordered@>

@<P@>Here's an example:

@<P@>
@<Begin verbatim@>@=#
@!************************************************

@$@##<Email FIELD@##>@M@{email_adr@}

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

@O@##<order.html@##>@{
@##<Begin page@##>@(Order Form@)

##<P##>
##<FORM ...##>
##<INPUT TYPE="text" NAME="@##<Email FIELD@##>"##>
...
##</FORM##>

@##<End page@##>
@}

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

@O@##<order.cgi@##>@{@-
@##<Begin CGI page@##>
...
$v = $form{'@##<Email FIELD@##>'};
@##<End CGI page@##>
@}

@!************************************************
#=@@<End verbatim@>

@<P@>This technique more or less completely eliminates
mismatch errors in form field names, for if any such error
is made, FunnelWeb will generate a "macro not defined"
error. All you have to do to benefit from this technique
is get into the habit of using it.

@<FWTutMan subheading@>@(When Global Replace Fails@)

@<P@>Many people who write HTML directly use nerve wracking
multi-file global replaces to perform the kind of web
parameterization that FunnelWeb makes so easy.
Unfortunately, these global replacements can go badly wrong
because the target text may be used in many different
contexts. In some cases, this approach fails completely.

@<P@>For example, suppose that you have to create a hundred
page web that has to be laced with two email addresses: a
"business" email address and a "personal" email address. No
problem so far. However, suppose that you haven't yet chosen
a business domain name and, as a result,  at the current
time, the two email addresses are the same! If this were the
case, you would have to put your address throughout all the
pages and would LOSE the information of which were supposed
to be business addresses and which were supposed to be
personal ones.

@<P@>FunnelWeb solves this problem (and others like it)
completely by allowing you to define two macros one for each
context. For example:

@<P@>
@<Begin verbatim@>@=#
@$@##<Business EMAIL@##>@M@{dave@@someisp.com.au@}
@$@##<Personal EMAIL@##>@M@{dave@@someisp.com.au@}
#=@@<End verbatim@>

@<P@>These macros can then be used as appropriate. Later,
when the domain name comes through and the business address
changes, all that needs to be changed is a single definition:

@<P@>
@<Begin verbatim@>@=#
@$@##<Business EMAIL@##>@M@{dave@@megacorp.com.au@}
@$@##<Personal EMAIL@##>@M@{dave@@someisp.com.au@}
#=@@<End verbatim@>

@<P@>There is no need to perform a multi-file global replace
and evaluate the context of the use of each email address,
as the information was not lost when the web was originally
created, because of the two macros.

@<P@>This example is just one of many similar situations that
arise. By locating all the pages of your web in a single file
and allowing you to define macros for different purposes,
you can eliminate much of the time and danger of global
replacements.

@<Nav@>@(@<Web_messy FILE@>@,@<Web FILE@>@,@<Web_style FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Web_style HEADING@>@M@{@<SH@>@(7.5@)Defining A Consistent Style@}
@$@<Web_style FILE@>@M@{web_style.html@}
@O@<web_style.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Web_style HEADING@>@)

@<P@>We have already seen how FunnelWeb can be used, through the
use of @<TT@>@(@@@<<@>Begin page@@@<>@>@) and
@<TT@>@(@@@<<@>End page@@@<>@>@) macros to set up
a particular page style throughout a web.
However, this is really just the beginning of FunnelWeb's capacity
to manage the style of a web. This page provides some other ideas.

@<FWTutMan subheading@>@(Generic Style Macros@)

@<P@>HTML contains some tags such as @<TT@>@(@<<@>em@<>@>@)
that have a high-level meaning (@<DQ@>@(emphasis@)) rather than
a low-level meaning such as @<DQ@>@(italics@). You can use FunnelWeb
to create your own high level formatting macros so that you can later
change the style of the web just by changing the macro definitions.

@<P@>For example, suppose that your web contains lots of latin names
of plants. You've decided that you want to highlight the names, but
haven't decided how. Using FunnelWeb you can just define a macro:

@<P@>
@<Begin verbatim@>@=#
@$@##<Latin@##>@(@1@)@M@{##<B##>@1##</B##>@}
#=@@<End verbatim@>

@<P@>This means that all latin names will be set in bold. However,
if at a later date, you change your mind, you can just change the
definition to some other format.

@<FWTutMan subheading@>@(Margins@)

@<P@>Here's another example. Suppose that you want some parts of
the text in your web to be narrower than others. You can achive
this by defining and using a macro like this:

@<P@>
@<Begin verbatim@>@=#
@$@##<Narrower@##>@(@1@)@M@{@-
##<TABLE##>##<TR##>##<TD WIDTH="200"##>
@1
##</TD##>##</TR##>##</TABLE##>
@}
#=@@<End verbatim@>

@<P@>If at a later date, you want to change all the widths, you
just need to change the single definition.

@<Nav@>@(@<Web_errors FILE@>@,@<Web FILE@>@,@<Web_libraries FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Web_libraries HEADING@>@M@{@<SH@>@(7.6@)Defining Macro Libraries@}
@$@<Web_libraries FILE@>@M@{web_libraries.html@}
@O@<web_libraries.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Web_libraries HEADING@>@)

@<FWTutMan subheading@>@(Separating Macros Into An Include File@)

@<P@>Once you start using FunnelWeb to make webs, you'll discover
that you find yourself defining and using the same macros over and
over. Rather than redefining them for each new web you make, you
can place them all in a FunnelWeb include file, so that they can
be included in the FunnelWeb file for each web you make. Suppose
that we create a file called @<TT@>@(style.fwi@) containing the
following text:

@<P@>
@<Begin verbatim@>@=#
@$@##<Begin page@##>@(@1@)@M@{
##<HTML##>
##<HEAD##>
##<TITLE##>@1##</TITLE##>
##</HEAD##>
##<BODY BGCOLOR=#@FFFFFF TEXT=#@000033##>
@}

@$@##<End page@##>@{
##</BODY##>
##</HTML##>
@}

@$@##<Dilbert@##>@Z@M@{@-
##<A HREF="http://www.dilbert.com/"##>Dilbert##</A##>@}
@$@##<Yahoo@##>@Z@M@{@-
##<A HREF="http://www.yahoo.com/"##>Yahoo##</A##>@}
#=@@<End verbatim@>

@<P@>Once this is done, the main web file can become:

@<P@>
@<Begin verbatim@>@=#
@!************************************************

@i style

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

@O@##<index.html@##>@{
@##<Begin page@##>@(Dave's Home Page@)

##<P##>Welcome to my home page. Check out my
##<A HREF="@##<Links FILE@##>"##>links page##</A##>.

@##<End page@##>
@}

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

@$@##<Links FILE@##>@M@{links.html@}
@O@##<links.html@##>@{
@##<Begin page@##>@(Dave's Links@)

##<P##>Check out @##<Yahoo@##> and @##<Dilbert@##>.

@##<End page@##>
@}

@!************************************************
#=@@<End verbatim@>

@<P@>Now we're starting to see some real simplification!

@<P@>Note: It's important to attach @<TT@>@(@@Z@) to any
macro you place in an include file that you think might
not be called in some webs. If you don't, FunnelWeb will issue
@<DQ@>@(this macro is unused@) errors for the included
macros you don't use.

@<FWTutMan subheading@>@(Library Macros@)

@<P@>Once you've created one or more macro libraries in the
form of FunnelWeb include files, you might find that sometimes
you want to redefine some of the macros that the include
file provides. For example, suppose that we are preparing
an Australian web page and that when we refer to Yahoo, we
want to refer to the Australian Yahoo site. If we try to
redefine the Yahoo macro:

@<P@>
@<Begin verbatim@>@=#

@i style

...

@$@##<Yahoo@##>@Z@M@{@-
##<A HREF="http://www.yahoo.com.au/"##>Yahoo##</A##>@}
#=@@<End verbatim@>

@<P@>then FunnelWeb will issue an error @<DQ@>@(this macro
is already defined@). FunnelWeb does not allow macros to
be redefined because this could be dangerous in a programming
context. It would be very bad if a programmer thought they
was invoking one piece of text when they were really invoking
another. So FunnelWeb complains.

@<P@>To stop FunnelWeb complaining, you can tag with a library
macro marker @<TT@>@(@@L@) any macro in the include file that
you want to be able to redefine. For example:

@<P@>
@<Begin verbatim@>@=#
@$@##<Dilbert@##>@Z@M@L@{@-
##<A HREF="http://www.dilbert.com/"##>Dilbert##</A##>@}
@$@##<Yahoo@##>@Z@M@L@{@-
##<A HREF="http://www.yahoo.com/"##>Yahoo##</A##>@}
#=@@<End verbatim@>

@<P@>This allows us to redefined the Yahoo and Dilbert macros.

@<FWTutMan subheading@>@(Modifying Default Behaviour@)

@<P@>The library macro mechanism allows you to set up all kinds
of default behaviour that can be modified in specific webs. For
example, suppose that we rewrote the macro library as:

@<P@>
@<Begin verbatim@>@=#
@$@##<Begin page@##>@(@1@)@M@{
##<HTML##>
##<HEAD##>
##<TITLE##>@1##</TITLE##>
##</HEAD##>
@##<Body@##>
@}

@$@##<End page@##>@{
##</BODY##>
##</HTML##>
@}

@$@##<Body@##>@L@{@-
##<BODY BGCOLOR=#@FFFFFF TEXT=#@000033##>@}
#=@@<End verbatim@>

@<P@>Once this is done, we can modify the page background
and colours of any web by redefining the @<TT@>@(Body@)
macro without having to redefine the start and end
of page macros.

@<P@>
@<Begin verbatim@>@=#
@!************************************************

@i style

@$@##<Body@##>@{@-
##<BODY BGCOLOR=#@000000 TEXT=#@FFFFFF##>@}

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

@O@##<index.html@##>@{
@##<Begin page@##>@(Dave's Home Page@)

##<P##>Welcome to my home page. Check out my
##<A HREF="@##<Links FILE@##>"##>links page##</A##>.

@##<End page@##>
@}

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

@$@##<Links FILE@##>@M@{links.html@}
@O@##<links.html@##>@{
@##<Begin page@##>@(Dave's Links@)

##<P##>Check out @##<Yahoo@##> and @##<Dilbert@##>.

@##<End page@##>
@}

@!************************************************
#=@@<End verbatim@>

@<FWTutMan subheading@>@(Use Of Additive Macros@)

@<P@>Additive macros can be used to insert information into
the middle of macros already defined. For example, suppose
you defined:

@<P@>
@<Begin verbatim@>@=#
@$@##<Begin page@##>@(@1@)@M@{
##<HTML##>
##<HEAD##>
##<TITLE##>@1##</TITLE##>
@##<Header fields@##>
##</HEAD##>
##<BODY BGCOLOR=#@FFFFFF TEXT=#@000033##>
@}

@$@##<Header fields@##>+=@{@}
#=@@<End verbatim@>

@<P@>Once the header fields macro is in place, you can add text such
as style commands or keyword tags to each of the pages of your web
without having to modify the header include file. Just add a definition,
such as the following, to your main FunnelWeb file:

@<P@>
@<Begin verbatim@>@=#
@$@##<Header fields@##>+=@{
##<STYLE TYPE="text/css"##>
##<!-- A {text-decoration: none} // --##>
##</STYLE##>
@}
#=@@<End verbatim@>

@<FWTutMan subheading@>@(Selecting Absolute Or Relative Links@)

@<P@>Sometimes it's important to generate a web that uses
relative hyperlinks, and sometimes it's important to generate
a web that uses absolute hyperlinks. For example, it's important
to use relative links if you want to browse a web offline, or
if you want to ensure that username and password fields in
the URL are not obliterated by the following of an absolute link.
Absolute links are important where a web that is normally
adjacent to another web (and hence usually links to it using
a relative link) is separated and must be browsed offline.

@<P@>A good way to organize all this is to define FunnelWeb
macros for the URLs of webs in include files, but allow them
to be overruled by including files. For example, an
file might contain the following definitions:

@<P@>
@<Begin verbatim@>@=#
@$@##<Rocksoft WWW@##>@Z@M@L@{http://www.rocksoft.com/@}
@$@##<Ross WWW@##>@Z@M@L@{http://www.ross.net/@}
@$@##<Veracity WWW@##>@Z@M@L@{http://www.veracity.com/@}
#=@@<End verbatim@>

@<P@>These symbols are useful for referring to these various
webs from within these webs. However, it is convenient for
each subweb to refer to other subwebs using a relative path
rather than an absolute path, so when generating (say) a
subweb of the Ross webspace, the Ross macro could be redefined to:

@<P@>
@<Begin verbatim@>@=#
@$@##<Ross WWW@##>@Z@M@{../@}
#=@@<End verbatim@>

@<P@>This technique can be used in various forms to manage
the links in the online and offline versions of webs.

@<Nav@>@(@<Web_style FILE@>@,@<Web FILE@>@,@<Web_param FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Web_param HEADING@>@M@{@<SH@>@(7.7@)Parameterizing Entire Webs@}
@$@<Web_param FILE@>@M@{web_param.html@}
@O@<web_param.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Web_param HEADING@>@)

@<P@>The previous section has shown how individual macros within
included files can be redefined to modify the details of a web.
A more radical approach to web parameterization is to swap in
entire include files!

@<FWTutMan subheading@>@(Include Files As Parameter Sets@)

@<P@>Suppose that we have a web that we are providing to three
different web customers, where each web customer wants the web
customized for their business. One way to approach this
situation is to embody all the elements of the web that must
be changed into macros located in an include file. Then define
a different include file for each customer. So the include
file for one customer could be:

@<P@>
@<Begin verbatim@>@=#
@! Include file for MegaCorp
@$@##<Home page title@##>@{Welcome To MegaCorp@}
@$@##<Background colour@##>@{#@FFFFFF@}
@$@##<Emphasis@##>@(@1@)@M@{##<B##>@1##</B##>@}
#=@@<End verbatim@>

@<P@>whereas the include file for a different customer might be:

@<P@>
@<Begin verbatim@>@=#
@! Include file for MicroCorp
@$@##<Home page title@##>@{MicroCorp Home Page@}
@$@##<Background colour@##>@{#@000000@}
@$@##<Emphasis@##>@(@1@)@M@{##<I##>@1##</I##>@}
#=@@<End verbatim@>

@<P@>In this way you can parameterize the style of an entire
web, and generate different versions for different situations.

@<Nav@>@(@<Web_libraries FILE@>@,@<Web FILE@>@,@<Web_conventions FILE@>@)

@<End FWTutMan page@>
@}

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

@$@<Web_conventions HEADING@>@M@{@<SH@>@(7.8@)Hints And Conventions@}
@$@<Web_conventions FILE@>@M@{web_conventions.html@}
@O@<web_conventions.html@>@{@-
@<Begin FWTutMan page/H1@>@(@<Web_conventions HEADING@>@)

@<FWTutMan subheading@>@(Where To Include Include Files@)

@<P@>It's better to include your include files at the end of the
main web file, as if FunnelWeb generates an error, the line number
in the listing file is easier to correlate with the main file if
several files have not been included.

@<FWTutMan subheading@>@(Separating Pages@)

@<P@>It's a good idea to separate the macro for each page in a web
in the FunnelWeb file, by a line of asterisks in a FunnelWeb comment.
This makes the FunnelWeb source file easier to work on in your
text editor.

@<P@>
@<Begin verbatim@>@=#
@!************************************************

@O@##<index.html@##>@{
@##<Begin page@##>@(Dave's Home Page@)

##<P##>Welcome to my home page. Check out my
##<A HREF="@##<Links FILE@##>"##>links page##</A##>.

@##<End page@##>
@}

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

@$@##<Links FILE@##>@M@{links.html@}
@O@##<links.html@##>@{
@##<Begin page@##>@(Dave's Links@)

##<P##>Check out @##<Yahoo@##> and @##<Dilbert@##>.

@##<End page@##>
@}

@!************************************************
#=@@<End verbatim@>

@<FWTutMan subheading@>@(Input And Output Line Lengths@)

@<P@>When using FunnelWeb to create webs, you will probably find
that your input and output files have lines longer than the
FunnelWeb standard 80 characters. So you may wish to include the
following directives in your main and include files:

@<P@>
@<Begin verbatim@>@=#
@p maximum_input_line_length = 200
@p maximum_output_line_length = 200
#=@@<End verbatim@>

@<FWTutMan subheading@>@(Macro Naming Conventions@)

@<P@>Since 1994, I (@<Ross Williams@>) have been using FunnelWeb to
generate all the webs in all my webspaces. During this time, I have
developed some macro naming conventions which you may wish to adopt.

@<Narrowthing@>@(FILE:@,Use this suffix for macros that contain
the names of files that form part of the web.@)

@<Narrowthing@>@(WWW:@,Use this suffix for macros that define
web directory URLs, up to and including the trailing slash.
The URL may be absolute or relative, depending on the context.@)

@<Narrowthing@>@(WWW/abs:@,Use this suffix where the URL must
be absolute.@)

@<Narrowthing@>@(EMAIL:@,Use this suffix for email addresses.@)

@<Narrowthing@>@(FTP:@,Use this suffix for FTP directory addresses.@)

@<Narrowthing@>@(WINDOWNAME:@,Use this suffix for the names of
browser windows.@)

@<P@>Here are some examples:

@<P@>
@<Begin verbatim@>@=#
@$@##<Home FILE@##>@Z@M@{index.html@}
@$@##<Ross WWW@##>@Z@M@{http://www.ross.net/@}
@$@##<Ross WWW/abs@##>@Z@M@{http://www.ross.net/@}
@$@##<Ross EMAIL@##>@Z@M@{ross@ross.net@}
@$@##<Ross FTP@##>@Z@M@{@-
ftp://www.ross.net/clients/ross/@}
@$@##<Ross WINDOWNAME@##>@Z@M@{ross@}
#=@@<End verbatim@>

@<Nav/last@>@(@<Web_param FILE@>@,@<Web FILE@>@,@<Web FILE@>@)

@<End FWTutMan page@>
@}

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

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

@<FunnelWeb webs copyright page contents@>

@<End FWTutMan page@>
@}

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

@B@<Search Form Section@>

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

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

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

@<End FWTutMan page@>
@}

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

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

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

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

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

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

@<End FWTutMan page@>
@}

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

@O@<search_e_nokeywords.txt@>@{@-
@<Begin FWTutMan 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 FWTutMan page@>
@}

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

@O@<search_e_nomanual.txt@>@{@-
@<Begin FWTutMan 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 FWTutMan 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

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