3.1 Format of the Pseudo Macro

The pseudo-macro starts with up to seven (7) punctuation characters used for the template start-macro marker, followed by the autogen magic marker (autogen5), the template marker (template), zero or more suffix specifications, scheme expressions and the end-macro marker. It may also consist of up to seven (7) punctuation characters. Interspersed may be comment lines (blank lines or lines starting with a hash mark [#]) and edit mode markers (text between pairs of -*- characters).

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") +]

Note 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.

Detailed description:

The starting macro marker must be the first non-white space characters encountered in the file. The marker consists of all the contiguous ASCII punctuation characters found there. With optional intervening white space, this marker must be immediately followed by the keywords, "autogen5" and "template". Capitalization of these words is not important. This is followed by zero, one or more suffix specifications and, possibly, a scheme expression.

Suffix specifications consist 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.) If there are no suffix specifications, then the generated file will be written to the stdout file descriptor.

The scheme expression is intended 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. You can specify the shell as follows:

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

This works because AutoGen examines the value of the SHELL environment variable in order to select the shell to run. If that shell is allowed to be csh, AutoGen will break. If it is allowed to be zsh, AutoGen may break. Your milage may vary.

The pseudo macro ends with an end macro marker. Like the starting macro marker, it consists of a contiguous sequence of arbitrary punctuation characters. However, additionally, it may not begin with any of the POSIX file name characters and it may not contain the start macro marker.

This pseudo macro may appear on one or several lines of text. Intermixed may be comment lines (completely blank or starting with the hash character # in column 1), and file content markers (text between -*- pairs on a single line). This may be used to establish editing "modes" for the file. These are ignored by AutoGen.

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