3.6.4 DEFINE - Define a user AutoGen macro

This function will define a new macro. You must provide a name for the macro. You do not specify any arguments, though the invocation may specify a set of name/value pairs that are to be active during the processing of the macro.

[+ define foo +]
... macro body with macro functions ...
[+ enddef +]
... [+ foo bar='raw text' baz=<<text expression>> +]

Once the macro has been defined, this new macro can be invoked by specifying the macro name as the first token after the start macro marker. Alternatively, you may make the invocation explicitly invoke a defined macro by specifying INVOKE (see section INVOKE - Invoke a User Defined Macro) in the macro invocation. If you do that, the macro name can be computed with an expression that gets evaluated every time the INVOKE macro is encountered.

Any remaining text in the macro invocation will be used to create new name/value pairs that only persist for the duration of the processing of the macro. The expressions are evaluated the same way basic expressions are evaluated. See section Macro Expression Syntax.

The resulting definitions are handled much like regular definitions, except:

1. The values may not be compound. That is, they may not contain nested name/value pairs.
2. The bindings go away when the macro is complete.
3. The name/value pairs are separated by whitespace instead of semi-colons.
4. Sequences of strings are not concatenated.

NB: The macro is extracted from the template as the template is scanned. You cannot conditionally define a macro by enclosing it in an IF/ENDIF (see section IF - Conditionally Emit a Template Block) macro pair. If you need to dynamically select the format of a DEFINEd macro, then put the flavors into separate template files that simply define macros. INCLUDE (see section INCLUDE - Read in and emit a template block) the appropriate template when you have computed which you need.

Due to this, it is acceptable and even a good idea to place all the DEFINE macros at the end of the template. That puts the main body of the template at the beginning of the file.

This document was generated by Bruce Korb on September, 30 2006 using texi2html 1.76.