[FYI] {test-protocols} docs: some fixlets in documentation on testsuites support

[Stefano Lattarini]

* doc/automake.texi (Script-based Testsuites): Rename node ...
(Scripts-based Testsuites): ... to this.  Break overly long lines
in an example (were causing problems with PDF output).
(Parallel Test Harness): Don't intend paragraphs that come after
examples or bulleted list.
(Overview of Custom Test Drivers Support): Fix typo s/the the/the/.
(Declaring Custom Test Drivers): When giving an aside, prefer comma
to parentheses, as it disrupts the reading flow less.
(API for Custom Test Drivers): Remove a sentence that was basically
duplicated from the previous subsection.
(Command-line arguments for test drivers): Don't intend paragraph
coming after an itemized list.  Clarify wording and fix grammaros.
Add a couple of cross-references to earlier explanations of `.log'
and `.trs' files.
(Links and external resources): Node renamed ...
(Links and external resources on TAP): ... to this, for clarity.
Slightly extend and clarify introductory sentence.
---
 ChangeLog         |   21 ++++++++++++++++
 doc/automake.texi |   68 ++++++++++++++++++++++++++++-------------------------
 2 files changed, 57 insertions(+), 32 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index f5c8d10..036e18e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,24 @@
+2011-08-05  Stefano Lattarini  <address@hidden>
+
+       docs: some fixlets in documentation on testsuites support
+       * doc/automake.texi (Script-based Testsuites): Rename node ...
+       (Scripts-based Testsuites): ... to this.  Break overly long lines
+       in an example (were causing problems with PDF output).
+       (Parallel Test Harness): Don't intend paragraphs that come after
+       examples or bulleted list.
+       (Overview of Custom Test Drivers Support): Fix typo s/the the/the/.
+       (Declaring Custom Test Drivers): When giving an aside, prefer comma
+       to parentheses, as it disrupts the reading flow less.
+       (API for Custom Test Drivers): Remove a sentence that was basically
+       duplicated from the previous subsection.
+       (Command-line arguments for test drivers): Don't intend paragraph
+       coming after an itemized list.  Clarify wording and fix grammaros.
+       Add a couple of cross-references to earlier explanations of `.log'
+       and `.trs' files.
+       (Links and external resources): Node renamed ...
+       (Links and external resources on TAP): ... to this, for clarity.
+       Slightly extend and clarify introductory sentence.
+
 2011-08-04  Stefano Lattarini  <address@hidden>
 
        test harness: be aware of more metadata, simplify test drivers
diff --git a/doc/automake.texi b/doc/automake.texi
index 2ae1aaa..cab0fca 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -326,7 +326,7 @@ Support for test suites
 
 Simple Tests
 
-* Script-based Testsuites::     Automake-specific concepts and terminology
+* Scripts-based Testsuites::    Automake-specific concepts and terminology
 * Serial Test Harness::         Older (and obsolescent) serial test harness
 * Parallel Test Harness::       Generic concurrent test harness
 
@@ -335,7 +335,7 @@ Using the TAP test protocol
 * Introduction to TAP::
 * Use TAP with the Automake test harness::
 * Incompatibilities with other TAP parsers and drivers::
-* Links and external resources::
+* Links and external resources on TAP::
 
 Custom Test Drivers
 
@@ -8795,13 +8795,13 @@ terminology)?
 @section Simple Tests
 
 @menu
-* Script-based Testsuites::     Automake-specific concepts and terminology
+* Scripts-based Testsuites::    Automake-specific concepts and terminology
 * Serial Test Harness::         Older (and obsolescent) serial test harness
 * Parallel Test Harness::       Generic concurrent test harness
 @end menu
 
address@hidden Script-based Testsuites
address@hidden Script-based Testsuites
address@hidden Scripts-based Testsuites
address@hidden Scripts-based Testsuites
 
 If the special variable @code{TESTS} is defined, its value is taken to be
 a list of programs or scripts to run in order to do the testing.  Under
@@ -8931,9 +8931,9 @@ HP-UX's @command{/bin/sh},
 @c Keep in sync with tests-environment-backcompat.test.
 @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.
+## 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.
@@ -8941,10 +8941,10 @@ AM_TESTS_ENVIRONMENT = \
     PATH=/usr/xpg4/bin:$$PATH; export PATH; \
   fi;
 @c $$ restore font-lock
-## With this, the test scripts will be able to print diagnostic messages
-## to the original standard error stream, even if the test driver
-## redirects the stderr of the test scripts to a log file before executing
-## them.
+## With this, the test scripts will be able to print diagnostic
+## messages to the original standard error stream, even if the test
+## driver redirects the stderr of the test scripts to a log file
+## before executing them.
 AM_TESTS_FD_REDIRECT = 9>&2
 @end example
 
@@ -9129,6 +9129,7 @@ AM_LOG_FLAGS = -Mstrict -w
 @trindex check-html
 @vindex RST2HTML
 @vindex TEST_SUITE_HTML
address@hidden
 With @code{make check-html}, the log files may be converted from RST
 (reStructuredText, see @uref{http://docutils.sourceforge.net/@/rst.html})
 to HTML using @samp{RST2HTML}, which defaults to @command{rst2html} or
@@ -9204,6 +9205,7 @@ does the same as @code{recheck} but again converts the 
resulting
 @file{.log} file in HTML format, like the @code{check-html} target.
 @end itemize
 
address@hidden
 In order to guarantee an ordering between tests even with @code{make
 address@hidden, dependencies between the corresponding @file{.log} files
 may be specified through usual @command{make} dependencies.  For example,
@@ -9295,7 +9297,7 @@ protocols are TAP and SubUnit).
 
 It's very important to note that, even when using custom test drivers,
 most of the infrastructure described in the previous section about the
-the parallel harness remains in place; this includes:
+parallel harness remains in place; this includes:
 
 @itemize
 @item
@@ -9361,9 +9363,9 @@ coexist.
 
 The developer-reserved variable @code{AM_LOG_DRIVER_FLAGS} and the
 user-reserved variable @code{LOG_DRIVER_FLAGS} can be used to define
-flags that will be passed to each invocation of @code{LOG_DRIVER}
-(with the user-defined flags obviously taking precedence over the
-developer-reserved ones).  Similarly, for each extension @var{ext}
+flags that will be passed to each invocation of @code{LOG_DRIVER},
+with the user-defined flags obviously taking precedence over the
+developer-reserved ones.  Similarly, for each extension @var{ext}
 declared in @code{TEST_EXTENSIONS}, flags listed in
 @address@hidden and
 @address@hidden will be passed to
@@ -9378,9 +9380,7 @@ for new features or to satisfy additional portability 
requirements.
 
 The main characteristic of these APIs is that they are designed to share
 as much infrastructure, semantics, and implementation details as possible
-with the parallel test harness and its default driver.  So everything
-said in the previous section should apply here too, unless explicitly
-stated otherwise.
+with the parallel test harness and its default driver.
 
 @menu
 * Command-line arguments for test drivers::
@@ -9409,13 +9409,15 @@ suffix and a directory component (as in e.g., 
@file{sub/foo.test}), and is
 mostly meant to be used in console reports about testsuite advancements and
 results (@pxref{Testsuite progress output}).
 @item address@hidden@var{PATH}.log}
-The @file{.log} file the test driver must create.  If it has a directory
-component (as in e.g., @file{sub/foo.log}), the test harness will ensure
-that such directory exist @emph{before} the test driver is called.
+The @file{.log} file the test driver must create (@pxref{Basics of
+test metadata}).  If it has a directory component (as in e.g.,
address@hidden/foo.log}), the test harness will ensure that such directory
+exists @emph{before} the test driver is called.
 @item address@hidden@var{PATH}.trs}
-The @file{.trs} file the test driver must create.  If it has a directory
-component (as in e.g., @file{sub/foo.trs}), the test harness will ensure
-that such directory exist @emph{before} the test driver is called.
+The @file{.trs} file the test driver must create (@pxref{Basics of
+test metadata}).  If it has a directory component (as in e.g.,
address@hidden/foo.trs}), the test harness will ensure that such directory
+exists @emph{before} the test driver is called.
 @item address@hidden|address@hidden
 Whether the console output should be colorized or not (@pxref{Simple
 tests and color-tests}, to learn when this option gets activated and
@@ -9431,9 +9433,10 @@ conventions in use.
 Explicitly terminate the list of options.
 @end table
 
-The first of the remaining arguments passed to the test driver is the
-program to be run, and the other arguments are command-line options
-and arguments for this program.
address@hidden
+The first non-option argument passed to the test driver is the program to
+be run, and all the following ones are command-line options and arguments
+for this program.
 
 Note that the exact semantics attached to the @option{--color-tests},
 @option{--expect-failure} and @option{--enable-hard-errors} options are
@@ -9589,7 +9592,7 @@ harness should remain untouched, and continue to work 
correctly.
 * Introduction to TAP::
 * Use TAP with the Automake test harness::
 * Incompatibilities with other TAP parsers and drivers::
-* Links and external resources::
+* Links and external resources on TAP::
 @end menu
 
 @node Introduction to TAP
@@ -9761,12 +9764,13 @@ the ``hard error'' concept of the default 
@option{parallel-tests} driver.
 @emph{TODO}: there's surely something else ...
 @end itemize
 
address@hidden Links and external resources
address@hidden Links and external resources
address@hidden Links and external resources on TAP
address@hidden Links and external resources on TAP
 
 @noindent
 Here are some links to more extensive official or third-party
-documentation and resources:
+documentation and resources about the TAP protocol and related
+tools and libraries.
 @itemize @bullet
 @item
 @uref{http://search.cpan.org/~petdance/Test-Harness/lib/Test/Harness/TAP.pod,
-- 
1.7.2.3