1.3 An Architectural Overview

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 input file (also called the FunnelWeb file). The file is processed by passing it through a series of stages called phases. The result is that some output files are generated. A journal file is generated containing a copy of the messages that appear on the console during the FunnelWeb run. A listing file is created containing a summary of the run, including any error messages. A documentation file is generated containing typesetter commands that when fed into a typesetter program will result in printed documentation. Finally, one or more product files are generated containing the result of unscrambling the macro definitions of the input file.

     .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

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

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

The phases are briefly described below.

The Scanner reads 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.

The Parser reads the scanner's token list and parses it, constructing a document list and a macro table. which are passed to later phases.

The Analyser examines 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.

Tangle expands certain macros in the macro table to generate one or more product files.

Weave uses the document list to generate a documentation file.

A single run through these phases constitutes a single invocation of FunnelWeb proper. Most invocations of the 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.