Re: [FYI] {master} docs: fix unportable example of AM_TESTS_ENVIRONMENT usage

[Ralf Wildenhues]

* Stefano Lattarini wrote on Thu, Jun 23, 2011 at 07:09:16PM CEST:
> * doc/automake.texi (Simple Tests using parallel-tests): The
> old example on AM_TESTS_ENVIRONMENT relied on unportable shell
> features, and in particular didn't work with various Korn
> Shells (see also commit `v1.11-925-g29ca903').  Give another
> example, simpler this time, but still inspired to real-world
> usage (the GNU coreutils testsuite).

> --- a/doc/automake.texi
> +++ b/doc/automake.texi
> @@ -8742,21 +8742,23 @@ code and set environment variables for the tests' 
> runs.  The user can
>  still employ the @code{TESTS_ENVIRONMENT} variable to override settings
>  from @code{AM_TESTS_ENVIRONMENT}.  Note that, for implementation reasons,
>  if the @code{AM_TESTS_ENVIRONMENT} variable is set, its contents
> address@hidden be terminated by a semicolon.
> -
> address@hidden
> -# The tests below are expected to use the file descriptor passed in
> -# the environment variable 'warn_fileno' to print warnings (e.g.,
> -# about skipped and failed tests).  If this variable were to be set
> -# to `2' (i.e. default stderr), the warnings would be redirected by
> -# the automake parallel-tests driver into the .log files.  But the
> -# AM_TESTS_ENVIRONMENT definition below will cause the reasons for
> -# skip/failure to be printed to the console instead.  The user
> -# can still override this by setting TESTS_ENVIRONMENT to e.g.
> -# `warn_fileno=2' at make runtime, which will cause the warnings
> -# to be sent to the .log files again.
> -TESTS = test1.sh test2.sh ...
> -AM_TESTS_ENVIRONMENT = exec 9>&2; warn_fileno=9; export warn_fileno;

This example served two purposes: use of AM_TESTS_ENVIRONMENT, and
showing how to produce output while the test is running.  Your patch
removes the second feature.  Can we have it back, ideally in a portable
fashion?

> address@hidden be terminated by a semicolon.  Here is an example of a
> +slightly elaborate definition:
> +
> address@hidden
> +# Some environment initializations are kept in a separate shell file
> +# `tests-env.sh', which can be helpful to run tests from the command line.

> +# We don't want to depend on the `srcdir' value exported by the Automake
> +# testsuite harness; we define it statically in the `tests-env' file.

This sentence does not make sense to me, in this particular context.
As a user, it would confuse me, at least without further explanation.

> +# On Solaris, prefer more POSIX-compliant versions of the standard tools
> +# by default.
> +AM_TESTS_ENVIRONMENT = \
> +  unset srcdir; \
> +  . $(srcdir)/tests-env.sh; \
> +  if test -d /usr/xpg4/bin; then \
> +    PATH=/usr/xpg4/bin:$$PATH; export PATH; \
> +  fi;
> address@hidden $$ restore font-lock
>  @end example
>  
>  @trindex mostlyclean

Thanks,
Ralf