Re: [PATCH 4/5] Documentation of specific and general cache variables.

[Ralf Wildenhues]

Hello Bruno,

* Bruno Haible wrote on Sun, Oct 04, 2009 at 07:31:05PM CEST:
> >  @defmac AC_PROG_GREP

> >  Look for the best available @code{grep} or @code{ggrep} that accepts the
> >  longest input lines possible, and that supports multiple @option{-e} 
> > options.
> >  Set the output variable @code{GREP} to whatever is chosen.
> >  @xref{grep, , Limitations of Usual Tools}, for more information about
> > -portability problems with the @command{grep} command family.
> > +portability problems with the @command{grep} command family.  The result
> > +is cached in the @code{ac_cv_path_GREP} variable.
> >  @end defmac
> 
> I fear that by reading this, people think that using $ac_cv_path_GREP is
> preferred to using $GREP.
> 
> Recall that the reason to document the cache variables is
>   1) to tell people how to override the results (from the command line
>      invocation of configure, or through config.site),
>   2) to legitimize the use of e.g. ac_cv_func_foo for autoconf macros
>      which have no documented output/result variable - but only for these!

This is good reasoning in general.

> So I propose to reformulate the sentence about the cache variable for those
> macros which already have a documented output variable.

To me, it seems some of your changes stress the importance of the cache
variables even more than the text before did; but I may be
misunderstanding them.  Details below.

> Note also that the cache variable for AC_PROG_SED is ac_cv_path_SED, not
> ac_cv_prog_SED.

Yep.

> And ac_cv_func_getmntent is used as a result variable of
> AC_FUNC_GETMNTENT, not as a cache variable name.

Ouch.  It means setting ac_cv_func_getmntent doesn't impact the result.
That's an unfortunate inconsistency.

Thanks for proof-reading, BTW!

> 2009-10-04  Bruno Haible  <address@hidden>
> 
>       * doc/autoconf.texi (AC_PROG_AWK, AC_PROG_GREP, AC_PROG_EGREP,
>       AC_PROG_FGREP, AC_PROG_INSTALL, AC_PROG_MKDIR_P, AC_PROG_LEX,
>       AC_PROG_YACC, AC_CHECK_PROG, AC_CHECK_PROGS, AC_PATH_PROG,
>       AC_PATH_PROGS): Don't suggest to use the cache variable, only to 
> override it.
>       (AC_PROG_SED): Likewise. Fix name of cache variable.
>       (AC_FUNC_GETMNTENT): Fix name cache variable.
>       (AC_FUNC_LSTAT): Fix typo.
> 
> --- doc/autoconf.texi.orig    2009-10-04 19:23:44.000000000 +0200
> +++ doc/autoconf.texi 2009-10-04 18:44:58.000000000 +0200
> @@ -3873,8 +3873,8 @@
>  Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that
>  order, and set output variable @code{AWK} to the first one that is found.
>  It tries @code{gawk} first because that is reported to be the
> -best implementation.  The result is cached in the @code{ac_cv_prog_AWK}
> -variable.
> +best implementation.  The result can be overridden by setting the
> +variable @code{AWK} or the cache variable @code{ac_cv_prog_AWK}.

Looks good.  Below, I have dropped further hunks that look good to me.

> @@ -3886,7 +3886,7 @@
>  Set the output variable @code{GREP} to whatever is chosen.
>  @xref{grep, , Limitations of Usual Tools}, for more information about
>  portability problems with the @command{grep} command family.  The result
> -is cached in the @code{ac_cv_path_GREP} variable.
> +can be overridden by setting the cache variable @code{ac_cv_path_GREP}.

This sounds to me like we stress ac_cv_path_GREP over GREP even more
than before your patch.  Maybe it's due to my lack of understanding
English nuances, but "is cached" sounds less like "go, use this variable"
than "can be overridden" does.  IOW, to me, this text makes it even less
clear that $GREP is the method of choice.  Why not something like?

  The result can be overridden by setting the @code{GREP} variable and
  is cached in the @code{ac_cv_path_GREP} cache variable.

If we can agree on this I can apply a combined patch to change these.

> @@ -3896,7 +3896,7 @@
>  Check whether @code{$GREP -E} works, or else look for the best available
>  @code{egrep} or @code{gegrep} that accepts the longest input lines possible.
>  Set the output variable @code{EGREP} to whatever is chosen.  The result
> -is cached in the @code{ac_cv_path_EGREP} variable.
> +can be overridden by setting the cache variable @code{ac_cv_path_EGREP}.
>  @end defmac
>  
>  @defmac AC_PROG_FGREP
> @@ -3906,7 +3906,7 @@
>  Check whether @code{$GREP -F} works, or else look for the best available
>  @code{fgrep} or @code{gfgrep} that accepts the longest input lines possible.
>  Set the output variable @code{FGREP} to whatever is chosen.  The result
> -is cached in the @code{ac_cv_path_FGREP} variable.
> +can be overridden by setting the cache variable @code{ac_cv_path_FGREP}.

These have the same issues as the GREP case.

[...]
> @@ -4092,13 +4093,14 @@
>  @defmac AC_PROG_SED
>  @acindex{PROG_SED}
>  @ovindex SED
> address@hidden prog_SED
> address@hidden path_SED
>  Set output variable @code{SED} to a Sed implementation that conforms to
>  Posix and does not have arbitrary length limits.  Report an error if no
>  acceptable Sed is found.  @xref{sed, , Limitations of Usual Tools}, for more
>  information about portability problems with Sed.
>  
> -The result of this test is cached in the @code{ac_cv_prog_SED} variable.
> +The result of this test can be overridden by setting the cache variable
> address@hidden

This has the same problems as the GREP case.

> @@ -4147,8 +4150,9 @@
>  that case, set @var{variable} using the absolute file name of the
>  @var{prog-to-check-for} found that is not @var{reject}.  If
>  @var{variable} was already set, do nothing.  Calls @code{AC_SUBST} for
> address@hidden  The result of this test is cached in the
> address@hidden@var{variable}} variable.
> address@hidden  The result of this test can be overridden by setting the
> +variable @var{variable} or the cache variable

I think it is better English style to transpose words here:
  @var{variable} variable

> address@hidden@var{variable}}.
>  @end defmac
>  
>  @anchor{AC_CHECK_PROGS}

> @@ -4163,7 +4167,8 @@
>  list are found, set @var{variable} to @var{value-if-not-found}; if
>  @var{value-if-not-found} is not specified, the value of @var{variable}
>  is not changed.  Calls @code{AC_SUBST} for @var{variable}.  The result of
> -this test is cached in the @address@hidden variable.
> +this test can be overridden by setting the variable @var{variable} or the

Likewise.

> +cache variable @address@hidden
>  @end defmac

[...]
> @@ -4245,8 +4250,9 @@
>  @acindex{PATH_PROG}
>  @caindex address@hidden
>  Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute
> -name of @var{prog-to-check-for} if found.  A positive result of this
> -test is cached in the @address@hidden variable.
> +name of @var{prog-to-check-for} if found.  The result of this test
> +can be overridden by setting the cache variable
> address@hidden@var{variable}}.

That has the same problem as the GREP case.

Furter, it is less specific than the formulation I used; it is an
important part of the API that the cache variable is not set if no
program is found.  That is needed for AC_PATH_PROGS, and I'm sure
in some user scripts as well.

> @@ -4256,7 +4262,8 @@
>  @caindex address@hidden
>  Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for}
>  are found, set @var{variable} to the absolute name of the program
> -found.
> +found.  The result of this test can be overridden by setting the cache
> +variable @address@hidden

Oops.  Good catch.

> @@ -5000,14 +5007,16 @@
>  @cvindex HAVE_GETMNTENT
>  @c @fuindex getmntent
>  @prindex @code{getmntent}
> address@hidden func_getmntent
> address@hidden search_getmntent
>  Check for @code{getmntent} in the standard C library, and then in the
>  @file{sun}, @file{seq}, and @file{gen} libraries, for @sc{unicos},
>  @sc{irix} 4, @sc{ptx}, and UnixWare, respectively.  Then, if
> address@hidden is available, define @code{HAVE_GETMNTENT}.
> address@hidden is available, define @code{HAVE_GETMNTENT} and set
> address@hidden to @code{yes}.  Otherwise set
> address@hidden to @code{no}.

Thanks.

> -The result of this macro is cached in the @code{ac_cv_func_getmntent}
> -variable.
> +The result of this macro can be overridden by setting the cache variable
> address@hidden

Again, I'm not sure what is bought by this change here.

Cheers,
Ralf