The pseudo macro is used to tell AutoGen how to process a template.
It tells autogen:
The start macro marker. It consists of 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.
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.
That start marker must be immediately followed by the identifier strings
"AutoGen5" and then "template", though capitalization is not important.
The next several components may be intermingled:
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 SCM suffix).
The suffix specification consists of a sequence of POSIX compliant file name
characters and, optionally, an equal sign and a file name formatting
specification. That specification may be either an ordinary sequence of
file name characters with zero, one or two "%s" formatting sequences in it,
or else it may be a Scheme expression that, when evaluated, produces such a
string. The Scheme result may not be empty. The two string arguments
allowed for that string are 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 the suffix begins with one of these three latter characters and
a formatting string is not specified, then that character is presumed to
be the suffix separator. Otherwise, without a specified format string,
a single period will separate the suffix from the base name in constructing
the output file name.
Shell specification: to specify that the template was written expecting a
particular shell to run the shell commands. By default, the shell used is the
autoconf-ed CONFIG_SHELL. This will usually be /bin/sh. The
shell is specified by a hash mark (#) followed by an exclamation mark
(!) followed by a full-path file name (e.g. /usr/xpg4/bin/sh on
Solaris):
[= Autogen5 Template c
#!/usr/xpg4/bin/sh
=]
Comments: blank lines, lines starting with a hash mark (#) and not
specifying a shell, and edit mode markers (text between pairs of -*-
strings) are all treated as comments.
Some scheme expressions may be inserted in order to make configuration
changes before template processing begins.
before template processing begins means that there is no current
output file, no current suffix and, basically, none of the AutoGen
specific functions
(see AutoGen Functions) may be invoked.
The scheme expression can also be used, for example, to save a pre-existing
output file for later text extraction (see SCM extract).
(shellf "mv -f %1$s.c %1$s.sav" (base-name))
After these must come the end macro marker:
The punctuation characters used to demarcate the end of a macro.
Like the start marker, it must consist of seven or fewer punctuation
characters.
The ending macro marker has a few constraints on its content. Some of
them are just advisory, though. There is no special check for advisory
restrictions.
It must not begin with a POSIX file name character (hyphen -,
underscore _ or period .), the backslash (\) or
open parenthesis ((). These are used to identify a suffix
specification, indicate Scheme code and trim white space.
If it begins with an equal sign, then it
must be separated from any suffix specification by white space.
The closing marker may not begin with an open parenthesis, as that is used
to enclose a scheme expression.
It cannot begin with a backslash, as that is used to indicate white
space trimming after the end macro mark. If, in the body of the template,
you put the backslash character (\) before the end macro mark, then
any white space characters after the mark and through the newline character
are trimmed.
It is also helpful to avoid using the comment marker (#).
It might be seen as a comment within the pseudo macro.
You should avoid using any of the quote characters double,
single or back-quote. It won’t confuse AutoGen, but it might well
confuse you and/or your editor.
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 pseudo macro might 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.