m4: Manual
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.18
As each of the predefined macros in 'm4' is described, a prototype
call of the macro will be shown, giving descriptive names to the
arguments, e.g.,
-- 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'.
Info Catalog
m4: Bugs
m4: Preliminaries