[PATCH] doc: mention how to set early defaults

Jonathon 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 Jonathon Lebon.

Signed-off-by: Eric Blake <[email protected]>
---
 THANKS            |  1 +
 doc/autoconf.texi | 15 ++++++++++++++-
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/THANKS b/THANKS
index 1e3e5ef..f41f16c 100644
--- a/THANKS
+++ b/THANKS
(redacted to avoid feeding spammers...)
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 3c559a5..d611758 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -11997,6 +11997,7 @@ Diversion support
 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,12 @@ External Software
 @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}).
+
 The argument @var{help-string} is a description of the option that
 looks like this:
 @example
@@ -22111,7 +22118,7 @@ External Software
   [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 +22245,12 @@ Package Options
 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}).
+
 You should format your @var{help-string} with the macro
 @code{AS_HELP_STRING} (@pxref{Pretty Help Strings}).

-- 
1.8.3.1