[PATCH] docs: document set -n pitfalls

[Eric Blake]

* doc/autoconf.texi (Limitations of Builtins) <set>: Document
issues with set -n.
---

I was surprised that we hadn't documented this one, especially since
our own configure.ac has to work around it.

 doc/autoconf.texi |   20 ++++++++++++++++++++
 1 files changed, 20 insertions(+), 0 deletions(-)

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 9442e22..2ae8bb9 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -18083,6 +18083,26 @@ Limitations of Builtins
 c
 @end example

address@hidden @command{set -n}
+Use of @command{set -n} (typically via @command{sh -n script}) to
+validate a script is not foolproof.  Modern @command{ksh93} tries to be
+helpful by informing you about better syntax, but switching the script
+to use the suggested syntax in order to silence the warnings would
+render the script no longer portable to older shells:
+
address@hidden
+$ @kbd{ksh -nc '``'}
+ksh: warning: line 1: `...` obsolete, use $(...)
+0
address@hidden example
+
+Furthermore, on ancient hosts, such as SunOS 4, @command{sh -n} could go
+into an infinite loop; even with that bug fixed, Solaris 8
address@hidden/bin/sh} takes extremely long to parse large scripts.  Autoconf
+itself uses @command{sh -n} within its testsuite to check that correct
+scripts were generated, but only after first probing for other shell
+features (such as @code{test -n "address@hidden@}"}) that indicate
+a reasonably fast and working implementation.

 @item @command{shift}
 @c ------------------
-- 
1.7.7.6