3.1 Overview

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

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

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

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

The following example demonstrates how all this works. Type in the following as example.fw and run it through FunnelWeb with the command "fw example +t". The "+t" instructs FunnelWeb to generate a documentation file called example.tex. Run the file through TeX and print it. Examine the files example.out and example.tex.

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

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

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

@t new_page

This sentence will appear on the next page.

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

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

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

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

\fwnewpage

This sentence will appear on the next page.

The following points explain the example.tex file.

You don't have to know TeX: If you don't know TeX, don't pay too much attention to this section. You don't need to know TeX to use FunnelWeb.

In order: FunnelWeb has merely transformed the input. It hasn't rearranged it.

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

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

fw sequences: The fw sequences (e.g. \fwbeginmacro) invoke TeX macros defined earlier in the documentation file (and not shown here).

The macro: The macro is typeset using a set of predefined TeX macros. See the printed documentation to see what this looks like on paper.

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

FunnelWeb can also generate documentation in HTML form. Just replace the +t option with the +u option.

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