m4_pattern_forbid: better documentation

Give a more concrete description of what the m4_pattern_forbid
thingy that pretends it is a macro accepts as an argument.

Copyright-paper-exempt: Yes
Signed-off-by: Eric Blake <eblake@redhat.com>

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index bab87ad268340083a427ef11da77caa40d4d13af..b2ca0ae5019945caa10d98a07f234ed340695431 100644 (file)
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -13370,7 +13370,13 @@ patterns to the list.
 
 @defmac m4_pattern_forbid (@var{pattern})
 @msindex{pattern_forbid}
-Declare that no token matching @var{pattern} must be found in the output.
+Declare that no token matching @var{pattern} must be found in the
+output.  The output file is (temporarily) split into one word per line
+as part of the @command{autom4te} post-processing, with each line (and
+therefore word) then being checked against the Perl regular expression
+@var{pattern}.  If the regular expression matches, and
+@code{m4_pattern_allow} does not also match, then an error is raised.
+
 Comments are not checked; this can be a problem if, for instance, you
 have some macro left unexpanded after an @samp{#include}.  No consensus
 is currently found in the Autoconf community, as some people consider it
@@ -13379,6 +13385,11 @@ 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, if you define your own macros that begin with @samp{M_}
+and are composed from capital letters and underscores, the specification
+of @code{m4_pattern_forbid([^M_[A-Z_]+])} will ensure all your macros
+are expanded when not used in comments.
+
 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
@@ -13386,7 +13397,7 @@ 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,
+mentioning the unexpanded @code{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.

diff --git a/lib/m4sugar/m4sugar.m4 b/lib/m4sugar/m4sugar.m4
index f6be8bcd240c0c667f16351e66149f184c49017f..9bdafd59f5d160d0dd1b66905205c07d7c1548dc 100644 (file)
--- a/lib/m4sugar/m4sugar.m4
+++ b/lib/m4sugar/m4sugar.m4
@@ -2000,7 +2000,7 @@ m4_define([_m4_defun_once],
 
 # m4_pattern_forbid(ERE, [WHY])
 # -----------------------------
-# Declare that no token matching the forbidden extended regular
+# Declare that no token matching the forbidden perl extended regular
 # expression ERE should be seen in the output unless...
 m4_define([m4_pattern_forbid], [])
 
@@ -2008,7 +2008,7 @@ m4_define([m4_pattern_forbid], [])
 # m4_pattern_allow(ERE)
 # ---------------------
 # ... that token also matches the allowed extended regular expression ERE.
-# Both used via traces.
+# Both used via traces, by autom4te post-processing.
 m4_define([m4_pattern_allow], [])