3.2 Typesetter Independence

FunnelWeb encourages typesetter independence by neutralizing all TeX (or HTML) control sequences before writing them out. The result is that you don't have worry about upsetting or depending on TeX by accidentally including some special character or sequence. By default your input file is typesetter independent.

This scheme differs from other literate programming tools (including very early versions of FunnelWeb) which copy their free text directly to the documentation file, the justification being that the programmer can use the full power of the typesetter language to describe the program. The disadvantages of doing this are first that the programmer is required to know the typesetting language and second that the input file becomes typesetter dependent. FunnelWeb avoids these problems by nobbling the free text be default.

However, FunnelWeb does provide a trapdoor for those who want their free text to be fed directly to TeX. To open the trapdoor, simply include one of the following pragmas somewhere in your input file.

@p typesetter = tex
@p typesetter = html

See the FunnelWeb Reference Manual for more information.

FunnelWeb leaves the degree to which the user wishes to bind a particular document to a particular typesetter up to the user. In some cases, the extra typesetting power may compensate for the lack of portability. However, as a rule, it is best to avoid typesetter-specific commands, so as to allow your input files to be formatted at a later date for different typesetters. FunnelWeb includes a number of its own typesetter commands so as to support typesetter-independent input files. The following sections describe some of these commands. In particular, the next section describes the most powerful FunnelWeb typesetting directives which allow the user to structure the document hierarchically.