File: 0fw_ref.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 (5104 lines) | stat: -rw-r--r-- 186,718 bytes
parent folder | download | duplicates (5)
@!345678901234567890123456789012345678901234567890123456789012345678901234567890
@!******************************************************************************

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

This document contains the FunnelWeb source for the
FunnelWeb reference 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@{
15-Apr-1999: Converted the original 1992 FunnelWeb manual to this web.
08-May-1999: Documented new +u (HTML) option.
11-May-1999: Documented new fwinit.fws semantics.
12-May-1999: Documented library macro feature.
29-Dec-1999 RNW Added sidebar image strut to stop it collapsing.
30-Dec-1999 RNW Changed manual version number scheme.
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,51,102).

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 Reference WWW@>@Z@M@{@}
@$@<FunnelWeb Tutorial WWW@>@Z@M@{../tutorial/@}
@$@<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 FWRefMan 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 FWRefMan 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 FWRefMan margin@>@M@{
@<End size3@>
</TD>
</TR>
@<End table@>
@}

The tablecolour macro is needed so that people can read the white text
in the sidebar if the user has images turned off. The tablecolour is
macro is not applied to the images because Netscape writes their ALT tags
in black regardless of the background.

@$@<Sidebar menu@>@M@{@-
@<Begin size2@>
@<BR@>
@<RossNet linklogo IMAGE@>@<BR@>
@<BR@>
@<FunnelWeb linklogo IMAGE@>@<BR@>
@<BR@>
@<Begin tablecolour@>@(#000000@)
@<SideLink/bold/target@>@(@<FunnelWeb Tutorial WWW@>index.html@,@<FunnelWeb Tutorial WINDOWNAME@>@,Tutorial@)
@<BR@>
@<SideLink/bold/target@>@(@<FunnelWeb Developer WWW@>index.html@,@<FunnelWeb Developer WINDOWNAME@>@,Developer@)
@<BR@>
@<SideLink/bold@>@(@<FunnelWeb Reference WWW@>index.html@,Reference@)
@<SideLink@>@(@<Intro FILE@>@,@<Intro HEADING/short@>@)
@<SideLink@>@(@<Interface FILE@>@,@<Interface HEADING/short@>@)
@<SideLink@>@(@<Scanner FILE@>@,@<Scanner HEADING/short@>@)
@<SideLink@>@(@<Parser FILE@>@,@<Parser HEADING/short@>@)
@<SideLink@>@(@<Analyser FILE@>@,@<Analyser HEADING/short@>@)
@<SideLink@>@(@<Tangle FILE@>@,@<Tangle HEADING/short@>@)
@<SideLink@>@(@<Weave FILE@>@,@<Weave HEADING/short@>@)
@<SideLink@>@(@<Shell FILE@>@,@<Shell HEADING/short@>@)
@<SideLink@>@(@<Commands FILE@>@,@<Commands HEADING/short@>@)
@<SideLink@>@(@<Glossary FILE@>@,@<Glossary HEADING/short@>@)
@<SideLink@>@(@<References FILE@>@,@<References HEADING/short@>@)

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

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

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

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

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

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

@<End NormalSize@>
</BODY>

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

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

@B@<Images@>

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

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

@B@<General Macros@>

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

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

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

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

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

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

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

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

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

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

@<Body@>

@<Begin FWRefMan margin@>

@<RunningHeader IMAGE@>

@<FunnelWeb manual version notice@>

@<P@>@<Bigger@>@(T@)HIS REFERENCE MANUAL provides a concise
and precise definition of the functionality of the FunnelWeb
literate programming preprocessor. You should refer to this
manual when you have specific technical questions about
FunnelWeb. The SEARCH facility in the margin provides a
quick way to find what you need quickly. If you are not
already familiar with FunnelWeb, you may wish to refer to
the @<FunnelWeb Tutorial Manual@> which provides a
structured introduction to FunnelWeb, along with lots of
examples and application-specific information. If you want
to compile FunnelWeb, refer to the
@<FunnelWeb Developer Manual@>

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

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

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

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

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

@<HeadStyle@>@(@<Analyser FILE@>@,@<Analyser HEADING@>@)
@! No index.

@<HeadStyle@>@(@<Tangle FILE@>@,@<Tangle HEADING@>@)
@! No index.

@<HeadStyle@>@(@<Weave FILE@>@,@<Weave HEADING@>@)
@! No index.

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

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

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

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

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

@<End FWRefMan 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 FWRefMan page/H1@>@(@<Intro HEADING@>@)

@<P@>

@<Intro index@>

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

@<End FWRefMan page@>
@}

@$@<Intro index@>@M@{
@<Begin size3@>
@<Begin indent/narrow@>
<A HREF="@<Intro_notation FILE@>">@<Intro_notation HEADING@></A>@<BR@>
<A HREF="@<Intro_terminology FILE@>">@<Intro_terminology HEADING@></A>@<BR@>
<A HREF="@<Intro_arch FILE@>">@<Intro_arch HEADING@></A>@<BR@>
<A HREF="@<Intro_diagnostics FILE@>">@<Intro_diagnostics HEADING@></A>@<BR@>
<A HREF="@<Intro_typesetter FILE@>">@<Intro_typesetter HEADING@></A>@<BR@>
@<End indent/narrow@>
@<End size3@>
@}

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

@$@<Intro_notation HEADING@>@M@{@<SH@>@(1.1@)Notation@}
@$@<Intro_notation FILE@>@M@{intro_notation.html@}
@O@<intro_notation.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Intro_notation HEADING@>@)

@<P@>A particular variant of EBNF@<XX@>@(EBNF@,syntax@)
(Extended Bachus Naur Form) will be used to
describe the FunnelWeb syntax. In this variant, literal strings are
delimited by double quotes (@<eg@>@<TT@>@("string"@)), optional constructs by
square brackets (@<eg@>@<TT@>@([optional]@)), and constructs repeated zero or
more times by braces (@<eg@>@<TT@>@({zeroormore}@)). Constructs to be repeated
a fixed number of times are enclosed in braces followed by a decimal
number indicating the number of times to be repeated
(@<eg@>@<TT@>@({sixtimes}6@)). Constructs to be
repeated one or more times are
enclosed in braces and followed by a @<TT@>@(+@) (@<eg@>@<TT@>@({oneormore}+@)).
The traditional BNF @<DQP@>@(::=@)
is replaced by the visually simpler @<DQP@>@(=@). The traditional BNF angle
brackets are abandoned.

@<P@>Although FunnelWeb allows the special character to be changed using the
construct @<DQ@>@(@<<@>special@<>@>=@), use of @<DQ@>@(@<<@>special@<>@>@) to refer to
FunnelWeb's special character is cumbersome and abstract. To simplify
the presentation, the default special character @<DQP@>@(@@@) is used throughout
this chapter to represent the special character.

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

@<End FWRefMan page@>
@}

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

@$@<Intro_terminology HEADING@>@M@{@<SH@>@(1.2@)Terminology@}
@$@<Intro_terminology FILE@>@M@{intro_terminology.html@}
@O@<intro_terminology.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Intro_terminology HEADING@>@)

@<P@>A specific terminology has arisen for dealing with FunnelWeb. Some
particularly useful examples are:

@<NarrowThing@>@(Journal file:@,An output file containing
a copy of the output sent to
the user's console during an invocation of FunnelWeb. In other systems,
this file is sometimes called a @<DQ@>@(log file@).@)

@<NarrowThing@>@(Product file:@,An output file, generated by the Tangle
component of
FunnelWeb, that contains the expansion of the macros in the input
file. (Other names considered for this were:
generated file, expanded file, result file, program file, and tangle file.)@)

@<P@>A complete list of all the special FunnelWeb terminology appears in the
@<glossary@>. Be sure to refer to it if any of the terms used are unclear.

@<Nav@>@(@<Intro_notation FILE@>@,@<Intro FILE@>@,@<Intro_arch FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Intro_arch HEADING@>@M@{@<SH@>@(1.3@)An Architectural Overview@}
@$@<Intro_arch FILE@>@M@{intro_arch.html@}
@O@<intro_arch.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Intro_arch HEADING@>@)

@<P@>An understanding of the internals of FunnelWeb assists
with understanding its operation. During a single run,
FunnelWeb reads and processes a single input file called the
@<NewTerm@>@(input file@) (also called the
@<NewTerm@>@(FunnelWeb file@)). The file is processed by
passing it through a series of stages called
@<NewTerm@>@(phases@). The result is that some
@<NewTerm@>@(output files@) are generated. A
@<NewTerm@>@(journal file@) is generated containing a copy
of the messages that appear on the console during the
FunnelWeb run. A @<NewTerm@>@(listing file@) is created
containing a summary of the run, including any error
messages. A @<NewTerm@>@(documentation@) file is generated
containing typesetter commands that when fed into a
typesetter program will result in printed documentation.
Finally, one or more @<NewTerm@>@(product files@) are
generated containing the result of unscrambling the macro
definitions of the input file.

@<P@>
@<Begin verbatim@>

     .fw Input File
     (FunnelWeb file)
            V
       +---------+         \
       | Scanner |         |
       +---------+         |
            V              |
        +--------+         |
        | Parser |         |
        +--------+         |
            V              |
       +----------+        >----+--------+
       | Analyser |        |    |        |
       +----------+        |    |        |
            V              |    |        |
    +-------+-------+      |    V        V
    V               V      |    |        |
+--------+      +-------+  |    |        |
| Tangle |      | Weave |  |    |        |
+--------+      +-------+  /    |        |
    |               |           |        |
    V               V           V        V
 Product      Documentation  Listing  Journal
  Files           File         File    File
@<End verbatim@>
@<CaptionTitle@>@(FunnelWeb's processing phases@)

@<P@>These files need not all be generated on any particular FunnelWeb run.
Whether each output file appears, is controlled by command line options.

@<P@>FunnelWeb processes each input file in a sequence of phases.
If an error occurs during a phase, no subsequent phases are executed.

@<P@>The phases are briefly described below.

@<NarrowThing@>@(The
Scanner@,reads@<X@>@(scanner@) the input file,
expands and reads in include files, scans the
input stream, processes pragmas and typesetter
directives, and parses all the FunnelWeb special
sequences. The result is a list of tokens that is
handed to the parser.@)

@<NarrowThing@>@(The Parser@,reads@<X@>@(parser@)
the scanner's token list and parses it, constructing a
document list@<XX@>@(document@,list@) and a macro
table.@<XX@>@(macro@,table@) which are passed to later phases.@)

@<NarrowThing@>@(The Analyser@,examines@<X@>@(analyser@)
the macro table generated by the parser
and performs a number of checks of the macro structures
that the parser could not make on its single pass.
For example, the
analyser detects and flags unused macros and recursive macros. The
analyser forms the final stage of FunnelWeb's front-end processing.@)

@<NarrowThing@>@(Tangle@,expands certain macros in the macro table
to generate@<X@>@(tangle@) one or more product files.@)

@<NarrowThing@>@(Weave@,uses the document list to generate@<X@>@(weave@)
a documentation file.@)

@<P@>A single run through these phases constitutes a single invocation of
@<NewTerm@>@(FunnelWeb proper@). Most invocations of the
@<NewTerm@>@(FunnelWeb program@)
will consist only of a single execution of FunnelWeb proper. However,
FunnelWeb also provides a command shell that provides many useful commands,
including a command to invoke FunnelWeb proper. Discussion of the command
shell is deferred until later.

@<Nav@>@(@<Intro_terminology FILE@>@,@<Intro FILE@>@,@<Intro_diagnostics FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Intro_diagnostics HEADING@>@M@{@<SH@>@(1.4@)Diagnostics@}
@$@<Intro_diagnostics FILE@>@M@{intro_diagnostics.html@}
@O@<intro_diagnostics.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Intro_diagnostics HEADING@>@)

@<P@>During execution, FunnelWeb proceeds cautiously with
each of its phases, only proceeding with the next phase if
the previous phase has been successful. This means that,
when debugging a FunnelWeb file, you may find that the
number of errors @<I@>@(increases@) after you fix some of
them, as you will be exposing yourself to the next FunnelWeb
phase.

@<P@>FunnelWeb employs five levels of
diagnostics@<XX@>@(diagnostics@,levels of@) at different
levels of severity.@<X@>@(severity@) Severity is defined in
terms of the level of activity at which the diagnostic
causes FunnelWeb to abort.

@<NarrowThing@>@(Warning:@,A
warning@<XX@>@(warning@,severity@) does not cause FunnelWeb
to terminate or curtail its operation in any way, but serves
merely to warn the user of particular conditions that might
be symptomatic of deeper problems.@)

@<NarrowThing@>@(Error:@,An@<XX@>@(error@,severity@) error
causes FunnelWeb to terminate processing of the current
input file at the end of the current phase. For example, if
an error occurs during scanning, FunnelWeb will continue
scanning (and possibly generate further scanning
diagnostics), but will not invoke the parser.@)

@<NarrowThing@>@(Severe Error:@,A@<XX@>@(severe@,severity@)
severe error (or @<DQ@>@(severe@) for short) is the same as
an error except that FunnelWeb terminates the current phase
immediately.@)

@<NarrowThing@>@(Fatal Error:@,A@<XX@>@(fatal@,severity@)
fatal error causes FunnelWeb not only to terminate the
current phase and run immediately, but also to terminate
total FunnelWeb processing immediately. A severe error will
not cause a FunnelWeb script to terminate, but a fatal error
will. A fatal error causes FunnelWeb to return control to
the operating system.@)

@<NarrowThing@>@(Assertion
Error:@,An@<XX@>@(assertion@,severity@) assertion error
occurs if FunnelWeb detects an internal inconsistency, in
which case FunnelWeb terminates immediately and
ungracefully.  Such an error can occur only if there are
bugs in FunnelWeb. With luck, such errors will be extremely
rare.@)

@<P@>FunnelWeb indicates the level of severity of each
diagnostic that it issues by starting each diagnostic either
with the full name of the severity level or with just the
first letter of the severity level followed by a colon.

@<P@>FunnelWeb conveys the presence or absence of
diagnostics at the operating system level by returning
@<TT@>@(EXIT_SUCCESS@)@<XX@>@(return@,status@) status if no
diagnostics occurred during the run and
@<TT@>@(EXIT_FAILURE@) status if one or more diagnostics
(including warnings) occurred during the run. (From
the symbols of the ANSI standard C library
@<TT@>@(stdlib.h@). See @<Paper@>@(Kernighan88@), p.252.)

@<Nav@>@(@<Intro_arch FILE@>@,@<Intro FILE@>@,@<Intro_typesetter FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Intro_typesetter HEADING@>@M@{@<SH@>@(1.5@)Typesetter Independence@}
@$@<Intro_typesetter FILE@>@M@{intro_typesetter.html@}
@O@<intro_typesetter.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Intro_typesetter HEADING@>@)

@<P@>One of the design goals of FunnelWeb was to provide a
@<I@>@(target-language independent@) literate programming
system. This goal has been achieved simply by treating the
text written to the product file as homogeneous and
typesetting it in @<TT@>@(tt font@). A secondary goal was to
provide a @<I@>@(typesetter independent@) literate
programming system. By this is meant that it be possible to
create FunnelWeb input files that do not contain
typesetter-specific commands. To a lesser extent this goal
has also been achieved.

@<P@>The difficulty with providing typesetter-independent
typesetting is that each desired typesetting feature must be
recreated in a typesetter-independent FunnelWeb typesetting
construct that FunnelWeb can translate into whatever
typesetting language is being targeted by Weave. Taken to
the extreme, this would result in FunnelWeb providing the
full syntactic and semantic power of TeX, but with a more
generic, FunnelWeb-specific syntax. This was unfeasible in
the time available, and undesirable as well.

@<P@>The compromise struck in the FunnelWeb design is to
provide a set of primitive typesetter-independent
typesetting features that are implemented by FunnelWeb.
These are the @<NewTerm@>@(typesetter directives@). If the
user is prepared to restrict to these directives, then the
user's FunnelWeb document will be both target-language and
typesetter independent. However, if the user wishes to use
the more sophisticated features of the target typesetting
system, the user can specify the typesetter in a
@<DQP@>@(typesetter@) pragma and then place typesetter
commands in the free text of the FunnelWeb document where
they will be passed verbatim to the documentation file. The
choice of the trade-off between typesetter independence and
typesetting power is left to the user.

@<P@>This said, experience with FunnelWeb, over more than a
decade, indicates that the typesetting facilities provided by
FunnelWeb are sufficient for most documentation.

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

@<End FWRefMan page@>
@}

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

@$@<Interface HEADING@>@M@{@<SH@>@(2@)Command Line Interface@}
@$@<Interface HEADING/short@>@M@{@<SH@>@(2@)Interface@}
@$@<Interface FILE@>@M@{interface.html@}
@O@<interface.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Interface HEADING@>@)

@<P@>

@<Interface index@>

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

@<End FWRefMan page@>
@}

@$@<Interface index@>@M@{
@<Begin size3@>
@<Begin indent/narrow@>
<A HREF="@<Interface_invoking FILE@>">@<Interface_invoking HEADING@></A>@<BR@>
<A HREF="@<Interface_arguments FILE@>">@<Interface_arguments HEADING@></A>@<BR@>
<A HREF="@<Interface_options FILE@>">@<Interface_options HEADING@></A>@<BR@>
<A HREF="@<Interface_inheritance FILE@>">@<Interface_inheritance HEADING@></A>@<BR@>
<A HREF="@<Interface_startup FILE@>">@<Interface_startup HEADING@></A>@<BR@>
@<End indent/narrow@>
@<End size3@>
@}

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

@$@<Interface_invoking HEADING@>@M@{@<SH@>@(2.1@)Invoking FunnelWeb@}
@$@<Interface_invoking FILE@>@M@{interface_invoking.html@}
@O@<interface_invoking.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Interface_invoking HEADING@>@)
@<XX@>@(FunnelWeb@,invoking@)@<XX@>@(FunnelWeb@,running@)

@<P@>When a user invokes FunnelWeb at the operating system
command level, the user must provide a command line
instructing FunnelWeb what to do. Typically an operating
system command line consists of a @<I@>@(verb@) indicating
that a particular program should be run, followed by a list
of options. For example:

@<P@>
@<Begin verbatim@>
rename file1 file2
@<End verbatim@>

@<P@>In this case, the verb is @<TT@>@(rename@) and the
command line options are @<TT@>@(file1 file2@).

@<P@>Operating systems differ greatly in the depth with
which they process their command@<XX@>@(command
line@,processing@) lines, ranging from systems that simply
pass the entire command line string to the invoked program
(@<eg@>MSDOS) through to systems that perform complete
command line parsing (@<eg@>OpenVMS). Syntax conventions vary
considerably.

@<P@>So as to achieve maximum portability and consistency of
invocation across different platforms, FunnelWeb reads its
command line as a raw string and performs all its own
parsing.@<XX@>@(command line@,parsing@) This is portable
because, at the very least, all operating systems allow
invoked programs access to the raw command line.

@<P@>The command verb used to invoke FunnelWeb should be
@<DQP@>@(fw@).@<XX@>@(fw@,command verb@)

@<P@>
@<Begin verbatim@>
FunnelWeb_verb =  "fw"
@<End verbatim@>

@<P@>If this verb is not available, some alternatives are
@<DQP@>@(funweb@), @<DQP@>@(fun@), and @<DQP@>@(funnelweb@).
The verbs @<TT@>@(web@) or @<TT@>@(fweb@) should be avoided
as they are the names of other literate programming tools.

@<Nav/first@>@(@<Interface FILE@>@,@<Interface FILE@>@,@<Interface_arguments FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Interface_arguments HEADING@>@M@{@<SH@>@(2.2@)Command Line Arguments@}
@$@<Interface_arguments FILE@>@M@{interface_arguments.html@}
@O@<interface_arguments.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Interface_arguments HEADING@>@)
@<XX@>@(command line@,argument@)@<XX@>@(syntax@,command line@)

@<P@>Following the verb is the body of the command line
which FunnelWeb parses into zero or more
@<NewTerm@>@(arguments@) separated by runs of one or more
blanks.

@<P@>
@<Begin verbatim@>
FunnelWeb_command_line =
   FunnelWeb_verb { {" "}+ argument }
@<End verbatim@>

@<P@>Because some operating systems convert their command
line to upper case before handing it to the invoked program,
FunnelWeb has been constructed so as to be
@<I@>@(insensitive@) to the case of its command line
arguments.@<XX@>@(case@,dependence@) However, when dealing
internally with arguments, FunnelWeb @<I@>@(preserves@) the
case of its command line arguments so that it will be able
to operate with operating systems (such as
Unix@<X@>@(Unix@)) whose file names are case dependent.

@<P@>A valid FunnelWeb argument consists of a
@<NewTerm@>@(sign@), an identifying @<NewTerm@>@(letter@),
and an optional @<NewTerm@>@(string@) with no spaces
separating them.@<XX@>@(command line
options@,syntax@)@<XX@>@(options@,syntax@)

@<P@>
@<Begin verbatim@>
argument  = sign id_letter [non_blank_string]
sign      = "+" | "-" | "="
id_letter = "B" | "C" | "D" | "F" | "H" | "I" |
            "J" | "K" | "L" | "O" | "Q" | "S" |
            "T" | "W" | "X"
@<End verbatim@>

@<P@>In addition there is a special form of argument that
does not begin with a sign.

@<P@>
@<Begin verbatim@>
argument = non_blank_string_not_starting_with_+_=_or_-
@<End verbatim@>

@<P@>This form is exactly equivalent to the same string with
@<DQP@>@(+F@) prepended to it.

@<P@>The semantic effect of these arguments is defined in
terms of @<NewTerm@>@(options@) which are the internal
parameters of FunnelWeb and which correspond closely with
the set of legal command line arguments. FunnelWeb has a
predefined set of options each identified by an identifying
letter having two attributes: a @<I@>@(string@), and a
@<I@>@(boolean@). The boolean determines whether an option
is turned @<I@>@(on@) or @<I@>@(off@). The string contains
additional information depending on the option.

@<P@>When FunnelWeb starts up, its options have predefined
default values. FunnelWeb then parses its command line
sequentially from left to right executing the effect of each
argument on the argument's corresponding option.  The sign
and the string components of the argument are processed
@<I@>@(independently@). A sign of @<TT@>@(+@) turns the
option on. A sign of @<TT@>@(-@) turns the option off. A
sign of @<TT@>@(=@) leaves the option's boolean attribute
unchanged. The argument string replaces the string of the
corresponding option, unless the argument string is empty,
in which case the option string is not changed.

@<P@>Because FunnelWeb processes its command line arguments
from left to right, a later argument can cancel the effect
of an earlier one. For example @<TT@>@(fw +t -t@) will
result in the @<TT@>@(t@) option ending up @<I@>@(off@).
This allows users to set up their own default arguments by
defining a symbol in their operating system's command
language. For example, a Unix user who wants FunnelWeb to
delete all identical output files and create a documentation
file on each run with a default @<TT@>@(.typ@) extension
could simply place the following definition in their
@<DQP@>@(.login@) file.

@<P@>
@<Begin verbatim@>
alias fw fw +d +t.typ
@<End verbatim@>

@<P@>These default options can then later be easily
overridden on the command line.

@<Nav@>@(@<Interface_invoking FILE@>@,@<Interface FILE@>@,@<Interface_options FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Interface_options HEADING@>@M@{@<SH@>@(2.3@)Options@}
@$@<Interface_options FILE@>@M@{interface_options.html@}
@O@<interface_options.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Interface_options HEADING@>@)
@<X@>@(options@)@<XX@>@(list@,options@)

@<P@>FunnelWeb's options are internal parameters which can
be modified by corresponding arguments on FunnelWeb's
command line. A description of each argument and option
follows.

@<NarrowThing@>@(B1@<LDots@>B6:
Tracedumps:@,These@<XX@>@(B@,option@)
six@<XX@>@(tracedump@,options@)@<XX@>@(dump@,option@)
options have been provided to assist in the debugging and
testing of FunnelWeb. They determine which of six possible
trace dumps are to be written to the listing file. Only the
boolean attributes of these options are ever used. The six
dumps are identified by the digits @<TT@>@(1..6@) as
follows:@<XX@>@(dump@,mapped file@) @<XX@>@(dump@,global
line list@)@<XX@>@(dump@,token list@) @<XX@>@(dump@,macro
table@)@<XX@>@(dump@,document list@)@<XX@>@(dump@,times@)@)

@<P@>
@<Begin list/ordered@>
@<Item@>Dump a hexdump of each mapped input and include file.
@<Item@>Dump the global line list created by the scanner.
@<Item@>Dump the token list created by the scanner.
@<Item@>Dump the macro table created by the parser.
@<Item@>Dump the document list created by the parser.
@<Item@>Dump a table summarizing CPU and real time usage.
@<End list/ordered@>

@<P@>Because these options are so closely related, a hack
has been pulled to enable them to all to be controlled by
the @<TT@>@(B@) argument. The string argument to the
@<TT@>@(B@) argument determines which of the six options are
to be affected by the sign. Examples: @<TT@>@(+B134@) turns
on options @<TT@>@(B1@), @<TT@>@(B3@), and @<TT@>@(B4@).
@<TT@>@(-B1@) turns off option @<TT@>@(B1@).
@<TT@>@(Default:@<_@>-B123456@).

@<NarrowThing@>@(B7: Determinism:@,If the @<TT@>@(B7@)
option is turned on, FunnelWeb suppresses the output of
anything non-deterministic,@<X@>@(non-determinism@) or
machine dependent. This assists in regression testing. Only
the boolean attribute is used in this option. This option is
controlled by the @<TT@>@(B7@) argument which falls under
the same argument syntax as the other @<TT@>@(B@) options.
Examples: @<TT@>@(+B7@), @<TT@>@(-B7@).
@<TT@>@(Default:@<_@>-B7@).@)

@<NarrowThing@>@(C: Listing File
Context:@,The@<XX@>@(C@,option@) @<TT@>@(C@)@<XX@>@(listing
file@,context@) option is always turned on and cannot be
turned off. Its only attribute is a number which determines
the number of lines of context that the lister will place
around lines flagged with diagnostics in the listing file
(if a listing file is written). A value of 100 indicates
infinite context@<XX@>@(infinite@,context@) which means that
the entire listing file will be written out if a single
diagnostic occurs. The value of this number can be specified
by specifying it as a string of decimal digits to the
@<TT@>@(+C@) argument. Examples: @<TT@>@(+C100@),
@<TT@>@(+C10@). @<TT@>@(Default:@<_@>+C2@).@)

@<NarrowThing@>@(D: Delete Identical Output Files:@,Only the
boolean attribute of this option is
used.@<XX@>@(D@,option@)@<XX@>@(delete output@,option@) When
turned on, the option causes the suppression (deletion) of
product files and documentation files (but not listing or
journal files) that are identical to the currently existing
files of the same name. For example, if FunnelWeb is
instructed to generate @<TT@>@(stack.h@) as an product file,
and the text to be written to @<TT@>@(stack.h@) is identical
to the currently existing @<TT@>@(stack.h@), then FunnelWeb
will simply not write any product file, leaving the
currently existing @<TT@>@(stack.h@) as it is (and in
particular leaving the file's date attribute the same). This
prevents unnecessary @<TT@>@(make@) propagations. For
example, in a C program, if @<TT@>@(stack.fw@) is a
FunnelWeb input file that generates @<TT@>@(stack.h@) and
@<TT@>@(stack.c@), a modification to @<TT@>@(stack.fw@) that
affects @<TT@>@(stack.c@) but does not affect
@<TT@>@(stack.h@) will not provoke the recompilation of
modules that @<TT@>@(#include stack.h@), so long as the
intervening FunnelWeb run has @<TT@>@(+D@) set. Examples:
@<TT@>@(-D@), @<TT@>@(+D@). @<TT@>@(Default:@<_@>-D@).@)

@<NarrowThing@>@(F: FunnelWeb Input
File:@,If@<XX@>@(F@,option@) this option is turned on,
FunnelWeb@<XX@>@(input file@,option@) processes the input
file whose name is specified by the option string. Examples:
@<TT@>@(+Fsloth.fw@), @<TT@>@(+Fwalrus@), @<TT@>@(-F@).
@<TT@>@(Default:@<_@>-F@).@)

@<NarrowThing@>@(H: Display Help
Message:@,If@<XX@>@(H@,option@) this
option@<XX@>@(help@,option@) is turned on, FunnelWeb
displays the message specified by the argument string. Each
message has a name. The main help message is called
@<DQP@>@(menu@) and contains a list of the other help
messages. Examples: @<TT@>@(+Hregistration@),
@<TT@>@(+Hoptions@). @<TT@>@(Default:@<_@>-Hmenu@).@)

@<NarrowThing@>@(I: Include default file
specification:@,This@<XX@>@(I@,option@)
option@<XX@>@(include file@,option@)@<XX@>@(include@,file@)
is always turned on and cannot be turned off. Its string
attribute is used as the default file specification for
include files. Usually this option is used to specify a
directory from which include files should be obtained.
Examples: @<TT@>@(=I/usr/dave/includes/@).
@<TT@>@(Default:@<_@>+I@).@)

@<NarrowThing@>@(J: Journal File:@,If@<XX@>@(J@,option@)
this option is turned on, FunnelWeb generates
a@<XX@>@(journal file@,option@)@<XX@>@(journal@,file@)
journal file. A journal file contains a log of all the
console input and output to FunnelWeb during a single
invocation of the FunnelWeb program (Note: The @<TT@>@(Q@)
option does not affect this.). The journal file is
particularly useful for examining what happened during a
FunnelWeb shell run. The string attribute is the name of the
journal file. Examples: @<TT@>@(+Jjournfile@), @<TT@>@(-J@).
@<TT@>@(Default:@<_@>-J@).@)

@<NarrowThing@>@(K: Keyboard:@,If@<XX@>@(K@,option@) this
option@<XX@>@(keyboard@,option@)@<XX@>@(interactive@,option@)
is turned on, FunnelWeb enters an interactive mode in which
the user can enter FunnelWeb shell commands interactively.
The string attribute is unused. Examples: @<TT@>@(+K@),
@<TT@>@(-K@). @<TT@>@(Default:@<_@>-K@).@)

@<NarrowThing@>@(L: Listing File:@,If@<XX@>@(L@,option@)
this option is turned on, FunnelWeb generates
a@<XX@>@(listing file@,option@)@<XX@>@(listing@,file@)
listing file containing a summary of a run on FunnelWeb
proper. The string argument is the name of the listing file
to be created. Examples: @<TT@>@(+L@), @<TT@>@(-L@),
@<TT@>@(+Llisting.lis@). @<TT@>@(Default:@<_@>-L@).@)

@<NarrowThing@>@(O: Product Files:@,If this option is turned
on, FunnelWeb generates a product file for each macro in the
input file that is bound to an output file. The string
attribute contributes to the name of the product files. This
option is controlled by the @<TT@>@(O@) argument because
product files used to be called @<DQ@>@(@<B@>@(O@)utput
files@)). Examples: @<TT@>@(-O@),
@<TT@>@(+O/usr/dave/product/@). @<TT@>@(Default:@<_@>+O@).@)

@<NarrowThing@>@(Q: Quiet:@,If@<XX@>@(Q@,option@) this
option is turned on, FunnelWeb suppresses
all@<XX@>@(quiet@,option@)@<XX@>@(suppress@,console output@)
output to the screen (standard output) unless one or more
errors occur, in which case a single line summarizing the
errors is sent to standard output at the end of the run. If
this option is turned off, FunnelWeb writes to the console
in its normal garrulous way. The string attribute is unused
in this option. Examples: @<TT@>@(-Q@), @<TT@>@(+Q@).
@<TT@>@(Default:@<_@>-Q@).@)

@<NarrowThing@>@(S: Screen:@,If@<XX@>@(S@,option@) this
option is turned on, FunnelWeb writes
all@<XX@>@(screen@,option@) diagnostics to the screen
(standard output) as well as to the listing file. By
default, they are sent only to the listing file. This option
has a single numerical attribute that can be specified as a
decimal string in the string component of the @<TT@>@(S@)
argument. The number is the number of lines of context that
should surround each diagnostic sent to the
screen.@<X@>@(context@) Examples: @<TT@>@(-S@),
@<TT@>@(+S6@), @<TT@>@(+S0@). @<TT@>@(Default:@<_@>-S@).@)

@<NarrowThing@>@(T: TeX Documentation
file:@,If@<XX@>@(T@,option@) this option is turned on,
FunnelWeb@<XX@>@(typeset@,option@)@<XX@>@(typeset@,file@)
generates a documentation file in TeX format. The string
argument contributes to the name of the documentation file
to be created. By default this option is turned off, as
experience has shown that most FunnelWeb runs are made
during program development; documentation runs occur far
more rarely. This option is controlled by the @<TT@>@(T@)
command line argument because documentation files used to be
called typesetter files. Examples: @<TT@>@(-T@),
@<TT@>@(+Tsloth.tex@). @<TT@>@(Default:@<_@>-T@).@)

@<NarrowThing@>@(U: HTML Documentation
file:@,If@<XX@>@(U@,option@) this option is turned on,
FunnelWeb@<XX@>@(typeset@,option@)@<XX@>@(typeset@,file@)
generates a documentation file in HTML format. The string
argument contributes to the name of the documentation file
to be created. By default this option is turned off, as
experience has shown that most FunnelWeb runs are made
during program development; documentation runs occur far
more rarely. @<TT@>@(U@) was chosen for this feature
because it follows @<TT@>@(T@), and @<TT@>@(H@) and
@<TT@>@(W@) were already allocated to other functions.
Examples: @<TT@>@(-U@),
@<TT@>@(+Usloth.html@). @<TT@>@(Default:@<_@>-U@).@)

@<NarrowThing@>@(W: Width of Product
Files:@,If@<XX@>@(W@,option@) this
option@<XX@>@(width@,option@)@<XX@>@(product file@,width@)
is turned on, a limit is placed on the length of lines in
product files generated during the run. Lines that breach
the limit are flagged with error messages. This option has a
single numerical attribute that can be specified as a
decimal string in the string component of the @<TT@>@(W@)
argument. The number is the specified maximum width. This
option is one of two limits that are placed on the width of
product files. The other limit is an attribute of the input
file that defaults to 80 characters, but can be raised or
lowered using an output line length pragma. The width that
is enforced is the lower of this value and the value of the
@<TT@>@(W@) option (if turned on). Examples: @<TT@>@(-W@),
@<TT@>@(+W100@). @<TT@>@(Default:@<_@>-W80@).@)

@<NarrowThing@>@(X: Execute:@,If@<XX@>@(X@,option@) this
option@<XX@>@(execute script@,option@) is turned on,
FunnelWeb executes the FunnelWeb shell script file specified
by the string attribute. Examples: @<TT@>@(+Xmaster@),
@<TT@>@(-X@). @<TT@>@(Default:@<_@>-X@).@)

@<Nav@>@(@<Interface_arguments FILE@>@,@<Interface FILE@>@,@<Interface_inheritance FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Interface_inheritance HEADING@>@M@{@<SH@>@(2.4@)File Name Inheritance@}
@$@<Interface_inheritance FILE@>@M@{interface_inheritance.html@}
@O@<interface_inheritance.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Interface_inheritance HEADING@>@)
@<XX@>@(filename@,inheritance@)

@<P@>During a single run of FunnelWeb, FunnelWeb can produce
many different output files. As it would be very tedious to
have to specify the name of each of these files explicitly
each time FunnelWeb is run, FunnelWeb provides a system of
defaults that allows the user to specify the minimum
required to successfully complete the run. To do this,
FunnelWeb allows file specifications to inherit fields from
one another.

@<P@>FunnelWeb structures filenames into three
fields@<XX@>@(filename@,fields@) which are inherited
independently. The fields are: @<NewTerm@>@(directory@),
@<NewTerm@>@(name@), and @<NewTerm@>@(extension@). On
systems having other fields (@<eg@>@<I@>@(network node@),
@<I@>@(device name@)), the extra fields are considered to be
part of the directory field. Version numbers are ignored. A
field can inherit a value if its current value is the empty
string.

@<P@>The following table gives the full inheritance scheme
used in FunnelWeb.

@<P@>
@<Begin table/border@>
@<Row8@>@(@<B@>@(Script@) @, @<B@>@(Input@) @, @<B@>@(Include@)@, @<B@>@(Journal@)@,  @<B@>@(List@)  @, @<B@>@(TeX@)     @, @<B@>@(HTML@)     @, @<B@>@(Prod@) @)
@<Row8@>@(@<_@>           @, @<_@>          @, @<TT@>@(@@i@)   @, @<_@>           @, @<_@>           @, @<_@>            @, @<_@>             @, @<TT@>@(@@o@) @)
@<Row8@>@(@<TT@>@(+x@)    @, @<TT@>@(+f@)   @, @<TT@>@(+i@)    @, @<TT@>@(+j@)    @, @<TT@>@(+l@)    @, @<TT@>@(+t@)     @, @<TT@>@(+u@)      @, @<TT@>@(+o@)  @)
@<Row8@>@(@<DQP@>@(.fws@) @, @<DQP@>@(.fw@) @, @<DQP@>@(.fwi@) @, @<DQP@>@(.jrn@) @, @<DQP@>@(.lis@) @, @<DQP@>@(.tex@)  @, @<DQP@>@(.html@)  @, @<_@>         @)
@<Row8@>@(@<_@>           @, @<_@>          @, @<TT@>@(+f@)    @, @<TT@>@(+f@)    @, @<TT@>@(+f@)    @, @<TT@>@(+f@)     @, @<TT@>@(+f@)      @, @<_@>         @)
@<Row8@>@(DefDir          @, Defdir         @, Defdir          @, Defdir          @, Defdir          @, Defdir           @, Defdir            @, Defdir        @)
@<End table@>

@<P@>The table is arranged with items of highest priority at
the top. The @<DQP@>@(+<letter>@) cells refer to the file
specification supplied in the given command line argument.
@<DQP@>@(+F@) is the name of the input file.
@<DQ@>@(Defdir@) refers to the default directory
specification provided by the operating system. Empty cells
do not contribute.

@<P@>The following example shows how the table is used.
Suppose that the user invoked FunnelWeb as
follows:@<XX@>@(filename inheritance@,example@)

@<P@>
@<Begin verbatim@>
fw /usr/ross/work/sloth.fw +twalrus
@<End verbatim@>

@<P@>To work out what the documentation file should be
called, FunnelWeb starts with the empty string and then
works down the Document column of the table. The top entry
is empty so we ignore it and proceed to the second entry
which consists of @<DQP@>@(+T@). The user specified the
string @<DQP@>@(walrus@) as the value of this option, and as
our current (empty) string does not have a name field, we
insert the string @<DQP@>@(walrus@) into the name field,
resulting in the string @<DQP@>@(walrus@). Moving down to
the next row, we encounter the constant string
@<DQP@>@(.tex@). This string consists of an empty directory
and name field, but a @<DQP@>@(.tex@) file extension. As our
current string @<DQP@>@(walrus@), does not already have a
file extension (@<ie@>the file extension field of our
current string is empty), we add in @<DQP@>@(.tex@),
resulting in the string @<DQP@>@(walrus.tex@). Next we
encounter the @<DQP@>@(+F@) field which is the input
filename @<DQP@>@(/usr/ross/work/sloth.fw@) consisting of a
directory field @<DQP@>@(/usr/ross/work/@), a name field
@<DQP@>@(sloth@), and a file extension field @<DQP@>@(.fw@).
Our @<DQP@>@(walrus.tex@) string already has name and file
extension fields, but its directory field is empty, and so
we add in the directory field from the input file
specification, resulting in the string
@<DQP@>@(/usr/ross/work/walrus.tex@). Finally, we hit the
default directory specification, which is (say)
@<DQP@>@(/usr/ross/play/@). However, as the directory field
of our walrus string is already full, it has no effect.

@<P@>In general, there is no need to remember the exact
details of FunnelWeb's filename inheritance. The important
thing is to know that it exists, and to use it.

@<Nav@>@(@<Interface_options FILE@>@,@<Interface FILE@>@,@<Interface_startup FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Interface_startup HEADING@>@M@{@<SH@>@(2.5@)FunnelWeb Startup@}
@$@<Interface_startup FILE@>@M@{interface_startup.html@}
@O@<interface_startup.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Interface_startup HEADING@>@)
@<XX@>@(FunnelWeb@,startup@)@<XX@>@(FunnelWeb@,initialization@)

@<P@>FunnelWeb's command line options can be divided into
two groups. @<NewTerm@>@(Action options@) instruct FunnelWeb
to performs some sort of independent action such as
processing a file. @<NewTerm@>@(Ordinary options@) merely
modify the way in which FunnelWeb executes the actions.

@<P@>The four action options are: @<TT@>@(+F@),
@<TT@>@(+K@), @<TT@>@(+X@), and @<TT@>@(+H@).

@<P@>When FunnelWeb is invoked, if no action options are
specified, and there is a file called @<TT@>@(fwinit.fws@) in the
current directory, then FunnelWeb executes the FunnelWeb script
file (@<TT@>@(.fws@)) and terminates. If there isn't such a file,
FunnelWeb issues a help message and terminates.

@<P@>If, when FunnelWeb is invoked, one or more action options
are specified, FunnelWeb performs the actions in a predefined
order as follows:@<XX@>@(action execution@,order@)

@<NarrowThing@>@(Initialization
script:@,FunnelWeb@<XX@>@(initialization@,script@) starts by
looking in the current directory for a file called
@<DQP@>@(fwinit.fws@).@<X@>@(fwinit.fws@) If it doesn't find
one, it doesn't raise any error. If it does find one, it
executes it as a FunnelWeb shellscript. Initialization
scripts are useful for setting up FunnelWeb options
(@<eg@>using the @<DQP@>@(set@) command without having to
type them each time).@)

@<NarrowThing@>@(Execute argument script:@,If a shellscript
has been specified using the @<DQP@>@(+X@) option, FunnelWeb
executes it.@)

@<NarrowThing@>@(Process input file:@,If the user has
specified an input file using the @<DQP@>@(+F@) option, then
this is processed next (by FunnelWeb proper).@)

@<NarrowThing@>@(Display help message:@,If the user
requested, using the @<DQP@>@(+H@) option, that a help
message be displayed, the message is displayed at this
time.@)

@<NarrowThing@>@(Interactive mode:@,If the user specified
the @<DQP@>@(+K@) option, FunnelWeb enters interactive
(keyboard) mode.@)

@<P@>FunnelWeb processes these actions in the above order
regardless of the order in which they appear on the command
line.

@<P@>It may be hard to see how some of these actions might
be combined. Nevertheless, FunnelWeb allows this. For
example,  a user might wish to process a batch of files as
specified in a script (@<DQP@>@(+Xscript.fws@)), be reminded
of the interactive commands available
(@<DQP@>@(+Hcommand@)), and then enter interactive mode so
as to be able to reprocess files for which FunnelWeb
reported errors (after correcting the errors in a different
workstation window).

@<Nav/last@>@(@<Interface_inheritance FILE@>@,@<Interface FILE@>@,@<Interface FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner HEADING@>@M@{@<SH@>@(3@)Scanner@}
@$@<Scanner HEADING/short@>@M@{@<SH@>@(3@)Scanner@}
@$@<Scanner FILE@>@M@{scanner.html@}
@O@<scanner.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner HEADING@>@)

@<P@> The scanner reads in the input file and produces a
list of tokens which it hands onto the parser. In addition,
some input constructs may cause the scanner to modify some
of FunnelWeb's options.

@<Scanner index@>

@<Nav@>@(@<Interface FILE@>@,@<Index FILE@>@,@<Parser FILE@>@)

@<End FWRefMan page@>
@}

@$@<Scanner index@>@M@{
@<Begin size3@>
@<Begin indent/narrow@>
<A HREF="@<Scanner_basic FILE@>">@<Scanner_basic HEADING@></A>@<BR@>
<A HREF="@<Scanner_special FILE@>">@<Scanner_special HEADING@></A>@<BR@>
<A HREF="@<Scanner_special_set FILE@>">@<Scanner_special_set HEADING@></A>@<BR@>
<A HREF="@<Scanner_special_ins FILE@>">@<Scanner_special_ins HEADING@></A>@<BR@>
<A HREF="@<Scanner_arbitrary FILE@>">@<Scanner_arbitrary HEADING@></A>@<BR@>
<A HREF="@<Scanner_comments FILE@>">@<Scanner_comments HEADING@></A>@<BR@>
<A HREF="@<Scanner_quicknames FILE@>">@<Scanner_quicknames HEADING@></A>@<BR@>
<A HREF="@<Scanner_eol_ins FILE@>">@<Scanner_eol_ins HEADING@></A>@<BR@>
<A HREF="@<Scanner_eol_supp FILE@>">@<Scanner_eol_supp HEADING@></A>@<BR@>
<A HREF="@<Scanner_include FILE@>">@<Scanner_include HEADING@></A>@<BR@>
<A HREF="@<Scanner_prag FILE@>">@<Scanner_prag HEADING@></A>@<BR@>
<A HREF="@<Scanner_prag_ind FILE@>">@<Scanner_prag_ind HEADING@></A>@<BR@>
<A HREF="@<Scanner_prag_maxin FILE@>">@<Scanner_prag_maxin HEADING@></A>@<BR@>
<A HREF="@<Scanner_prag_maxout FILE@>">@<Scanner_prag_maxout HEADING@></A>@<BR@>
<A HREF="@<Scanner_prag_type FILE@>">@<Scanner_prag_type HEADING@></A>@<BR@>
<A HREF="@<Scanner_type FILE@>">@<Scanner_type HEADING@></A>@<BR@>
<A HREF="@<Scanner_type_newpage FILE@>">@<Scanner_type_newpage HEADING@></A>@<BR@>
<A HREF="@<Scanner_type_contents FILE@>">@<Scanner_type_contents HEADING@></A>@<BR@>
<A HREF="@<Scanner_type_vskip FILE@>">@<Scanner_type_vskip HEADING@></A>@<BR@>
<A HREF="@<Scanner_type_title FILE@>">@<Scanner_type_title HEADING@></A>@<BR@>
<A HREF="@<Scanner_parser FILE@>">@<Scanner_parser HEADING@></A>@<BR@>

@<End indent/narrow@>
@<End size3@>
@}

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

@$@<Scanner_basic HEADING@>@M@{@<SH@>@(3.1@)Basic Input File Processing@}
@$@<Scanner_basic FILE@>@M@{scanner_basic.html@}
@O@<scanner_basic.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_basic HEADING@>@)

@<P@>In order to read in an input file or include file, the
scanner calls a submodule called the @<NewTerm@>@(mapper@)
that reads a file in and creates a contiguous copy of it in
memory. The scanner then performs three checks on the file,
the first (file termination) of which is performed before
scanning commences, and the other two of which take place
during scanning before each line is scanned.

@<NarrowThing@>@(File
Termination:@,The@<XX@>@(file@,termination@) first check the
scanner makes@<XX@>@(line@,termination@) is whether the file
is terminated properly. A file is considered to be properly
terminated if it either contains no lines, or if the last
line in the file is terminated by an end-of-line marker. If
the scanner detects that an input file is not properly
terminated, it adds an end-of-line marker itself (to the
copy in memory only).@)

@<NarrowThing@>@(Unprintable Characters:@,The second check
the scanner makes is for@<XX@>@(unprintable@,characters@)
unprintable characters (ASCII 0--31 and 127--255 (except for
EOL(10))) which it flags as errors and  replaces by question
marks.@)

@<NarrowThing@>@(Line Lengths:@,The third check the scanner
makes is input line length.@<XX@>@(line@,length@) When
FunnelWeb starts up, a default maximum input line length of
80 is set. This can be changed dynamically during scanning
using a @<TT@>@(@@p maximum_input_line_length@) pragma. If
the number of characters on a line (not including the end of
line marker) exceeds this limit, FunnelWeb generates an
error.@)

@<Nav/first@>@(@<Scanner FILE@>@,@<Scanner FILE@>@,@<Scanner_special FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_special HEADING@>@M@{@<SH@>@(3.2@)Special Sequences@}
@$@<Scanner_special FILE@>@M@{scanner_special.html@}
@O@<scanner_special.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_special HEADING@>@)

@<P@>The scanner scans the input file from top to bottom,
left to right, treating the input as ordinary text (to be
handed directly to the parser as a text token) unless it
encounters the @<NewTerm@>@(special character@) which
introduces a @<NewTerm@>@(special sequence@). Thus, the
scanner partitions the input file into ordinary text and
special sequences. (Note: This sort of character is often
referred to as the @<DQ@>@(escape character@) or the
@<DQ@>@(control character@) in other systems. However, as
there is great potential to confuse these names with the
@<DQ@>@(escape@) character (ASCII 27) and ASCII
@<DQ@>@(control@) characters, the term @<DQ@>@(special@) has
been chosen instead. This results in the terms
@<I@>@(special character@) and @<I@>@(special sequence@).

@<P@>
@<Begin verbatim@>
input_file = { ordinary_text | special_sequence }
@<End verbatim@>

@<P@>Upon startup, the special
character@<XX@>@(default@,special character@) is
@<TT@>@(@@@), but it can be changed using the
@<<@>special@<>@>@<TT@>@(=@)@<<@>new_special@<>@> special sequence.
Rather than using @<<@>special@<>@> whenever the special
character appears, this document uses the default special
character @<DQP@>@(@@@) to represent the current special
character. More importantly, FunnelWeb's error messages all
use the default special character in examples,
even if the special character has been changed.

@<P@>An occurrence of the special character in the input
file introduces a special sequence. The kind of special
sequence is determined by the character following the
special character. Only printable characters can follow the
special character.

@<P@>The following list gives all the possible characters
that can follow the special character, and the legality of
each sequence. The first column gives the ASCII number of
each ASCII character. The second column gives the special
sequence for that character. The next column contains one of
three characters: @<DQP@>@(-@) means that the sequence is
illegal. @<DQP@>@(S@) indicates that the sequence is a
@<NewTerm@>@(simple sequence@) (with no attributes or side
effects) that appears exactly as shown and is converted
directly into a token and fed to the parser. Finally,
@<DQP@>@(C@) indicates that the special sequence is complex,
possibly having a following syntax or producing funny side
effects.

@<P@>
@<Begin verbatim@>
ASC  SEQ  COMMENT
-----------------
000       \
016        | Unprintable chars (illegal specials).
031       /
032  @@    - Illegal (space).
033  @@!   C Comment.
034  @@"   S Parameter delimeter.
035  @@#   C Short name sequence.
036  @@$   S Start of macro definition.
037  @@%   - Illegal.
038  @@&   - Illegal.
039  @@'   - Illegal.
040  @@(   S Open parameter list.
041  @@)   S Close parameter list.
042  @@*   - Illegal.
043  @@+   C Insert newline.
044  @@,   S Parameter separator.
045  @@-   C Suppress end of line marker.
046  @@.   - Illegal.
047  @@/   S Open or close emphasised text.
048  @@0   - Illegal.
049  @@1   S Formal parameter 1.
050  @@2   S Formal parameter 2.
051  @@3   S Formal parameter 3.
052  @@4   S Formal parameter 4.
053  @@5   S Formal parameter 5.
054  @@6   S Formal parameter 6.
055  @@7   S Formal parameter 7.
056  @@8   S Formal parameter 8.
057  @@9   S Formal parameter 9.
058  @@:   - Illegal.
059  @@;   - Illegal.
060  @@<   S Open macro name.
061  @@=   C Set special character.
062  @@>   S Close macro name.
063  @@?   - Illegal. Reserved for future use.
064  @@@@   C Insert special character into text.
065  @@A   S New section (level 1).
066  @@B   S New section (level 2).
067  @@C   S New section (level 3).
068  @@D   S New section (level 4).
069  @@E   S New section (level 5).
070  @@F   - Illegal.
071  @@G   - Illegal.
072  @@H   - Illegal.
073  @@I   C Include file.
074  @@J   - Illegal.
075  @@K   - Illegal.
076  @@L   S Macro is library macro.
077  @@M   S Macro may be called many times.
078  @@N   - Illegal.
079  @@O   S Macro is attached to product file.
080  @@P   C Pragma.
081  @@Q   - Illegal.
082  @@R   - Illegal.
083  @@S   - Illegal.
084  @@T   C Typesetter directive.
085  @@U   - Illegal.
086  @@V   - Illegal.
087  @@W   - Illegal.
088  @@X   - Illegal.
089  @@Y   - Illegal.
090  @@Z   S Macro may be called zero times.
091  @@[   - Illegal. Reserved for future use.
092  @@\   - Illegal.
093  @@]   - Illegal. Reserved for future use.
094  @@^   C Insert control character into text
095  @@_   - Illegal.
096  @@`   - Illegal.
097  @@a   \
109  @@m    | Identical to @@A..@@Z.
122  @@z   /
123  @@{   S Open macro body/Open literal directive.
124  @@|   - Illegal.
125  @@}   S Close macro body/Close literal directive.
126  @@~   - Illegal.
127 to 255 - Illegal specials (as non-standard ASCII).
@<End verbatim@>

@<P@>The most important thing to remember about the scanner
is that @<I@>@(nothing happens unless the special character
is seen.@) There are no funny sequences that will cause
strange things to happen. The best way to view a FunnelWeb
document at the scanner level is as a body of text
punctuated by special sequences that serve to structure the
text at a higher level.

@<P@>The remaining description of the scanner consists of a
detailed description of the effect of each complex special
sequence.

@<Nav@>@(@<Scanner_basic FILE@>@,@<Scanner FILE@>@,@<Scanner_special_set FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_special_set HEADING@>@M@{@<SH@>@(3.3@)Setting the Special Character@}
@$@<Scanner_special_set FILE@>@M@{scanner_special_set.html@}
@O@<scanner_special_set.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_special_set HEADING@>@)

@<P@>The special character can be set using the sequence
@<<@>special@<>@>@<TT@>@(=@)@<<@>newspecialchar@<>@>. For example,
@<TT@>@(@@=#@) would change the special character to a hash
(@<TT@>@(#@)) character. The special character may be set
to any printable ASCII character except the blank character
(@<ie@>any character in the ASCII range [33,126]). In
normal use, it should not be necessary to change the special
character of FunnelWeb, and it is probably best to avoid
changing the special character so as not to confuse
FunnelWeb readers conditioned to the @<TT@>@(@@@) character.
However, the feature is very useful where the text being
prepared contains many @<TT@>@(@@@) characters (@<eg@>a list
of internet electronic mail addresses).

@<Nav@>@(@<Scanner_special FILE@>@,@<Scanner FILE@>@,@<Scanner_special_ins FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_special_ins HEADING@>@M@{@<SH@>@(3.4@)Inserting the Special Character into the Text@}
@$@<Scanner_special_ins FILE@>@M@{scanner_special_ins.html@}
@O@<scanner_special_ins.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_special_ins HEADING@>@)
@<XX@>@(special character@,inserting into text@)

@<P@>The special sequence @<<@>special@<>@>@<TT@>@(@@@) inserts
the special character into the text as if it were not
special at all. The @<TT@>@(@@@) of this sequence has nothing
to do with the current special character. If the current
special character is @<TT@>@(P@) then the sequence
@<TT@>@(P@@@) will insert a @<TT@>@(P@) into the text.
Example: @<TT@>@(@@@@#@@=#@@#@@#=@@@@@@@) translates to
@<TT@>@(@@#@@#@@@).

@<Nav@>@(@<Scanner_special_set FILE@>@,@<Scanner FILE@>@,@<Scanner_arbitrary FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_arbitrary HEADING@>@M@{@<SH@>@(3.5@)Inserting Arbitrary Characters into the Text@}
@$@<Scanner_arbitrary FILE@>@M@{scanner_arbitrary.html@}
@O@<scanner_arbitrary.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_arbitrary HEADING@>@)
@<XX@>@(arbitrary characters@,inserting into text@)
@<XX@>@(control characters@,inserting into text@)@<X@>@(@@circumflex@)

@<P@>While FunnelWeb does not tolerate unprintable
characters in the input file (except for the end of line
character), it does allow the user to specify that
unprintable characters appear in the product file. The
@<TT@>@(@@^@) sequence inserts a single
character of the user's choosing into the text. The
character can be specified by giving its ASCII number in one
of four bases: binary, octal, decimal, and hexadecimal. Here
is the syntax:

@<P@>
@<Begin verbatim@>
control_sequence = "@@^" char_spec
char_spec        = binary  | octal |
                   decimal | hexadecimal
binary           = ("b" | "B")
                   "(" {binary_digit}8  ")"
octal            = ("o" | "O" | "q" | "Q")
                   "(" {octal_digit}3   ")"
decimal          = ("d" | "D")
                   "(" {decimal_digit}3 ")"
hexadecimal      = ("h" | "H" | "x" | "X")
                   "(" {hex_digit}2     ")"
binary_digit     = "0" | "1"
octal_digit      = binary_digit | "2" | "3" |
                   "4" | "5" | "6" | "7"
decimal_digit    = octal_digit | "8" | "9"
hex_digit        = decimal_digit |
                   "A" | "B" | "C" | "D" | "E" | "F" |
                   "a" | "b" | "c" | "d" | "e" | "f"
@<End verbatim@>

@<P@>Example:

@<Begin verbatim@>
@@! Unix Make requires that productions
@@! commence with tab characters.
@@^D(009)prog.o <- prog.c
@<End verbatim@>

@<P@>Note that the decimal @<DQP@>@(9@) is expressed with
leading zeros as @<DQP@>@(009@). FunnelWeb requires a fixed
number of digits for each base. Eight digits for base two,
three digits for base ten, three digits for base eight and
two digits for base sixteen.

@<P@>FunnelWeb treats the character resulting from a
@<TT@>@(@@^@) sequence as ordinary text in every
sense. If your input file contains many instances of a
particular control character, you can package it up in a
macro like any other text. In particular, quick names can be
used to great effect:

@<P@>
@<Begin verbatim@>
@@! Unix "Make" requires that productions
@@! commence with tab characters.
@@! So we define a macro with a quick name
@@! as a tab character.
$@@#T@@{@@^D(009)@@}
@@! And use it in our productions.
@@#Tprog.o <- prog.c
@@#Ta.out <- prog.o
@<End verbatim@>

@<P@>Warning: If you insert a Unix@<X@>@(Unix newline@)
newline character (decimal 10) into the text, FunnelWeb will
treat this as an end of line sequence regardless of what the
character sequence for end of line is on the machine upon
which it is running. Unix EOL is FunnelWeb's internal
representation for end of line. Thus, in the current version
of FunnelWeb, inserting character 10 into the text is
impossible unless this also happens to be the character used
by the operating system to mark the end of line.

@<Nav@>@(@<Scanner_special_ins FILE@>@,@<Scanner FILE@>@,@<Scanner_comments FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_comments HEADING@>@M@{@<SH@>@(3.6@)Comments@}
@$@<Scanner_comments FILE@>@M@{scanner_comments.html@}
@O@<scanner_comments.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_comments HEADING@>@)
@<XX@>@(comments@,FunnelWeb@)

@<P@>When FunnelWeb encounters the @<TT@>@(@@!@)@<X@>@(@@!@)
sequence during its left-to-right scan of the line, it
throws away the rest of the line (including the EOL) without
analysing it further. Comments can appear in any line except
@<DQP@>@(@@i@), @<DQP@>@(@@t@), and @<DQP@>@(@@p@) lines.

@<P@>FunnelWeb comments can be used to insert comments into
your input file that will neither appear in the product
files nor in the documentation file, but will be solely for
the benefit of those reading and editing the input file
directly. Example:

@<P@>@<Begin verbatim@>
@@! I have used a quick macro for this definition
@@! as it will be used often.
@@$@@#C@@{--@@}
@<End verbatim@>

@<P@>Because comments are defined to include the end-of-line
marker, care must be taken when they are being added or
removed within the text of macro bodies. For example the
text fragment

@<P@>
@<Begin verbatim@>
for (i=0;i@<<@>MAXVAL;i++) @@! Print out a[0..MAXVAL-1].
   printf("%u\n",a[i]);
@<End verbatim@>

@<P@>will expand to

@<P@>
@<Begin verbatim@>
for (i=0;i@<<@>MAXVAL;i++) printf("%u\n",a[i]);
@<End verbatim@>

@<P@>This problem really has no solution; if FunnelWeb
comments were defined to omit the end of line marker, the
expanded text would contain trailing blanks! As it is,
FunnelWeb comments are designed to support single line
comments which can be inserted and removed as a line without
causing trouble. For example:

@<P@>
@<Begin verbatim@>
@@! Print out a[0..MAXVAL-1].
for (i=0;i@<<@>MAXVAL;i++)
   printf("%u\n",a[i]);
@<End verbatim@>

@<P@>If you want a comment construct that does not enclose
the end of line marker, combine the insert end of line
construct @<TT@>@(@@+@) with the comment construct
@<TT@>@(@@!@) as in

@<P@>
@<Begin verbatim@>
for (i=0;i@<<@>MAXVAL;i++)  @@+@@! Print out a[0..MAXVAL-1].
   printf("%u\n",a[i]);
@<End verbatim@>

@<P@>FunnelWeb comments should really only be used to
comment the FunnelWeb constructs being used in the input
file. Comments on the target code are best placed in
comments in the target language or in the documenting text
surrounding the macro definitions. In the example above, a C
comment would have been more appropriate.

@<Nav@>@(@<Scanner_arbitrary FILE@>@,@<Scanner FILE@>@,@<Scanner_quicknames FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_quicknames HEADING@>@M@{@<SH@>@(3.7@)Quick Names@}
@$@<Scanner_quicknames FILE@>@M@{scanner_quicknames.html@}
@O@<scanner_quicknames.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_quicknames HEADING@>@)
@<XX@>@(quick@,names@)

@<P@>FunnelWeb provides a @<NewTerm@>@(quick name@) syntax
as an alternative, for macros whose name consists of a
single character, to the angle bracket syntax usually used
(@<eg@>@<TT@>@(@@@<<@>Sloth@@@<>@>@)). A quick name sequence
consists of @<TT@>@(@@#@)x@<X@>@(@@hash@) where x, the name
of the macro, can be any printable character except space.

@<P@>@<Begin verbatim@>
quick_name = "@@#" non_space_printable
@<End verbatim@>

@<P@>The result is identical to the equivalent ordinary name
syntax, but is shorter. For example, @<TT@>@(@@#X@) is
equivalent to @<TT@>@(@@@<<@>X@@@<>@>@). This shorter way of
writing one-character macro names is more convenient where a
macro must be used very often. For example, the macro calls
in the following fragment of an Ada program are a little
clumsy.

@<P@>
@<Begin verbatim@>
@@! Define @@@<<@>D@@@<>@> as "" to turn on debug code
@@! and "--" to turn it off.
@@$@@@<<@>D@@>@@{--@@@@)
@@@<<@>D@@@<>@>assert(b>3);
@@@<<@>D@@@<>@>if x@<>@>7 then write("error") end if
@<End verbatim@>

@<P@>The calls can be shortened using the alternative syntax.

@<Begin verbatim@>
@@! Define @@#| as "" to turn on debug code
@@! and "--" to turn it off.
@@$@@#|@@{--@@@@)
@@#|assert(b@<>@>3);
@@#|if x@<>@>7 then write("error") end if
@<End verbatim@>

@<Nav@>@(@<Scanner_comments FILE@>@,@<Scanner FILE@>@,@<Scanner_eol_ins FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_eol_ins HEADING@>@M@{@<SH@>@(3.8@)Inserting End of Line Markers@}
@$@<Scanner_eol_ins FILE@>@M@{scanner_eol_ins.html@}
@O@<scanner_eol_ins.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_eol_ins HEADING@>@)
@<XX@>@(EOL markers@,inserting@)

@<P@>An end of line marker/character can be inserted into
the text using the @<TT@>@(@@+@)@<X@>@(@@+@) sequence. This
is exactly equivalent to a real end of line in the text at
the point where it occurs. While this feature may sound
rather useless, it is very useful for laying out the input
file. For example, the following input data for a database
program

@<P@>
@<Begin verbatim@>
Animal = Kangaroo
Size   = Medium
Speed  = Fast

Animal = Sloth
Size   = Medium
Speed  = Slow

Animal = Walrus
Size   = Big
Speed  = Medium
@<End verbatim@>

@<P@>can be converted into

@<P@>
@<Begin verbatim@>
Animal = Kangaroo @@+Size = Medium @@+Speed = Fast   @@+
Animal = Sloth    @@+Size = Medium @@+Speed = Slow   @@+
Animal = Walrus   @@+Size = Big    @@+Speed = Medium @@+
@<End verbatim@>

@<P@>which is easier to read, and more easily allows comparisons between
records.

@<Nav@>@(@<Scanner_quicknames FILE@>@,@<Scanner FILE@>@,@<Scanner_eol_supp FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_eol_supp HEADING@>@M@{@<SH@>@(3.9@)Suppressing End of Line Markers@}
@$@<Scanner_eol_supp FILE@>@M@{scanner_eol_supp.html@}
@O@<scanner_eol_supp.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_eol_supp HEADING@>@)
@<XX@>@(EOL markers@,suppressing@)

@<P@>End of line markers can be suppressed by the
@<TT@>@(@@-@)@<X@>@(@@-@) sequence. A single occurrence of a
@<TT@>@(@@-@) sequence serves to suppress only the end of
line marker following it and must appear @<I@>@(exactly@)
before the end of line marker to be suppressed. No trailing
spaces, @<TT@>@(@@!@) comments, or any other characters are
permitted between a @<TT@>@(@@-@) sequence and the end of
line that it is supposed to suppress. The @<TT@>@(@@-@)
sequence is useful for constructing long output lines
without them having to appear in the input. It can also be
used in the same way as the @<TT@>@(@@+@) was used in the
previous section to assist in exposing the structure of
output text without affecting the output text itself.
Finally, it is invaluable for suppressing the EOL after the
opening macro text @<TT@>@(@@{@) construct. For example:

@<P@>
@<Begin verbatim@>
@@$@@@<<@>Walrus@@@<>@>@@{@@-
I am the walrus!@@}
@<End verbatim@>

@<P@>is equivalent to

@<P@>
@<Begin verbatim@>
@@$@@@<<@>Walrus@@@<>@>@@{I am the walrus!@@}
@<End verbatim@>

@<P@>The comment construct (@<TT@>@(@@!@)) can also be used
to suppress end of lines. However, the @<TT@>@(@@-@)
construct should be preferred for this purpose as it makes
explicit the programmer's intent to suppress the end of
line.

@<Nav@>@(@<Scanner_eol_ins FILE@>@,@<Scanner FILE@>@,@<Scanner_include FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_include HEADING@>@M@{@<SH@>@(3.10@)Include Files@}
@$@<Scanner_include FILE@>@M@{scanner_include.html@}
@O@<scanner_include.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_include HEADING@>@)
@<XX@>@(include@,files@)

@<P@>FunnelWeb provides an include file facility with a
maximum depth of 10. When FunnelWeb sees a line of the form
@<TT@>@(@@i @<<@>filename@<>@>@),@<X@>@(@@i@) it replaces the entire
line (including the EOL) with the contents of the specified
include file. FunnelWeb's include file facility is intended
to operate at the line level. If the last line of the
include file is not terminated by an EOL, FunnelWeb issues a
warning and inserts one (in the copy in memory).

@<P@>The
@<TT@>@(@@i@) construct is illegal if it appears anywhere except
at the start of a line.
The construct must be followed by a single blank. The file
name is defined to be everything
between the blank and the end of the line (no
comments (@<TT@>@(@@!@)) please!). Example: If the input file is

@<P@>
@<Begin verbatim@>
"Uh Oh, It's the Fuzz. We're busted!" said Baby Bear.
@@i mr_plod.txt
"Quick! Flush the stash down the dunny and split."
   said Father Bear.
@<End verbatim@>

@<P@>and there is a file called @<TT@>@(mr_plod.txt@) containing

@<P@>
@<Begin verbatim@>
"'Ello, 'Ello, 'Ello! What's all this 'ere then?"
   Mr Plod exclaimed.
@<End verbatim@>

@<P@>then the scanner translates the input file into

@<P@>
@<Begin verbatim@>
"Uh Oh, It's the Fuzz. We're busted!" said Baby Bear.
"'Ello, 'Ello, 'Ello! What's all this 'ere then?"
   Mr Plod exclaimed.
"Quick! Flush the stash down the dunny and split."
   said Father Bear.
@<End verbatim@>

@<P@>As a point of terminology, FunnelWeb calls the original
input file the @<NewTerm@>@(input file@) and calls include
files and their included files @<NewTerm@>@(include files@).

@<P@>The include file construct operates at a very low
level. An include line can appear anywhere in the input file
regardless of the context of the surrounding lines.

@<P@>FunnelWeb sets the special character to the default
(@<TT@>@(@@@)) at the start of each include file and restores
it to its previous value at the end of the include file.
This allows macro libraries to be constructed and included
that are independent of the prevailing special character at
the point of inclusion. The same goes for the input line
length limit which is reset to the default value at the
start of each include file and restored to its previous
value afterwards.

@<Nav@>@(@<Scanner_eol_supp FILE@>@,@<Scanner FILE@>@,@<Scanner_prag FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_prag HEADING@>@M@{@<SH@>@(3.11@)Pragmas@}
@$@<Scanner_prag FILE@>@M@{scanner_prag.html@}
@O@<scanner_prag.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_prag HEADING@>@)
@<X@>@(pragmas@)@<XX@>@(pragmas@,visible@)@<XX@>@(pragmas@,invisible@)

@<P@>Most tools have to support some essential, but rather
inelegant features. In FunnelWeb these messy bits have all
been stuffed into the scanner's @<NewTerm@>@(pragma@) (for
@<I@>@(pragma@)tic) construct.

@<P@>A pragma consists of a single line of input (including
the EOL) commencing with @<TT@>@(@@p@). This must be followed
by a single space, and then the pragma verb. This must be
followed by a sequence of zero or more arguments separated
by one or more spaces. Four pragmas are available

@<P@>
@<Begin verbatim@>
pragma = pragma_ident | pragma_mill |
         pragma_moll | pragma_typesetter
@<End verbatim@>
The following syntax definitions assist in defining the pragmas.

@<P@>
@<Begin verbatim@>
s        = {" "}+
ps       = ("@@p" | "@@P") " "
number   = { decimal_digit }+
numorinf = number | "infinity"
@<End verbatim@>

@<P@>The arguments to pragmas are case-sensitive and must be
specified in lower case.

@<P@>Pragmas are processed and consumed entirely by the
scanner. The parser never sees them and so they can play no
part in the parser level syntax. As a result, pragma lines
can appear anywhere in the entire input file regardless of
the surrounding context (@<eg@>even in the middle of a macro
definition). The sole effect of a pragma is to modify some
internal parameter of FunnelWeb.

@<P@>The following sections describe the four FunnelWeb pragmas.

@<Nav@>@(@<Scanner_include FILE@>@,@<Scanner FILE@>@,@<Scanner_prag_ind FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_prag_ind HEADING@>@M@{@<SH@>@(3.12@)Pragma: Indentation@}
@$@<Scanner_prag_ind FILE@>@M@{scanner_prag_ind.html@}
@O@<scanner_prag_ind.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_prag_ind HEADING@>@)
@<XX@>@(indentation@,macro expansion@)

@<P@>When FunnelWeb expands a macro, it can do so in two
ways. First it can treat the text it is processing as a
one-dimensional stream of text, and merely insert the body
of the macro in place of the macro call. Second, it can
treat the text of the macro as a two dimensional object and
indent each line of the macro body by the amount that the
macro call itself was indented. Consider the following
macros.

@<P@>
@<Begin verbatim@>
@@$@@@<<@>Loop Structure@@@<>@>@@{@@-
i=1;
while (i@<<@>=N)
   @@@<<@>Loop body@@@<>@>
endwhile
@@}

@@$@@@<<@>Loop body@@@<>@>@@{@@-
a[i]:=0;
i:=i+1;@@}
@<End verbatim@>

@<P@>Under the regime of @<NewTerm@>@(no
indentation@)@<XX@>@(indentation@,none@) the loop structure
macro expands to:

@<P@>
@<Begin verbatim@>
i=1;
while (i@<<@>=N)
   a[i]:=0;
i:=i+1;
endwhile
@<End verbatim@>

@<P@>Under the regime of @<NewTerm@>@(blank
indentation@)@<XX@>@(indentation@,blank@) the loop structure
macro expands to:

@<P@>
@<Begin verbatim@>
i=1;
while (i@<<@>=N)
   a[i]:=0;
   i:=i+1;
endwhile
@<End verbatim@>

@<P@>The @<TT@>@(indentation@) pragma determines which of
these two regimes will be used to expand the macros when
constructing the product files. The syntax of the pragma is:

@<P@>
@<Begin verbatim@>
pragma_ident = ps "indentation" s "=" s
               ("blank" | "none")
@<End verbatim@>

@<P@>Its two forms look like this:

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

@<P@>In the current version of FunnelWeb, the indentation
regime is an attribute that is attached to an entire run of
Tangle; it is not possible to bind it to particular product
files or to particular macros. As a result, it doesn't
matter where indentation pragmas occur in the input file or
how many there are so long as they are all the same. By
default FunnelWeb uses blank indentation.

@<Nav@>@(@<Scanner_prag FILE@>@,@<Scanner FILE@>@,@<Scanner_prag_maxin FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_prag_maxin HEADING@>@M@{@<SH@>@(3.13@)Pragma: Maximum Input Line Length@}
@$@<Scanner_prag_maxin FILE@>@M@{scanner_prag_maxin.html@}
@O@<scanner_prag_maxin.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_prag_maxin HEADING@>@)
@<XX@>@(input@,line length@)@<XX@>@(maximum@,input line length@)

@<P@>FunnelWeb generates an error for each input line that
exceeds a certain maximum number of characters. At the start
of the processing of each input file and each include file,
this maximum is set to a default value of 80. However, the
maximum can be changed using a maximum input line length
pragma.@<XX@>@(pragma@,input line length@)

@<P@>
@<Begin verbatim@>
pragma_mill = ps "maximum_input_line_length" s
              "=" s numorinf
@<End verbatim@>

@<P@>The maximum input line length can be varied
@<I@>@(dynamically@) throughout the input file. Each maximum
input line length pragma's scope covers the line following
the pragma through to and including the next maximum input
line length pragma, but not covering any intervening include
files. At the start of  an include file, FunnelWeb resets
the maximum input line length to the default value. It
restores it to its previous value at the end of the include
file.

@<P@>This pragma is useful for detecting text that has
strayed off the right side of the screen when editing. If
you use FunnelWeb, and set the maximum input line length to
be the width of your editing window, you will never be
caught by, for example, off-screen opening comment symbols.
You can also be sure that your source text can be printed
raw, if necessary, without lines wrapping around.

@<Nav@>@(@<Scanner_prag_ind FILE@>@,@<Scanner FILE@>@,@<Scanner_prag_maxout FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_prag_maxout HEADING@>@M@{@<SH@>@(3.14@)Pragma: Maximum Output File Line Length@}
@$@<Scanner_prag_maxout FILE@>@M@{scanner_prag_maxout.html@}
@O@<scanner_prag_maxout.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_prag_maxout HEADING@>@)
@<XX@>@(maximum@,product file line length@)
@<XX@>@(pragma@,maximum product file line length@)
@<XX@>@(maximum@,output file line length@)
@<XX@>@(pragma@,maximum output file line length@)

@<P@>As well as keeping an eye on input line lengths,
FunnelWeb also keeps an eye on the line lengths of product
files and flags all lines longer than a certain limit with
error messages. Unlike the maximum input line length, which
can vary dynamically throughout the input file, the maximum
product file line length remains fixed throughout the
generation of all the product files. The maximum product
file line length pragma allows this value to be set. If
there is more than one such pragma in an input file, the
pragmas must all specify the same value.

@<P@>
@<Begin verbatim@>
pragma_moll = ps "maximum_output_line_length"
              s "=" s numorinf
@<End verbatim@>

@<P@>The default value is 80 characters.

@<P@>This pragma is only one of two constraints on the
length of the lines of the product files. The @<TT@>@(+W@)
command line option also contributes. The actual value that
FunnelWeb uses is the minimum of the limits specified in the
command line and pragmas.

@<P@>FunnelWeb does not monitor the length of the lines of
its other output files (journal file, listing file,
documentation file).

@<Nav@>@(@<Scanner_prag_maxin FILE@>@,@<Scanner FILE@>@,@<Scanner_prag_type FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_prag_type HEADING@>@M@{@<SH@>@(3.15@)Pragma: Typesetter@}
@$@<Scanner_prag_type FILE@>@M@{scanner_prag_type.html@}
@O@<scanner_prag_type.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_prag_type HEADING@>@)
@<XX@>@(typesetter@,pragma@)@<XX@>@(typesetter@,independence@)

@<P@>The @<TT@>@(typesetter@) pragma allows the user to
specify whether the input file is supposed to be
typesetter-independent, or whether it contains commands in a
particular typesetter language. The pragma has the following
syntax.

@<P@>
@<Begin verbatim@>
pragma_typesetter = ps "typesetter" s "="
                    s ("none" | "tex" | "html")
@<End verbatim@>

@<P@>The three forms of the pragma look like this.

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

@<P@>A source file can contain more than one typesetter
pragma, but they must all specify the same value. The
default is @<TT@>@(none@). The typesetter setting affects
two things:

@<NarrowThing@>@(Handling of free text:@,If the typesetter
is not @<TT@>@(none@), Weave writes the free text
@<I@>@(directly@) to the documentation file without changing
it whatsoever. This means that if (say) @<TT@>@(\centerline@)
appears in the input file, it will copied
directly to the documentation file. If the typesetter is
@<TT@>@(none@), Weave intercepts any characters or sequences
that might have a special meaning to the target typesetter
and replaces them with typesetter commands to typeset the
sequences so that they will appear as they do in the input.
For example, if the typesetter is @<TT@>@(none@) and the
target typesetter is TeX, then if @<TT@>@($@) (the TeX
@<DQ@>@(mathematics mode@) character) appears in the input
file, it will be be written to the documentation file as
@<TT@>@(\$@).@)

@<NarrowThing@>@(Restrictions on the target typesetter:@,
If you make your FunnelWeb input file depedent on one
particular typesetter, it's important that no attempt be
made to generate documentation for a different target format.
FunnelWeb enforces this at the Weave stage.@)

@<P@>The aim of all this is to ensure that any typesetter
dependency is correctly proclaimed. Because @<TT@>@(none@)
is the default typesetter, a user who creates a source file
without a @<TT@>@(typesetter = x@) pragma will soon find
that the control sequences they are inserting into the
source document are appearing verbatim in the printed
documentation! In order to activate these sequences, they
will be forced to add a @<TT@>@(typesetter@) pragma, thus
making the dependency explicit.

@<P@>It may seem strange to place the @<TT@>@(typesetter@)
setting facility within a pragma (@<TT@>@(@@p@)) when there
is a separate typesetting construct (@<TT@>@(@@t@)). This has
been done to sustain the rule of thumb that says that
pragmas do not participate in the parser-level syntax, but
typesetter directives do.

@<Nav@>@(@<Scanner_prag_maxout FILE@>@,@<Scanner FILE@>@,@<Scanner_type FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_type HEADING@>@M@{@<SH@>@(3.16@)Freestanding Typesetter Directives@}
@$@<Scanner_type FILE@>@M@{scanner_type.html@}
@O@<scanner_type.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_type HEADING@>@)
@<XX@>@(typesetter@,directives@)

@<P@>FunnelWeb provides two kinds of typesetter directive to
assist the user to produce documentation. These are
@<NewTerm@>@(inline@) and @<NewTerm@>@(freestanding@).
Unlike pragmas, each of these categories of directive
participates in the parser-level syntax and can appear only
in certain contexts (see the parser section). Inline
directives are designed to be used within paragraphs to
alter the look of the enclosed text. Freestanding typesetter
directives are designed to appear on lines of their own and
have a bigger typographical impact.

@<P@>The syntax of freestanding typesetter directives is
almost identical to that of pragmas. All the same syntax
rules apply (except that the actual keywords are different).
The following subsections describe the four typesetter
directives available.

@<P@>
@<Begin verbatim@>
ftd = ftd_newpage | ftd_toc | ftd_vskip | ftd_title
ts  = "@@t "
@<End verbatim@>

@<Nav@>@(@<Scanner_prag_type FILE@>@,@<Scanner FILE@>@,@<Scanner_type_newpage FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_type_newpage HEADING@>@M@{@<SH@>@(3.17@)New Page Directives@}
@$@<Scanner_type_newpage FILE@>@M@{scanner_type_newpage.html@}
@O@<scanner_type_newpage.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_type_newpage HEADING@>@)
@<X@>@(new page@)@<XX@>@(pragma@,new page@)

@<P@>The new page pragma is a typesetting pragma with the
following syntax.

@<Begin verbatim@>
ftd_newpage = ts "new_page"
@<End verbatim@>

@<P@>It only form looks like this.

@<Begin verbatim@>
@@t new_page
@<End verbatim@>

@<P@>Its sole effect is to cause a @<DQ@>@(skip to a new
page@) command to be inserted into the documentation file.
The new page command is such that if the typesetter is
already at the top of a page, it will skip to the top of the
next page.

@<Nav@>@(@<Scanner_type FILE@>@,@<Scanner FILE@>@,@<Scanner_type_contents FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_type_contents HEADING@>@M@{@<SH@>@(3.18@)Table of Contents@}
@$@<Scanner_type_contents FILE@>@M@{scanner_type_contents.html@}
@O@<scanner_type_contents.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_type_contents HEADING@>@)
@<XX@>@(table of@,contents@)@<XX@>@(pragma@,table of contents@)

@<P@>The table of contents pragma is a typesetting pragma
with the following syntax.

@<P@>
@<Begin verbatim@>
ftd_toc = ts "table_of_contents"
@<End verbatim@>

@<P@>It only form looks like this.

@<P@>
@<Begin verbatim@>
@@t table_of_contents
@<End verbatim@>

@<P@>Its sole effect is to instruct Weave to insert a table
of contents at this point in the printed documentation. This
pragma does not skip to a top of a new page first.

@<Nav@>@(@<Scanner_type_newpage FILE@>@,@<Scanner FILE@>@,@<Scanner_type_vskip FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_type_vskip HEADING@>@M@{@<SH@>@(3.19@)Vertical Skip@}
@$@<Scanner_type_vskip FILE@>@M@{scanner_type_vskip.html@}
@O@<scanner_type_vskip.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_type_vskip HEADING@>@)
@<XX@>@(vertical@,skip@)@<XX@>@(pragma@,vskip@)

@<P@>The vertical skip pragma is a typesetting pragma that
instructs Weave to insert a specified amount of vertical
space into the documentation. The pragma has the following
syntax.

@<P@>
@<Begin verbatim@>
ftd_vskip = ts "vskip" s number s "mm"
@<End verbatim@>

@<P@>For example:

@<P@>
@<Begin verbatim@>
@@t vskip 26 mm
@<End verbatim@>

@<Nav@>@(@<Scanner_type_contents FILE@>@,@<Scanner FILE@>@,@<Scanner_type_title FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_type_title HEADING@>@M@{@<SH@>@(3.20@)Title@}
@$@<Scanner_type_title FILE@>@M@{scanner_type_title.html@}
@O@<scanner_type_title.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_type_title HEADING@>@)
@<X@>@(title@)@<XX@>@(pragma@,title@)

@<P@>The title pragma is a typesetting pragma with the following syntax.

@<P@>
@<Begin verbatim@>
ftd_title = ts "title" s font s alignment text
font      = "normalfont" | "titlefont" |
            "smalltitlefont"
alignment = "left" | "centre" | "right"
text      = """" { printable_char } """"
@<End verbatim@>

@<P@>It's effect is to instruct Weave to insert a single
line into the printed documentation containing the specified
text set in the specified font and aligned in the specified
manner. The double quotes delimiting the text are for show
only; if you want to put a double quote in the string, you
don't need to double them.

@<P@>Here is an example of the pragma.

@<P@>
@<Begin verbatim@>
@@t title smalltitlefont centre "How to Flip a Bit"
@<End verbatim@>

@<Nav@>@(@<Scanner_type_vskip FILE@>@,@<Scanner FILE@>@,@<Scanner_parser FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Scanner_parser HEADING@>@M@{@<SH@>@(3.21@)Scanner/Parser Interface@}
@$@<Scanner_parser FILE@>@M@{scanner_parser.html@}
@O@<scanner_parser.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Scanner_parser HEADING@>@)
@<X@>@(title@)@<XX@>@(pragma@,title@)

@<P@>If the scanner terminates without any errors, control
is passed to the parser. The parser parses the token list
generated by the scanner. The token list consists of text
scraps, freestanding typesetter directives, and special
sequence tokens.

@<P@>The user should bear in mind that @<I@>@(the scanner
finishes running before the parser starts running.@) This
means that the scanner cannot be influenced in any way by
higher order structures such as the parser might parse. For
example, it is impossible to write a FunnelWeb macro to
include a file, or to write a macro that inserts a
@<TT@>@(vskip@) pragma into the input text.

@<Nav/last@>@(@<Scanner_type_title FILE@>@,@<Scanner FILE@>@,@<Scanner FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Parser HEADING@>@M@{@<SH@>@(4@)Parser@}
@$@<Parser HEADING/short@>@M@{@<SH@>@(4@)Parser@}
@$@<Parser FILE@>@M@{parser.html@}
@O@<parser.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Parser HEADING@>@)

@<P@>
@<Parser index@>

@<Nav@>@(@<Scanner FILE@>@,@<Index FILE@>@,@<Analyser FILE@>@)

@<End FWRefMan page@>
@}

@$@<Parser index@>@M@{
@<Begin size3@>
@<Begin indent/narrow@>
@<Link@>@(@<Parser_introduction FILE@>@,@<Parser_introduction HEADING@>@)@<BR@>
@<Link@>@(@<Parser_structure FILE@>@,@<Parser_structure HEADING@>@)@<BR@>
@<Link@>@(@<Parser_freetext FILE@>@,@<Parser_freetext HEADING@>@)@<BR@>
@<Link@>@(@<Parser_type FILE@>@,@<Parser_type HEADING@>@)@<BR@>
@<Link@>@(@<Parser_type_section FILE@>@,@<Parser_type_section HEADING@>@)@<BR@>
@<Link@>@(@<Parser_type_literal FILE@>@,@<Parser_type_literal HEADING@>@)@<BR@>
@<Link@>@(@<Parser_type_emphasis FILE@>@,@<Parser_type_emphasis HEADING@>@)@<BR@>
@<Link@>@(@<Parser_macros FILE@>@,@<Parser_macros HEADING@>@)@<BR@>
@<Link@>@(@<Parser_macros_name FILE@>@,@<Parser_macros_name HEADING@>@)@<BR@>
@<Link@>@(@<Parser_macros_params FILE@>@,@<Parser_macros_params HEADING@>@)@<BR@>
@<Link@>@(@<Parser_expressions FILE@>@,@<Parser_expressions HEADING@>@)@<BR@>
@<Link@>@(@<Parser_macro_calls FILE@>@,@<Parser_macro_calls HEADING@>@)@<BR@>
@<Link@>@(@<Parser_parameters FILE@>@,@<Parser_parameters HEADING@>@)@<BR@>
@<Link@>@(@<Parser_static FILE@>@,@<Parser_static HEADING@>@)@<BR@>
@<End indent/narrow@>
@<End size3@>
@}

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

@$@<Parser_introduction HEADING@>@M@{@<SH@>@(4.1@)Introduction@}
@$@<Parser_introduction FILE@>@M@{parser_introduction.html@}
@O@<parser_introduction.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Parser_introduction HEADING@>@)

@<P@>By the time the parser starts, the scanner has
completely terminated. At this point, it is not possible for
any more files  to be included, and special characters are
no longer present  to confuse things.  All that remains is a
list of @<NewTerm@>@(text tokens@), @<NewTerm@>@(special
tokens@), and @<NewTerm@>@(typesetter directive tokens@).
Text  tokens consist  entirely of sequences of  printable
characters and end  of line markers. Special tokens
represent the special sequences that the scanner found in
the input file. Typesetter directive tokens represent the
freestanding typesetter directives that the scanner
encountered. The parser consumes the token list and builds a
macro table that is later used to generate product files. It
also constructs a document list that is used to generate the
documentation file.

@<P@>The syntax rules appearing in the following sections
refer to the token list.

@<Nav/first@>@(@<Parser FILE@>@,@<Parser FILE@>@,@<Parser_structure FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Parser_structure HEADING@>@M@{@<SH@>@(4.2@)High Level Structure@}
@$@<Parser_structure FILE@>@M@{parser_structure.html@}
@O@<parser_structure.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Parser_structure HEADING@>@)
@<XX@>@(syntax@,high level@)

@<P@>At the highest level, the FunnelWeb parser parses the
input file (token list) into a sequence of text scraps,
macro definitions, and typesetter directives.

@<P@>
@<Begin verbatim@>
input_file = { text | macro | directive }
@<End verbatim@>

@<P@>All three of these kinds of components contribute to
the documentation file, but only macro definitions
contribute to the product files. If all the free text and
directives were removed from a FunnelWeb input file, the
product files would not be affected.

@<Nav@>@(@<Parser_introduction FILE@>@,@<Parser FILE@>@,@<Parser_freetext FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Parser_freetext HEADING@>@M@{@<SH@>@(4.3@)Free Text@}
@$@<Parser_freetext FILE@>@M@{parser_freetext.html@}
@O@<parser_freetext.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Parser_freetext HEADING@>@)
@<XX@>@(free@,text@)

@<P@>@<NewTerm@>@(Free text@) is any text that is not part
of a macro definition or a directive. A scrap of free text
consists of a sequence of items drawn from the following
list: non-special printable characters, insert-eol special
sequences, insert special character special sequences,
insert arbitrary character special sequence.

@<P@>
@<Begin verbatim@>
free_text      = ordinary_text
ordinary_text  = { ordinary_char | eol | text_special }+
text_special   = "@@+" | "@@@@" | "@@^" char_spec
ordinary_char  = " ".."~" - special
@<End verbatim@>

@<P@>An example of some rather messy free text is as
follows:

@<Begin verbatim@>
This@@@@ is a very@@+ messy
@@^D(009)chunk of text indeed.
But FunnelWeb still views it as
a single chunk of text.
@<End verbatim@>

@<P@>FunnelWeb never sees two text chunks next to each other
in the input; they are always merged into a single text
token.

@<P@>The free text in an input file does not affect the
product files. However, by default, it appears in the
printed documentation exactly as it is given in the input
file, except that it is filled and justified into
paragraphs.

@<P@>Any printable character or particular sequence of
characters may appear in the free text of a document.
FunnelWeb ensures that they will appear exactly as given in
the input file, even if they happen to be escape characters
or commands in the target typesetter. However, FunnelWeb
also provides a special mode that allows this censoring to
be overridden.

@<Nav@>@(@<Parser_structure FILE@>@,@<Parser FILE@>@,@<Parser_type FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Parser_type HEADING@>@M@{@<SH@>@(4.4@)Typesetter Directives@}
@$@<Parser_type FILE@>@M@{parser_type.html@}
@O@<parser_type.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Parser_type HEADING@>@)

@<P@>FunnelWeb provides a variety of typesetter directives
to assist the user to typeset the document in a
typesetter-independent way. These are divided into
@<NewTerm@>@(freestanding typesetter directives@) (ftd) and
@<NewTerm@>@(inline typesetter directives@) (itd). The
internal syntax of the freestanding typesetter directives
has already been discussed in the scanner section. The
following syntax rule defines the context in which these
constructs can appear.

@<P@>
@<Begin verbatim@>
directive = ftd | itd
itd       = section | literal | emphasis
@<End verbatim@>

@<P@>The remainder of this section describes the inline
typesetter directives.

@<Nav@>@(@<Parser_freetext FILE@>@,@<Parser FILE@>@,@<Parser_type_section FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Parser_type_section HEADING@>@M@{@<SH@>@(4.5@)Section Directive@}
@$@<Parser_type_section FILE@>@M@{parser_type_section.html@}
@O@<parser_type_section.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Parser_type_section HEADING@>@)
@<XX@>@(section@,constructs@)

@<P@>The section directive provides a way for the user to
structure the program and documentation into a hierarchical
tree structure,@<XX@>@(tree@,structure@) just as in most
large documents. A section construct consists of a
case-insensitive identifying letter, which determines the
absolute level of the section in the document, and an
optional section name, which has exactly the same syntax as
a macro name.

@<P@>
@<Begin verbatim@>
section   = "@@" levelchar [name]
levelchar = "A" | "B" | "C" | "D" | "E" |
            "a" | "b" | "c" | "d" | "e"
@<End verbatim@>

@<P@>The section construct is not quite @<DQ@>@(inline@), as
it must appear only at the start of a line. However, unlike
the @<DQP@>@(@@i@), @<DQP@>@(@@p@), and @<DQP@>@(@@t@)
constructs, it does not consume the remainder of the line
(although it would be silly to place anything on the same
line anyway).

@<P@>FunnelWeb provides five levels of sections, ranging
from the highest level of @<TT@>@(A@) (like a
LaTeX@<X@>@(LaTeX@) chapter) to the lowest level of
@<TT@>@(E@) (like a LaTeX subsubsubsection). FunnelWeb
input files need not contain any sections at all, but if
they do, the first section must be at level @<TT@>@(A@), and
following sections must not skip hierarchical levels
(@<eg@>an @<TT@>@(@@E@) cannot follow an @<TT@>@(@@C@)).
FunnelWeb generates an error if a level is skipped.

@<P@>All section @<I@>@(must@) have names associated with
them, but for convenience, the section name is optional if
the section contains one or more macro definitions (@<ie@>at
least one macro definition appears between the section
construct in question and the next section construct in the
input file.). In this case, the section @<I@>@(inherits@)
the name of the first macro defined in the section. This
feature streamlines the input file, avoiding duplicate name
inconsistencies.

@<P@>Any sequence of printable characters can be used in the
section name,@<XX@>@(section@,name@) even the target
typesetter's escape sequence (@<eg@>in TeX,
@<DQP@>@(\@)).

@<P@>The following example demonstrates the section
construct.

@<P@>
@<Begin verbatim@>
@@A@@@<<@>Life Simulation@@@<>@>

This is the main simulation module for planet
earth, simulated down to the molecular level. This
is a REALLY big program. I mean really big. I
mean, if you thought the X-Windows source code was
big, you're in for a shock...

@@B We start by looking at the code for six legged
stick insects as they form a good example of a
typical object-oriented animal implementation.

@@$@@@<<@>Six Legged Stick Insects@@@<>@>@@{@@-
slsi.creep; slsi.crawl; slsi.creep;@@}
@<End verbatim@>

@<P@>In the above example, the name for the level A
section is provided explicitly, while the name for
the level B section will be inherited from the
macro name.

@<Nav@>@(@<Parser_type FILE@>@,@<Parser FILE@>@,@<Parser_type_literal FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Parser_type_literal HEADING@>@M@{@<SH@>@(4.6@)Literal Directive@}
@$@<Parser_type_literal FILE@>@M@{parser_type_literal.html@}
@O@<parser_type_literal.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Parser_type_literal HEADING@>@)
@<XX@>@(literal@,directive@)

@<P@>Experience has shown that one of the most common
typesetting requirements is that of being able to typeset
small program fragments in the middle of the documenting
free text. Typically there is a frequent need to refer to
program identifiers, and it assists the reader to have such
identifiers typeset in the same manner as the program text
in the macro definition.

@<P@>To specify that some text be typeset in @<TT@>@(tt
font@), enclose the text in curly brace special sequences as
follows.

@<P@>
@<Begin verbatim@>
literal = "@@{" ordinary_text "@@}"
@<End verbatim@>

@<P@>As in macro names, section names, and macro bodies, the
text contained within the literal construct is protected by
FunnelWeb from any non-literal interpretation by the
typesetter and the user is free to enclose @<I@>@(any@) text
covered by the definition @<TT@>@(ordinary_text@).
FunnelWeb guarantees that, no matter what the text is, it
will be typeset in @<TT@>@(tt font@) exactly as it appears.
However, the text will be filled and justified into a
paragraph as usual.

@<P@>Here is an example of the use of the construct:

@<P@>
@<Begin verbatim@>
@@C The @@{WOMBAT@@} (Waste Of Money, Brains, And
Time) function calls the @@{kangaroo@@} input
function which has been known to cause keybounce.
This keybounce can be dampened using the
@@{wet_sloth@@} subsystem.
@<End verbatim@>

@<Nav@>@(@<Parser_type_section FILE@>@,@<Parser FILE@>@,@<Parser_type_emphasis FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Parser_type_emphasis HEADING@>@M@{@<SH@>@(4.7@)Emphasis Directive@}
@$@<Parser_type_emphasis FILE@>@M@{parser_type_emphasis.html@}
@O@<parser_type_emphasis.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Parser_type_emphasis HEADING@>@)
@<XX@>@(emphasis@,directive@)

@<P@>The emphasis directive is very similar to the literal
directive except that it causes its argument to be typeset
in an emphasised manner (@<eg@>italics). Like the literal
directive, the emphasis directive protects its text
argument.

@<P@>
@<Begin verbatim@>
emphasise = "@@/" ordinary_text "@@/"
@<End verbatim@>

@<P@>Example:

@<P@>
@<Begin verbatim@>
@@C What you @@/really@@/ need, of course, is a
@@/great@@/, @@/big@@/, network with packets just
flying @@/everywhere@@/. This section implements an
interface to such a @@/humungeous@@/ network.
@<End verbatim@>

@<Nav@>@(@<Parser_type_literal FILE@>@,@<Parser FILE@>@,@<Parser_macros FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Parser_macros HEADING@>@M@{@<SH@>@(4.8@)Macros@}
@$@<Parser_macros FILE@>@M@{parser_macros.html@}
@O@<parser_macros.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Parser_macros HEADING@>@)

@<P@>The third category of construct appearing at the
highest syntactic level in a FunnelWeb input file is the
macro definition. A macro definition binds a unique
@<NewTerm@>@(macro name@) to a @<NewTerm@>@(macro body@)
containing an @<NewTerm@>@(expression@) consisting of text,
calls to other macros, and formal parameters. The syntax for
a macro definition is as follows:

@<P@>
@<Begin verbatim@>
macro = ("@@O" | "@@$") name [formal_parameter_list]
        ["@@Z"] ["@@M"] { "@@L" } ["==" | "+="]
        "@@{" expression "@@}"
@<End verbatim@>

@<P@>The complexity of the macro definition syntax is mostly
to enable the user to attach various attributes to the
macro.@<XX@>@(macro@,attributes@) If the user chooses
@<TT@>@(@@O@), then the macro cannot be called, but is
instead attached to a product file. If the user chooses
@<TT@>@(@@$@), then the macro is an ordinary macro definition
that is not attached to a file. Here are some example macro
definitions.

@<P@>
@<Begin verbatim@>
@@O@@@<<@>example.txt@@@<>@>@@{This is an @@@<<@>ugly duckling@@@<>@>.@@}

@@$@@@<<@>ugly duckling@@@<>@>@@M@@{swan@@}
@<End verbatim@>

@<FWRefMan subheading@>@(Number Of Invocations Constraint@)

@<P@>By default, a non-file macro must be invoked exactly
once by one other macro. Macros that aren't are flagged with
errors by the FunnelWeb analyser. However, if the user uses
the @<TT@>@(@@Z@)@<X@>@(@@Z@) sequence in the macro
definition, the macro is then permitted to be invoked zero
times, as well as once. Similarly, if the user uses the
@<TT@>@(@@M@)@<X@>@(@@M@) sequence in the macro definition,
the macro is permitted to be called many times as well as
once. If both @<TT@>@(@@Z@) and @<TT@>@(@@M@) are present then
the macro is permitted to be invoked zero, one, or many
times.

@<P@>The purpose of enforcing the default @<DQ@>@(exactly
one call@) rule is to flag pieces of code that the user may
have defined in a macro but not hooked into the rest of the
program. Experience shows that this is a common error.
Similarly, it can be dangerous to multiply invoke a macro
intended to be invoked only once. For example, it may be
dangerous to invoke a scrap of non-idempotent initialization
code in two different parts of the main function of a
program! However, FunnelWeb will not generate an error if a
macro without @<TT@>@(@@M@) is called by another macro that
is called more than once.

@<FWRefMan subheading@>@(Additive Macros@)

@<P@>If the text string @<TT@>@(==@)@<X@>@(==@) (or nothing)
follows the macro name, the  expression that follows is the
entire text  of the macro body. If the  text string
@<TT@>@(+=@)@<X@>@(+=@) follows the macro name,  then more
than one  such definition is allowed (but not required) in
the document and  the body of the macro consists of the
concatenation of all such expressions in the order in which
they occur in the input file. Such a macro is said to be
additive and is @<NewTerm@>@(additively defined@). Thus a
macro body  can either be defined in one place using one
definition (using  @<TT@>@(==@)) or it can be
@<I@>@(distributed@) throughout the input file in a sequence
of one or more macro definitions (using @<TT@>@(+=@)). If
neither @<TT@>@(==@) and @<TT@>@(+=@) are present, FunnelWeb
assumes a default of @<TT@>@(==@).

@<P@>Macros attached to product files cannot be additively
defined. Additively defined macros can have parameter lists
and @<TT@>@(@@Z@) and @<TT@>@(@@M@) attributes, but these must
be specified only in the first definition of the macro.
However,  @<TT@>@(+=@) must appear in each definition.

@<FWRefMan subheading@>@(Library Macros@)

@<P@>An ordinary macro definition can have from zero to five
@<TT@>@(@@L@) library level markers. These define the macro
definition's library level. A macro having a particular name
may be defined up to once at each library level, and each
such definition may be multipart (additive). At tangle time,
the definition having the lowest library level is used, with
all other definitions of the same name being completely
ignored. This feature allows the creation of general-purpose
include files that contain macro definitions that can be
overridden by definitions of the same name in the including
file. Similarly, it allows the creation of include files
containing macro definitions that override definitions in
the including file. How you use the library macro feature
is up to you.

@<P@>In the example below, the ugly duckling macro will
be expanded to @<TT@>@(swan@) because the swan definition
has the lowest library level.

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

@<P@>Note that the library macro facility imposes no
requirement on the order of appearance of the various macros
of the same name; all that matters is the library level.
This means that macros defined in an include file that is
included at the @<I@>@(end@) of a main file can be
overridden by macros appearing earlier in the main file.

@<Nav@>@(@<Parser_type_emphasis FILE@>@,@<Parser FILE@>@,@<Parser_macros_name FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Parser_macros_name HEADING@>@M@{@<SH@>@(4.9@)Macro Names@}
@$@<Parser_macros_name FILE@>@M@{parser_macros_name.html@}
@O@<parser_macros_name.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Parser_macros_name HEADING@>@)
@<X@>@(names@)@<XX@>@(macro@,names@)@<XX@>@(section@,names@)

@<P@>Names are used to identify macros and sections. A name
consists of a sequence of from zero to 80 printable
characters, including the blank character. End of line
characters are not permitted in names. Names are case
sensitive; two different macros are permitted to have names
that differ in case only. Like free text, names are typeset
by FunnelWeb and are safe from misinterpretation by the
target typesetter. For example, it is quite acceptable to
use the macro name @<TT@>@(@@<\medskip@@>@) even if the
target typesetter is TeX.

@<P@>
@<Begin verbatim@>
name      = "@@<" name_text "@@>"
name_text = { ordinary_char | text_special }
@<End verbatim@>

@<Nav@>@(@<Parser_macros FILE@>@,@<Parser FILE@>@,@<Parser_macros_params FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Parser_macros_params HEADING@>@M@{@<SH@>@(4.10@)Formal Parameter Lists@}
@$@<Parser_macros_params FILE@>@M@{parser_macros_params.html@}
@O@<parser_macros_params.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Parser_macros_params HEADING@>@)
@<XX@>@(parameter lists@,formal@)

@<P@>FunnelWeb allows macros to have up to nine macro
parameters, named @<TT@>@(@@1@),@<X@>@(@@1...@) @<TT@>@(@@2@),
@<LDots@>, @<TT@>@(@@9@). If a macro does not have a formal
parameter list, it is defined to have no parameters, and an
actual parameter list must not appear at the point of call.
If a macro has a formal parameter list, it is defined to
have one or more parameters, and a corresponding actual
parameter must be supplied for each formal parameter, at the
point of call.

@<P@>Because FunnelWeb parameters have predictable names,
the only information that a formal parameter list need
convey is @<I@>@(how many@) parameters a macro has. For this
reason a formal parameter list takes the form of the highest
numbered formal parameter desired, enclosed in parentheses
sequences.

@<P@>
@<Begin verbatim@>
formal_parameter_list = "@@(" formal_parameter "@@)".
formal_parameter = "@@1" | "@@2" | "@@3" | "@@4" | "@@5" |
                   "@@6" | "@@7" | "@@8" | "@@9"
@<End verbatim@>

@<Nav@>@(@<Parser_macros_name FILE@>@,@<Parser FILE@>@,@<Parser_expressions FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Parser_expressions HEADING@>@M@{@<SH@>@(4.11@)Expressions@}
@$@<Parser_expressions FILE@>@M@{parser_expressions.html@}
@O@<parser_expressions.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Parser_expressions HEADING@>@)
@<XX@>@(macro@,expressions@)

@<P@>Expressions are FunnelWeb's most powerful form of
expressing a text string. Macro bodies are defined as
expressions. Actual parameters consist of expressions.

@<P@>An expression consists of a sequence of zero or more
expression elements. An expression element can be ordinary
text, a macro call, or a formal parameter of the macro
@<I@>@(definition@) in which the formal parameter occurs.

@<P@>
@<Begin verbatim@>
expression = { ordinary_text | macro_call |
               formal_parameter }
@<End verbatim@>

@<Nav@>@(@<Parser_macros_params FILE@>@,@<Parser FILE@>@,@<Parser_macro_calls FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Parser_macro_calls HEADING@>@M@{@<SH@>@(4.12@)Macro Calls@}
@$@<Parser_macro_calls FILE@>@M@{parser_macro_calls.html@}
@O@<parser_macro_calls.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Parser_macro_calls HEADING@>@)
@<XX@>@(macro@,calls@)

@<P@>A macro  call consists  of a name optionally followed
by an actual parameter list. The number  of parameters  in
the  actual parameter  list must  be the same as the  number
of formal parameters specified in the definition of the
macro. If the macro has no formal parameter list, its call
must have no actual parameter list.

@<P@>
@<Begin verbatim@>
macro_call = name [actual_parameter_list]
actual_parameter_list =
      "@@(" actpar { "@@," actpar } "@@)"
actpar     = expression |
             ( whitespace "@@""" expression
               "@@""" whitespace )
whitespace = {" " | eol }
@<End verbatim@>

@<P@>FunnelWeb allows parameters to be passed directly, or
delimited by special double quotes.@<XX@>@(macro
parameter@,delimiting@) Each form is useful under different
circumstances. Direct specification is useful where the
parameters are short and can be all placed on one line.
Double quoted parameters allow whitespace on either side
(that is not considered part of the parameter) and are
useful for laying out rather messy parameters. Here are
examples of the two forms.

@<P@>
@<Begin verbatim@>
@@@<<@>Generic Loop@@@<>@>@@(
   @@"x:=1;@@"  @@,
   @@"x<=10;@@" @@,
   @@"print "x=%u, x^2=%u",x,x*x;
   x:=x+1;@@+@@"
@@)

@@@<<@>Colours@@@<>@>@@(red@@,green@@,blue@@,yellow@@)
@<End verbatim@>

@<P@>The two forms may be mixed within the same
parameter list.

@<P@>Experience has shown that, in most FunnelWeb files,
the vast majority of macros have no parameters.

@<Nav@>@(@<Parser_expressions FILE@>@,@<Parser FILE@>@,@<Parser_parameters FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Parser_parameters HEADING@>@M@{@<SH@>@(4.13@)Macro Formal Parameters@}
@$@<Parser_parameters FILE@>@M@{parser_parameters.html@}
@O@<parser_parameters.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Parser_parameters HEADING@>@)
@<XX@>@(formal@,parameters@)

@<P@>Formal parameters can appear in the expressions forming
macro bodies in accordance with the syntax rules defined
above. A formal parameter expands to the text of the
expansion of its corresponding actual parameter. There is
nothing preventing a formal parameter being provided as part
of an expression that forms an actual parameter. In that
happens, the formal parameter is bound to the actual
parameter of the calling macro, not the called macro. After
the following definitions,

@<P@>
@<Begin verbatim@>
@@$@@@<<@>One@@@<>@>@@(@@1@@)=@@{A walrus in @@1 is a walrus in vain.@@}
@@$@@@<<@>Two@@@<>@>@@(@@1@@)=@@{@@@<<@>One@@@<>@>@@(S@@1n@@)@@}
@<End verbatim@>

@<P@>the call

@<P@>
@<Begin verbatim@>
@@@<<@>Two@@@<>@>@@(pai@@)
@<End verbatim@>

@<P@>will result in the expansion

@<P@>
@<Begin verbatim@>
A walrus in Spain is a walrus in vain.
@<End verbatim@>

@<Nav@>@(@<Parser_macro_calls FILE@>@,@<Parser FILE@>@,@<Parser_static FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Parser_static HEADING@>@M@{@<SH@>@(4.14@)Macros Are Static@}
@$@<Parser_static FILE@>@M@{parser_static.html@}
@O@<parser_static.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Parser_static HEADING@>@)
@<XX@>@(macro@,definition@)@<XX@>@(macro@,expansion@)@<XX@>@(macros@,static@)

@<P@>In FunnelWeb, the actions of @<I@>@(macro  definition@)
and  @<I@>@(macro expansion@) occur during two separate
phases (parser and tangle) and cannot be interleaved. As a
result, the FunnelWeb macro facility is completely static.
It is not possible for one macro to define another while the
first macro is being expanded; each must be defined
statically. It is not possible to define a macro to even
assist in the definition of other macros. Because the
scanner, parser, analyser, and tangler phases are all
invoked sequentially, there is no room for feedback of
definitions between different levels (@<eg@>the user cannot
define a macro for the @<TT@>@(vskip@) pragma).

@<P@>This lack of power is fully intentional. By totally
excluding the more incomprehensible ways in which a general
purpose macro preprocessor can be used, FunnelWeb provides
definite guarantees to the reader of its input files:

@<P@>
@<Begin list@>

@<Item@>FunnelWeb guarantees that a piece of text does not
contain a macro call unless it contains the special
character followed by @<TT@>@(@<<@>@) or @<TT@>@(#@).

@<Item@>FunnelWeb allows calls to be made to macros that are
defined later in the input file.

@<End list@>

@<Nav/last@>@(@<Parser_parameters FILE@>@,@<Parser FILE@>@,@<Parser FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Analyser HEADING@>@M@{@<SH@>@(5@)Analyser@}
@$@<Analyser HEADING/short@>@M@{@<SH@>@(5@)Analyser@}
@$@<Analyser FILE@>@M@{analyser.html@}
@O@<analyser.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Analyser HEADING@>@)
@<X@>@(analyser@)@<XX@>@(checks@,macro@)

@<P@>The effect of the parser is to construct a macro table
containing a representation of all the macros defined within
the document, and a document list which contains a complete
representation of the entire document. If there are no error
diagnostics (or worse) at the end of the parser run,
FunnelWeb invokes the analyser which tests for the following
conditions and flags them with errors if they arise.

@<P@>
@<Begin list@>
@<Item@>No macros defined in the input file.
@<Item@>No macros connected to output files.
@<Item@>Call of an undefined macro.
@<Item@>Call having the wrong number of parameters.
@<Item@>Call of a macro that is connected to an output file.
@<Item@>No calls made to a macro without the @<TT@>@(@@Z@) option.
@<Item@>More than one call made to a macro without the @<TT@>@(@@M@) option.
@<Item@>Directly or indirectly recursively defined macros.
@<Item@>Unnamed sections that contain no macro definitions.
@<End list@>

@<P@>FunnelWeb performs a static
analysis@<XX@>@(static@,analysis@) to detect
recursion.@<XX@>@(macro@,recursion@) Unfortunately, the
recursion detection algorithm flags all macros that have an
infinite expansion rather than just all macros with a
recursive definition. If A calls B, and B calls C, and C
calls B, then FunnelWeb will flag A as well as B and C. It
is hoped that this problem will be fixed in a later version.

@<P@>Because FunnelWeb does not provide any kind of
conditional feature, the prevention of recursion does not
represent a curtailment of expressive power.

@<P@>Macros may be invoked recursively, but may not be
recursive. Thus:

@<P@>
@<Begin verbatim@>
@@! LEGAL   recursive invocation.
@@@<<@>Sloth@@@<>@>@@(@@@<<@>Sloth@@@<>@>@@(Walrus@@)@@)

@@! ILLEGAL recursive definition.
@@$@@@<<@>Teapot@@@<>@>==@@{@@@<<@>Teapot@@@<>@>@@}
@<End verbatim@>

@<Nav@>@(@<Parser FILE@>@,@<Index FILE@>@,@<Tangle FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Tangle HEADING@>@M@{@<SH@>@(6@)Tangle@}
@$@<Tangle HEADING/short@>@M@{@<SH@>@(6@)Tangle@}
@$@<Tangle FILE@>@M@{tangle.html@}
@O@<tangle.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Tangle HEADING@>@)
@<X@>@(tangle@)

@<P@>If the scanner, parser, and analyser have successfully
(@<ie@>with no errors, severe errors, or fatal errors)
completed, and the Tangle option (@<TT@>@(+O@)) is turned on
(it is by default), then the Tangle component of FunnelWeb
is invoked to generate the product files specified in the
@<TT@>@(@@O@) macros of the input file.

@<P@>The operation of Tangle is very simple. Each
@<TT@>@(@@O@) macro is expanded and written to a file of the
same name. As there are a finite number of macros, and the
analyser guarantees that the macro structure is
non-recursive, Tangle is guaranteed to terminate.

@<P@>Three remaining points are worth mentioning.

@<P@>
@<Begin list@>

@<Item@>Tangle expands macros using blank indentation unless
the user has specified otherwise in an indentation pragma in
the input file.

@<Item@>Tangle keeps track of the length of the lines that
it is writing and issues an error if any line of any product
file that it generates is longer than the maximum. The
maximum is the minimum of a value defaulted or specified in
the input file, and the value (if any) provided by the
@<TT@>@(+w@) command line argument.

@<Item@>If there is more than one macro definition of the
same name, then each such definition must have a different
library level (@<TT@>@(@@L@)). Tangle uses the macro
definition that has the lowest library level and ignores
the others completely.

@<End list@>

@<FWRefMan subheading@>@(Memory Use During Tangling@)

@<P@>When FunnelWeb executes, it reads each input file (the
main input file and any include files) into memory where
they are kept for the duration of the run. This means that
there must be room in memory for all of the input files.
This approach is necessary to support FunnelWeb's
unrestricted forward referencing.

@<P@>In contrast, there is no requirement that there be
enough memory to hold the product files, as these are
written to disk sequentially during their expansion.
Furthermore, FunnelWeb does not expand the values of actual
parameters in memory.

@<P@>This means that, so long as the input files fit in
memory, your product files can be arbitrarily large. You can
also pass arbitrary large arguments to FunnelWeb macros.

@<Nav@>@(@<Analyser FILE@>@,@<Index FILE@>@,@<Weave FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Weave HEADING@>@M@{@<SH@>@(7@)Weave@}
@$@<Weave HEADING/short@>@M@{@<SH@>@(7@)Weave@}
@$@<Weave FILE@>@M@{weave.html@}
@O@<weave.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Weave HEADING@>@)
@<X@>@(weave@)@<X@>@(typesetting@)

@<P@>If the scanner, parser, and analyser have successfully
(@<ie@>with no errors, severe errors, or fatal errors)
completed, and either or both of the two Weave options
(@<TT@>@(+T@), @<TT@>@(U@)) is turned on
(both are @<I@>@(off@) by default), then the Weave component of
FunnelWeb is invoked to generate one or two documentation files.

@<FWRefMan subheading@>@(Target Typesetter@)
@<XX@>@(target@,typesetter@)

@<P@>All versions of FunnelWeb up to V3.1 could generate only
TeX documentation. This used the @<TT@>@(+t@) option. FunnelWeb
V3.2 can now generate HTML documention using the @<TT@>@(+u@)
option. You can generate both at once if you like.

@<FWRefMan subheading@>@(Cross Reference Numbering@)
@<XX@>@(cross@,referencing@)@<XX@>@(cross reference@,numbering@)
@<XX@>@(section@,numbering@)

@<P@>When FunnelWeb produces its typeset documentation, it
@<I@>@(numbers@) each section and each macro definition and
cross references the macro definitions. The exact scheme
used has been carefully thought out. However, as it can be a
little confusing to the beginner, it is explained here in
full.

@<P@>The most important thing is that there is @<I@>@(no
relation@) between the macro numbering and the section
numbering. In Knuth's Web there are only section numbers. In
FunnelWeb,  the numbering of sections and macros is
separated.

@<P@>In FunnelWeb, @<I@>@(sections@) are numbered
hierarchically in ascending order. For example, the second
level-C section of the third level-B section of the first
level-A section is numbered @<DQ@>@(1.3.2@). In contrast,
@<I@>@(macro definitions@) are numbered sequentially in
ascending order. For example, the first macro definition is
number 1, the second is number 2, and so on. Note that it is
@<I@>@(macro definitions@) that are numbered, not
@<I@>@(macros@). This distinction is necessary because
additive macros (@<ie@>the ones with @<TT@>@(+=@)) can be
defined by a collection of partial definitions scattered
throughout the input file. A single additive macro may be
defined in definitions 5, 67, 128, and 153.

@<Nav@>@(@<Tangle FILE@>@,@<Index FILE@>@,@<Shell FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Shell HEADING@>@M@{@<SH@>@(8@)FunnelWeb Shell@}
@$@<Shell HEADING/short@>@M@{@<SH@>@(8@)Shell@}
@$@<Shell FILE@>@M@{shell.html@}
@O@<shell.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Shell HEADING@>@)
@<XX@>@(FunnelWeb@,command shell@)@<XX@>@(commands@,FunnelWeb@)@<XX@>@(FunnelWeb@,shell@)

@<P@>
@<Shell index@>

@<Nav@>@(@<Weave FILE@>@,@<Index FILE@>@,@<Commands FILE@>@)

@<End FWRefMan page@>
@}

@$@<Shell index@>@M@{
@<Begin size3@>
@<Begin indent/narrow@>
@<Link@>@(@<Shell_introduction FILE@>@,@<Shell_introduction HEADING@>@)@<BR@>
@<Link@>@(@<Shell_statuses FILE@>@,@<Shell_statuses HEADING@>@)@<BR@>
@<Link@>@(@<Shell_linelen FILE@>@,@<Shell_linelen HEADING@>@)@<BR@>
@<Link@>@(@<Shell_strsubs FILE@>@,@<Shell_strsubs HEADING@>@)@<BR@>
@<Link@>@(@<Shell_processing FILE@>@,@<Shell_processing HEADING@>@)@<BR@>
@<Link@>@(@<Shell_options FILE@>@,@<Shell_options HEADING@>@)@<BR@>
@<End indent/narrow@>
@<End size3@>
@}

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

@$@<Shell_introduction HEADING@>@M@{@<SH@>@(8.1@)Introduction@}
@$@<Shell_introduction FILE@>@M@{shell_introduction.html@}
@O@<shell_introduction.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Shell_introduction HEADING@>@)

@<P@>One of the goals of FunnelWeb is that it must be
extremely portable, and a significant effort has gone into
achieving this.

@<P@>An equally important goal was that of correctness and
reliability. To this end, it was determined that a large
automated suite of test programs be prepared to assist in
regression testing. Preparing the test suite was tedious,
but achievable. Automating it portably was more difficult.

@<P@>The difficulty faced was that if FunnelWeb was
implemented in the form of a utility that could be invoked
from the operating system command language, the only way to
set up regression testing was in the command language of the
operating system of the target machine (shellscripts for
UNIX, DCL for OpenVMS, batch files for MSDOS, and
@<I@>@(nothing@) on the Macintosh). The huge variation in
these command languages led to the conclusion that either
the automation of regression testing would have to be
rewritten on each target machine, or a small command
language would have to be created within FunnelWeb. In the
end, the twin goals of portability and regression testing
were considered so important that a small command shell was
constructed inside FunnelWeb. This is called the
@<NewTerm@>@(FunnelWeb command shell@), or just @<DQ@>@(the
shell@) for short.

@<P@>By default, when FunnelWeb is invoked, it does not
enter its shell. If just given the name of an input file, it
will simple process the input file in the normal manner and
then terminate. To instruct FunnelWeb to invoke its shell,
the @<TT@>@(+K@) or @<TT@>@(+X@) command line option must be
specified when FunnelWeb is invoked from the operating
system. It is also invoked upon startup if the file
@<TT@>@(fwinit.fws@) exists.

@<P@>Most FunnelWeb users will never need to use the shell
and need not even know about it. There are four main uses of
the shell:@<XX@>@(uses@,shell@)

@<Begin list/ordered@>

@<Item@>As a tool to support automated regression testing.

@<Item@>As a development tool on machines that do not have a
built in shell (@<eg@>the Macintosh). The shell can be used
to process whole groups of files automatically.

@<Item@>As a convenience. A user working on a multi-tasking,
multi-window workstation@<X@>@(workstation@) may wish to
keep an interactive session of FunnelWeb going in one window
rather than having to run up the utility each time it is
required.

@<Item@>As a convenient vehicle for enclosing utilities. The
FunnelWeb shell contains useful general purpose commands
such as the differences command @<TT@>@(diff@).

@<End list/ordered@>

@<Nav/first@>@(@<Shell FILE@>@,@<Shell FILE@>@,@<Shell_statuses FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Shell_statuses HEADING@>@M@{@<SH@>@(8.2@)Return Statuses@}
@$@<Shell_statuses FILE@>@M@{shell_statuses.html@}
@O@<shell_statuses.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Shell_statuses HEADING@>@)
@<XX@>@(errors@,shell@)@<XX@>@(status@,success@)
@<XX@>@(status@,warning@)@<XX@>@(status@,error@)@<XX@>@(status@,severe@)@<XX@>@(status@,fatal@)
@<XX@>@(status@,assertion@)

@<P@>The hierarchy of diagnostics is also used in the shell
commands. Each shell command returns a status which can
affect further processing.

@<NarrowThing@>@(Success@,status is the normal command
return status.@)

@<NarrowThing@>@(Warning@,status is returned if some minor
problem arose with the execution of the command.@)

@<NarrowThing@>@(Error@,status is returned if a significant
problem arises during the execution of the command. However,
unlike a severe error, it does @<I@>@(not@) cause
termination of the enclosing shellscript.@)

@<NarrowThing@>@(Severe error@,status is returned if a
problem arises during the execution of the command that
prevents the command from delivering on its
@<DQ@>@(promise@). A severe error causes FunnelWeb to abort
the script (and any stacked scripts) to the interactive
level. (However, the @<TT@>@(tolerate@) command allows this
to be temporarily overridden).@)

@<NarrowThing@>@(Fatal error@,status is returned if a
problem arises that is so serious that execution of
FunnelWeb cannot continue. A fatal error causes FunnelWeb to
abort to the operating system level.@)

@<NarrowThing@>@(Assertion error@,status is never returned.
If an assertion error occurs, FunnelWeb bombs out
ungracefully to the operating system. Assertion errors
should never happen. If they do, then there is a bug in
FunnelWeb.@)

@<P@>To be precise, the status returned by each command is a
vector of numbers being the number of each of the different
kinds of diagnostic generated by the command. Usually only
one kind of diagnostic is generated. However, the
@<TT@>@(fw@) command and a few of the other commands can
generate more than one kind of diagnostic. These status
vectors are summed internally where they may later be
accessed using the @<TT@>@(status@) command. However, the
current diagnostic state evaporates as soon as the next
command is encountered.

@<Nav@>@(@<Shell_introduction FILE@>@,@<Shell FILE@>@,@<Shell_linelen FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Shell_linelen HEADING@>@M@{@<SH@>@(8.3@)Command Line Length@}
@$@<Shell_linelen FILE@>@M@{shell_linelen.html@}
@O@<shell_linelen.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Shell_linelen HEADING@>@)
@<XX@>@(command@,length@)

@<P@>The maximum length of a shell command line is
guaranteed to be at least 300 characters.

@<Nav@>@(@<Shell_statuses FILE@>@,@<Shell FILE@>@,@<Shell_strsubs FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Shell_strsubs HEADING@>@M@{@<SH@>@(8.4@)String Substitution@}
@$@<Shell_strsubs FILE@>@M@{shell_strsubs.html@}
@O@<shell_strsubs.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Shell_strsubs HEADING@>@)

@<P@>Most command shells provide some form of string
substitution so as to provide some degree of
parameterization. The FunnelWeb shell provides 36 different
string variables named @<TT@>@($0..$9@) and @<TT@>@($A..$Z@)
(case insensitive). Each variable can hold a string
containing any sequence of printable characters and can be
as long as a command line.

@<P@>The @<TT@>@(define@) command@<XX@>@(define@,command@)
allows the user to assign a value to these variables. The
@<TT@>@(define@) command takes two arguments. The first is
the digit or letter of the variable to be defined. The
second is a double quote delimited string being the string
value to be assigned to the variable. If you want to include
a double quote character within the string, you don't need
to double it.

@<P@>Examples:

@<P@>
@<Begin verbatim@>
define 3 "/root/usr/dave/workdir/fwdir/testdir"
define M "/user/local/rubbish/bin/fw"
define Q "You don't need to double" double quotes"
@<End verbatim@>

@<P@>Only the identifying character of the variable being
assigned is used in the definition. This syntax is a simple
way of preventing the variable from being substituted before
it has a chance to be defined!

@<P@>The following points clean up the remaining semantic
details:

@<Begin list@>

@<Item@>There is only one set of variables and they are
global to all shellscripts. There are @<I@>@(no local
variables@).

@<Item@>When a shellscript is invoked using the
@<TT@>@(execute@) command, the substitution variables
@<TT@>@(0@) through @<TT@>@(9@) are affected. See the
EXECUTE command for more details.

@<Item@>If you want to include a dollar sign character in a
command use @<DQP@>@($$@).

@<Item@>FunnelWeb also defines @<DQP@>@($/@) which
translates to the character that separates directory and
file name fields in file names on the host machine. For
example: Sun=@<DQP@>@(/@), Vax=@<DQP@>@(]@),
Mac=@<DQP@>@(:@), PC=@<DQP@>@(\@).

@<Item@>Substitution is not performed recursively.

@<End list@>

@<Nav@>@(@<Shell_linelen FILE@>@,@<Shell FILE@>@,@<Shell_processing FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Shell_processing HEADING@>@M@{@<SH@>@(8.5@)How a Command Line is Processed@}
@$@<Shell_processing FILE@>@M@{shell_processing.html@}
@O@<shell_processing.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Shell_processing HEADING@>@)
@<XX@>@(command line@,processing@)

@<P@>When FunnelWeb reads in a command line (from the
console or a script file), it processes it in the following
sequence:

@<Begin list/ordered@>

@<Item@>The command line is checked for non-printable
characters. If there are any, they are flagged with a severe
error.

@<Item@>All dollar string substitution variables in the
command line are replaced by their corresponding string. The
command line is processed from left to right. Substitutions
are performed non recursively.

@<Item@>At this point, if the line is empty, or consists
entirely of blanks, it is ignored and the interpreter moves
to the next line.

@<Item@>A severe error is generated if the line at this
stage begins with a blank.

@<Item@>If the first character of the line is @<DQP@>@(!@),
the line is a comment line and is ignored.

@<Item@>The run of non-blanks commencing at the start of the
line is compared case-insensitively to each of the legal
command verbs. If the command is illegal, a severe error is
generated, otherwise the command is processed.

@<End list/ordered@>

@<Nav@>@(@<Shell_strsubs FILE@>@,@<Shell FILE@>@,@<Shell_options FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Shell_options HEADING@>@M@{@<SH@>@(8.6@)Options@}
@$@<Shell_options FILE@>@M@{shell_options.html@}
@O@<shell_options.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Shell_options HEADING@>@)
@<XX@>@(command@,options@)@<XX@>@(default@,options@)

@<P@>The FunnelWeb shell maintains three sets of command
line options.

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

@<Item@>The set of options resulting from applying the
operating system level command line arguments to the default
option settings.

@<Item@>A set of shell options that prevail during the shell
invocation.

@<Item@>The set of option values active during a particular
invocation of FunnelWeb proper.

@<End list/ordered@>

@<P@>When FunnelWeb is invoked from the operating system
with just @<TT@>@(+F@), only the first of these three sets
comes into existence. If the user invokes the FunnelWeb
shell, the shell options come into existence and are
initialized with the value of the first set. These shell
options are used as the default for all subsequent
@<TT@>@(fw@) commands. However, they can be altered using
the script command @<TT@>@(set@). If a @<TT@>@(fw@) command
executed in a shell contains additional command line
options, these override the shell options for that run, but
do not change the shell options. An example follows:

@<P@>
@<Begin verbatim@>
$ fw +k +t            ! Original invocation from OS.
                      ! Options default with "+t".
FunnelWeb>fw sloth    ! Equivalent to fw sloth +t.
FunnelWeb>set -l      ! Change the l shell option.
FunnelWeb>fw sloth +q ! Equiv to fw sloth +t -l +q.
FunnelWeb>fw sloth    ! Equiv to fw sloth +t -l.
@<End verbatim@>

@<P@>The existence of the shell option set means that the
user can set up a set of defaults to be applied to all
@<TT@>@(fw@) commands issued within the shell.

@<Nav/last@>@(@<Shell_processing FILE@>@,@<Shell FILE@>@,@<Shell FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands HEADING@>@M@{@<SH@>@(9@)Shell Commands@}
@$@<Commands HEADING/short@>@M@{@<SH@>@(9@)Commands@}
@$@<Commands FILE@>@M@{commands.html@}
@O@<commands.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands HEADING@>@)
@<XX@>@(shell commands@,list@)@<XX@>@(commands@,shell@)

@<Commands index@>

@<Nav@>@(@<Shell FILE@>@,@<Index FILE@>@,@<Glossary FILE@>@)

@<End FWRefMan page@>
@}

@$@<Commands index@>@M@{
@<Begin size3@>
@<Begin indent/narrow@>
@<Link@>@(@<Commands_introduction FILE@>@,@<Commands_introduction HEADING@>@)@<BR@>
@<Link@>@(@<Commands_absent FILE@>@,@<Commands_absent HEADING@>@)@<BR@>
@<Link@>@(@<Commands_codify FILE@>@,@<Commands_codify HEADING@>@)@<BR@>
@<Link@>@(@<Commands_compare FILE@>@,@<Commands_compare HEADING@>@)@<BR@>
@<Link@>@(@<Commands_define FILE@>@,@<Commands_define HEADING@>@)@<BR@>
@<Link@>@(@<Commands_diff FILE@>@,@<Commands_diff HEADING@>@)@<BR@>
@<Link@>@(@<Commands_diffsummary FILE@>@,@<Commands_diffsummary HEADING@>@)@<BR@>
@<Link@>@(@<Commands_diffzero FILE@>@,@<Commands_diffzero HEADING@>@)@<BR@>
@<Link@>@(@<Commands_eneo FILE@>@,@<Commands_eneo HEADING@>@)@<BR@>
@<Link@>@(@<Commands_execute FILE@>@,@<Commands_execute HEADING@>@)@<BR@>
@<Link@>@(@<Commands_exists FILE@>@,@<Commands_exists HEADING@>@)@<BR@>
@<Link@>@(@<Commands_fixeols FILE@>@,@<Commands_fixeols HEADING@>@)@<BR@>
@<Link@>@(@<Commands_fw FILE@>@,@<Commands_fw HEADING@>@)@<BR@>
@<Link@>@(@<Commands_help FILE@>@,@<Commands_help HEADING@>@)@<BR@>
@<Link@>@(@<Commands_here FILE@>@,@<Commands_here HEADING@>@)@<BR@>
@<Link@>@(@<Commands_quit FILE@>@,@<Commands_quit HEADING@>@)@<BR@>
@<Link@>@(@<Commands_set FILE@>@,@<Commands_set HEADING@>@)@<BR@>
@<Link@>@(@<Commands_show FILE@>@,@<Commands_show HEADING@>@)@<BR@>
@<Link@>@(@<Commands_skipto FILE@>@,@<Commands_skipto HEADING@>@)@<BR@>
@<Link@>@(@<Commands_status FILE@>@,@<Commands_status HEADING@>@)@<BR@>
@<Link@>@(@<Commands_tolerate FILE@>@,@<Commands_tolerate HEADING@>@)@<BR@>
@<Link@>@(@<Commands_trace FILE@>@,@<Commands_trace HEADING@>@)@<BR@>
@<Link@>@(@<Commands_write FILE@>@,@<Commands_write HEADING@>@)@<BR@>
@<Link@>@(@<Commands_writeu FILE@>@,@<Commands_writeu HEADING@>@)@<BR@>
@<End indent/narrow@>
@<End size3@>
@}

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

@$@<Commands_introduction HEADING@>@M@{@<SH@>@(9.1@)Introduction@}
@$@<Commands_introduction FILE@>@M@{commands_introduction.html@}
@O@<commands_introduction.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_introduction HEADING@>@)

@<P@>This section describes each of the FunnelWeb shell
commands. The syntax is:

@<P@>
@<Begin verbatim@>
shell_command = absent   | codify  | compare     |
                define   | diff    | diffsummary |
                diffzero | eneo    | execute     |
                exists   | fixeols | help        |
                here     | quit    | set         |
                show     | skipto  | status      |
                tolerate | trace   | write       |
                writeu
s = { " " }+
@<End verbatim@>

@<P@>As a rule, FunnelWeb shell commands return severe
status if their arguments are syntactically incorrect or if
they are unable to successfully operate on argument files.

@<Nav/first@>@(@<Commands FILE@>@,@<Commands FILE@>@,@<Commands_absent FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_absent HEADING@>@M@{@<SH@>@(9.2@)Absent@}
@$@<Commands_absent FILE@>@M@{commands_absent.html@}
@O@<commands_absent.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_absent HEADING@>@)
@<XX@>@(command@,absent@)

@<P@>The @<TT@>@(absent@) command performs no action except
to return a status. If the file specified in its argument
doesn't exist it returns success status, otherwise it
returns severe status.

@<P@>
@<Begin verbatim@>
Syntax : absent = "absent" s filename
Example: absent result.out
@<End verbatim@>

@<P@>This command is useful in regression testing for making
sure that FunnelWeb @<I@>@(hasn't@) produced a particular
output file.

@<Nav@>@(@<Commands_introduction FILE@>@,@<Commands FILE@>@,@<Commands_codify FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_codify HEADING@>@M@{@<SH@>@(9.3@)Codify@}
@$@<Commands_codify FILE@>@M@{commands_codify.html@}
@O@<commands_codify.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_codify HEADING@>@)
@<XX@>@(command@,codify@)

@<P@>The @<TT@>@(codify@) command takes two arguments: an
input file and an output file. It reads each line of the
input file and writes a corresponding line to the output
file. The corresponding line consists of a C macro call
containing a string containing the input line. The command
converts all backslashes in input lines to double
backslashes so as to avoid unwanted interpretations by the C
compiler. It also converts double quotes in the line to
backslashed double quotes.

@<P@>
@<Begin verbatim@>
Syntax : codify = "codify" s filename s filename
Example: codify header.tex header.c
@<End verbatim@>

@<P@>The following example demonstrates the transformation.

@<P@>
@<Begin verbatim@>
Input  Line:
 \def\par{\leavevmode\endgraf}% A "hack".
Output Line:
 WX("\\def\\par{\\leavevmode\\endgraf}% A \"hack\".");
@<End verbatim@>

@<P@>The @<TT@>@(codify@) command was introduced to assist
in the development of FunnelWeb. It is used to convert
longish text files into C code to write them out. The C code
is then included within the FunnelWeb C program. For
example, the set of TeX definitions that appears at the top
of every documentation file was @<TT@>@(codif@)ied and
inserted into the FunnelWeb code so that FunnelWeb would not
have to look for a file containing the definitions at run
time.

@<Nav@>@(@<Commands_absent FILE@>@,@<Commands FILE@>@,@<Commands_compare FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_compare HEADING@>@M@{@<SH@>@(9.4@)Compare@}
@$@<Commands_compare FILE@>@M@{commands_compare.html@}
@O@<commands_compare.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_compare HEADING@>@)
@<XX@>@(command@,compare@)

@<P@>The @<TT@>@(compare@) command takes two filename
arguments and performs a binary comparison of the two files.
If the files are identical, success status is returned. If
they are different, severe status is returned. No
information about the manner in which the files differ is
conveyed.

@<P@>
@<Begin verbatim@>
Syntax : compare = "compare" s filename s filename
Example: compare result.txt answer.txt
@<End verbatim@>

@<P@>The @<TT@>@(compare@) command was created as the main
checking mechanism for regression testing. However, its
binary output was soon found to be unworkable and the more
sophisticated @<TT@>@(diff@) command was added so that the
actual differences between the files could be examined.

@<Nav@>@(@<Commands_codify FILE@>@,@<Commands FILE@>@,@<Commands_define FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_define HEADING@>@M@{@<SH@>@(9.5@)Define@}
@$@<Commands_define FILE@>@M@{commands_define.html@}
@O@<commands_define.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_define HEADING@>@)
@<XX@>@(command@,define@)@<XX@>@(string@,substitution@)

@<P@>The @<TT@>@(define@) command assigns a value to a shell
string substitution variable. The @<TT@>@(define@) command
takes two arguments. The first is the digit or letter of the
variable to be defined. The second is a double quote
delimited string being the string value to be assigned to
the variable. If you want to include a double quote
character within the string, you don't need to double it.

@<P@>
@<Begin verbatim@>
Syntax  :
   define = "define" s letter s """" text """"
Examples:
   define 3 "/usr/usrs/thisuser/workdir/fwdir/testdir"
   define M "/user/local/rubbish/bin/fw"
   define Q "You don't need to double" double quotes"
@<End verbatim@>

@<P@>The command interpreter expands the command line before
it executes the @<TT@>@(define@) command. This means that
you can define string substitution variables in terms of
each other with static binding.

@<P@>The @<TT@>@(define@) command was introduced to allow
the parameterization of the directories involved in
regression testing.

@<P@>See the section on string substitution for more
details.

@<Nav@>@(@<Commands_compare FILE@>@,@<Commands FILE@>@,@<Commands_diff FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_diff HEADING@>@M@{@<SH@>@(9.6@)Diff@}
@$@<Commands_diff FILE@>@M@{commands_diff.html@}
@O@<commands_diff.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_diff HEADING@>@)
@<XX@>@(command@,diff@)@<XX@>@(file@,differences@)

@<P@>The @<TT@>@(diff@) command reads in two text files and
@<I@>@(appends@) a report to a log file containing a list of
the differences between the two input files. If the log file
does not already exist, an empty one is created first.

@<P@>
@<Begin verbatim@>
Syntax  :
   diff = "diff" s filename s filename s
                   filename s ["ABORT"]
Examples:
   diff result.tex answer.tex diff.log
   diff $Otest23.out $Atest23.out $Ldiff.log ABORT
@<End verbatim@>

@<P@>The @<TT@>@(diff@) command performs a full line-based
differences operation. It will identify different sections
in a file, even if they are of differing length.

@<P@>The implementation of the @<TT@>@(diff@) command is
quite complicated. To be sure that it is at least getting
its same/different proclamation right, the @<TT@>@(diff@)
command performs a binary comparison as an extra check.

@<P@>The following points describe the rules for determining
the result status.

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

@<Item@>@<TT@>@(diff@) aborts with a severe error if the log
file cannot be opened or created for appending.

@<Item@>An ordinary error is generated if either or both of
the input files cannot be opened.

@<Item@>If, at the end of the run, the two input files have
not been proven to be identical, and the @<TT@>@(ABORT@)
keyword is present, @<TT@>@(diff@) returns severe status.

@<Item@>@<TT@>@(diff@) returns success status if none of the
above conditions (or similar conditions) occur, even if the
two files are different.

@<End list/ordered@>

@<P@>The @<TT@>@(diff@) command @<I@>@(appends@) its
differences report rather than merely writing it. This
allows a regression test script to perform a series of
regression tests and produce a report for the user.

@<P@>The @<TT@>@(diff@) command was added to the shell after
it had become apparent that the simpler @<TT@>@(compare@)
command was not yielding enough information. Whereas early
on, regression testing was treated mainly as a tool to
ensure that FunnelWeb was being ported to other machines
correctly, it began to place an increasing role during
development in identifying the effects of changes made to
the code. The @<TT@>@(diff@) command supports this
application of regression testing by pinpointing the
differences between nearly-identical text files.

@<Nav@>@(@<Commands_define FILE@>@,@<Commands FILE@>@,@<Commands_diffsummary FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_diffsummary HEADING@>@M@{@<SH@>@(9.7@)Diffsummary@}
@$@<Commands_diffsummary FILE@>@M@{commands_diffsummary.html@}
@O@<commands_diffsummary.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_diffsummary HEADING@>@)
@<XX@>@(command@,diffsummary@)

@<P@>The @<TT@>@(diffsummary@) command writes a short report
to the console giving the number of difference operations
that have taken place and how many of the pairs of files
compared were identical. Counting starts at the most recent
execution of a @<TT@>@(diffzero@) command, or if there has
been none, when FunnelWeb started up.

@<P@>
@<Begin verbatim@>
Syntax  : diffsummary = "diffsummary"
Examples: diffsummary
@<End verbatim@>

@<P@>The @<TT@>@(diffsummary@) command was added so as to
allow regression testing scripts to display a summary of the
results of the test. If the summary indicates that no pair
of files differed, then there is no need to look in the
@<TT@>@(diff@) log file.

@<Nav@>@(@<Commands_diff FILE@>@,@<Commands FILE@>@,@<Commands_diffzero FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_diffzero HEADING@>@M@{@<SH@>@(9.8@)Diffzero@}
@$@<Commands_diffzero FILE@>@M@{commands_diffzero.html@}
@O@<commands_diffzero.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_diffzero HEADING@>@)
@<XX@>@(command@,diffzero@)

@<P@>The @<TT@>@(diffzero@) command zeros the different
summary counters used by the @<TT@>@(diff@) and
@<TT@>@(diffsummary@) commands.

@<P@>
@<Begin verbatim@>
Syntax  : diffzero = "diffzero"
Examples: diffzero
@<End verbatim@>

@<P@>The @<TT@>@(diffzero@) command was added so as to allow
regression testing shellscripts to zero their differences
counters at the start of a run. This allows testers to
invoke the same regression testing script twice in one
interactive session without receiving an inflated
differences summary.

@<Nav@>@(@<Commands_diffsummary FILE@>@,@<Commands FILE@>@,@<Commands_eneo FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_eneo HEADING@>@M@{@<SH@>@(9.9@)Eneo@}
@$@<Commands_eneo FILE@>@M@{commands_eneo.html@}
@O@<commands_eneo.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_eneo HEADING@>@)
@<XX@>@(command@,eneo@)

@<P@>The @<TT@>@(eneo@) command takes one filename argument.
If the file does not exist, no action is taken. If the file
does exist, it is deleted. In both cases success status is
returned. However, if the file exists and cannot be deleted,
@<TT@>@(eneo@) returns severe status.

@<P@>
@<Begin verbatim@>
Syntax  : eneo = "eneo" s filename
Examples: eneo result.out
@<End verbatim@>

@<P@>The @<TT@>@(eneo@) command was added so as to allow
regression testing scripts to ensure that existing output
files were not present before proceeding with a test run. If
FunnelWeb were to fail to generate an output file, it would
be extremely undesirable for the old version to be used.

@<P@>ENEO stands for @<B@>@(E@)stablish the @<B@>@(N@)on
@<B@>@(E@)xistence @<B@>@(O@)f. Most operating systems provide a
command to delete files. Typically these commands are verbs
such as @<DQ@>@(delete@), @<DQ@>@(remove@), and
@<DQ@>@(kill@). As a consequence, the designers of delete
commands usually consider the command to have failed if it
fails to find the file to be deleted. However, in scripts,
the delete command is very commonly used to
@<I@>@(establish the non-existence of@) one or more files.
Typically, a script is starting up and needs to clear the
air before getting started. If the files are there, they
should be deleted; if they are not, then that's OK
too. (Note: As far as I know, the @<TT@>@(eneo@) command
is original).

@<Nav@>@(@<Commands_diffzero FILE@>@,@<Commands FILE@>@,@<Commands_execute FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_execute HEADING@>@M@{@<SH@>@(9.10@)Execute@}
@$@<Commands_execute FILE@>@M@{commands_execute.html@}
@O@<commands_execute.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_execute HEADING@>@)
@<XX@>@(command@,execute@)

@<P@>The @<TT@>@(execute@) command causes a specified text
file to be executed as a FunnelWeb shellscript. The first
argument is the name of the script file. The remaining
arguments are assigned to the substitution variables
@<TT@>@($1@), @<TT@>@($2@), @<LDots@>, @<TT@>@($9@).
Substitution variables in the range @<TT@>@($1@) to
@<TT@>@($9@) that do not correspond to an argument are set
to the empty string @<TT@>@(""@). @<TT@>@($0@) is set to the
empty string regardless. The execute command can be used
recursively, allowing shell scripts to invoke each other. A
file extension default of @<DQP@>@(.fws@) (FunnelWeb Script)
applies to script files.

@<P@>
@<Begin verbatim@>
Syntax  :
   execute = "execute" s filename {argument_string}
Examples:
   execute megatest.fws /usr/users/ross/fwtest !
   execute sloth
@<End verbatim@>

@<P@>The first example above will result in the following
substitution variable assignments.

@<P@>
@<Begin verbatim@>
$0 = ""
$1 = "/usr/users/ross/fwtest"
$2 = "!"
$3 = ""
...
$9 = ""
@<End verbatim@>

@<P@>It should be stressed that there are no local variables
in the FunnelWeb command language; the variables above are
globally modified.

@<P@>The @<TT@>@(execute@) command was added to allow the
creation of sub-scripts to test FunnelWeb in particular
ways.

@<Nav@>@(@<Commands_eneo FILE@>@,@<Commands FILE@>@,@<Commands_exists FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_exists HEADING@>@M@{@<SH@>@(9.11@)Exists@}
@$@<Commands_exists FILE@>@M@{commands_exists.html@}
@O@<commands_exists.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_exists HEADING@>@)
@<XX@>@(command@,exists@)

@<P@>The @<TT@>@(exists@) command performs no action except
to return a status. If the file specified in its argument
exists it returns success status, otherwise it returns
severe status.

@<P@>
@<Begin verbatim@>
Syntax : exists = "exists" s filename
Example: exists test6.fw
@<End verbatim@>

@<P@>This command is useful in regression testing for
ensuring that FunnelWeb has produced a particular output
file.

@<Nav@>@(@<Commands_execute FILE@>@,@<Commands FILE@>@,@<Commands_fixeols FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_fixeols HEADING@>@M@{@<SH@>@(9.12@)Fixeols@}
@$@<Commands_fixeols FILE@>@M@{commands_fixeols.html@}
@O@<commands_fixeols.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_fixeols HEADING@>@)
@<XX@>@(command@,fixeols@)

@<P@>The @<TT@>@(fixeols@) command takes two filename
arguments: an input file and an output file. It reads in the
input file and writes it to the output file changing all the
end of line control character sequences to the local format.
It can also take one filename argument, in which case it
replaces the target file with its transformation.

@<P@>
@<Begin verbatim@>
Syntax  : fixeols = "fixeols" s filename [s filename]
Examples: fixeols imported.hak result.kln
          fixeols sloth.dat
@<End verbatim@>

@<P@>The @<TT@>@(fixeols@) command works by parsing the
input file into alternating runs of printable characters
(ASCII 20 to ASCII 126) and runs of non-printable characters
(all the others). It then@<XX@>@(non-printable@,characters@)
parses each run of non-printable characters from left to
right into subruns of non-printables not containing the same
character twice. It then replaces each subrun with a native
EOL. (Note: A native EOL can be inserted into a text
file in a portable manner simply by writing
@<DQP@>@(\n@) to the text output stream). For example,
if a native EOL is @<TT@>@(X@), and @<TT@>@(ABCD@) are
non-printable characters, and the file to be converted is

@<P@>
@<Begin verbatim@>
thisABisABCDanABABexampleABCCCof the conversion.
@<End verbatim@>

@<P@>then @<TT@>@(fixeols@) would produce

@<P@>
@<Begin verbatim@>
thisXisXanXXexampleXXXof the conversion.
@<End verbatim@>

@<P@>The @<TT@>@(fixeols@) command was devised to solve the
problem created sometimes when text files are moved from one
machine to another (@<eg@>with the Kermit program) using a
binary transfer mode rather than a text transfer mode. If
such a transfer is made, and the text file line termination
conventions differ on the two machines, one can wind up with
a set of text files with improperly terminated lines. This
can cause problems on a number of fronts, but in particular
affects regression testing which relies heavily on exact
comparisons between files. The @<TT@>@(fixeols@) command
provides a solution to this problem by providing a portable
way to @<DQ@>@(purify@) text files whose end of lines have
become incorrect. The regression testing scripts all apply
@<TT@>@(fixeols@) to their input and output files before
each test.

@<Nav@>@(@<Commands_exists FILE@>@,@<Commands FILE@>@,@<Commands_fw FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_fw HEADING@>@M@{@<SH@>@(9.13@)Fw@}
@$@<Commands_fw FILE@>@M@{commands_fw.html@}
@O@<commands_fw.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_fw HEADING@>@)
@<XX@>@(command@,fw@)

@<P@>The @<TT@>@(fw@) command allows FunnelWeb proper to be
invoked from a shell script. The syntax is almost identical
to the syntax with which FunnelWeb is invoked from the
operating system.

@<P@>
@<Begin verbatim@>
Syntax  : fw = "fw" s ordinary_funnelweb_command_line
Examples: fw sloth +t +d
          fw -l walrus
@<End verbatim@>

@<P@>Some important points about this @<TT@>@(fw@) command
are:

@<P@>
@<Begin list@>
@<Item@>Options are inherited from the default shell options.
@<Item@>The @<TT@>@(F@) (input file option) must be turned on.
@<Item@>The @<TT@>@(K@), @<TT@>@(H@), and @<TT@>@(X@) options must be turned off.
@<Item@>The @<TT@>@(J@) option must be turned off.
@<Item@>The options specified in a @<TT@>@(fw@) command do not affect the default
shell options.
@<Item@>This command performs no action in the OpenVMS version of FunnelWeb.
@<End list@>

@<Nav@>@(@<Commands_fixeols FILE@>@,@<Commands FILE@>@,@<Commands_help FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_help HEADING@>@M@{@<SH@>@(9.14@)Help@}
@$@<Commands_help FILE@>@M@{commands_help.html@}
@O@<commands_help.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_help HEADING@>@)
@<XX@>@(command@,help@)

@<P@>The @<TT@>@(help@) command provides online help from
within the FunnelWeb shell. It provides access to all of the
same messages that the @<TT@>@(+H@) command line option
does.

@<P@>
@<Begin verbatim@>
Syntax  : help = "help" [s help_message_name]
Examples: help
          help commands
@<End verbatim@>

@<P@>If no message name is given, the default message is
displayed. It contains a list of the other help messages and
their names. The actual messages themselves are not listed
here.

@<Nav@>@(@<Commands_fw FILE@>@,@<Commands FILE@>@,@<Commands_here FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_here HEADING@>@M@{@<SH@>@(9.15@)Here@}
@$@<Commands_here FILE@>@M@{commands_here.html@}
@O@<commands_here.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_here HEADING@>@)
@<XX@>@(command@,here@)

@<P@>The @<TT@>@(here@) command acts as a target for the
@<TT@>@(skipto@) command. When the shell interpreter
encounters a @<TT@>@(skipto@) command, it ignores all the
following commands until it encounters a @<TT@>@(here@)
command.

@<P@>
@<Begin verbatim@>
Syntax : here = "here"
Example: here
@<End verbatim@>

@<P@>The @<TT@>@(skipto@)/@<TT@>@(here@) mechanism was
created to allow groups of regression tests to be skipped
during debugging without having to comment them out.

@<Nav@>@(@<Commands_help FILE@>@,@<Commands FILE@>@,@<Commands_quit FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_quit HEADING@>@M@{@<SH@>@(9.16@)Quit@}
@$@<Commands_quit FILE@>@M@{commands_quit.html@}
@O@<commands_quit.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_quit HEADING@>@)
@<XX@>@(command@,quit@)

@<P@>The @<TT@>@(quit@) command terminates FunnelWeb
immediately and returns control to the operating system.
This applies regardless of the depth of the script being
executed.

@<P@>
@<Begin verbatim@>
Syntax : quit = "quit"
Example: quit
@<End verbatim@>

@<Nav@>@(@<Commands_here FILE@>@,@<Commands FILE@>@,@<Commands_set FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_set HEADING@>@M@{@<SH@>@(9.17@)Set@}
@$@<Commands_set FILE@>@M@{commands_set.html@}
@O@<commands_set.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_set HEADING@>@)
@<XX@>@(command@,set@)

@<P@>The @<TT@>@(set@) command modifies the default shell
options. For example, @<TT@>@(set +t@) sets the @<TT@>@(+t@)
option for all subsequent FunnelWeb runs within the shell
until another set command sets @<TT@>@(-t@).

@<P@>
@<Begin verbatim@>
Syntax:
   set = "set" s ordinary_funnelweb_command_line
Examples:
   set sloth +t +d
   set -lwalrus
@<End verbatim@>

@<P@>The restrictions on the @<TT@>@(set@) command are
identical to those on the @<TT@>@(fw@) command except that,
in addition, the @<TT@>@(+F@) option cannot be turned on in
the @<TT@>@(set@) command.

@<P@>The set command is useful for setting option defaults
before a long run of regression tests. It could also be
useful to set default options in a FunnelWeb shell kept by a
user in a workstation window.

@<Nav@>@(@<Commands_quit FILE@>@,@<Commands FILE@>@,@<Commands_show FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_show HEADING@>@M@{@<SH@>@(9.18@)Show@}
@$@<Commands_show FILE@>@M@{commands_show.html@}
@O@<commands_show.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_show HEADING@>@)
@<XX@>@(command@,show@)

@<P@>The @<TT@>@(show@) command displays the current default shell options.
These options are the options that subsequent @<TT@>@(fw@) commands will
inherit.

@<P@>
@<Begin verbatim@>
Syntax : show = "show"
Example: show
@<End verbatim@>

@<Nav@>@(@<Commands_set FILE@>@,@<Commands FILE@>@,@<Commands_skipto FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_skipto HEADING@>@M@{@<SH@>@(9.19@)Skipto@}
@$@<Commands_skipto FILE@>@M@{commands_skipto.html@}
@O@<commands_skipto.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_skipto HEADING@>@)
@<XX@>@(command@,skipto@)

@<P@>The @<TT@>@(skipto@) command causes the shell to ignore
all subsequent commands until a @<TT@>@(here@) command is
encountered.

@<P@>
@<Begin verbatim@>
Syntax  : skipto = "skipto"
Examples: skipto
@<End verbatim@>

@<P@>The @<TT@>@(skipto@)/@<TT@>@(here@) mechanism was
created to allow groups of regression tests to be skipped
during debugging without having to comment them out. It is
like a cut price @<TT@>@(goto@). For example, supposing that
there were eight tests and that you had debugged the first
five. You might want to skip the first five tests so that
you can concentrate on the next three. The following code
shows how this can be done.

@<P@>
@<Begin verbatim@>
skipto
execute test infile1
execute test infile2
execute test infile3
execute test infile4
execute test infile5
here
execute test infile6
execute test infile7
execute test infile8
@<End verbatim@>

@<P@>It should be stressed that FunnelWeb performs full
command line processing including the dollar substitutions
before testing the line to see if it is @<TT@>@(here@). This
can lead to non-obvious problems. For example.

@<P@>
@<Begin verbatim@>
skipto
! Test the Parser
! ---------------
define X "execute parsertest.fws"
$X infile1
$X infile2
$X infile3
$X infile4
$X infile5
here
@<End verbatim@>

@<P@>The above looks correct, but, because the
@<TT@>@(define@) command isn't executed (and @<TT@>@($X@) is
not defined) the subsequent @<TT@>@($X@) lines result in a
leading blanks error. The problem can be corrected by
defining @<TT@>@($X@) before the @<TT@>@(skipto@) command.

@<Nav@>@(@<Commands_show FILE@>@,@<Commands FILE@>@,@<Commands_status FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_status HEADING@>@M@{@<SH@>@(9.20@)Status@}
@$@<Commands_status FILE@>@M@{commands_status.html@}
@O@<commands_status.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_status HEADING@>@)
@<XX@>@(command@,status@)

@<P@>The @<TT@>@(status@) command takes two forms. In its
first form in which no arguments are given, it writes out
the number of warnings, errors and severe errors that 1)
were generated by the previous command and 2) have been
generated during the entire shell invocation. In its second
form it takes from one to three arguments each of which
specifies a diagnostic severity and a number. The
@<TT@>@(status@) command compares each of these numbers with
the number of that diagnostic generated by the previous
command and generates a severe error if they differ.

@<P@>
@<Begin verbatim@>
Syntax  : status = "status" {s ("w"|"e"|"s") num}0..3
Examples: status
          status w1 e5 s1
          status w4
          status s1 e2
@<End verbatim@>

@<P@>The @<TT@>@(status@) command was introduced to test the
status results of commands during their debugging. It is
also useful for checking to see that the right number of
diagnostics have been generated at particular points in test
scripts.

@<Nav@>@(@<Commands_skipto FILE@>@,@<Commands FILE@>@,@<Commands_tolerate FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_tolerate HEADING@>@M@{@<SH@>@(9.21@)Tolerate@}
@$@<Commands_tolerate FILE@>@M@{commands_tolerate.html@}
@O@<commands_tolerate.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_tolerate HEADING@>@)
@<XX@>@(command@,tolerate@)

@<P@>The @<TT@>@(tolerate@) command instructs the shell not
to abort processing of the script if the next command
generates one or more warnings, errors, or severe errors.
For the purposes of this command, a blank line counts as a
command, so be sure to place the @<TT@>@(tolerate@) command
immediately above the command about which you wish to be
tolerant.

@<P@>
@<Begin verbatim@>
Syntax : tolerate = "tolerate"
Example: tolerate
@<End verbatim@>

@<P@>The tolerate command was introduced to allow FunnelWeb
(@<ie@>the @<TT@>@(fw@) command) to be tested in a script
under conditions which would normally cause it to abort the
script.

@<Nav@>@(@<Commands_status FILE@>@,@<Commands FILE@>@,@<Commands_trace FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_trace HEADING@>@M@{@<SH@>@(9.22@)Trace@}
@$@<Commands_trace FILE@>@M@{commands_trace.html@}
@O@<commands_trace.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_trace HEADING@>@)
@<XX@>@(command@,trace@)

@<P@>The @<TT@>@(trace@) command turns on or off command
tracing during script execution. By default, tracing is
turned off.

@<P@>
@<Begin verbatim@>
Syntax  : trace = "trace" [s ("on" | "off")]
Examples: trace on
          trace off
@<End verbatim@>

@<P@>The @<TT@>@(trace@) command was introduced to assist in
the debugging of regression test scripts.

@<Nav@>@(@<Commands_tolerate FILE@>@,@<Commands FILE@>@,@<Commands_write FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_write HEADING@>@M@{@<SH@>@(9.23@)Write@}
@$@<Commands_write FILE@>@M@{commands_write.html@}
@O@<commands_write.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_write HEADING@>@)
@<XX@>@(command@,write@)

@<P@>The @<TT@>@(write@) command accepts a double-quoted
argument and writes it followed by an EOL to the console
(standard output). There is no need to double any double
quotes occurring within the string.

@<P@>
@<Begin verbatim@>
Syntax:
   write = "write" s string
Examples:
   write "Now about to start the next test."
   write "No need to " double enclosed double quotes."
@<End verbatim@>

@<P@>The @<TT@>@(write@) command was added so as to allow
regression testing scripts to inform the user of their
progress.

@<Nav@>@(@<Commands_trace FILE@>@,@<Commands FILE@>@,@<Commands_writeu FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Commands_writeu HEADING@>@M@{@<SH@>@(9.24@)Writeu@}
@$@<Commands_writeu FILE@>@M@{commands_writeu.html@}
@O@<commands_writeu.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Commands_writeu HEADING@>@)
@<XX@>@(command@,writeu@)

@<P@>The @<TT@>@(writeu@) command is identical to the
@<TT@>@(write@) command except that it underlines the text
on an additional following output line.

@<P@>
@<Begin verbatim@>
Syntax  : writeu = "writeu" s string
Examples: writeu "Test 6"
@<End verbatim@>

@<Nav/last@>@(@<Commands_write FILE@>@,@<Commands FILE@>@,@<Commands FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<Gloss@>@(@1@)@M@{<P><B>@1:</B>@}
@$@<glossary@>@M@{@<Link@>@(@<Glossary FILE@>@,glossary@)@}

@$@<Glossary HEADING@>@M@{@<SH@>@(10@)Glossary@}
@$@<Glossary HEADING/short@>@M@{@<SH@>@(10@)Glossary@}
@$@<Glossary FILE@>@M@{glossary.html@}
@O@<glossary.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<Glossary HEADING@>@)

@<Gloss@>@(Analyser@) A component of the FunnelWeb program
that checks the macro table created by the parser for errors.
For example, the analyser checks to see if any macro without a @<TT@>@(@@Z@) has
not been called.

@<Gloss@>@(Argument@) A string delimited by blanks appearing on the FunnelWeb
command line. Arguments are used to control options.

@<Gloss@>@(Directive@) A FunnelWeb special sequence or
cooperating group of special sequences that do not form part of
a macro definition. A directive can take the form of a pragma.

@<Gloss@>@(Documentation@) Descriptive text.

@<Gloss@>@(Documentation file@) An output file, produced by the Weave
component of FunnelWeb, that
contains typesetter commands. When fed into the appropriate typesetter
program, the result is a typeset image of the input file.

@<Gloss@>@(Free text@) The text in an input file that remains
if one were to remove macro definitions and directives.

@<Gloss@>@(FunnelWeb@) This word has a number of different meanings all
pertaining to the FunnelWeb system of programming. 1) The
entire system of programming as in @<DQ@>@(Maybe FunnelWeb can help.@)
2) The computer program that implements the
system as in @<DQ@>@(Run it through FunnelWeb and see what comes out.@)
3) The language implemented by the FunnelWeb program as in @<DQ@>@(I wrote the
program in FunnelWeb.@) or @<DQ@>@(I wrote the program in Ada using FunnelWeb.@).

@<Gloss@>@(FunnelWeb file@) A file whose contents are written in the FunnelWeb
language.

@<Gloss@>@(FunnelWeb language@) The language in which FunnelWeb input files are
written.

@<Gloss@>@(FunnelWeb proper@) Usually, when FunnelWeb is invoked, it processes
a single input file and then terminates. However, it also has a command
language mode in which it is possible to invoke @<DQ@>@(FunnelWeb@) many times.
This leads to confusion between @<DQ@>@(FunnelWeb@) the outer program and
@<DQ@>@(FunnelWeb@) the inner program. To avoid this confusion, the inner
FunnelWeb is sometimes referred to as @<DQ@>@(FunnelWeb proper@).

@<Gloss@>@(FW@) An abbreviation for @<DQ@>@(FunnelWeb@) that is
used wherever appropriate.

@<Gloss@>@(Include file@) A file read in by FunnelWeb as the result of an
include pragma (@<TT@>@(@@i filename@)).

@<Gloss@>@(Input file@) Any file read in by FunnelWeb. The phrase
@<DQ@>@(the input file@) refers to the root input file
(specified using the @<TT@>@(+F@) option).

@<Gloss@>@(Journal file@) An output file containing a copy of the output sent to
the user's console during an invocation of FunnelWeb. In other systems,
this file is sometimes called a @<DQ@>@(log file@).

@<Gloss@>@(Listing file@) An output file summarizing the result of processing
an input file.

@<Gloss@>@(Macro@) A binding of a name to a string.

@<Gloss@>@(Macro definition@) A construct appearing in a FunnelWeb file that
binds a name to a text string.
A FunnelWeb file consists of a series of macro definitions surrounded by
documentary text.

@<Gloss@>@(Mapper@) A component of the FunnelWeb program
that reads in the input file and creates a copy of it in memory.

@<Gloss@>@(Option@) An parameter internal to the FunnelWeb program which can be
controlled by command line arguments or pragmas.

@<Gloss@>@(Output file@) Any file written by FunnelWeb. This includes
listing, journal, product, and documentation files. (Warning: During most
of FunnelWeb's development the term @<DQ@>@(output file@) was also used to
refer to what are now called @<DQ@>@(product files@). This turned out to be
extremely confusing and so the term @<DQ@>@(product file@) was invented to
distinguish the generic from the specific.
However, as this was a late modification,
you may find some occurrences of the old
use of @<DQ@>@(output file@).).

@<Gloss@>@(Parser@) A component of the FunnelWeb program
that processes the token list generated by the scanner and produces a
macro table and a document list. The parser mainly
analyses the input file at the syntactic level, but also does some lightweight
semantic checking too.

@<Gloss@>@(Pragma@) Single-line directives that appears in
FunnelWeb files. Pragmas control everything from maximum input line length
to typesetter dependence. A pragma line starts with @<DQP@>@(@@p@)

@<Gloss@>@(Printed documentation@) Sheets of paper
resulting from actually typesetting and printing a documentation file.

@<Gloss@>@(Product file@) An output file, generated by the Tangle component of
FunnelWeb, that contains the expansion of the macros in the input
file. Note: Other names considered for this were:
generated file, expanded file, result file, program file, and tangle file.

@<Gloss@>@(Scanner@) A component of the FunnelWeb program
that scans a copy of the input file in memory and generates a line list
and a token list to be fed to the parser. The scanner processes the input
at the lexical level.

@<Gloss@>@(Script@) A file containing FunnelWeb shell commands.

@<Gloss@>@(Shell@) A command language interpreter built into the FunnelWeb
program. The interpreter allows the user to invoke FunnelWeb proper
many times during a single invocation of the FunnelWeb program.

@<Gloss@>@(Special character@) A distinguished character
in a FunnelWeb input file that introduces a special sequence.
By default the special
character is @<DQP@>@(@@@). However, it can be changed using the @<DQP@>@(@@=@)
special sequence.

@<Gloss@>@(Special sequence@) A special sequence is a construct introduced by the
special character. Special sequences are used to define a structure in a
FunnelWeb input file that exists at a higher level to the surrounding text.
A FunnelWeb input file may be considered to be a sequence of text and
special sequences.

@<Gloss@>@(Tangle@) This is the name for the component of FunnelWeb that
generates one or more product files containing the expansion of macros
in the input file.

@<Gloss@>@(Typesetting directive@) A FunnelWeb directive whose
sole effect is to modify the way in which the input file is represented
in the documentation file.

@<Gloss@>@(Weave@) This is the name for the component of FunnelWeb that
generates a documentation file containing typesetting commands representing
the input file.

@<Nav@>@(@<Commands FILE@>@,@<Index FILE@>@,@<References FILE@>@)

@<End FWRefMan page@>
@}

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

@$@<References HEADING@>@M@{@<SH@>@(11@)References@}
@$@<References HEADING/short@>@M@{@<SH@>@(11@)References@}
@$@<References FILE@>@M@{references.html@}
@O@<references.html@>@{@-
@<Begin FWRefMan page/H1@>@(@<References HEADING@>@)

@<P@>@<Paper@>@(ANSI@) Australian Standard AS@<_@>3955-1991,
@<DQ@>@(Programming Languages --- C@), (ISBN:
0-7262-6970-0), 12@<_@>July@<_@>1991. Identical to:
International Standard ISO/IEC 9899: 1990 Programming
Languages --- C.

@<P@>@<Paper@>@(ANZE@) @<DQ@>@(Australia, New Zealand
Encyclopedia@), Entry: @<DQ@>@(Funnel-web spiders@),
Vol@<_@>7, pp.@<_@>564--565, Bay Books, Sydney, (ISBN:
85835--127--7), 1975.

@<P@>@<Paper@>@(BSI82@) British Standards Institute,
@<DQ@>@(Specification for Computer Programming Language
Pascal@), Publication BS6192:1982, British Standards
Institute, P.O. Box 372, Milton Keynes, MK146LO, 1982.

@<P@>@<Paper@>@(Gries81@) Gries@<_@>D., @<DQ@>@(The Science of
Programming@), Springer-Verlag, (ISBN: 0-387-90641-X), 1981.

@<P@>@<Paper@>@(Humphries91@) Humphries@<_@>B, @<DQ@>@(Neglected
Poems and Other Creatures@), Angus and Robertson, Sydney,
(ISBN: 0-207-17212-9), 1991.

@<P@>@<Paper@>@(Kernighan88@) Kernighan@<_@>B.W.,
Ritchie@<_@>D.M., @<DQ@>@(The@<_@>C Programming Language@),
(second edition,@<DQ@>@(ANSI@<_@>C@)), Prentice Hall, (ISBN:
0-13-110362-8), 1988.

@<P@>@<Paper@>@(Knuth83@) Knuth@<_@>D.E., @<DQ@>@(The WEB System
of Structured Documentation@), (Web User Manual,
Version@<_@>2.5, November, 1983), Stanford University, 1983.

@<P@>@<Paper@>@(Knuth84@) Knuth@<_@>D.E., @<DQ@>@(The TeXbook@),
Addison-Wesley, (ISBN: 0-201-13448-9), 1984.

@<P@>@<Paper@>@(Knuth84@) Knuth@<_@>D.E., @<DQ@>@(Literate
Programming@), @<I@>@(The Computer Journal@), Vol.@<_@>27,
No.@<_@>2, pp.@<_@>97-111, 1984. (Reference copied
from SIGPLAN 26(1) p.16). Note: The author of this manual
has not yet obtained this paper.

@<P@>@<Paper@>@(Lamport86@) Lamport@<_@>L., @<DQ@>@(LaTeX: A
Document Preparation System@), Addison-Wesley, (ISBN:
0-201-15790-X), 1986.

@<P@>@<Paper@>@(Rosovsky90@) Rosovsky@<_@>H., @<DQ@>@(The
University: An Owner's Manual@), W.W.Norton @<&@> Company,
Inc., (ISBN: 0-393-02782-1), 1990.

@<P@>@<Paper@>@(Smith91@) Smith@<_@>L.M.C., @<DQ@>@(An Annotated
Bibliography of Literate Programming@), ACM SIGPLAN Notices,
Vol.@<_@>26, No.@<_@>1, January 1991.

@<P@>@<Paper@>@(Strunk79@) Strunk@<_@>W., White@<_@>E.B.,
@<DQ@>@(The Elements of Style@), Third Edition, MacMillan
Publishing Company, New York, (ISBN: 0-02-418200-1), 1979.

@<P@>@<Paper@>@(USDOD83@) @<DQ@>@(The Programming Language Ada
Reference Manual@), American National Standards Institute
Inc, ANSI/MIL-STD-1815A-1983, 1983.

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

@<End FWRefMan page@>
@}

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

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

@<FunnelWeb webs copyright page contents@>

@<End FWRefMan page@>
@}

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

@B@<Search Form Section@>

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

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

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

@<End FWRefMan page@>
@}

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

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

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

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

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

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

@<End FWRefMan page@>
@}

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

@O@<search_e_nokeywords.txt@>@{@-
@<Begin FWRefMan 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 FWRefMan page@>
@}

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

@O@<search_e_nomanual.txt@>@{@-
@<Begin FWRefMan 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 FWRefMan 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

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