doc: mention how to set early defaults

Jonathan Lebon reported an issue to me off-list about a regression
in libvirt's configure script, which I traced to a patch that
rearranged code that was checking $with_library compared to the
AC_ARG_WITH that actually set $with_library [1].  As the whole point
of the libvirt patch was to refactor code to make maintenance
easier by hiding the AC_ARG_WITH in a helper macro for a net
reduction in lines, it makes sense to actually document how to
check what value a variable has prior to the AC_ARG_WITH usage.

Alas, although the functionality for this has been present in
autoconf for ages, the documentation has been lacking.

[1] libvirt.org/git/?p=libvirt.git;a=commitdiff;h=654c709

* doc/autoconf.texi (Diversion support) <m4_divert_text>: Add
anchor.
(External Software) <AC_ARG_WITH>: Demonstrate how to use DEFAULTS
diversion, for earlier defaults.
(Package Options) <AC_ARG_ENABLE>: Likewise.
* THANKS: Add Jonathan Lebon.

Signed-off-by: Eric Blake <eblake@redhat.com>

diff --git a/THANKS b/THANKS
index 1e3e5ef41425e9f17d7787e98e91e47111ba90f7..f41f16c0215344bbd403593209977d1fded52031 100644 (file)
--- a/THANKS
+++ b/THANKS
@@ -210,6 +210,7 @@ John Interrante             interran@uluru.stanford.edu
 John R. Cary                cary@txcorp.com
 John W. Eaton               jwe@bevo.che.wisc.edu
 Jonathan Kamens             jik@kamens.brookline.ma.us
+Jonathan Lebon              jlebon@redhat.com
 Josef Tran                  josef@timetrackertechnology.com
 Josef Vukovic               josefvukovic@googlemail.com
 Joseph S. Myers             jsm28@cam.ac.uk

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 3c559a5dd1ca643701edd44f724969fa1fa6c551..26e7b1768c2bfcaa8bc9247b5e3c8220c20b7c9d 100644 (file)
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -11997,6 +11997,7 @@ stack, and issues an error if there is not a matching pop for every
 push.
 @end defmac
 
+@anchor{m4_divert_text}
 @defmac m4_divert_text (@var{diversion}, @ovar{content})
 @msindex{divert_text}
 Output @var{content} and a newline into @var{diversion}, without
@@ -22085,6 +22086,14 @@ actually just the value of the shell variable named
 @var{package} changed into @samp{_}.  You may use that variable instead,
 if you wish.
 
+Note that @var{action-if-not-given} is not expanded until the point that
+@code{AC_ARG_WITH} was expanded.  If you need the value of
+@code{with_@var{package}} set to a default value by the time argument
+parsing is completed, use @code{m4_divert_text} to the @code{DEFAULTS}
+diversion (@pxref{m4_divert_text}) (if done as an argument to
+@code{AC_ARG_WITH}, also provide non-diverted text to avoid a shell
+syntax error).
+
 The argument @var{help-string} is a description of the option that
 looks like this:
 @example
@@ -22111,7 +22120,7 @@ AC_ARG_WITH([readline],
   [AS_HELP_STRING([--with-readline],
     [support fancy command line editing @@<:@@default=check@@:>@@])],
   [],
-  [with_readline=check])
+  [: m4_divert_text([DEFAULTS], [with_readline=check])])
 
 LIBREADLINE=
 AS_IF([test "x$with_readline" != xno],
@@ -22238,6 +22247,14 @@ actually just the value of the shell variable named
 if you wish.  The @var{help-string} argument is like that of
 @code{AC_ARG_WITH} (@pxref{External Software}).
 
+Note that @var{action-if-not-given} is not expanded until the point that
+@code{AC_ARG_ENABLE} was expanded.  If you need the value of
+@code{enable_@var{feature}} set to a default value by the time argument
+parsing is completed, use @code{m4_divert_text} to the @code{DEFAULTS}
+diversion (@pxref{m4_divert_text}) (if done as an argument to
+@code{AC_ARG_ENABLE}, also provide non-diverted text to avoid a shell
+syntax error).
+
 You should format your @var{help-string} with the macro
 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).