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 typeset1.4 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 $\backslash$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.
1cm 1cm 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.
1cm 1cm In order: FunnelWeb has merely transformed the input. It hasn't rearranged it.
1cm 1cm 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.
1cm 1cm 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.
1cm 1cm fw sequences: The fw sequences (e.g. \fwbeginmacro) invoke TEX macros defined earlier in the documentation file (and not shown here).
1cm 1cm 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.
1cm 1cm 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}''.
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.