diff --git a/ChangeLog b/ChangeLog
index d6337f6a..071f2a9c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2008-10-14  Eric Blake  <ebb9@byu.net>
+
+	Document shell function environment pitfall.
+	* doc/autoconf.texi (Shell Functions): Document bugs in bash,
+	Solaris /bin/sh.
+
 2008-10-14  Paolo Bonzini  <bonzini@gnu.org>
 
 	Use m4_require to implement AS_REQUIRE.
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index ff81c2ec..dc864626 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -14225,6 +14225,23 @@ For example, Korn shells reset and restore trace output (@samp{set -x})
 and other options upon function entry and exit.  Inside a function,
 @acronym{IRIX} sh sets @samp{$0} to the function name.
 
+It is not portable to pass temporary environment variables to shell
+functions.  Solaris @command{/bin/sh} does not see the variable.  Meanwhile,
+@command{bash} 3.2 breaks the Posix rule that the assignment must not affect
+the current environment, but only when Posix compliance is requested!
+
+@example
+$ @kbd{/bin/sh -c 'func()@{ echo $a;@}; a=1 func; echo $a'}
+@result{}
+@result{}
+$ @kbd{bash -c 'func()@{ echo $a;@}; a=1 func; echo $a'}
+@result{}1
+@result{}
+$ @kbd{bash -c 'set -o posix; func()@{ echo $a;@}; a=1 func; echo $a'}
+@result{}1
+@result{}1
+@end example
+
 Some ancient Bourne shell variants with function support did not reset
 @samp{$@var{i}, @var{i} >= 0}, upon function exit, so effectively the
 arguments of the script were lost after the first function invocation.