Merge branch 'maint' into yacc-work

* maint:
  docs: avoid a footnote, some related rewordings and improvements
  Revert "docs: parallel-tests is not experimental anymore"
  docs: minor cosmetic fixes
  help: improve text about automatically-distributed files
  refactor: split 'usage' subroutine in automake
  tests: fix bug in 'autodist.test'
  maintcheck: extend 'sc_tests_plain_*' checks
  maintcheck: avoid few spurious failures
  check: don't use multi-line coloring for the report
  ansi2knr: deprecate, it will go away in the next major release
  docs: primary/prefix combination "pkglib_PROGRAMS" is now invalid
  docs: replace obsolete @vindex entry with a useful one
  docs: AM_DISTCHECK_CONFIGURE_FLAGS is for corner cases
  parallel-tests: stricter checks on DISABLE_HARD_ERRORS support
  docs: parallel-tests is not experimental anymore
  check: document and test $(TEST_SUITE_LOG) overriding

1 files changed, 82 insertions, 47 deletions

diff --git a/doc/automake.texi b/doc/automake.texi
index e5f977b65..a02cea51c 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -84,7 +84,8 @@ section entitled ``GNU Free Documentation License.''
 @c Put the macros in the function index.
 @syncodeindex ac fn
 
-@c Put everything else into one index (arbitrarily chosen to be the concept index).
+@c Put everything else into one index (arbitrarily chosen to be the
+@c concept index).
 @syncodeindex op cp
 @syncodeindex tr cp
 @syncodeindex cm cp
@@ -232,7 +233,7 @@ Building Programs and Libraries
 * Java Support::                Compiling Java sources
 * Vala Support::                Compiling Vala sources
 * Support for Other Languages::  Compiling other languages
-* ANSI::                        Automatic de-ANSI-fication (obsolete)
+* ANSI::                        Automatic de-ANSI-fication (deprecated, soon to be removed)
 * Dependencies::                Automatic dependency tracking
 * EXEEXT::                      Support for executable extensions
 
@@ -2226,8 +2227,9 @@ source in case you need more recent versions.
 @table @code
 @item ansi2knr.c
 @itemx ansi2knr.1
-These two files are used for de-ANSI-fication support (obsolete
-@pxref{ANSI}).
+These two files are used for de-ANSI-fication support (they are
+deprecated now, and @emph{will be removed} in the next major Automake
+release; @pxref{ANSI}).
 
 @item compile
 This is a wrapper for compilers that do not accept options @option{-c}
@@ -2447,20 +2449,8 @@ false.o: true.c
         $(COMPILE) -DEXIT_CODE=1 -c true.c && mv true.o false.o
 @end example
 
-Also, these explicit rules do not work if the obsolete de-ANSI-fication feature
-is used (@pxref{ANSI}).  Supporting de-ANSI-fication requires a little
-more work:
-
-@example
-true_.o: true_.c false_.o
-        $(COMPILE) -DEXIT_CODE=0 -c true_.c
-
-false_.o: true_.c
-        $(COMPILE) -DEXIT_CODE=1 -c true_.c && mv true_.o false_.o
-@end example
-
 As it turns out, there is also a much easier way to do this same task.
-Some of the above techniques are useful enough that we've kept the
+Some of the above technique is useful enough that we've kept the
 example in the manual.  However if you were to build @code{true} and
 @code{false} in real life, you would probably use per-program
 compilation flags, like so:
@@ -2476,10 +2466,9 @@ true_CPPFLAGS = -DEXIT_CODE=0
 @end example
 
 In this case Automake will cause @file{true.c} to be compiled twice,
-with different flags.  De-ANSI-fication will work automatically.  In
-this instance, the names of the object files would be chosen by
-automake; they would be @file{false-true.o} and @file{true-true.o}.
-(The name of the object files rarely matters.)
+with different flags.  In this instance, the names of the object files
+would be chosen by automake; they would be @file{false-true.o} and
+@file{true-true.o}. (The name of the object files rarely matters.)
 
 
 @node Invoking Automake
@@ -3033,8 +3022,9 @@ this way, e.g., @code{AC_PATH_XTRA} defines @code{X_CFLAGS} and
 if @code{AC_PATH_XTRA} is called.
 
 @item AM_C_PROTOTYPES
-This is required when using the obsolete de-ANSI-fication feature; see
-@ref{ANSI}.
+This is required when using the deprecated de-ANSI-fication feature;
+@pxref{ANSI}.  @emph{It will be removed} in the next major Automake
+release.
 
 @item AM_CONDITIONAL
 This introduces an Automake conditional (@pxref{Conditionals}).
@@ -4010,8 +4000,10 @@ Autoconf Manual}).
 Check to see if function prototypes are understood by the compiler.  If
 so, define @samp{PROTOTYPES} and set the output variables @code{U} and
 @code{ANSI2KNR} to the empty string.  Otherwise, set @code{U} to
-@samp{_} and @code{ANSI2KNR} to @samp{./ansi2knr}.  Automake uses these
-values to implement the obsolete de-ANSI-fication feature.
+@samp{_} and @code{ANSI2KNR} to @samp{./ansi2knr}.  Automake used these
+values to implement the deprecated de-ANSI-fication feature; however,
+support for @emph{that feature will be removed} in the next major Automake
+release, and then @emph{these macros and variables will go away as well}.
 
 @item AM_CONFIG_HEADER
 @acindex AM_CONFIG_HEADER
@@ -4611,7 +4603,7 @@ to build programs and libraries.
 * Java Support::                Compiling Java sources
 * Vala Support::                Compiling Vala sources
 * Support for Other Languages::  Compiling other languages
-* ANSI::                        Automatic de-ANSI-fication (obsolete)
+* ANSI::                        Automatic de-ANSI-fication (deprecated, soon to be removed)
 * Dependencies::                Automatic dependency tracking
 * EXEEXT::                      Support for executable extensions
 @end menu
@@ -4642,14 +4634,14 @@ programs.  Most of the comments about these also apply to libraries
 @vindex bin_PROGRAMS
 @vindex sbin_PROGRAMS
 @vindex libexec_PROGRAMS
-@vindex pkglib_PROGRAMS
+@vindex pkglibexec_PROGRAMS
 @vindex noinst_PROGRAMS
 @vindex check_PROGRAMS
 
 In a directory containing source that gets built into a program (as
 opposed to a library or a script), the @code{PROGRAMS} primary is used.
 Programs can be installed in @code{bindir}, @code{sbindir},
-@code{libexecdir}, @code{pkglibdir}, @code{pkglibexecdir}, or not at all
+@code{libexecdir}, @code{pkglibexecdir}, or not at all
 (@code{noinst_}).  They can also be built only for @samp{make check}, in
 which case the prefix is @samp{check_}.
 
@@ -5838,8 +5830,8 @@ needs to be avoided: when a target should not be built from sources.
 We already saw such an example in @ref{true}; this happens when all
 the constituents of a target have already been compiled and just need
 to be combined using a @code{_LDADD} variable.  Then it is necessary
-to define an empty @code{_SOURCES} variable, so that @command{automake} does not
-compute a default.
+to define an empty @code{_SOURCES} variable, so that @command{automake}
+does not compute a default.
 
 @example
 bin_PROGRAMS = target
@@ -6764,13 +6756,14 @@ suffix rule handling (@pxref{Suffixes}).
 
 
 @node ANSI
-@section Automatic de-ANSI-fication
+@section Automatic de-ANSI-fication (deprecated, soon to be removed)
 
 @cindex de-ANSI-fication, defined
 
-The features described in this section are obsolete; you should not
-used any of them in new code, and they may be withdrawn in future
-Automake releases.
+@emph{The features described in this section are deprecated; you must
+not use any of them in new code, and remove their use from older but
+still maintained code: they will be withdrawn in the next major
+Automake release.}
 
 When the C language was standardized in 1989, there was a long
 transition period where package developers needed to worry about
@@ -6824,8 +6817,9 @@ If no directory prefix is given, the files are assumed to be in the
 current directory.
 
 Note that automatic de-ANSI-fication will not work when the package is
-being built for a different host architecture.  That is because @command{automake}
-currently has no way to build @command{ansi2knr} for the build machine.
+being built for a different host architecture.  That is because
+@command{automake} currently has no way to build @command{ansi2knr}
+for the build machine.
 
 @c FIXME: this paragraph might be better moved to an `upgrading' section.
 @cindex @code{LTLIBOBJS} and @code{ansi2knr}
@@ -6919,10 +6913,10 @@ bin_PROGRAMS = liver$(EXEEXT)
 The targets Automake generates are likewise given the @samp{$(EXEEXT)}
 extension.
 
-The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests}) are also
-rewritten if they contain filenames that have been declared as programs
-in the same @file{Makefile}.  (This is mostly useful when some programs
-from @code{check_PROGRAMS} are listed in @code{TESTS}.)
+The variables @code{TESTS} and @code{XFAIL_TESTS} (@pxref{Simple Tests})
+are also rewritten if they contain filenames that have been declared as
+programs in the same @file{Makefile}.  (This is mostly useful when some
+programs from @code{check_PROGRAMS} are listed in @code{TESTS}.)
 
 However, Automake cannot apply this rewriting to @command{configure}
 substitutions.  This means that if you are conditionally building a
@@ -8302,14 +8296,19 @@ is run.  The default setting is @option{--best}.
 @cmindex include
 For the most part, the files to distribute are automatically found by
 Automake: all source files are automatically included in a distribution,
-as are all @file{Makefile.am}s and @file{Makefile.in}s.  Automake also
+as are all @file{Makefile.am} and @file{Makefile.in} files.  Automake also
 has a built-in list of commonly used files that are automatically
 included if they are found in the current directory (either physically,
-or as the target of a @file{Makefile.am} rule).  This list is printed by
-@samp{automake --help}.  Also, files that are read by @command{configure}
+or as the target of a @file{Makefile.am} rule); this list is printed by
+@samp{automake --help}.  Note that some files in this list are actually
+distributed only if other certain conditions hold (for example,
+@c The following example is covered by autodist-config-headers.test.
+the @file{config.h.top} and @file{config.h.bot} files are automatically
+distributed only if, e.g., @samp{AC_CONFIG_HEADERS([config.h])} is used
+in @file{configure.ac}).  Also, files that are read by @command{configure}
 (i.e.@: the source files corresponding to the files specified in various
 Autoconf macros such as @code{AC_CONFIG_FILES} and siblings) are
-automatically distributed.  Files included in @file{Makefile.am}s (using
+automatically distributed.  Files included in a @file{Makefile.am} (using
 @code{include}) or in @file{configure.ac} (using @code{m4_include}), and
 helper scripts installed with @samp{automake --add-missing} are also
 distributed.
@@ -8437,6 +8436,21 @@ to supply additional flags to @command{configure}, define them in the
 provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable,
 on the command line when invoking @command{make}.
 
+Still, developers are encouraged to strive to make their code buildable
+without requiring any special configure option; thus, in general, you
+shouldn't define @code{AM_DISTCHECK_CONFIGURE_FLAGS}. However, there
+might be few scenarios in which the use of this variable is justified.
+GNU @command{m4} offers an example.  GNU @command{m4} configures by
+default with its experimental and seldom used "changeword" feature
+disabled; so in its case it is useful to have @command{make distcheck}
+run configure with the @option{--with-changeword} option, to ensure that
+the code for changeword support still compiles correctly.
+GNU @command{m4} also employs the @code{AM_DISTCHECK_CONFIGURE_FLAGS}
+variable to stress-test the use of @option{--program-prefix=g}, since at
+one point the @command{m4} build system had a bug where @command{make
+installcheck} was wrongly assuming it could blindly test "@command{m4}",
+rather than the just-installed "@command{gm4}".
+
 @trindex distcheck-hook
 If the @code{distcheck-hook} rule is defined in your top-level
 @file{Makefile.am}, then it will be invoked by @code{distcheck} after
@@ -8640,10 +8654,10 @@ parallel-tests}).
 @cindex Tests, expected failure
 @cindex Expected test failure
 
+@vindex XFAIL_TESTS
 You may define the variable @code{XFAIL_TESTS} to a list of tests
 (usually a subset of @code{TESTS}) that are expected to fail.  This will
 reverse the result of those tests.
-@vindex XFAIL_TESTS
 
 Automake ensures that each file listed in @code{TESTS} is built before
 any tests are run; you can list both source and derived programs (or
@@ -8787,6 +8801,20 @@ use a command like this to run only a subset of the tests:
 env TESTS="foo.test bar.test" make -e check
 @end example
 
+Note however that the command above will unconditionally overwrite the
+@file{test-suite.log} file, thus clobbering the recorded results
+of any previous testsuite run.  This might be undesirable for packages
+whose testsuite takes long time to execute.  Luckily, this problem can
+easily be avoided by overriding also @code{TEST_SUITE_LOG} at runtime;
+for example,
+
+@example
+env TEST_SUITE_LOG=partial.log TESTS="..." make -e check
+@end example
+
+will write the result of the partial testsuite runs to the
+@file{partial.log}, without touching @file{test-suite.log}.
+
 @item
 You can set the @code{TEST_LOGS} variable.  By default, this variable is
 computed at @command{make} run time from the value of @code{TESTS} as
@@ -8797,6 +8825,9 @@ set x subset*.log; shift
 env TEST_LOGS="foo.log $*" make -e check
 @end example
 
+The comments made above about @code{TEST_SUITE_LOG} overriding applies
+here too.
+
 @item
 @vindex RECHECK_LOGS
 @cindex lazy test execution
@@ -9067,11 +9098,15 @@ implies options @option{readme-alpha} and @option{check-news}.
 @itemx @option{@var{path}/ansi2knr}
 @cindex Option, @option{ansi2knr}
 @opindex ansi2knr
-Turn on the obsolete de-ANSI-fication feature.  @xref{ANSI}.  If preceded by a
+Turn on the deprecated de-ANSI-fication feature (@pxref{ANSI}).  Note
+that that feature and this option @emph{will be removed} in the next
+major Automake release.
+
+If preceded by a
 path, the generated @file{Makefile.in} will look in the specified
 directory to find the @file{ansi2knr} program.  The path should be a
 relative path to another directory in the same distribution (Automake
-currently does not check this).
+does not check this).
 
 @item @option{check-news}
 @cindex Option, @option{check-news}