Command:   m4  macro processor
     Syntax:    m4 [D name = value] [U name]
     Flags:     D   Define a symbol
     Flags:     U   Undefine a symbol
     Example:   m4 <m4test               # Run M4

     M4 is a macro processor intended as a front end for  Ratfor,
     Pascal,  and  other  languages  that  do not have a built-in
     macro processing capability.  M4 reads standard  input,  the
     processed text is written on the standard output.

     The options and their effects are as follows:

          D name[=val]Defines name to val, or to  null  in  val's
          absence.
          U name      Undefines name.


     Macro calls have the form: name(arg1,arg2, ..., argn)

     The '(' must immediately follow the name of  the  macro.  If
     the  name  of  a  defined macro is not followed by a ( it is
     taken to be a call of that macro  with  no  arguments,  i.e.
     name().  Potential macro names consist of alphabetic letters
     and digits.

     Leading unquoted blanks, tabs and newlines are ignored while
     collecting arguments.  Left and right single quotes are used
     to quote strings.  The value  of  a  quoted  string  is  the
     string stripped of the quotes.

     When a macro name is recognized, its arguments are collected
     by  searching for a matching ).  If fewer arguments are sup-
     plied than are in the macro definition, the  trailing  argu-
     ments  are taken to be null.  Macro evaluation proceeds nor-
     mally during the collection of the arguments, and any commas
     or  right  parentheses  which  happen  to turn up within the
     value of a nested call are as effective as those in the ori-
     ginal  input  text.  (This is typically referred as  inside-
     out macro expansion.)  After argument collection, the  value
     of  the  macro is pushed back onto the input stream and res-
     canned.

     M4 makes available the following built-in macros.  They  may
     be  redefined, but once this is done the original meaning is
     lost.  Their values are null unless otherwise stated.

     define "(name [, val])" the second argument is installed  as
     the value of the macro whose name is the first argument.  If
     there is no  second  argument,  the  value  is  null.   Each
     occurrence  of  $  n  in  the replacement text, where n is a
     digit, is replaced by the n -th argument.  Argument 0 is the
     name  of  the  macro;  missing arguments are replaced by the
     null string.

     defn "(name [, name ...])" returns the quoted definition  of
     its argument(s). Useful in renaming macros.

     undefine "(name [, name ...])" removes the definition of the
     macro(s) named. If there is more than one definition for the
     named macro, (due to previous use of  pushdef)  all  defini-
     tions are removed.

     pushdef "(name [, val])" like define, but saves any previous
     definition by stacking the current definition.

     popdef "(name [, name ...])" removes current  definition  of
     its argument(s), exposing the previous one if any.

     ifdef "(name, if-def [, ifnot-def])" if the  first  argument
     is  defined, the value is the second argument, otherwise the
     third.  If there is no third argument, the value is null.  A
     word  indicating the current operating system is predefined.
     (e.g. unix or vms).

     shift "(arg, arg, arg, ...)" returns all but its first argu-
     ment.   The  other arguments are quoted and pushed back with
     commas in between.  The quoting nullifies the effect of  the
     extra scan that will subsequently be performed.

     changequote "(lqchar, rqchar)" change quote symbols  to  the
     first  and  second arguments.  With no arguments, the quotes
     are reset back to the default characters. (i.e., `').

     changecom "(lcchar, rcchar)" change left and  right  comment
     markers  from the default # and newline.  With no arguments,
     the comment mechanism is reset back to the  default  charac-
     ters.   With one argument, the left marker becomes the argu-
     ment and the right marker becomes newline.  With  two  argu-
     ments, both markers are affected.

     divert "(divnum)" maintains 10 output streams, numbered 0-9.
     Initially  stream  0 is the current stream. The divert macro
     changes the current  output  stream  to  its  (digit-string)
     argument.   Output diverted to a stream other than 0 through
     9 is lost.

     undivert "([divnum [, divnum ...]])" causes immediate output
     of  text from diversions named as argument(s), or all diver-
     sions if no argument.  Text may be undiverted  into  another
     diversion.   Undiverting  discards the diverted text. At the
     end of input processing, M4  forces  an  automatic  undivert
     unless is defined.

     divnum "()" returns the value of the current output stream.

     dnl "()" reads and discards characters up to  and  including
     the next newline.

     ifelse "(arg, arg, if-same [, ifnot-same | arg,  arg  ...])"
     has  three  or more arguments.  If the first argument is the
     same string as the second, then the value is the third argu-
     ment.   If  not,  and if there are more than four arguments,
     the process is repeated with arguments 4, 5, 6 and 7.   Oth-
     erwise,  the value is either the fourth string, or, if it is
     not present, null.

     incr "(num)" returns the value of its  argument  incremented
     by 1.  The value of the argument is calculated by interpret-
     ing an initial digit-string as a decimal number.

     decr "(num)" returns the value of its  argument  decremented
     by 1.

     eval "(expression)" evaluates its  argument  as  a  constant
     expression,   using   integer  arithmetic.   The  evaluation
     mechanism is very similar to that of cpp  (#if  expression).
     The  expression can involve only integer constants and char-
     acter constants, possibly connected by the binary operators
          *    /    %    +    -    >>   <<    <     >    <=    >=
          ==   !=   &    ^    |     &&   ||
     or the unary operators - ! or tilde or by the ternary opera-
     tor  ?  :  .  Parentheses  may  be  used for grouping. Octal
     numbers may be specified as in C.

     len "(string)" returns the number of characters in its argu-
     ment.

     index "(search-string, string)" returns the position in  its
     first  argument  where the second argument begins (zero ori-
     gin), or 1 if the second argument does not occur.

     substr "(string, index [, length])" returns a  substring  of
     its  first  argument.  The  second argument is a zero origin
     number selecting the first character (internally treated  as
     an  expression);  the third argument indicates the length of
     the substring.  A missing third  argument  is  taken  to  be
     large enough to extend to the end of the first string.

     translit  "(source, from [, to])" transliterates the charac-
     ters  in its first argument from the set given by the second
     argument to the set given by the third.  If the third  argu-
     ment is shorter than the second, all extra characters in the
     second argument are deleted from the first argument. If  the
     third  argument is missing altogether, all characters in the
     second argument are deleted from the first argument.
     include "(filename)" returns the contents of the  file  that
     is named in the argument.

     sinclude "(filename)"is identical to include, except that it
     says nothing if the file is inaccessable.

     paste "(filename)" returns the contents of the file named in
     the argument without any processing, unlike include.

     spaste "(filename)" is identical to paste,  except  that  it
     says nothing if the file is inaccessibl[De.

     syscmd "(command)" executes the UNIX command  given  in  the
     first argument. No value is returned.

     sysval "()" is the return code from the last call to syscmd.
      .PP maketemp '(string)" fills in a string of XXXXXX in  its
     argument with the current process ID.

     m4exit "([exitcode])" causes immediate exit from M4.   Argu-
     ment 1, if given, is the exit code; the default is 0.

     m4wrap "(m4-macro-or-built-n)" argument  1  will  be  pushed
     back at final EOF; example: m4wrap(`dumptable()').

     errprint "(str [, str, str, ...])" prints its argument(s) on
     stderr. If there is more than one argument, each argument is
     separated by a space during the output.  An arbitrary number
     of arguments may be supplied.

     dumpdef "([name,  name,  ...])"  prints  current  names  and
     definitions, for the named items, or for all if no arguments
     are given.


     Author


     M4 was written by Ozan S. Yigif.