[automake-commit] branch master updated: doc: test-driver option args are separate words.

[Karl Berry]

This is an automated email from the git hooks/post-receive script.

karl pushed a commit to branch master
in repository automake.

View the commit online:
https://git.savannah.gnu.org/gitweb/?p=automake.git;a=commitdiff;h=0d49ecb2e74d84fc2672eb4404fa22ccc8cc3170

The following commit(s) were added to refs/heads/master by this push:
     new 0d49ecb2e doc: test-driver option args are separate words.
0d49ecb2e is described below

commit 0d49ecb2e74d84fc2672eb4404fa22ccc8cc3170
Author: Mark Wooding <mdw@distorted.org.uk>
AuthorDate: Tue May 21 09:54:35 2024 -0700

    doc: test-driver option args are separate words.
    
    For https://bugs.gnu.org/70638.
    
    As now mentioned in the manual, the description of the
    test-driver command-line interface has been wrong since 2011
    when it was first added. The manual, and the driver usage
    messages themselves, have consistently shown option arguments
    joined to the option name with `=' characters, while the
    implementation of Automake has always provided option arguments
    in the following argument word, and the provided test drivers
    only accepted option arguments in the following argument word.
    
    Because Automake has never used the `=' syntax, there can't
    possibly be a working driver which actually follows the
    specification as written, so, despite the fierce language of the
    manual, we agreed that changing the specification was the right
    approach. The `test-driver' program's usage message has already
    been fixed (#22445), but the full extent of the problem wasn't
    noticed at that time.
    
    * doc/automake.texi (Command-line arguments for test drivers): Fix the
    table of options to show arguments passed as separate words; add
    footnote explaining this rather sorry situation.
    * doc/automake.texi (Use TAP with the Automake test harness):
    Remove `=' from documentation of `--diagnostic-string', because
    that was never acceptable either.
    * lib/tap-driver.sh: Fix usage message.
    * contrib/tap-driver.pl: Change usage message to match the defined
    protocol.  (This implementation parses options using Perl's
    `Getopt::Long' module, so it accepts the `=' syntax as specified, but
    this program isn't actually used.)
---
 contrib/tap-driver.pl |  8 ++++----
 doc/automake.texi     | 29 ++++++++++++++++++-----------
 lib/tap-driver.sh     |  8 ++++----
 3 files changed, 26 insertions(+), 19 deletions(-)

diff --git a/contrib/tap-driver.pl b/contrib/tap-driver.pl
index c48593984..787741e38 100755
--- a/contrib/tap-driver.pl
+++ b/contrib/tap-driver.pl
@@ -38,10 +38,10 @@ my $ME = "tap-driver.pl";
 
 my $USAGE = <<'END';
 Usage:
-  tap-driver --test-name=NAME --log-file=PATH --trs-file=PATH
-             [--expect-failure={yes|no}] [--color-tests={yes|no}]
-             [--enable-hard-errors={yes|no}] [--ignore-exit]
-             [--diagnostic-string=STRING] [--merge|--no-merge]
+  tap-driver --test-name NAME --log-file PATH --trs-file PATH
+             [--expect-failure {yes|no}] [--color-tests {yes|no}]
+             [--enable-hard-errors {yes|no}] [--ignore-exit]
+             [--diagnostic-string STRING] [--merge|--no-merge]
              [--comments|--no-comments] [--] TEST-COMMAND
 The '--test-name', '--log-file' and '--trs-file' options are mandatory.
 END
diff --git a/doc/automake.texi b/doc/automake.texi
index 2b897204e..4f7029fff 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -10127,37 +10127,44 @@ with the parallel test harness and its default driver.
 @subsubsection Command-line arguments for test drivers
 
 A custom driver can rely on various command-line options and arguments
-being passed to it automatically by the Automake-generated test harness.
-It is @emph{mandatory} that it understands all of them (even if the exact
-interpretation of the associated semantics can legitimately change
-between a test driver and another, and even be a no-op in some drivers).
+being passed to it automatically by the Automake-generated test
+harness.  It is @emph{mandatory} that it understands all of them (even
+if the exact interpretation of the associated semantics can
+legitimately change between a test driver and another, and even be a
+no-op in some drivers).  Options are separated from their arguments by
+whitespace.@footnote{Regrettably, older versions of this manual stated
+that option arguments should be joined to their options with a
+@code{=} character, rather than passed as in the following argument
+word as shown here.  The syntax with @code{=} has never been accepted
+by the test drivers supplied with Automake, and has never been
+produced by @file{Makefile}s generated by Automake.}
 
 @noindent
 Here is the list of options:
 
 @table @option
-@item --test-name=@var{NAME}
+@item --test-name @var{NAME}
 The name of the test, with VPATH prefix (if any) removed.  This can have a
 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 --log-file=@file{@var{PATH}.log}
+@item --log-file @file{@var{PATH}.log}
 The @file{.log} file the test driver must create (@pxref{Basics of
 test metadata}).  If it has a directory component (as in e.g.,
 @file{sub/foo.log}), the test harness will ensure that such directory
 exists @emph{before} the test driver is called.
-@item --trs-file=@file{@var{PATH}.trs}
+@item --trs-file @file{@var{PATH}.trs}
 The @file{.trs} file the test driver must create (@pxref{Basics of
 test metadata}).  If it has a directory component (as in e.g.,
 @file{sub/foo.trs}), the test harness will ensure that such directory
 exists @emph{before} the test driver is called.
-@item --color-tests=@{yes|no@}
+@item --color-tests @{yes|no@}
 Whether the console output should be colorized or not (@pxref{Simple
 tests and color-tests}, to learn when this option gets activated and
 when it doesn't).
-@item --expect-failure=@{yes|no@}
+@item --expect-failure @{yes|no@}
 Whether the tested program is expected to fail.
-@item --enable-hard-errors=@{yes|no@}
+@item --enable-hard-errors @{yes|no@}
 Whether ``hard errors'' in the tested program should be treated differently
 from normal failures or not (the default should be @code{yes}).  The exact
 meaning of ``hard error'' is highly dependent from the test protocols or
@@ -10383,7 +10390,7 @@ harness to get confused if anything that appears on 
standard error
 looks like a test result.
 @item --no-merge
 Revert the effects of @option{--merge}.
-@item --diagnostic-string=@var{STRING}
+@item --diagnostic-string @var{STRING}
 Change the string that introduces TAP diagnostics from the default value
 of ``@code{#}'' to @code{@var{STRING}}.  This can be useful if your
 TAP-based test scripts produce verbose output on which they have limited
diff --git a/lib/tap-driver.sh b/lib/tap-driver.sh
index f16f44df3..69121683a 100755
--- a/lib/tap-driver.sh
+++ b/lib/tap-driver.sh
@@ -48,10 +48,10 @@ print_usage ()
 {
   cat <<END
 Usage:
-  tap-driver.sh --test-name=NAME --log-file=PATH --trs-file=PATH
-                [--expect-failure={yes|no}] [--color-tests={yes|no}]
-                [--enable-hard-errors={yes|no}] [--ignore-exit]
-                [--diagnostic-string=STRING] [--merge|--no-merge]
+  tap-driver.sh --test-name NAME --log-file PATH --trs-file PATH
+                [--expect-failure {yes|no}] [--color-tests {yes|no}]
+                [--enable-hard-errors {yes|no}] [--ignore-exit]
+                [--diagnostic-string STRING] [--merge|--no-merge]
                 [--comments|--no-comments] [--] TEST-COMMAND
 The '--test-name', '-log-file' and '--trs-file' options are mandatory.
 END