Re: m4_pattern_forbid documentation

[Eric Blake]

On 04/16/2015 03:00 PM, Matěj Týč wrote:
> Hello,
> I attach the suggestion of autoconf m4sugar-related documentation
> improvement.
> Specifically, the patch adds a more concrete description of what the
> m4_pattern_forbid thingy that pretends it is a macro accepts as an
> argument.

Thanks for the patch. This one is small enough that it doesn't need
copyright assignment; but if you want to continue contributing, you
should probably considering assigning copyright to FSF.  I can give you
more details off-list, if you are interested.


> +++ b/doc/autoconf.texi
> @@ -13379,6 +13379,15 @@ the authors of this documentation: input, such as 
> macros, should be
>  documented by @samp{dnl} comments; reserving @samp{#}-comments to
>  document the output).
>  
> +The regular expression family the output is checked against is a Perl one.
> +Therefore, if you define your own macros that begin with @samp{M_} and
> +are composed from capital letters and underscores,
> +you want to specify @code{m4_pattern_forbid([^M_[A-Z_]+])}
> +Although @samp{^} is a Perl regexp for beginning of lines, due to the
> +output post-processing performed by @command{autom4te}, it will have
> +the same effect as the regular expression @samp{\b},
> +that matches beginning of words.

This reads a bit awkwardly; I would like to propose this alternate
wording, still in your name.  If you agree, I'll go ahead and push.

Oh, and I just noticed that we don't document the two-arg form; the
m4sugar.m4 file mentions that you can do m4_pattern_forbid([^PKG_], [did
you forget to install pkg-config?]) for nicer error messages, although I
haven't actually tested that.  So it would be a good idea for a further
patch in this area.

>From b2d15a95f53d0f06df7cd723f829dea59ea32069 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mat=C4=9Bj=20T=C3=BD=C4=8D?= <address@hidden>
Date: Thu, 16 Apr 2015 23:00:24 +0200
Subject: [PATCH] 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.

Signed-off-by: Eric Blake <address@hidden>
Copyright-paperwork-exempt: Yes
---
 doc/autoconf.texi      | 15 +++++++++++++--
 lib/m4sugar/m4sugar.m4 |  4 ++--
 2 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index bab87ad..b2ca0ae 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -13370,7 +13370,13 @@ Forbidden Patterns

 @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
address@hidden  If the regular expression matches, and
address@hidden 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 @@ Forbidden Patterns
 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 @@ Forbidden Patterns
 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 f6be8bc..9bdafd5 100644
--- 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], [])


-- 
2.1.0



-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org