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")
The two forms of the pragma look like this.
@ typesetter = none @ typesetter = tex
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:At a later date, different weave modules might be incorporated into FunnelWeb to cater for a variety of different typesetters. If this happens, it will be important to ensure that typesetter-specific source files (typesetter ≠ none) are not processed with different target typesetters. For example, a user might innocently attempt to generate a troff documentation file from a FunnelWeb source file containing a typesetter = tex (and by implication TEX control sequences). The pragma could also be useful for catching typesetter clashes in source and include files. The setting none is special because it is guaranteed to work with any future target typesetter.
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.