autoconf doc fixes for `...` gotchas

[Paul Eggert]

I installed this mostly to warn about a delicious new gotcha I learned about
in the Opengroup mailing list.  This shell command:

foo=`basename -- "$bar"`

is required by Posix to screw up if $bar ends in a newline: it drops
the newline.

2005-01-20  Paul Eggert  <address@hidden>

        * doc/autoconf.texi (Shell Substitutions): Fix typo in case statement.
        Warn about newline stripping in `` and $().  Update Solaris
        version to 9.
        (Limitations of Builtins): Use expr "X...", not expr "x...", as
        X insulates us from future changes to Posix.
        (Limitations of Usual Tools): For AS_DIRNAME, warn about newline
        stripping.

Index: autoconf.texi
===================================================================
RCS file: /cvsroot/autoconf/autoconf/doc/autoconf.texi,v
retrieving revision 1.864
diff -u address@hidden -r1.864 autoconf.texi
--- autoconf.texi       20 Jan 2005 10:59:57 -0000      1.864
+++ autoconf.texi       21 Jan 2005 00:02:18 -0000
@@ -10002,7 +10002,7 @@ @node Shell Substitutions
 
 @example
 case "$given_srcdir" in
-.)  top_srcdir="`echo "$dots" | sed 's,/$,,'`"
+.)  top_srcdir="`echo "$dots" | sed 's,/$,,'`" ;;
 *)  top_srcdir="$dots$given_srcdir" ;;
 esac
 @end example
@@ -10012,7 +10012,7 @@ @node Shell Substitutions
 
 @example
 case $given_srcdir in
-.)  top_srcdir=`echo "$dots" | sed 's,/$,,'`
+.)  top_srcdir=`echo "$dots" | sed 's,/$,,'` ;;
 *)  top_srcdir=$dots$given_srcdir ;;
 esac
 @end example
@@ -10190,6 +10190,11 @@ @node Shell Substitutions
 @item address@hidden
 @cindex address@hidden
 @cindex Command Substitution
+Posix requires shells to trim all trailing newlines from command
+output before substituting it, so assignments like
address@hidden(["$file"])`} will not work as expected if the
+directory of @samp{$file} ends in a newline.
+
 While in general it makes no sense, do not substitute a single builtin
 with side effects, because Ash 0.2, trying to optimize, does not fork a
 subshell to perform the command.
@@ -10210,14 +10215,17 @@ @node Shell Substitutions
 
 @item $(@var{commands})
 @cindex $(@var{commands})
-This construct is meant to replace @address@hidden; they can be
+This construct is meant to replace @address@hidden,
+and it has most of the problems listed under @address@hidden
+
+This construct can be
 nested while this is impossible to do portably with back quotes.
-Unfortunately it is not yet widely supported.  Most notably, even recent
+Unfortunately it is not yet universally supported.  Most notably, even recent
 releases of Solaris don't support it:
 
 @example
 $ @kbd{showrev -c /bin/sh | grep version}
-Command version: SunOS 5.8 Generic 109324-02 February 2001
+Command version: SunOS 5.9 Generic May 2002
 $ @kbd{echo $(echo blah)}
 syntax error: `(' unexpected
 @end example
@@ -11155,7 +11163,7 @@ @node Limitations of Builtins
 or better yet
 
 @example
-expr "x$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
+expr "X$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null &&
   @var{action}
 @end example
 
@@ -11481,6 +11489,10 @@ @node Limitations of Usual Tools
 dir=`AS_DIRNAME(["$file"])` # This is more portable.
 @end example
 
+Unfortunately, neither of the above commands work if @code{$file}'s
+directory name ends in newline, since @address@hidden removes all
+trailing newlines.
+
 @noindent
 This handles a few subtleties in the standard way required by
 Posix.  For example, under UN*X, should @samp{dirname //1} give