3.15 Pragma: Typesetter

The typesetter pragma allows the user to specify whether the input file is supposed to be typesetter-independent, or whether it contains commands in a particular typesetter language. The pragma has the following syntax.

pragma_typesetter = ps "typesetter" s "="
                    s ("none" | "tex" | "html")

The three forms of the pragma look like this.

@p typesetter = none
@p typesetter = tex
@p typesetter = html

A source file can contain more than one typesetter pragma, but they must all specify the same value. The default is none. The typesetter setting affects two things:

Handling of free text: If the typesetter is not none, Weave writes the free text directly  to the documentation file without changing it whatsoever. This means that if (say) \centerline appears in the input file, it will copied directly to the documentation file. If the typesetter is none, Weave intercepts any characters or sequences that might have a special meaning to the target typesetter and replaces them with typesetter commands to typeset the sequences so that they will appear as they do in the input. For example, if the typesetter is none and the target typesetter is TeX, then if $ (the TeX "mathematics mode" character) appears in the input file, it will be be written to the documentation file as \$.

Restrictions on the target typesetter: If you make your FunnelWeb input file depedent on one particular typesetter, it's important that no attempt be made to generate documentation for a different target format. FunnelWeb enforces this at the Weave stage.

The aim of all this is to ensure that any typesetter dependency is correctly proclaimed. Because none is the default typesetter, a user who creates a source file without a typesetter = x pragma will soon find that the control sequences they are inserting into the source document are appearing verbatim in the printed documentation! In order to activate these sequences, they will be forced to add a typesetter pragma, thus making the dependency explicit.

It may seem strange to place the typesetter setting facility within a pragma (@p) when there is a separate typesetting construct (@t). This has been done to sustain the rule of thumb that says that pragmas do not participate in the parser-level syntax, but typesetter directives do.