[SCM] GNU Autoconf source repository branch, master, updated. v2.63-221-g26ba3d5

[Eric Blake]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU Autoconf source repository".

http://git.sv.gnu.org/gitweb/?p=autoconf.git;a=commitdiff;h=26ba3d53187631bd8febe617a957df5063ed2fe6

The branch, master has been updated
       via  26ba3d53187631bd8febe617a957df5063ed2fe6 (commit)
       via  54dd8a93795219ca8e51bb58963be5ea64e48d34 (commit)
      from  abe172f4ba8d375a8b078534e9cef1e084ff59ab (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 26ba3d53187631bd8febe617a957df5063ed2fe6
Author: Eric Blake <address@hidden>
Date:   Fri Nov 21 06:54:51 2008 -0700

    Add @anchors within Builtins and Usual Tools lists.
    
    * doc/autoconf.texi (Limitations of Builtins)
    (Limitatations of Usual Tools): Add anchors for tools called out
    by name.  Adjust callers to narrow in on tool of interest.
    
    Signed-off-by: Eric Blake <address@hidden>

commit 54dd8a93795219ca8e51bb58963be5ea64e48d34
Author: Eric Blake <address@hidden>
Date:   Fri Nov 21 06:35:35 2008 -0700

    Move case statement style discussion to m4 quoting section.
    
    * doc/autoconf.texi (Limitations of Builtins): Move comparison of
    quoting styles...
    (Balancing Parentheses): ...to this new node.
    Suggested by Ralf Wildenhues.
    
    Signed-off-by: Eric Blake <address@hidden>

-----------------------------------------------------------------------

Summary of changes:
 ChangeLog         |   13 +++
 doc/autoconf.texi |  282 ++++++++++++++++++++++++++++++-----------------------
 2 files changed, 173 insertions(+), 122 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 8381688..a1b8a46 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2008-11-21  Eric Blake  <address@hidden>
+
+       Add @anchors within Builtins and Usual Tools lists.
+       * doc/autoconf.texi (Limitations of Builtins)
+       (Limitatations of Usual Tools): Add anchors for tools called out
+       by name.  Adjust callers to narrow in on tool of interest.
+
+       Move case statement style discussion to m4 quoting section.
+       * doc/autoconf.texi (Limitations of Builtins): Move comparison of
+       quoting styles...
+       (Balancing Parentheses): ...to this new node.
+       Suggested by Ralf Wildenhues.
+
 2008-11-20  Eric Blake  <address@hidden>
 
        Factor more common code out of AT_CHECK into shell function.
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 7a154b7..e5e2b3a 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -445,6 +445,7 @@ M4 Quotation
 * Quotation and Nested Macros::  Macros calling macros
 * Changequote is Evil::         Worse than INTERCAL: M4 + changequote
 * Quadrigraphs::                Another way to escape special characters
+* Balancing Parentheses::       Dealing with unbalanced parentheses
 * Quotation Rule Of Thumb::     One parenthesis, one quote
 
 Using @command{autom4te}
@@ -2957,7 +2958,8 @@ them does not change their contents.  This feature avoids 
unnecessary
 recompilation.  You should include the file @file{stamp-h.in} your
 package's distribution, so that @command{make} considers
 @file{config.h.in} up to date.  Don't use @command{touch}
-(@pxref{Limitations of Usual Tools}); instead, use @command{echo} (using
+(@pxref{touch, , Limitations of Usual Tools}); instead, use
address@hidden (using
 @command{date} would cause needless differences, hence @acronym{CVS}
 conflicts, etc.).
 
@@ -3767,7 +3769,7 @@ best implementation.
 Look for the best available @code{grep} or @code{ggrep} that accepts the
 longest input lines possible, and that supports multiple @option{-e} options.
 Set the output variable @code{GREP} to whatever is chosen.
address@hidden of Usual Tools}, for more information about
address@hidden, , Limitations of Usual Tools}, for more information about
 portability problems with the @command{grep} command family.
 @end defmac
 
@@ -3950,7 +3952,7 @@ is found, and otherwise to @samp{:} (do nothing).
 @ovindex SED
 Set output variable @code{SED} to a Sed implementation that conforms to
 Posix and does not have arbitrary length limits.  Report an error if no
-acceptable Sed is found.  @xref{Limitations of Usual Tools}, for more
+acceptable Sed is found.  @xref{sed, , Limitations of Usual Tools}, for more
 information about portability problems with Sed.
 @end defmac
 
@@ -9292,6 +9294,7 @@ former helps one to follow the latter.
 * Quotation and Nested Macros::  Macros calling macros
 * Changequote is Evil::         Worse than INTERCAL: M4 + changequote
 * Quadrigraphs::                Another way to escape special characters
+* Balancing Parentheses::       Dealing with unbalanced parentheses
 * Quotation Rule Of Thumb::     One parenthesis, one quote
 @end menu
 
@@ -9778,6 +9781,126 @@ invention, and I suppose it could have been a common 
pun around the
 Cambridge University computer lab at the time.
 @end quotation
 
+
address@hidden Balancing Parentheses
address@hidden Dealing with unbalanced parentheses
address@hidden balancing parentheses
address@hidden parentheses, balancing
address@hidden unbalanced parentheses, managing
+
+One of the pitfalls of portable shell programming is that @command{case}
+statements require unbalanced parentheses (@pxref{case, , Limitations of
+Shell Builtins}).  With syntax highlighting
+editors, the presence of unbalanced @samp{)} can interfere with editors
+that perform syntax highlighting of macro contents based on finding the
+matching @samp{(}.  Another concern is how much editing must be done
+when transferring code snippets between shell scripts and macro
+definitions.  But most importantly, the presence of unbalanced
+parentheses can introduce expansion bugs.
+
+For an example, here is an underquoted attempt to use the macro
address@hidden, which happens to expand to a portable @command{case}
+statement:
+
address@hidden
+AC_DEFUN([my_case],
+[case $file_name in
+  *.c) echo "C source code";;
+esac])
+AS_IF(:, my_case)
address@hidden example
+
address@hidden
+In the above example, the @code{AS_IF} call underquotes its arguments.
+As a result, the unbalanced @samp{)} generated by the premature
+expansion of @code{my_case} results in expanding @code{AS_IF} with a
+truncated parameter, and the expansion is syntactically invalid:
+
address@hidden
+if :; then
+  case $file_name in
+  *.c
+fi echo "C source code";;
+esac)
address@hidden example
+
+If nothing else, this should emphasize the importance of the quoting
+arguments to macro calls.  On the other hand, there are several
+variations for defining @code{my_case} to be more robust, even when used
+without proper quoting, each with some benefits and some drawbacks.
+
address@hidden @asis
address@hidden Creative literal shell comment
address@hidden
+AC_DEFUN([my_case],
+[case $file_name in #(
+  *.c) echo "C source code";;
+esac])
address@hidden example
address@hidden
+This version provides balanced parentheses to several editors, and can
+be copied and pasted into a terminal as is.  Unfortunately, it is still
+unbalanced as an Autoconf argument, since @samp{#(} is an M4 comment
+that masks the normal properties of @samp{(}.
+
address@hidden Quadrigraph shell comment
address@hidden
+AC_DEFUN([my_case],
+[case $file_name in @@%:@@(
+  *.c) echo "C source code";;
+esac])
address@hidden example
address@hidden
+This version provides balanced parentheses to even more editors, and can
+be used as a balanced Autoconf argument.  Unfortunately, it requires
+some editing before it can be copied and pasted into a terminal, and the
+use of the quadrigraph @samp{@@%:@@} for @samp{#} reduces readability.
+
address@hidden Quoting just the parenthesis
address@hidden
+AC_DEFUN([my_case],
+[case $file_name in
+  *.c[)] echo "C source code";;
+esac])
address@hidden example
address@hidden
+This version quotes the @samp{)}, so that it can be used as a balanced
+Autoconf argument.  As written, this is not balanced to an editor, but
+it can be coupled with @samp{[#(]} to meet that need, too.  However, it
+still requires some edits before it can be copied and pasted into a
+terminal.
+
address@hidden Double-quoting the entire statement
address@hidden
+AC_DEFUN([my_case],
+[[case $file_name in #(
+  *.c) echo "C source code";;
+esac]])
address@hidden example
address@hidden
+Since the entire macro is double-quoted, there is no problem with using
+this as an Autoconf argument; and since the double-quoting is over the
+entire statement, this code can be easily copied and pasted into a
+terminal.  However, the double quoting prevents the expansion of any
+macros inside the case statement, which may cause its own set of
+problems.
+
address@hidden Using @code{AS_CASE}
address@hidden
+AC_DEFUN([my_case],
+[AS_CASE([$file_name],
+  [*.c], [echo "C source code"])])
address@hidden example
address@hidden
+This version avoids the balancing issue altogether, by relying on
address@hidden (@pxref{Common Shell Constructs}); it also allows for the
+expansion of @code{AC_REQUIRE} to occur prior to the entire case
+statement, rather than within a branch of the case statement that might
+not be taken.  However, the abstraction comes with a penalty that it is
+no longer a quick copy, paste, and edit to get back to shell code.
address@hidden itemize
+
+
 @node Quotation Rule Of Thumb
 @subsection Quotation Rule Of Thumb
 
@@ -12009,6 +12132,8 @@ if @code{$file} is @samp{/one/two/three}, the command
 Expand into a shell @samp{case} statement, where @var{word} is matched
 against one or more patterns.  @var{if-matched} is run if the
 corresponding pattern matched @var{word}, else @var{default} is run.
+Avoids several portability issues (@pxref{case, , Limitations of Shell
+Builtins}).
 @end defmac
 
 @c Deprecated, to be replaced by a better API
@@ -12026,7 +12151,9 @@ if @code{$file} is @samp{/one/two/three}, the command
 Emits @var{word} to the standard output, followed by a newline.  @var{word}
 must be a single shell word (typically a quoted string).  The bytes of
 @var{word} are output as-is, even if it starts with "-" or contains "\".
-Redirections can be placed outside the macro invocation.
+Redirections can be placed outside the macro invocation.  This is much
+more portable than using @command{echo} (@pxref{echo, , Limitations of
+Shell Builtins}).
 @end defmac
 
 @defmac AS_ECHO_N (@var{word})
@@ -12045,8 +12172,8 @@ omitted, then @samp{$?} is used, except that a status 
of zero is
 converted to @samp{1}.  To exit with successful status, it is necessary
 to supply an explicit @var{status} that expands to @samp{0}.  This macro
 works around shells that see the exit status of the command prior to
address@hidden inside a @samp{trap 0} handler (@pxref{Limitations of
-Builtins, , Limitations of Shell Builtins}).
address@hidden inside a @samp{trap 0} handler (@pxref{trap, , Limitations
+of Shell Builtins}).
 @end defmac
 
 @defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false})
@@ -12074,7 +12201,8 @@ Make the directory @var{file-name}, including 
intervening directories
 as necessary.  This is equivalent to @samp{mkdir -p -- @var{file-name}},
 except that it is portable to older versions of @command{mkdir} that
 lack support for the @option{-p} option or for the @option{--}
-delimiter.  Also, @code{AS_MKDIR_P}
+delimiter (@pxref{mkdir, , Limitations of Usual Tools}).  Also,
address@hidden
 succeeds if @var{file-name} is a symbolic link to an existing directory,
 even though Posix is unclear whether @samp{mkdir -p} should
 succeed in that case.  If creation of @var{file-name} fails, exit the
@@ -12087,8 +12215,7 @@ Also see the @code{AC_PROG_MKDIR_P} macro 
(@pxref{Particular Programs}).
 @asindex{SET_STATUS}
 Emit shell code to set the value of @samp{$?} to @var{status} without
 forking.  However, this is not guaranteed to abort a shell running with
address@hidden -e} (@pxref{Limitations of Builtins, , Limitations of Shell
-Builtins}).
address@hidden -e} (@pxref{set, , Limitations of Shell Builtins}).
 @end defmac
 
 @defmac AS_TR_CPP (@var{expression})
@@ -12125,7 +12252,7 @@ optimizing the common cases (@var{dir} or @var{file} is 
@samp{.},
 @defmac AS_UNSET (@var{var})
 @asindex{UNSET}
 Unsets the shell variable @var{var}, working around bugs in older
-shells (@pxref{Limitations of Builtins, , Limitations of Shell
+shells (@pxref{unset, , Limitations of Shell
 Builtins}).  @var{var} can be a literal or indirect variable name.
 @end defmac
 
@@ -13682,8 +13809,7 @@ esac
 
 @noindent
 Make sure you quote the brackets if appropriate and keep the backslash as
-first character (@pxref{Limitations of Builtins, , Limitations of Shell
-Builtins}).
+first character (@pxref{case, , Limitations of Shell Builtins}).
 
 Also, because the colon is used as part of a drivespec, these systems don't
 use it as path separator.  When creating or accessing paths, you can use the
@@ -14413,7 +14539,7 @@ PS4='+ '
 
 @noindent
 (actually, there is some complication due to bugs in @command{unset};
-see @pxref{Limitations of Builtins, , Limitations of Shell Builtins}).
+see @pxref{unset, , Limitations of Shell Builtins}).
 
 @item FPATH
 The Korn shell uses @env{FPATH} to find shell functions, so avoid
@@ -14748,8 +14874,8 @@ arguments of the script were lost after the first 
function invocation.
 It is probably not worth worrying about these shells any more.
 
 With @acronym{AIX} sh, a @command{trap} on 0 installed in a shell function
-triggers at function exit rather than at script exit, see @xref{Limitations
-of Builtins}.
+triggers at function exit rather than at script exit, see @xref{trap, ,
+Limitations of Shell Builtins}.
 
 @node Limitations of Builtins
 @section Limitations of Shell Builtins
@@ -14873,6 +14999,7 @@ $ @kbd{pdksh -c 'false; @{ @}; echo $?' || echo $?}
 The use of @samp{break 2} etc.@: is safe.
 
 
address@hidden
 @item @command{case}
 @c -----------------
 @prindex @command{case}
@@ -14901,113 +15028,13 @@ $ @kbd{case foo in (foo) echo foo;; esac}
 @end example
 
 @noindent
address@hidden balancing parentheses
address@hidden parentheses, balancing
 The leading @samp{(} can be omitted safely.  Unfortunately, there are
 contexts where unbalanced parentheses cause other problems, such as when
 using a syntax-highlighting editor that searches for the balancing
 counterpart, or more importantly, when using a case statement as an
-underquoted argument to an Autoconf macro:
-
address@hidden
-AC_DEFUN([my_case],
-[case $file_name in
-  *.c) echo "C source code";;
-esac])
-AS_IF(:, my_case)
address@hidden example
-
address@hidden
-In the above example, the unbalanced @samp{)} in the premature expansion
-of @code{my_case} results in expanding @code{AS_IF} with a truncated
-parameter, and the expansion is syntactically invalid:
-
address@hidden
-if :; then
-  case $file_name in
-  *.c
-fi echo "C source code";;
-esac)
address@hidden example
-
address@hidden
-If nothing else, this should emphasize the importance of the quoting
-rule of thumb (@pxref{Quotation Rule Of Thumb}), that you should single
-quote all macro arguments that might be re-expanded, and double-quote
-macro arguments that are literal text.  On the other hand, there are
-several variations for defining @code{my_case} to be more robust, each
-with some benefits and some drawbacks.
-
address@hidden @asis
address@hidden Creative literal shell comment
address@hidden
-AC_DEFUN([my_case],
-[case $file_name in #(
-  *.c) echo "C source code";;
-esac])
address@hidden example
address@hidden
-This version provides balanced parentheses to several editors, and can
-be copied and pasted into a terminal as is.  Unfortunately, it is still
-unbalanced as an Autoconf argument, since @samp{#(} is an M4 comment
-that masks the normal properties of @samp{(}.
-
address@hidden Quadrigraph shell comment
address@hidden
-AC_DEFUN([my_case],
-[case $file_name in @@%:@@(
-  *.c) echo "C source code";;
-esac])
address@hidden example
address@hidden
-This version provides balanced parentheses to even more editors, and can
-be used as a balanced Autoconf argument.  Unfortunately, it requires
-some editing before it can be copied and pasted into a terminal, and the
-use of the quadrigraph @samp{@@%:@@} for @samp{#} reduces readability.
-
address@hidden Quoting just the parenthesis
address@hidden
-AC_DEFUN([my_case],
-[case $file_name in
-  *.c[)] echo "C source code";;
-esac])
address@hidden example
address@hidden
-This version quotes the @samp{)}, so that it can be used as a balanced
-Autoconf argument.  As written, this is not balanced to an editor, but
-it can be coupled with @samp{[#(]} to meet that need, too.  However, it
-still requires some edits before it can be copied and pasted into a
-terminal.
-
address@hidden Double-quoting the entire statement
address@hidden
-AC_DEFUN([my_case],
-[[case $file_name in #(
-  *.c) echo "C source code";;
-esac]])
address@hidden example
address@hidden
-Since the entire macro is double-quoted, there is no problem with using
-this as an Autoconf argument; and since the double-quoting is over the
-entire statement, this code can be easily copied and pasted into a
-terminal.  However, the double quoting prevents the expansion of any
-macros inside the case statement, which may cause its own set of
-problems.
-
address@hidden Using @code{AS_CASE}
address@hidden
-AC_DEFUN([my_case],
-[AS_CASE([$file_name],
-  [*.c], [echo "C source code"])])
address@hidden example
address@hidden
-This version avoids the balancing issue altogether, by relying on
address@hidden (@pxref{Common Shell Constructs}); it also allows for the
-expansion of @code{AC_REQUIRE} to occur prior to the entire case
-statement, rather than within a branch of the case statement that might
-not be taken.  However, the abstraction comes with a penalty that it is
-no longer a quick copy, paste, and edit to get back to shell code.
address@hidden table
+underquoted argument to an Autoconf macro.  @xref{Balancing
+Parentheses}, for tradeoffs involved in various styles of dealing with
+unbalanced @samp{)}.
 
 Zsh handles pattern fragments derived from parameter expansions or
 command substitutions as though quoted:
@@ -15115,6 +15142,7 @@ See @xref{Special Shell Variables}, for portability 
problems involving
 Also please see the discussion of the @command{pwd} command.
 
 
address@hidden
 @item @command{echo}
 @c -----------------
 @prindex @command{echo}
@@ -15278,6 +15306,7 @@ cannot determine whether it was invoked by plain 
@code{exit} or by
 @code{AC_MSG_ERROR} macro that has a workaround for this problem.
 
 
address@hidden
 @item @command{export}
 @c -------------------
 @prindex @command{export}
@@ -15496,6 +15525,7 @@ No options are portable, not even support @option{-r} 
(Solaris
 @command{/bin/sh} for example).
 
 
address@hidden
 @item @command{set}
 @c ----------------
 @prindex @command{set}
@@ -15704,6 +15734,7 @@ expr "X$ac_feature" : 'X.*[^-a-zA-Z0-9_]' >/dev/null &&
 @address@hidden contains backslashes.
 
 
address@hidden
 @item @command{trap}
 @c -----------------
 @prindex @command{trap}
@@ -15780,6 +15811,7 @@ for @command{true}.
 @end quotation
 
 
address@hidden
 @item @command{unset}
 @c ------------------
 @prindex @command{unset}
@@ -15811,7 +15843,7 @@ something like
 
 @noindent
 @xref{Special Shell Variables}, for some neutralizing values.  Also, see
address@hidden of Builtins}, documentation of @command{export}, for
address@hidden, , Limitations of Builtins}, for
 the case of environment variables.
 
 @item @command{wait}
@@ -16197,7 +16229,8 @@ foo
 |bar
 @end example
 
address@hidden also suffers the limitations of @command{grep}.
address@hidden also suffers the limitations of @command{grep}
+(@pxref{grep, , Limitations of Usual Tools}).
 
 @item @command{expr}
 @c -----------------
@@ -16364,6 +16397,7 @@ $ @kbd{find . -name foo -exec echo 
"@address@hidden@address@hidden" \;}
 while @acronym{GNU} @command{find} reports @samp{./foo-./foo}.
 
 
address@hidden
 @item @command{grep}
 @c -----------------
 @prindex @command{grep}
@@ -16490,6 +16524,7 @@ was equivalent to @samp{sources='*.c not found'} in the 
absence of
 @samp{.c} files.  This is no longer a practical problem, since current
 @command{ls} implementations send diagnostics to standard error.
 
address@hidden
 @item @command{mkdir}
 @c ------------------
 @prindex @command{mkdir}
@@ -16652,6 +16687,7 @@ perfectly portable among Posix hosts.
 Just as with @command{rm}, some platforms refuse to remove a working
 directory.
 
address@hidden
 @item @command{sed}
 @c ----------------
 @prindex @command{sed}
@@ -16919,6 +16955,7 @@ There are multiple file formats for @command{tar}; if 
you use Automake,
 the macro @code{AM_INIT_AUTOMAKE} has some options controlling which
 level of portability to use.
 
address@hidden
 @item @command{touch}
 @c ------------------
 @prindex @command{touch}
@@ -17028,7 +17065,8 @@ affected simple-commands so that they always succeed, 
e.g., @samp{touch
 T || :; rm -f U}.
 However, even this approach can run into common bugs in @acronym{BSD}
 implementations of the @option{-e} option of @command{sh} and
address@hidden (@pxref{Limitations of Builtins}), so if you are worried
address@hidden (@pxref{set, , Limitations of Shell Builtins}), so if you
+are worried
 about porting to buggy @acronym{BSD} shells it may be simpler to migrate
 complicated @command{make} actions into separate scripts.
 
@@ -17901,7 +17939,7 @@ is not a problem, but in some extreme cases you may 
need to use tricks
 like @samp{sleep 1} to work around timestamp truncation bugs.
 
 Commands like @samp{cp -p} and @samp{touch -r} typically do not copy
-file timestamps to their full resolutions (@pxref{Limitations of Usual
+file timestamps to their full resolutions (@pxref{touch, , Limitations of Usual
 Tools}).  Hence you should be wary of rules like this:
 
 @example


hooks/post-receive
--
GNU Autoconf source repository