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 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.
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 (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}.
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.