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