Prev: Bugs Up: Preliminaries
1.4 Using this manual
This manual contains a number of examples of `m4' input and output, and
a simple notation is used to distinguish input, output and error
messages from `m4'. Examples are set out from the normal text, and
shown in a fixed width font, like this
This is an example of an example!
To distinguish input from output, all output from `m4' is prefixed
by the string `=>', and all error messages by the string `error-->'.
When showing how command line options affect matters, the command line
is shown with a prompt `$ like this', otherwise, you can assume that a
simple `m4' invocation will work. Thus:
$ command line to invoke m4
Example of input line
=>Output line from m4
error-->and an error message
The sequence `^D' in an example indicates the end of the input file.
The sequence `<NL>' refers to the newline character. The majority of
these examples are self-contained, and you can run them with similar
results by invoking `m4 -d'. In fact, the testsuite that is bundled in
the GNU M4 package consists of the examples in this document! Some of
the examples assume that your current directory is located where you
unpacked the installation, so if you plan on following along, you may
find it helpful to do this now:
$ cd m4-1.4.13
As each of the predefined macros in `m4' is described, a prototype
call of the macro will be shown, giving descriptive names to the
-- Composite: example (STRING, [COUNT = `1'], [ARGUMENT]...)
This is a sample prototype. There is not really a macro named
`example', but this documents that if there were, it would be a
Composite macro, rather than a Builtin. It requires at least one
argument, STRING. Remember that in `m4', there must not be a
space between the macro name and the opening parenthesis, unless
it was intended to call the macro without any arguments. The
brackets around COUNT and ARGUMENT show that these arguments are
optional. If COUNT is omitted, the macro behaves as if count were
`1', whereas if ARGUMENT is omitted, the macro behaves as if it
were the empty string. A blank argument is not the same as an
omitted argument. For example, `example(`a')', `example(`a',`1')',
and `example(`a',`1',)' would behave identically with COUNT set to
`1'; while `example(`a',)' and `example(`a',`')' would explicitly
pass the empty string for COUNT. The ellipses (`...') show that
the macro processes additional arguments after ARGUMENT, rather
than ignoring them.
All macro arguments in `m4' are strings, but some are given special
interpretation, e.g., as numbers, file names, regular expressions, etc.
The documentation for each macro will state how the parameters are
interpreted, and what happens if the argument cannot be parsed
according to the desired interpretation. Unless specified otherwise, a
parameter specified to be a number is parsed as a decimal, even if the
argument has leading zeros; and parsing the empty string as a number
results in 0 rather than an error, although a warning will be issued.
This document consistently writes and uses "builtin", without a
hyphen, as if it were an English word. This is how the `builtin'
primitive is spelled within `m4'.
automatically generated by info2www