FYI: Some doc about $()

[Akim Demaille]

2000-11-10  Akim Demaille  <address@hidden>

        * doc/autoconf.texi (Shell Substitutions): Split into...
        (Shell Substitutions, Assignments): these.
        Move them before `Special Shell Variables'.
        (Shell Substitutions): Include information on `$()' from Russ
        Allbery.

Index: doc/autoconf.texi
===================================================================
RCS file: /cvs/autoconf/doc/autoconf.texi,v
retrieving revision 1.374
diff -u -u -r1.374 autoconf.texi
--- doc/autoconf.texi 2000/11/02 17:44:03 1.374
+++ doc/autoconf.texi 2000/11/10 11:40:54
@@ -152,7 +152,8 @@
 * Macro Index::                 Index of Autoconf macros
 * Concept Index::               General index
 
address@hidden --- The Detailed Node Listing ---
address@hidden
+ --- The Detailed Node Listing ---
 
 Making @code{configure} Scripts
 
@@ -265,8 +266,9 @@
 Portable Shell Programming
 
 * Shellology::                  A zoology of shells
+* Shell Substitutions::         Variable expansions...
+* Assignments::                 Varying side effects of assignments
 * Special Shell Variables::     Variables you should not change
-* Shell Substitutions::         Test and assign
 * Limitations of Builtins::     Portable use of not so portable /bin/sh
 * Limitations of Usual Tools::  Portable use of portable tools
 
@@ -4982,13 +4984,14 @@
 
 @menu
 * Shellology::                  A zoology of shells
+* Shell Substitutions::         Variable expansions...
+* Assignments::                 Varying side effects of assignments
 * Special Shell Variables::     Variables you should not change
-* Shell Substitutions::         Test and assign
 * Limitations of Builtins::     Portable use of not so portable /bin/sh
 * Limitations of Usual Tools::  Portable use of portable tools
 @end menu
 
address@hidden Shellology, Special Shell Variables, Portable Shell, Portable 
Shell
address@hidden Shellology, Shell Substitutions, Portable Shell, Portable Shell
 @subsection Shellology
 
 There are several families of shells, most prominently the Bourne
@@ -5066,7 +5069,119 @@
 @end table
 
 
address@hidden Special Shell Variables, Shell Substitutions, Shellology, 
Portable Shell
address@hidden Shell Substitutions, Assignments, Shellology, Portable Shell
address@hidden Shell Substitutions
+
+Contrary to a persistent urban legend, the Bourne shell does not
+systematically split variables and backquoted expressions, in
+particular, the following code:
+
address@hidden
+case "$given_srcdir" in
+.)  top_srcdir="`echo "$dots" | sed 's,/$,,'`"
+*)  top_srcdir="$dots$given_srcdir" ;;
+esac
address@hidden example
+
address@hidden
+is more readable with the right-hand side of the assignments, and the
+argument of @code{case} left without quotes:
+
address@hidden
+case $given_srcdir in
+.)  top_srcdir=`echo "$dots" | sed 's,/$,,'`
+*)  top_srcdir=$dots$given_srcdir ;;
+esac
address@hidden example
+
address@hidden
+and in fact it is even @emph{more} portable: in the first case of the
+first attempt, the computation of @code{top_srcdir} is not portable,
+since not all the shells understand properly @samp{"`... "foo"... `"}.
+Worse yet, not all the shells understand @samp{"`... \"foo\"... `"} the
+same way: there is just no portable way to use double-quoted strings
+inside double-quoted backquoted expressions (Pfew!).
+
address@hidden @code
address@hidden $@@
address@hidden @samp{"$@@"}
+One of the most famous shell portability issues is related to
address@hidden"$@@"}: when there are no positional argument, it is supposed to
+be equivalent to nothing.  But some shell, for instance under Digital
+Unix 4.0 and 5.0, will then replace it with an empty argument.  To be
+portable, use @address@hidden"$@@"@}}.
+
address@hidden address@hidden@var{var}:address@hidden@}
address@hidden address@hidden@var{var}:address@hidden@}
+0Old @sc{bsd} shells, including the Ultrix @code{sh}, don't accept the
+colon for any shell substitution, and complain and die.
+
address@hidden $(@var{commands})
address@hidden $(@var{commands})
+This construct is meant to replace @address@hidden; they can be
+nested while this is impossible to do portably with back quotes.
+Unfortunately it is not yet widely supported.  Most notably even recent
+releases of Solaris don't support it:
+
address@hidden
+$ uname -a
+SunOS shelby.Stanford.EDU 5.7 Generic_106541-10 sun4u sparc SUNW,Ultra-1
+$ echo $(echo blah)
+syntax error: `(' unexpected
address@hidden example
+
address@hidden
+nor does @sc{irix} 6.5's Bourne shell:
address@hidden
+$ uname -a
+IRIX firebird-image 6.5 07151432 IP22
+$ echo $(echo blah)
+$(echo blah)
address@hidden example
address@hidden table
+
+
address@hidden Assignments, Special Shell Variables, Shell Substitutions, 
Portable Shell
address@hidden Assignments
+
address@hidden FIXME: We should split the following information: part of it also
address@hidden belongs to the previous section.
+
+A nonportable shell programming construct is
+
address@hidden
address@hidden@address@hidden:address@hidden@}
address@hidden example
+
address@hidden
+The intent is to set @var{var} to @var{value} only if it is not already
+set, but if @var{var} has any value, even the empty string, to leave it
+alone.  Old @sc{bsd} shells, including the Ultrix @code{sh}, don't
+accept the colon for any shell substitution, and complain and die.  A
+portable equivalent is
+
address@hidden
+: address@hidden@address@hidden@}
address@hidden example
+
+If the value is a literal string, it should be quoted:
+
address@hidden
+: address@hidden'Some words'@}
address@hidden example
+
address@hidden
+otherwise some shells, such as on Digital Unix V 5.0, will die because
+of a ``bad substitution''.
+
+When setting several variables in a row, be aware that the order of the
+evaluation is undefined.  For instance @samp{foo=1 foo=2; echo $foo}
+gives @samp{1} with sh on Solaris, but @samp{2} with Bash.  You must use
address@hidden;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
+
+
+
address@hidden Special Shell Variables, Limitations of Builtins, Assignments, 
Portable Shell
 @subsection Special Shell Variables
 
 Some shell variables shall not be used or have a deep influence on the
@@ -5161,80 +5276,8 @@
 hence read-only.  Do not use it.
 @end table
 
-
address@hidden Shell Substitutions, Limitations of Builtins, Special Shell 
Variables, Portable Shell
address@hidden Shell Substitutions
-
-A nonportable shell programming construct is
-
address@hidden
address@hidden@address@hidden:address@hidden@}
address@hidden example
-
address@hidden
-The intent is to set @var{var} to @var{value} only if it is not already
-set, but if @var{var} has any value, even the empty string, to leave it
-alone.  Old @sc{bsd} shells, including the Ultrix @code{sh}, don't
-accept the colon for any shell substitution, and complain and die.  A
-portable equivalent is
-
address@hidden
-: address@hidden@address@hidden@}
address@hidden example
-
-If the value is a literal string, it should be quoted:
-
address@hidden
-: address@hidden'Some words'@}
address@hidden example
-
address@hidden
-otherwise some shells, such as on Digital Unix V 5.0, will die because
-of a ``bad substitution''.
-
-When setting several variables in a row, be aware that the order of the
-evaluation is undefined.  For instance @samp{foo=1 foo=2; echo $foo}
-gives @samp{1} with sh on Solaris, but @samp{2} with Bash.  You must use
address@hidden;} to enforce the order: @samp{foo=1; foo=2; echo $foo}.
-
address@hidden @samp{"$@@"}
-One of the most famous shell portability issues is related to
address@hidden"$@@"}: when there are no positional argument, it is supposed to
-be equivalent to nothing.  But some shell, for instance under Digital
-Unix 4.0 and 5.0, will then replace it with an empty argument.  To be
-portable, use @address@hidden"$@@"@}}.
-
-Contrary to a persistent urban legend, the Bourne shell does not
-systematically split variables and backquoted expressions, in
-particular, the following code:
-
address@hidden
-case "$given_srcdir" in
-.)  top_srcdir="`echo "$dots" | sed 's,/$,,'`"
-*)  top_srcdir="$dots$given_srcdir" ;;
-esac
address@hidden example
-
address@hidden
-is more readable with the right-hand side of the assignments, and the
-argument of @code{case} left without quotes:
-
address@hidden
-case $given_srcdir in
-.)  top_srcdir=`echo "$dots" | sed 's,/$,,'`
-*)  top_srcdir=$dots$given_srcdir ;;
-esac
address@hidden example
-
address@hidden
-and in fact it is even @emph{more} portable: in the first case of the
-first attempt, the computation of @code{top_srcdir} is not portable,
-since not all the shells understand properly @samp{"`... "foo"... `"}.
-Worse yet, not all the shells understand @samp{"`... \"foo\"... `"} the
-same way: there is just no portable way to use double-quoted strings
-inside double-quoted backquoted expressions (Pfew!).
 
address@hidden Limitations of Builtins, Limitations of Usual Tools, Shell 
Substitutions, Portable Shell
address@hidden Limitations of Builtins, Limitations of Usual Tools, Special 
Shell Variables, Portable Shell
 @subsection Limitations of Shell Builtins
 
 No no, we are serious: some shells do have limitations :)