docs: fix unportable example of AM_TESTS_ENVIRONMENT usage

* 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).

diff --git a/ChangeLog b/ChangeLog
index f121e0e0554a582dea7db6766ca020e48a1fe37b..7c8888e1b15e104b152c52b6035a5bf0b3f39c49 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2011-06-29  Stefano Lattarini  <stefano.lattarini@gmail.com>
+
+       docs: fix unportable example of AM_TESTS_ENVIRONMENT usage
+       * 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).
+
 2011-04-18  Stefano Lattarini  <stefano.lattarini@gmail.com>
 
        check: rename AM_TESTS_SETUP -> AM_TESTS_ENVIRONMENT

diff --git a/doc/automake.texi b/doc/automake.texi
index 7394253a200fcb3c705807b228ad15fc7867c02c..d60bfe49bb3f57f9cfa4fd5a8f0227e730e0144a 100644 (file)
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -8742,21 +8742,21 @@ 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
-@emph{must} be terminated by a semicolon.
-
-@example
-# 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;
+@emph{must} be terminated by a semicolon.  Here is an example of a
+slightly elaborate definition:
+
+@example
+AM_TESTS_ENVIRONMENT = \
+## Some environment initializations are kept in a separate shell file
+## `tests-env.sh', which can make it easier to also run tests from the
+## command line.
+  . $(srcdir)/tests-env.sh; \
+## On Solaris, prefer more POSIX-compliant versions of the standard tools
+## by default.
+  if test -d /usr/xpg4/bin; then \
+    PATH=/usr/xpg4/bin:$$PATH; export PATH; \
+  fi;
+@c $$ restore font-lock
 @end example
 
 @trindex mostlyclean