docs: more details about make VPATH rewriting woes

* doc/autoconf.texi (Automatic Rule Rewriting): Solaris make
VPATH rewriting applies to any whitespace-separated word in a
rule, so it might apply also to shell variables, functions
and keywords (and automake has already tripped on this once);
document this, with an example.  Since we are at it, do some
minor reformatting of existing text.

2 files changed, 41 insertions, 8 deletions

diff --git a/ChangeLog b/ChangeLog
index 5ff3e92f..01df9adf 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2011-09-14  Stefano Lattarini  <stefano.lattarini@gmail.com>
+
+	docs: more details about make VPATH rewriting woes
+	* doc/autoconf.texi (Automatic Rule Rewriting): Solaris make
+	VPATH rewriting applies to any whitespace-separated word in a
+	rule, so it might apply also to shell variables, functions
+	and keywords (and automake has already tripped on this once);
+	document this, with an example.  Since we are at it, do some
+	minor reformatting of existing text.
+
 2011-09-13  Stefano Lattarini  <stefano.lattarini@gmail.com>
 
 	docs: document Solaris 10 /bin/ksh and XPG4 sh 'unset' bug
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 90ab4b9e..3d990125 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -20256,14 +20256,37 @@ However, this rule leads to real problems in practice.  For example, if
 the source directory contains an ordinary file named @file{test} that is
 used in a dependency, Solaris @command{make} rewrites commands like
 @samp{if test -r foo; @dots{}} to @samp{if ../pkg/src/test -r foo;
-@dots{}}, which is typically undesirable.  To avoid this problem,
-portable makefiles should never mention a source file whose name is that
-of a shell keyword like @file{until} or a shell command like
-@command{cat} or @command{gcc} or @command{test}.
-
-Because of these problems GNU @command{make} and many other
-@command{make} implementations do not rewrite commands, so portable
-makefiles should
+@dots{}}, which is typically undesirable.  In fact, @command{make} is
+completely unaware of shell syntax used in the rules, so the VPATH
+rewrite can potentially apply to @emph{any} whitespace-separated word
+in a rule, including shell variables, functions, and keywords.
+
+@example
+$ @kbd{mkdir build}
+$ @kbd{cd build}
+$ @kbd{cat > Makefile <<'END'}
+VPATH = ..
+all: arg func for echo
+        func () @{ for arg in "$$@@"; do echo $$arg; done; @}; \
+        func "hello world"
+END
+$ @kbd{touch ../arg ../func ../for ../echo}
+$ @kbd{make}
+../func () @{ ../for ../arg in "$@@"; do ../echo $arg; done; @}; \
+../func "hello world"
+sh: syntax error at line 1: `do' unexpected
+*** Error code 2
+@end example
+
+@noindent
+To avoid this problem, portable makefiles should never mention a source
+file or dependency whose name is that of a shell keyword like @file{for}
+or @file{until}, a shell command like @command{cat} or @command{gcc} or
+@command{test}, or a shell function or variable used in the corresponding
+@command{Makefile} recipe.
+
+Because of these problems GNU @command{make} and many other @command{make}
+implementations do not rewrite commands, so portable makefiles should
 search @code{VPATH} manually.  It is tempting to write this:
 
 @smallexample