[PATCH] 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 <[email protected]>
---

No wonder it took us a couple of iterations to give you the
right advice - we didn't have good documentation.  This patch
should give us something to point the next person to, when
encountering a similar situation.

 doc/autoconf.texi | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 6c374c0..ae2987a 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -13373,6 +13373,18 @@ Forbidden Patterns
 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
+@command{autoconf} to succeed.
 @end defmac

 Of course, you might encounter exceptions to these generic rules, for
@@ -13382,6 +13394,11 @@ Forbidden Patterns
 @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
+@code{gl_} namespace for itself, but also uses
+@code{m4_pattern_allow([^gl_ES$])} to avoid a false negative on the
+valid locale name.
 @end defmac

 @node Debugging via autom4te
-- 
1.8.5.3