document AS_SHELL_SANITIZE and AS_BOURNE_COMPATIBLE (was: Word splitting with zsh fix)

[Ralf Wildenhues]

Dearest autoconf-patches readers,  ;-)

* somewhere in http://thread.gmane.org/gmane.comp.gnu.libtool.bugs/5298:
> 
> In the shell wrapper, we need the effect of _AS_BOURNE_COMPATIBLE, but
> not AS_SHELL_SANITIZE: the executed program should run in the user's
> locale.

> I'll write to autoconf-patches to have a public version of the macro.
> When we can rely on a released Autoconf version with the published
> macro, we can simplify the shell wrapper head[...]

CVS Libtool currently does the unspeakable (again), by using an
undocumented macro from Autoconf.  And now we'd like to use another one
even, at least at some point in the future.  Trying to be good m4tizens
and to minimize stepping on toes, how about if Autoconf documented
AS_SHELL_SANITIZE and AS_BOURNE_COMPATIBLE?  As you might have guessed,
the latter would do just what _AS_BOURNE_COMPATIBLE does now.

OK to apply?  Would you rather keep _AS_BOURNE_COMPATIBLE and have
just a wrapper
  m4_defun([AS_BOURNE_COMPATIBLE], [_AS_BOURNE_COMPATIBLE])
instead?  Or something entirely different?  _AS_BOURNE_COMPATIBLE has
not been in an released Autoconf version, so renaming should not be a
big issue, I guess.

Cheers,
Ralf

        * lib/m4sugar/m4sh.m4 (_AS_BOURNE_COMPATIBLE): Renamed to..
        (AS_BOURNE_COMPATIBLE): ..this.
        (_AS_RUN, AS_SHELL_SANITIZE): Adjusted all callers.
        * doc/autoconf.texi (Programming in M4sh): Document
        AS_BOURNE_COMPATIBLE and AS_SHELL_SANITIZE.

Index: doc/autoconf.texi
===================================================================
RCS file: /cvsroot/autoconf/autoconf/doc/autoconf.texi,v
retrieving revision 1.945
diff -u -r1.945 autoconf.texi
--- doc/autoconf.texi   10 Feb 2006 10:32:33 -0000      1.945
+++ doc/autoconf.texi   13 Feb 2006 17:53:11 -0000
@@ -8992,6 +8992,11 @@
 M4sh provides portable alternatives for some common shell constructs
 that unfortunately are not portable in practice.
 
address@hidden AS_BOURNE_COMPATIBLE
address@hidden
+Initialize the shell to be (more) Bourne and POSIX-compatible, if possible.
address@hidden defmac
+
 @defmac AS_DIRNAME (@var{file-name})
 @asindex{DIRNAME}
 Return the directory portion of @var{file-name}, using the algorithm
@@ -9018,6 +9023,14 @@
 succeed in that case.
 @end defmac
 
address@hidden AS_SHELL_SANITIZE
address@hidden
+Initialize the shell suitable for @code{configure} scripts.  This macro
+has the effect of @code{AS_BOURNE_COMPATIBLE}, and also sanitizes the
+locale and some other environment variables for predictable results
+from configuration tests, see @ref{Special Shell Variables}.
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}.
Index: lib/m4sugar/m4sh.m4
===================================================================
RCS file: /cvsroot/autoconf/autoconf/lib/m4sugar/m4sh.m4,v
retrieving revision 1.157
diff -u -r1.157 m4sh.m4
--- lib/m4sugar/m4sh.m4 13 Feb 2006 07:45:03 -0000      1.157
+++ lib/m4sugar/m4sh.m4 13 Feb 2006 17:53:11 -0000
@@ -157,10 +157,10 @@
 }])])])
 
 
-# _AS_BOURNE_COMPATIBLE
-# ---------------------
+# AS_BOURNE_COMPATIBLE
+# --------------------
 # Try to be as Bourne and/or POSIX as possible.
-m4_define([_AS_BOURNE_COMPATIBLE],
+m4_define([AS_BOURNE_COMPATIBLE],
 [# Be Bourne compatible
 if test -n "${ZSH_VERSION+set}" && (emulate sh) >/dev/null 2>&1; then
   emulate sh
@@ -184,7 +184,7 @@
 m4_define([_AS_RUN],
 [m4_ifval([$2],
 [{ $2 <<\_ASEOF
-_AS_BOURNE_COMPATIBLE
+AS_BOURNE_COMPATIBLE
 $1
 _ASEOF
 }],
@@ -319,7 +319,7 @@
 ## M4sh Initialization.  ##
 ## --------------------- ##
 
-_AS_BOURNE_COMPATIBLE
+AS_BOURNE_COMPATIBLE
 
 # PATH needs CR
 _AS_CR_PREPARE