[PATCH 3/5] New cache variable index in the manual.

[Ralf Wildenhues]

* doc/autoconf.texi: Define new index `CA' for cache variables.
(caindex): New macro.
(Cache Variable Index): New appendix node.
(Top, Indices): Adjust menus.
(Cache Variable Names, Site Defaults): Adjust text.
* doc/Makefile.am (CLEANFILES): Add files generated for CA index.
---

I wanted to use 'cv' as defcodeindex for the cache variable index this
but that was already used for CPP variables.  Hmm.

Cheers,
Ralf

 doc/Makefile.am   |    1 +
 doc/autoconf.texi |   43 ++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 41 insertions(+), 3 deletions(-)

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 1e4e53e..fd1ab33 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -30,4 +30,5 @@ EXTRA_DIST = gendocs_template
 # not know.
 CLEANFILES = autoconf.ACs  autoconf.cvs  autoconf.MSs  autoconf.prs \
             autoconf.ATs  autoconf.evs  autoconf.fns  autoconf.ovs \
+            autoconf.ca   autoconf.CA   autoconf.cas  autoconf.CAs \
             autoconf.tmp
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 1244ef3..0b0cbee 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -52,6 +52,8 @@
 @defcodeindex ov
 @c Define a CPP variable index.
 @defcodeindex cv
address@hidden Define a cache variable index.
address@hidden CA
 @c Define an Autoconf macro index that @defmac doesn't write to.
 @defcodeindex AC
 @c Define an Autotest macro index that @defmac doesn't write to.
@@ -154,6 +156,20 @@
 @end ifclear
 
 
address@hidden @caindex{VARIABLE}
address@hidden ------------------
address@hidden Registering an ac_cv_\VARIABLE\ cache variable.
address@hidden shortindexflag
address@hidden caindex{macro}
address@hidden \macro\
address@hidden macro
address@hidden ifset
address@hidden shortindexflag
address@hidden caindex{macro}
address@hidden ac_cv_\macro\
address@hidden macro
address@hidden ifclear
+
 @c Define an index for functions: `alloca' etc.  Used for the
 @c portability sections and so on.  We can't use `fn' (aka `fnindex),
 @c since address@hidden' goes into it => we'd get all the macros too.
@@ -636,6 +652,7 @@ Top
 * Environment Variable Index::  Index of environment variables used
 * Output Variable Index::       Index of variables set in output files
 * Preprocessor Symbol Index::   Index of C preprocessor symbols defined
+* Cache Variable Index::        Index of documented cache variables
 * Autoconf Macro Index::        Index of Autoconf macros
 * M4 Macro Index::              Index of M4, M4sugar, and M4sh macros
 * Autotest Macro Index::        Index of Autotest macros
@@ -9234,6 +9251,9 @@ Cache Variable Names
 The values assigned to cache variables may not contain newlines.
 Usually, their values are Boolean (@samp{yes} or @samp{no}) or the
 names of files or functions; so this is not an important restriction.
address@hidden Variable Index} for an index of cache variables with
+documented semantics.
+
 
 @node Cache Files
 @subsection Cache Files
@@ -20385,9 +20405,12 @@ Site Defaults
 that require running a test program.  You could ``prime the cache'' by
 setting those values correctly for that system in
 @address@hidden/etc/config.site}.  To find out the names of the cache
-variables you need to set, look for shell variables with @samp{_cv_} in
-their names in the affected @command{configure} scripts, or in the Autoconf
-M4 source code for those macros.
+variables you need to set, see the documentation of the respective
+Autoconf macro.  If the variables or their semantics are undocumented,
+you may need to look for shell variables with @samp{_cv_} in their names
+in the affected @command{configure} scripts, or in the Autoconf M4
+source code for those macros; but in that case, their name or semantics
+may change in a future Autoconf version.
 
 The cache file is careful to not override any variables set in the site
 files.  Similarly, you should not override command-line options in the
@@ -24178,6 +24201,7 @@ Indices
 * Environment Variable Index::  Index of environment variables used
 * Output Variable Index::       Index of variables set in output files
 * Preprocessor Symbol Index::   Index of C preprocessor symbols defined
+* Cache Variable Index::        Index of documented cache variables
 * Autoconf Macro Index::        Index of Autoconf macros
 * M4 Macro Index::              Index of M4, M4sugar, and M4sh macros
 * Autotest Macro Index::        Index of Autotest macros
@@ -24212,6 +24236,19 @@ Preprocessor Symbol Index
 
 @printindex cv
 
address@hidden Cache Variable Index
address@hidden Cache Variable Index
+
+This is an alphabetical list of documented cache variables used
+by macros defined in Autoconf.  Autoconf macro may use additional cache
+variables internally.
address@hidden shortindexflag
+To make the list easier to use, the variables are listed without their
+preceding @samp{ac_cv_}.
address@hidden ifset
+
address@hidden CA
+
 @node Autoconf Macro Index
 @appendixsec Autoconf Macro Index
 
-- 
1.6.3.2.388.gb7132