3.1 Format of the Pseudo Macro

The pseudo macro is used to tell AutoGen how to process a template. It tells autogen:

1. The punctuation characters used to demarcate the start of a macro. It may be up to seven characters long and must be the first non-whitespace characters in the file.

2. That start marker must be immediately followed by the marker strings "AutoGen5" and then "template", though capitalization is not important.

The next several components may be intermingled:

1. Zero, one or more suffix specifications tell AutoGen how many times to process the template file. No suffix specifications mean that it is to be processed once and that the generated text is to be written to stdout. The current suffix for each pass can be determined with the (suffix) scheme function (see section 3.4.34 `suffix' - get the current suffix).

   The suffix specification consists of a sequence of POSIX compliant file name characters and, optionally, an equal sign and a file name "printf"-style formatting string. Two string arguments are allowed for that string: the base name of the definition file and the current suffix (that being the text to the left of the equal sign). (Note: "POSIX compliant file name characters" consist of alphanumerics plus the period (.), hyphen (-) and underscore (_) characters.)

2. Comment lines: blank lines, lines starting with a hash mark [#]), and edit mode comments (text between pairs of -*- strings).

3. Scheme expressions may be inserted in order to make configuration changes before template processing begins. It is used, for example, to allow the template writer to specify the shell program that must be used to interpret the shell commands in the template. It can have no effect on any shell commands in the definitions file, as that file will have been processed by the time the pseudo macro is interpreted.

   (setenv "SHELL" "/bin/sh")

   This is extremely useful to ensure that the shell used is the one the template was written to use. By default, AutoGen determines the shell to use by user preferences. Sometimes, that can be the "csh", though.

   The scheme expression can also be used to save a pre-existing output file for later text extraction (see section 3.5.4 `extract' - extract text from another file).

   (shellf "mv -f %1$s.c %1$s.sav" (base-name))

4. Finally, the end-macro marker must be last. It must not begin with a POSIX file name character, and if it begins with an equal sign, then it must be separated from any suffix specification by white space.

It is generally a good idea to use some sort of opening bracket in the starting macro and closing bracket in the ending macro (e.g. {, (, [, or even < in the starting macro). It helps both visually and with editors capable of finding a balancing parenthesis. The closing marker may not begin with an open parenthesis, as that is used to enclose a scheme expression.

It is also helpful to avoid using the comment marker (#); the POSIXly acceptable file name characters period (.), hyphen (-) and underscore (_); and finally, it is advisable to avoid using any of the quote characters double, single or back-quote. But there is no special check for any of these advisories.

As an example, assume we want to use [+ and +] as the start and end macro markers, and we wish to produce a `.c' and a `.h' file, then the first macro invocation will look something like this:

[+ AutoGen5 template -*- Mode: emacs-mode-of-choice -*- h=chk-%s.h c # make sure we don't use csh: (setenv "SHELL" "/bin/sh") +]

The template proper starts after the pseudo-macro. The starting character is either the first non-whitespace character or the first character after the newline that follows the end macro marker.