(m4.info.gz) Manual

Info Catalog

(m4.info.gz) Bugs

(m4.info.gz) Preliminaries

 
 1.5 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-->'.
 Thus
 
      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 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!
 
    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.info.gz) Bugs

(m4.info.gz) Preliminaries