more M4sh documentation

[Ralf Wildenhues]

The M4sh macros are quite useful also outside of Autoconf.
OK to apply this to document some of them?

BTW, there is one more, _AS_PREPARE, that is currently used
by CVS Libtool.  A bit ugly, I know; it's not clear to me
whether that should be publicly documented, but also it's
not easy to avoid it in Libtool: it's used there to create
an early `libtool' script, which otherwise would be done by
config.status.

Note I just took the current implementation of AC_CHECK_FUNC
because it's a nice example for AS_VAR*, and uses only
publicly documented interfaces itself.

Cheers,
Ralf

        * doc/autoconf.texi (Programming in M4sh): Move documentation of
        AS_SET_CATFILE.  Document AS_COPYRIGHT, AS_EXECUTABLE_P,
        AS_LITERAL_IF, AS_LN_S, AS_TMPDIR, AS_VERSION_COMPARE,
        AS_VAR_GET, AS_VAR_SET, AS_VAR_SET_IF, AS_VAR_TEST_SET,
        AS_VAR_PUSHDEF, AS_VAR_POPDEF.  Add AC_CHECK_FUNC implementation
        as example for variable accessor usage.
        (Limitations of Usual Tools) <mktemp>: Refer to AS_TMPDIR.

Index: doc/autoconf.texi
===================================================================
RCS file: /cvsroot/autoconf/autoconf/doc/autoconf.texi,v
retrieving revision 1.968
diff -u -r1.968 autoconf.texi
--- doc/autoconf.texi   17 Mar 2006 19:32:53 -0000      1.968
+++ doc/autoconf.texi   20 Mar 2006 13:12:57 -0000
@@ -9339,6 +9339,17 @@
 corresponding pattern matched @var{word}, else @var{default} is run.
 @end defmac
 
address@hidden AS_COPYRIGHT (@var{copyright-notice})
address@hidden
address@hidden Copyright Notice
+State that, in addition to the Free Software Foundation's copyright on
+the M4sh macros, parts of your script are covered by
address@hidden
+
+The @var{copyright-notice} will show up in both the head of
+the generated script and in its @samp{--version} output.
address@hidden defmac
+
 @defmac AS_DIRNAME (@var{file-name})
 @asindex{DIRNAME}
 Return the directory portion of @var{file-name}, using the algorithm
@@ -9347,6 +9358,12 @@
 @command{dirname} command.
 @end defmac
 
address@hidden AS_EXECUTABLE_P (@var{file-name})
address@hidden
+Check whether @file{file-name} is executable (@pxref{Limitations of
+Builtins}).
address@hidden defmac
+
 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
 @asindex{IF}
 Run shell code @var{test1}.  If @var{test1} exits with a zero status then
@@ -9366,6 +9383,24 @@
 be expanded before the first test.
 @end defmac
 
address@hidden AS_LITERAL_IF (@var{expression}, @var{if-literal}, 
@var{if-not-literal})
address@hidden
+If @var{expression} contains shell indirections such as parameter
+expansion @samp{$var} or command substitution @samp{`command`}, expand
+to @var{if-not-literal}, else expand to @var{if-literal}.  The macro
+only approximates the answer, as some literals will not be recognized as
+such.  It may be used to create macros that are polymorphic to M4 and
+shell arguments, or to cope with variables both without and with
+indirection, such as @samp{ac_cv_$var}.
address@hidden defmac
+
address@hidden AS_LN_S (@var{file}, @var{link})
address@hidden
+Link @file{file} to @file{link} using @samp{ln -s} if the operating
+system and file system support symbolic links, otherwise using @samp{ln}
+if that works, otherwise using @samp{cp -p}.
address@hidden defmac
+
 @defmac AS_MKDIR_P (@var{file-name})
 @asindex{MKDIR_P}
 Make the directory @var{file-name}, including intervening directories
@@ -9377,6 +9412,13 @@
 succeed in that case.
 @end defmac
 
address@hidden AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
address@hidden
+Set the shell variable @var{var} to @var{dir}/@var{file}, but
+optimizing the common cases (@var{dir} or @var{file} is @samp{.},
address@hidden is absolute, etc.).
address@hidden defmac
+
 @defmac AS_SHELL_SANITIZE
 @asindex{SHELL_SANITIZE}
 Initialize the shell suitably for @code{configure} scripts.  This has
@@ -9386,6 +9428,18 @@
 @xref{Special Shell Variables}.
 @end defmac
 
address@hidden AS_TMPDIR (@var{prefix}, @dvar{directory, $TMPDIR})
address@hidden
+Create a temporary directory in @var{directory}, as safely as possible
+(@pxref{Limitations of Usual Tools}).
address@hidden defaults to @env{TMPDIR}, which is defaulted to
address@hidden/tmp}.  The @var{prefix} should be up to 4 characters long and
+indicate the script responsible for the directory.  If successful,
+set @env{tmp} to the name of the newly created directory, otherwise
+terminate the script.  No provision for the removal of @samp{$tmp} is
+made.
address@hidden defmac
+
 @defmac AS_TR_CPP (@var{expression})
 @asindex{TR_CPP}
 Transform @var{expression} into a valid right-hand side for a C @code{#define}.
@@ -9410,13 +9464,71 @@
 @end example
 @end defmac
 
address@hidden AS_SET_CATFILE (@var{var}, @var{dir}, @var{file})
address@hidden
-Set the shell variable @var{var} to @var{dir}/@var{file}, but
-optimizing the common cases (@var{dir} or @var{file} is @samp{.},
address@hidden is absolute, etc.).
address@hidden AS_VERSION_COMPARE (@var{version-1}, @var{version-2}, 
@ovar{action-if-less}, @ovar{action-if-greater}, @ovar{action-if-greater})
address@hidden
+Compare two version strings @var{version-1} and @var{version-2} in a way
+compatible with glibc strverscmp (@pxref{String/Array Comparison, , ,
+libc, @acronym{GNU} libc})
address@hidden defmac
+
+With the help of @samp{AS_LITERAL_IF}, it is possible to unify the
+handling of M4 and shell variables together with indirections to some
+extent.  M4sh offers a few helper macros to this end:
+
address@hidden AS_VAR_GET (@var{variable})
address@hidden
+Get the value of shell variable @var{variable}.
address@hidden defmac
+
address@hidden AS_VAR_SET (@var{variable}, @var{value})
address@hidden
+Set the shell variable @var{variable} to @var{value}.
address@hidden defmac
+
address@hidden AS_VAR_SET_IF (@var{variable}, @var{if-true}, @var{if-false})
address@hidden
+If shell variable @var{variable} is set, expand @var{if-true}, else
+expand @var{if-false}.
address@hidden defmac
+
address@hidden AS_VAR_TEST_SET (@var{variable})
address@hidden
+Expand into the @command{test} expression which determines whether
address@hidden is set.  This macro should be followed by @samp{dnl}.
address@hidden defmac
+
address@hidden AS_VAR_PUSHDEF (@var{varname}, @var{value})
address@hidden
+Define a M4 variable @var{varname} as an accessor to the shell variable
address@hidden, including indirections.  @var{varname} should be accessed
+with the @samp{AS_VAR_*} macros described above, and needs to be
+undefined with @samp{AS_VAR_POPDEF} at the end of the block.  This macro
+should be followed by @samp{dnl}.
 @end defmac
 
address@hidden AS_VAR_POPDEF (@var{varname})
address@hidden
+Undefine the M4 variable @var{varname} previously defined by
address@hidden  This macro should be followed by @samp{dnl}.
address@hidden defmac
+
address@hidden
+A possible implementation of @samp{AC_CHECK_FUNC} demonstrates the use
+of these accessor macros.  Note that it allows both literals and shell
+variables in the first argument:
+
address@hidden
+AC_DEFUN([AC_CHECK_FUNC],
+[AS_VAR_PUSHDEF([ac_var], [ac_cv_func_$1])dnl
+AC_CACHE_CHECK([for $1], ac_var,
+[AC_LINK_IFELSE([AC_LANG_FUNC_LINK_TRY([$1])],
+               [AS_VAR_SET(ac_var, yes)],
+               [AS_VAR_SET(ac_var, no)])])
+AS_IF([test AS_VAR_GET(ac_var) = yes], [$2], [$3])dnl
+AS_VAR_POPDEF([ac_var])dnl
+])
address@hidden example
+
 
 @node File Descriptor Macros
 @section File Descriptor Macros
@@ -12636,7 +12748,8 @@
 gaining control, though @command{mktemp} is far less likely to fail
 gratuitously under attack.
 
-Here is sample code to create a new temporary directory safely:
+Here is sample code to create a new temporary directory safely; it
+corresponds to @code{AS_TMPDIR} (@pxref{Programming in M4sh}):
 
 @example
 # Create a temporary directory $tmp in $TMPDIR (default /tmp).