[SCM] GNU Autoconf source repository branch, master, updated. v2.69-116-ge5d3c96

[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=e5d3c9621fbd23c5e2d62fdb19534ed1b5f3ab09

The branch, master has been updated
       via  e5d3c9621fbd23c5e2d62fdb19534ed1b5f3ab09 (commit)
      from  251d13ff2491e470f16569a9bb31123558ae84b2 (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 e5d3c9621fbd23c5e2d62fdb19534ed1b5f3ab09
Author: Eric Blake <address@hidden>
Date:   Mon Jan 27 11:33:07 2014 -0700

    doc: give an example of using the macro for pkg-config
    
    The autoconf manual doesn't mention any examples of actually
    using m4_pattern_forbid.  Yet this is the perfect macro for
    avoiding the all-too-common failure mode of configure dying with:
    
          checking if libxml2 is present... ./configure: line 11586: syntax
     error
     near unexpected token `LIBXML2,'
          ./configure: line 11586: `PKG_CHECK_MODULES(LIBXML2, libxml-2.0>=
     2.6.19,'
    
    for developers that forgot to install pkg-config.  While we don't
    necessarily advertise the use of PKG_CHECK_MODULES, it is a
    common enough situation that the manual should make it easier to
    help developers learn about missing third-party macros.
    
    Based on a mailing list report by Daniel Pocock:
    http://lists.gnu.org/archive/html/autoconf/2014-01/msg00030.html
    
    * doc/autoconf.texi (Forbidden Patterns): Add examples.
    
    Signed-off-by: Eric Blake <address@hidden>

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

Summary of changes:
 doc/autoconf.texi |   17 +++++++++++++++++
 1 files changed, 17 insertions(+), 0 deletions(-)

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 6c374c0..6795fcb 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -13373,6 +13373,18 @@ should be valid to name macros in comments (which 
doesn't make sense to
 the authors of this documentation: input, such as macros, should be
 documented by @samp{dnl} comments; reserving @samp{#}-comments to
 document the output).
+
+As an example of a common use of this macro, consider what happens in
+packages that want to use the @command{pkg-config} script via the
+third-party @code{PKG_CHECK_MODULES} macro.  By default, if a developer
+checks out the development tree but has not yet installed the pkg-config
+macros locally, they can manage to successfully run @command{autoconf}
+on the package, but the resulting @file{configure} file will likely
+result in a confusing shell message about a syntax error on the line
+mentioning the unexpanded PKG_CHECK_MODULES macro.  On the other hand,
+if @file{configure.ac} includes @code{m4_pattern_forbid([^PKG_])}, the
+missing pkg-config macros will be detected immediately without allowing
address@hidden to succeed.
 @end defmac
 
 Of course, you might encounter exceptions to these generic rules, for
@@ -13382,6 +13394,11 @@ instance you might have to refer to @samp{$m4_flags}.
 @msindex{pattern_allow}
 Any token matching @var{pattern} is allowed, including if it matches an
 @code{m4_pattern_forbid} pattern.
+
+For example, gnulib uses @code{m4_pattern_forbid([^gl_])} to reserve the
address@hidden namespace for itself, but also uses
address@hidden([^gl_ES$])} to avoid a false negative on the
+valid locale name.
 @end defmac
 
 @node Debugging via autom4te


hooks/post-receive
-- 
GNU Autoconf source repository