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