Re: [PATCH] {maint} docs: automake testsuite doesn't use TESTS_ENVIRONMENT anymore

[Stefano Lattarini]

On Wednesday 19 January 2011, Ralf Wildenhues wrote:
> Footnotes really impair the read flow, almost like top-posting,
> so it should be used very sparingly only.  How about this patch
> instead?
>
Just a nit below (and a praise below that :-)

> Thanks,
> Ralf
> 
> 2011-01-19  Stefano Lattarini  <address@hidden>
>           Ralf Wildenhues  <address@hidden>
> 
>       docs: automake testsuite doesn't use TESTS_ENVIRONMENT anymore
>       * doc/automake.texi (Simple Tests): Do not claim Automake uses
>       TESTS_ENVIRONMENT for the perl driver.  Instead, point to the
>       parallel-tests driver.
> 
> diff --git a/doc/automake.texi b/doc/automake.texi
> index 73c0e51..536b65f 100644
> --- a/doc/automake.texi
> +++ b/doc/automake.texi
> @@ -8596,13 +8596,19 @@ Simple Tests
>  set in the rule.  If all your test programs are scripts, you can also
>  set @code{TESTS_ENVIRONMENT} to an invocation of the shell (e.g.
>  @samp{$(SHELL) -x} can be useful for debugging the tests), or any other
> -interpreter.  For instance the following setup is used by the Automake
> -package to run four tests in Perl.
> +interpreter.  For instance the following setup may be used to run tests
> +with Perl:
> +
>  @example
>  TESTS_ENVIRONMENT = $(PERL) -Mstrict -I $(top_srcdir)/lib -w
>  TESTS = Condition.pl DisjConditions.pl Version.pl Wrap.pl
>
At this point, if we're not referring to Automake's own tests anymore,
I'd dumb that down to e.g.:

  For instance, the following setup may be used to run tests
  with Perl:

  @example
  TESTS_ENVIRONMENT = $(PERL) -Mstrict -w
  TESTS = foo.pl bar.pl baz.pl
  ...

which si IMVHO slightly clearer for the "casual" reader.  But I won't
hold my breath on this.

>  @end example
>  
> +Note that the @option{parallel-tests} driver provides a more elegant
> +way to achieve the same effect, freeing the @code{TESTS_ENVIRONMENT}
> +variable for the user to override (@pxref{Simple Tests using
> +parallel-tests}).
> +
>
I definitely like this second hunk; since I regard the 'parallel-tests'
driver as vastly superiour to the old 'simple-tests' driver, I'm happy
whenever the documentation advises to prefer (or at least try) the
former.

>  @cindex Tests, expected failure
>  @cindex Expected test failure
> 

Regards,
  Stefano