[PATCH 5/8] Improve description of `run_command' in README

[Stefano Lattarini]

Improve description of `run_command' in README

* tests/README: Improve and extend the existing description of
the `run_command' function, and explicitly tell that it can be
useful also to save stdout, not only stderr.  Also, point the
reader to the function's comments in `tests/defs.in' for more
information.

From 1637c448ad4c315f4fba501d46a568ceca3f2da8 Mon Sep 17 00:00:00 2001
From: Stefano Lattarini <address@hidden>
Date: Fri, 29 Jan 2010 15:22:11 +0100
Subject: [PATCH 5/8] Improve description of `run_command' in README

* tests/README: Improve and extend the existing description of
the `run_command' function, and explicitly tell that it can be
useful also to save stdout, not only stderr.  Also, point the
reader to the function's comments in `tests/defs.in' for more
information.
---
 ChangeLog    |    9 +++++++++
 tests/README |   27 ++++++++++++++++++++-------
 2 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 7713265..42cd834 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2010-01-31  Stefano Lattarini  <address@hidden>
+
+       Testsuite: improve description of `run_command' function in README
+       * tests/README: Improve and extend the existing description of
+       the `run_command' function, and explicitly tell that it can be
+       useful also to save stdout, not only stderr.  Also, point the
+       reader to the function's comments in `tests/defs.in' for more
+       information.
+
 2009-01-31  Stefano Lattarini  <address@hidden>
 
        Work around a bug of AT&T Korn shell w.r.t. `${1+"$@"}'.
diff --git a/tests/README b/tests/README
index dce0bc4..4340d44 100644
--- a/tests/README
+++ b/tests/README
@@ -133,15 +133,28 @@ Do
   Use $sleep when you have to make sure that some file is newer
   than another.
 
-  To run a program and analyze its stderr, use the run_command function.
-  For example:
+  To run a program and analyze its stderr, use the `run_command'
+  function rather than doing "direct" stderr redirection.
+  For example, *don't* do:
+     PROG [ARGS...] 2>prog.err
+     grep $pattern prog.err
+  but rather do:
      run_command PROG [ARGS...]
+     # the previous call has saved the standard error produced by
+     # PROG in the file `stderr'
      grep $pattern stderr
-  or (if you must check that nothing is written on stderr):
-     run_command PROG2 [ARGS...]
-     test ! -s stderr
-  See section "File Descriptors" in the Autoconf manual to understand why
-  this can be useful, or even required.
+  See section "File Descriptors" in the Autoconf manual to understand
+  why this can be useful, or even required (the reason is mostly linked
+  to a Zsh-specific behaviour of the `xtrace' shell option, which is
+  globally enabled in the Automake's testsuite).  Note moreover that
+  `run_command' can be useful also to run a program and analyze its
+  stdout; for example:
+     run_command PROG [ARGS...]
+     # the previous call has saved the standard output produced by
+     # PROG in the file `stdout'
+     diff expected-stdout stdout
+  A detailed and thorough description of `run_command' can be found
+  in the comments in file `tests/defs.in'.
 
   Use `cat' or `grep' to display (part of) files that may be
   interesting for debugging, so that when a user send a verbose
-- 
1.6.5