===================================================================
RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/m4/m4.1,v
retrieving revision 1.35
retrieving revision 1.36
diff -c -r1.35 -r1.36
*** src/usr.bin/m4/m4.1	2004/02/17 19:28:31	1.35
--- src/usr.bin/m4/m4.1	2004/05/25 18:41:17	1.36
***************
*** 1,4 ****
! .\"	@(#) $OpenBSD: m4.1,v 1.35 2004/02/17 19:28:31 miod Exp $
  .\"
  .\" Copyright (c) 1989, 1993
  .\"	The Regents of the University of California.  All rights reserved.
--- 1,4 ----
! .\"	@(#) $OpenBSD: m4.1,v 1.36 2004/05/25 18:41:17 espie Exp $
  .\"
  .\" Copyright (c) 1989, 1993
  .\"	The Regents of the University of California.  All rights reserved.
***************
*** 148,174 ****
  provides the following built-in macros.
  They may be redefined, losing their original meaning.
  Return values are null unless otherwise stated.
! .Bl -tag -width changequotexxx
! .It Ic builtin
! Calls a built-in by its name, overriding possible redefinitions.
! .It Ic changecom
  Change the start and end comment sequences.
  The default is the pound sign
  .Pq Sq #
  and the newline character.
  With no arguments comments are turned off.
  The maximum length for a comment marker is five characters.
! .It Ic changequote
  Defines the quote symbols to be the first and second arguments.
  The symbols may be up to five characters long.
  If no arguments are
  given it restores the default open and close single quotes.
! .It Ic decr
! Decrements the argument by 1.
! The argument must be a valid numeric string.
! .It Ic define
! Define a new macro named by the first argument to have the
! value of the second argument.
  Each occurrence of
  .Sq $n
  (where
--- 148,183 ----
  provides the following built-in macros.
  They may be redefined, losing their original meaning.
  Return values are null unless otherwise stated.
! .Bl -tag -width changequote
! .It Fn builtin name
! Calls a built-in by its 
! .Fa name , 
! overriding possible redefinitions.
! .It Fn changecom startcomment endcomment
  Change the start and end comment sequences.
  The default is the pound sign
  .Pq Sq #
  and the newline character.
  With no arguments comments are turned off.
  The maximum length for a comment marker is five characters.
! .It Fn changequote beginquote endquote
  Defines the quote symbols to be the first and second arguments.
  The symbols may be up to five characters long.
  If no arguments are
  given it restores the default open and close single quotes.
! .It Fn decr arg
! Decrements the argument 
! .Fa arg 
! by 1.
! The argument 
! .Fa arg
! must be a valid numeric string.
! .It Fn define name value
! Define a new macro named by the first argument 
! .Fa name 
! to have the
! value of the second argument
! .Fa value .
  Each occurrence of
  .Sq $n
  (where
***************
*** 187,197 ****
  is the same as
  .Sq $*
  but all arguments are quoted against further expansion.
! .It Ic defn
  Returns the quoted definition for each argument.
  This can be used to rename
  macro definitions (even for built-in macros).
! .It Ic divert
  There are 10 output queues (numbered 0-9).
  At the end of processing
  .Nm m4
--- 196,206 ----
  is the same as
  .Sq $*
  but all arguments are quoted against further expansion.
! .It Fn defn name ...
  Returns the quoted definition for each argument.
  This can be used to rename
  macro definitions (even for built-in macros).
! .It Fn divert num
  There are 10 output queues (numbered 0-9).
  At the end of processing
  .Nm m4
***************
*** 205,220 ****
  Returns the current output queue number.
  .It Ic dnl
  Discard input characters up to and including the next newline.
! .It Ic dumpdef
  Prints the names and definitions for the named items, or for everything
  if no arguments are passed.
! .It Ic errprint
  Prints the first argument on the standard error output stream.
! .It Ic esyscmd
  Passes its first argument to a shell and returns the shell's standard output.
  Note that the shell shares its standard input and standard error with
  .Nm m4 .
! .It Ic eval
  Computes the first argument as an arithmetic expression using 32-bit
  arithmetic.
  Operators are the standard C ternary, arithmetic, logical,
--- 214,229 ----
  Returns the current output queue number.
  .It Ic dnl
  Discard input characters up to and including the next newline.
! .It Fn dumpdef name ...
  Prints the names and definitions for the named items, or for everything
  if no arguments are passed.
! .It Fn errprint msg
  Prints the first argument on the standard error output stream.
! .It Fn esyscmd cmd
  Passes its first argument to a shell and returns the shell's standard output.
  Note that the shell shares its standard input and standard error with
  .Nm m4 .
! .It Fn eval expr
  Computes the first argument as an arithmetic expression using 32-bit
  arithmetic.
  Operators are the standard C ternary, arithmetic, logical,
***************
*** 224,233 ****
  The second argument (if any)
  specifies the radix for the result and the third argument (if any)
  specifies the minimum number of digits in the result.
! .It Ic expr
  This is an alias for
  .Ic eval .
! .It Ic ifdef
  If the macro named by the first argument is defined then return the second
  argument, otherwise the third.
  If there is no third argument, the value is
--- 233,242 ----
  The second argument (if any)
  specifies the radix for the result and the third argument (if any)
  specifies the minimum number of digits in the result.
! .It Fn expr expr
  This is an alias for
  .Ic eval .
! .It Fn ifdef name yes no
  If the macro named by the first argument is defined then return the second
  argument, otherwise the third.
  If there is no third argument, the value is
***************
*** 235,251 ****
  The word
  .Qq unix
  is predefined.
! .It Ic ifelse
! If the first argument matches the second argument then
! .Ic ifelse
  returns
! the third argument.
  If the match fails the three arguments are
  discarded and the next three arguments are used until there is
  zero or one arguments left, either this last argument or
  .Dv NULL
  is returned if no other matches were found.
! .It Ic include
  Returns the contents of the file specified in the first argument.
  If the file is not found as is, look through the include path:
  first the directories specified with
--- 244,265 ----
  The word
  .Qq unix
  is predefined.
! .It Fn ifelse a b yes ...
! If the first argument 
! .Fa a
! matches the second argument 
! .Fa b
! then
! .Fn ifelse
  returns
! the third argument
! .Fa yes .
  If the match fails the three arguments are
  discarded and the next three arguments are used until there is
  zero or one arguments left, either this last argument or
  .Dv NULL
  is returned if no other matches were found.
! .It Fn include name
  Returns the contents of the file specified in the first argument.
  If the file is not found as is, look through the include path:
  first the directories specified with
***************
*** 254,297 ****
  .Ev M4PATH ,
  as a colon-separated list of directories.
  Include aborts with an error message if the file cannot be included.
! .It Ic incr
  Increments the argument by 1.
  The argument must be a valid numeric string.
! .It Ic index
  Returns the index of the second argument in the first argument (e.g.,
  .Ic index(the quick brown fox jumped, fox)
  returns 16).
  If the second
  argument is not found index returns \-1.
! .It Ic indir
  Indirectly calls the macro whose name is passed as the first argument,
  with the remaining arguments passed as first, ... arguments.
! .It Ic len
  Returns the number of characters in the first argument.
  Extra arguments
  are ignored.
! .It Ic m4exit
  Immediately exits with the return value specified by the first argument,
  0 if none.
! .It Ic m4wrap
  Allows you to define what happens at the final
  .Dv EOF ,
  usually for cleanup purposes (e.g.,
  .Ic m4wrap("cleanup(tempfile)")
  causes the macro cleanup to be
  invoked after all other processing is done).
! .It Ic maketemp
  Invokes
  .Xr mkstemp 3
  on the first argument, and returns the modified string.
  This can be used to create unique
  temporary file names.
! .It Ic paste
  Includes the contents of the file specified by the first argument without
  any macro processing.
  Aborts with an error message if the file cannot be
  included.
! .It Ic patsubst
  Substitutes a regular expression in a string with a replacement string.
  Usual substitution patterns apply: an ampersand
  .Pq Sq \&&
--- 268,311 ----
  .Ev M4PATH ,
  as a colon-separated list of directories.
  Include aborts with an error message if the file cannot be included.
! .It Fn incr arg
  Increments the argument by 1.
  The argument must be a valid numeric string.
! .It Fn index string substring
  Returns the index of the second argument in the first argument (e.g.,
  .Ic index(the quick brown fox jumped, fox)
  returns 16).
  If the second
  argument is not found index returns \-1.
! .It Fn indir macro arg1 ...
  Indirectly calls the macro whose name is passed as the first argument,
  with the remaining arguments passed as first, ... arguments.
! .It Fn len arg
  Returns the number of characters in the first argument.
  Extra arguments
  are ignored.
! .It Fn m4exit code
  Immediately exits with the return value specified by the first argument,
  0 if none.
! .It Fn m4wrap todo
  Allows you to define what happens at the final
  .Dv EOF ,
  usually for cleanup purposes (e.g.,
  .Ic m4wrap("cleanup(tempfile)")
  causes the macro cleanup to be
  invoked after all other processing is done).
! .It Fn maketemp template
  Invokes
  .Xr mkstemp 3
  on the first argument, and returns the modified string.
  This can be used to create unique
  temporary file names.
! .It Fn paste file
  Includes the contents of the file specified by the first argument without
  any macro processing.
  Aborts with an error message if the file cannot be
  included.
! .It Fn patsubst string regexp replacement
  Substitutes a regular expression in a string with a replacement string.
  Usual substitution patterns apply: an ampersand
  .Pq Sq \&&
***************
*** 301,361 ****
  where
  .Sq #
  is a digit, is replaced by the corresponding back-reference.
! .It Ic popdef
  Restores the
  .Ic pushdef Ns ed
  definition for each argument.
! .It Ic pushdef
  Takes the same arguments as
  .Ic define ,
  but it saves the definition on a
  stack for later retrieval by
! .Ic popdef .
! .It Ic regexp
  Finds a regular expression in a string.
  If no further arguments are given,
  it returns the first match position or \-1 if no match.
  If a third argument
  is provided, it returns the replacement string, with sub-patterns replaced.
! .It Ic shift
  Returns all but the first argument, the remaining arguments are
  quoted and pushed back with commas in between.
  The quoting
  nullifies the effect of the extra scan that will subsequently be
  performed.
! .It Ic sinclude
  Similar to
  .Ic include ,
  except it ignores any errors.
! .It Ic spaste
  Similar to
! .Ic paste ,
  except it ignores any errors.
! .It Ic substr
  Returns a substring of the first argument starting at the offset specified
  by the second argument and the length specified by the third argument.
  If no third argument is present it returns the rest of the string.
! .It Ic syscmd
  Passes the first argument to the shell.
  Nothing is returned.
  .It Ic sysval
  Returns the return value from the last
  .Ic syscmd .
! .It Ic traceon
  Enables tracing of macro expansions for the given arguments, or for all
  macros if no argument is given.
! .It Ic traceoff
  Disables tracing of macro expansions for the given arguments, or for all
  macros if no argument is given.
! .It Ic translit
  Transliterate the characters in the first argument from the set
  given by the second argument to the set given by the third.
  You cannot use
  .Xr tr 1
  style abbreviations.
! .It Ic undefine
  Removes the definition for the macros specified by its arguments.
! .It Ic undivert
  Flushes the named output queues (or all queues if no arguments).
  .It Ic unix
  A pre-defined macro for testing the OS platform.
--- 315,375 ----
  where
  .Sq #
  is a digit, is replaced by the corresponding back-reference.
! .It Fn popdef arg ...
  Restores the
  .Ic pushdef Ns ed
  definition for each argument.
! .It Fn pushdef macro def
  Takes the same arguments as
  .Ic define ,
  but it saves the definition on a
  stack for later retrieval by
! .Fn popdef .
! .It Fn regexp string regexp replacement
  Finds a regular expression in a string.
  If no further arguments are given,
  it returns the first match position or \-1 if no match.
  If a third argument
  is provided, it returns the replacement string, with sub-patterns replaced.
! .It Fn shift arg1 ...
  Returns all but the first argument, the remaining arguments are
  quoted and pushed back with commas in between.
  The quoting
  nullifies the effect of the extra scan that will subsequently be
  performed.
! .It Fn sinclude file
  Similar to
  .Ic include ,
  except it ignores any errors.
! .It Fn spaste file
  Similar to
! .Fn paste ,
  except it ignores any errors.
! .It Fn substr string offset length
  Returns a substring of the first argument starting at the offset specified
  by the second argument and the length specified by the third argument.
  If no third argument is present it returns the rest of the string.
! .It Fn syscmd cmd
  Passes the first argument to the shell.
  Nothing is returned.
  .It Ic sysval
  Returns the return value from the last
  .Ic syscmd .
! .It Fn traceon arg ...
  Enables tracing of macro expansions for the given arguments, or for all
  macros if no argument is given.
! .It Fn traceoff arg ...
  Disables tracing of macro expansions for the given arguments, or for all
  macros if no argument is given.
! .It Fn translit string mapfrom mapto
  Transliterate the characters in the first argument from the set
  given by the second argument to the set given by the third.
  You cannot use
  .Xr tr 1
  style abbreviations.
! .It Fn undefine name1 ...
  Removes the definition for the macros specified by its arguments.
! .It Fn undivert arg ...
  Flushes the named output queues (or all queues if no arguments).
  .It Ic unix
  A pre-defined macro for testing the OS platform.