VERBOSE=1 in [AM_]TESTS_ENVIRONMENT doc/feature

[Karl Berry]

It seems the VERBOSE variable is documented in only two places in
automake.texi, and neither place gives examples:

In Parallel Test Harness
    If the variable @samp{VERBOSE} is set, this
    file is output after the summary.

In Overview of Custom Test Drivers Support:
    use of @code{VERBOSE} environment variable to get verbose output on
    testsuite failures;

(Incidentally, it seems that both uses should either be @samp or @code,
not one of each. :)

As the long thread starting at
http://lists.gnu.org/archive/html/automake/2015-05/msg00008.html
shows, this has occasionally lead to confusion. It feels natural to set
VERBOSE = 1
in a Makefile.am, either on its own or as part of [AM_]TESTS_ENVIRONMENT,
but this does not work.

Thus I suggest
(1) adding "environment" before "variable" in Parallel Test Harness, and
(2) adding a few more words:
  
  This is typically set on the command line, as in
  @samp{make VERBOSE=1 check}. It does not work to set @code{VERBOSE} in
  @code{Makefile.am} or as part of @code{AM_TESTS_ENVIRONMENT} or
  @code{TESTS_ENVIRONMENT}.
  
At least that would give more of a clue as to usage. I don't see a need
to get into GNU make "export VERBOSE=1" features, etc.; "environment" is
the key fact.


Alternatively, allowing VERBOSE=1 to be set as part of
[AM_]TESTS_ENVIRONMENT seems feasible. Those envvars are in
am__check_pre, which is expanded before any $(LOG_DRIVER) call. So
expanding it before the of test of $$VERBOSE seems like it should
suffice. That is, deep in the $(TEST_SUITE_LOG) target, the line
          test x"$$VERBOSE" = x || cat $(TEST_SUITE_LOG);               \

could become
          $(am__check_pre) test x"$$VERBOSE" = x || cat $(TEST_SUITE_LOG);      
        \

When I tried it (by editing the generated Makefile), it seemed to work ok.
(Perhaps it would be better to do it at the beginning of
$(TEST_SUITE_LOG), but that's a judgement call I can't make.)

Happy hacking,
Karl