Re: [PATCH 2/2] doc: index entries for non-environment, non-output variables.

[Ralf Wildenhues]

Hi Eric, and thanks for the reviews,

I've taken the uncontroversial part of 1/2 and pushed that now.

* Eric Blake wrote on Tue, Sep 07, 2010 at 04:29:51PM CEST:
> On 09/06/2010 12:06 AM, Ralf Wildenhues wrote:
> >@@ -4316,6 +4316,7 @@ Generic Programs
> >    @ovar{action-if-not-found}, @dvar{path, $PATH})
> >  @acindex{PATH_PROGS_FEATURE_CHECK}
> >  @caindex address@hidden
> >address@hidden address@hidden
> >  This macro was introduced in Autoconf 2.62.  If @var{variable} is not
> >  empty, then set the cache variable @address@hidden to
> 
> Is this right?
> 
> This section talks about:
> 
> ac_cv_path_VARIABLE
> ac_path_VARIABLE_found
> 
> But not ac_path_VARIABLE.

Both are mentioned:

  For each program
  found, execute @var{feature-test} with @address@hidden
  set to the absolute name of the candidate program. [...]
  [...] to accept the
  current setting and bypass all futher checks, @var{feature-test} can
  execute @address@hidden:}.

So I guess both of these could be indexed.

* Eric Blake wrote on Tue, Sep 07, 2010 at 04:35:09PM CEST:
> On 09/06/2010 12:07 AM, Ralf Wildenhues wrote:
> >* doc/autoconf.texi: Merge variable index `vr' into concept
> >index using syncodeindex.
> >* doc/autoconf.texi (Configuration Actions, Generic Programs)
> >(Generic Functions, Initialization Macros, Writing Testsuites):
> >Add index entries for documented shell variables used during
> >in configure and testsuite scripts.  Fix entry for `tmp'.
> 
> >
> >  @table @code
> >  @item srcdir
> >address@hidden srcdir
> 
> Why @vrindex instead of @ovindex?  We already document:
> 
> @c Define an output variable index.
> @defcodeindex ov
> 
> for all variables that are set during configure/autotest for use by
> the remainder of the script.
[...]

> Oh, I see - you're trying to make a distinction between @ovindex and
> @vrindex.  Can we document that distinction both in the commit
> message and in the comments at the top of autoconf.texi that
> describe all the various indices?

Sure.  Here's a redo of the remainder of 1/2 and fixed 2/2, with
comments for the various indices updated.  OK?

Thanks,
Ralf

    doc: index entries for non-environment, non-output variables.
    
    * doc/autoconf.texi: Clarify the meaning of the various variable
    indices.  Merge variable index `vr' into concept index using
    syncodeindex.
    (Configuration Actions, Generic Programs, Generic Functions)
    (Writing Testsuites): Add index entries for documented shell
    variables used during in configure and testsuite scripts.

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index e068ff7..22fd614 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -46,14 +46,18 @@
 @c with texi2dvi.  But then you wake up an old problem: we use macros
 @c in @defmac etc. where TeX does perform the expansion, but not makeinfo.
 
address@hidden Define an environment variable index.
address@hidden Define an environment variable index, for variables users may set
address@hidden in their environment or on the configure command line.
 @defcodeindex ev
address@hidden Define an output variable index.
address@hidden Define an output variable index, for commonly AC_SUBST'ed 
variables.
 @defcodeindex ov
address@hidden Define a CPP variable index.
address@hidden cv
address@hidden Define a cache variable index.
address@hidden Define a cache variable index, for variables matching *_cv_*.
 @defcodeindex CA
address@hidden Other shell variables not fitting the above categories should be
address@hidden listed in the predefined vrindex, which we merge in the concept 
index.
address@hidden vr cp
address@hidden Define a CPP preprocessor macro index, for #define'd strings.
address@hidden cv
 @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.
@@ -2250,25 +2254,30 @@ Configuration Actions
 
 @table @code
 @item srcdir
address@hidden srcdir
 The name of the top source directory, assuming that the working
 directory is the top build directory.  This
 is what the @command{configure} option @option{--srcdir} sets.
 
 @item ac_top_srcdir
address@hidden ac_top_srcdir
 The name of the top source directory, assuming that the working
 directory is the current build directory.
 
 @item ac_top_build_prefix
address@hidden ac_top_build_prefix
 The name of the top build directory, assuming that the working
 directory is the current build directory.
 It can be empty, or else ends with a slash, so that you may concatenate
 it.
 
 @item ac_srcdir
address@hidden ac_srcdir
 The name of the corresponding source directory, assuming that the
 working directory is the current build directory.
 
 @item tmp
address@hidden tmp
 The name of a temporary directory within the build tree, which you
 can use if you need to create additional temporary files.  The
 directory is cleaned up when @command{config.status} is done or
@@ -4320,6 +4329,8 @@ Generic Programs
   @ovar{action-if-not-found}, @dvar{path, $PATH})
 @acindex{PATH_PROGS_FEATURE_CHECK}
 @caindex address@hidden
address@hidden address@hidden
address@hidden address@hidden
 This macro was introduced in Autoconf 2.62.  If @var{variable} is not
 empty, then set the cache variable @address@hidden to
 its value.  Otherwise, check for each program in the blank-separated
@@ -5556,6 +5567,7 @@ Generic Functions
 Specify that @address@hidden must be included in the executables
 to replace a missing or broken implementation of @var{function}.
 
address@hidden ac_objext
 Technically, it adds @address@hidden to the output
 variable @code{LIBOBJS} if it is not already in, and calls
 @code{AC_LIBSOURCE} for @address@hidden  You should not
@@ -23969,6 +23981,7 @@ Writing Testsuites
 @defmac AT_ARG_OPTION (@var{options}, @var{help-text}, @
   @ovar{action-if-given}, @ovar{action-if-not-given})
 @atindex{ARG_OPTION}
address@hidden address@hidden
 Accept options from the space-separated list @var{options}, a list that
 has leading dashes removed from the options.  Long options will be
 prefixed with @samp{--}, single-character options with @samp{-}.  The
@@ -23982,6 +23995,8 @@ Writing Testsuites
 option, or passes @address@hidden, then the variable will be
 set to @samp{false}.
 
address@hidden at_optarg
address@hidden address@hidden
 @var{action-if-given} is run each time the option is encountered; here,
 the variable @code{at_optarg} will be set to @samp{:} or @samp{false} as
 appropriate.  @code{at_optarg} is actually just a copy of
@@ -24000,6 +24015,7 @@ Writing Testsuites
 @defmac AT_ARG_OPTION_ARG (@var{options}, @var{help-text}, @
   @ovar{action-if-given}, @ovar{action-if-not-given})
 @atindex{ARG_OPTION_ARG}
address@hidden address@hidden
 Accept options with arguments from the space-separated list
 @var{options}, a list that has leading dashes removed from the options.
 Long options will be prefixed with @samp{--}, single-character options
@@ -24012,6 +24028,7 @@ Writing Testsuites
 @address@hidden @var{arg}} to the @command{testsuite}, the
 variable will be set to @address@hidden
 
address@hidden at_optarg
 @var{action-if-given} is run each time the option is encountered; here,
 the variable @code{at_optarg} will be set to @address@hidden
 @code{at_optarg} is actually just a copy of @address@hidden