tt(SUBST) is a general-purpose substitution mechanism for strings appearing in
the input. tt(SUBST) takes two arguments: a search string and a substitution
string.  E.g., after
        verb(
    SUBST(VERSION)(1.00)
        ) 
    YODL transforms all occurrences of tt(VERSION) in its input into 
tt(1.00).

    tt(SUBST) is also useful in situations where multi-character sequences
should be converted to accented characters. E.g., a LaTeX() converter might
define:
        verb(
    SUBST('e)(+NOTRANS(\'{e}))
        )
    Each tt('e) in the input will subsequently be converted to tt(\'e). 

    tt(SUBST) may be used in combination with the command line 
flag tt(-P), as in a invocation
        verb(
    yodl2html -P'SUBST(VERSION)(1.00)' myfile.yo
        )

Another useful substitution might be:
        verb(
    SUBST(_OP_)(CHAR(C)HAR(40))
    SUBST(_CP_)(CHAR(C)HAR(41))
        )

which defines an opening parenthesis (tt(_OP_)) and a closing parenthesis
(tt(_CP_)) as mapped to the tt(CHAR) function. The strings tt(_OP_) and
tt(_CP_) might then be used to produce unbalanced arguments.

Note that:
    itemization(
    it() The first argument of the tt(SUBST) command, the search string, is
taken literally. Yodl does not expand it; the string must be literally
matched in the input.
    it() The second argument, the replacement, is further processed by Yodl. 
Protect this text by tt(NOTRANS) or tt(NOEXPAND) where appropriate.
    )

Substitutions occur extremely early while YODL processes its input files. In
order to process its input files, YODL takes the following steps:
    enumeration(
    eit() It requests input from its lexical scanner (so-called em(tokens))
    eit() Its parser processes the tokens produced by the lexical scanner
    eit() Its parser may send text to an output `object', which 
eventually appears in the output file generated by YODL.
    )
    YODL performs all macro substitutions in step 2, and all character
table conversions in step 3. However, the lexical scanner has access to the
tt(SUBST) definitions: as soon as its lexical analyzer detects a series of
characters matching the defining sequence of a tt(SUBST) definition, it 
replaces that defining sequence by its definition. That definition is then
again read by the lexical scanner. Of course, this definition may, in turn,
contain defining sequences of other tt(SUBST) definitions: these are then 
replaced by their definitions as well. This implies:
    itemization(
    it() Circular definitions may cause the lexical scanner to get stuck in a
replacement loop. It is the responsibility of the author defining tt(SUBST)
definitions to make sure that this doesn't happen.
    it() Neither the parser, nor the output object ever sees the tt(SUBST)
defining character sequences: they only see their definitions.
    )

    In some cases substitutions must be suppressed. Consider double
quoted text strings that are frequently used in programming
languages. E.g., tt("hello world"). The text inside the string should not be
converted by Yodl, but unless substitutions can be suppressed the string
    verb(\
    "\"evil code"
    )\
appears as
    verborg(\
    "\"evil code"
    )
To suppress the interpretation of tt(SUBST) definitions tt(PUSHSUBST),
introduced earlier, can be used. The predefined macro tt(verb) suppresses the
interpretation of tt(SUBST) definitions by starting with tt(PUSHSUBST)tt((0))
and ending with tt(POPSUBST)tt(()).






