AC_CHECK_PROG and precious variables (documentation)

[Stepan Kasal]

Hello,
  the autoconf manual contains the following notice:

        You are strongly encouraged to declare the VARIABLE passed to
        `AC_CHECK_PROG' etc. as precious, [...]

Why, I wondered?  After some experimenting I discovered, that if the
VARIABLE is already set, configure doesn't search for the program.
And it seems to be the same with all macros mentioned in that node.
(And, of course, the same holds for the specific program tests.)

Then I discovered that the manual mentiones this--at the end of
the paragraph describing AC_CHECK_PROG, it says:

        If VARIABLE was already set, do nothing.

But that short notice can be easily overlooked.  And, the other macros
don't contain such a notice.

Several macro descriptions in that node contain phrase:

        [...]; if VALUE-IF-NOT-FOUND is not specified, the value of
        VARIABLE is not changed.

This phrase is misleading, as the code is executed only if the variable
was empty.  Thus it in fact means ``the VARIABLE remains unassigned.''

I beleive the common information can be moved from the individual macro
descriptions to one place, prehaps the node ``Alternative Programs''.

BTW, wouldn't it be nicer to rename this node to ``Programs''?
I think that the current name doesn't reflect the fact that we often
check for the _presence_ of a program.  (Notice below that I added the
word ``also'' to the first paragraph of the node.)

It could look like this:

Alternative Programs
====================

These macros check for the presence or behavior of particular programs.
They are _also_ used to choose between several alternative programs and
to decide what to do once one has been chosen.

These macros work with an environment variable, eg. @code{GREP}; for 
the generic macros, you specify the variable name as the first
parameter.

If the variable is already set, the macro does nothing.

If it is not set, it looks for the program.  If the program is found,
it's name is assigned to the variable.  (Or name with parameters, or full
pathname, it depends on the individual macros.)  If the program is not
found and an optional parameter VALUE-IF-NOT-FOUND was specified, that
value is assigned to the variable.

All these macros call AC_SUBST on the variable.

As the result depends on the initial value of the variable, it should
be declared as precious.  This is done automatically by the specific
tests; for the generic macros, you are strongly encouradged to declare
the variable as precious, *Note Setting Output Variables::,
`AC_ARG_VAR', for more details.

If there is no macro specifically defined to check for a program you
need, and you don't need to check for any special properties of it,
then you can use one of the general program-check macros.

* Menu:
...
-------------------

I'm not making a patch at this stage, as I'm not sure what course
you'll take.

And, BTW, why don't the generic macros themselves make the variable
precious?

Regards,
        Stepan Kasal