docs: deprecate .log -> .html conversion by parallel-tests

That feature is to be deprecated in the 1.11.x series, and
removed in the 1.12 release.

Reference:
  <http://lists.gnu.org/archive/html/automake/2012-01/msg00005.html>

* doc/automake.texi (Simple Tests using parallel-tests): Deprecate
the '.log' -> '.html' conversion and the targets 'check-html' and
'recheck-html'.  Related rewording and reformatting.
* NEWS (Future backward-incompatibilities): Update.

2 files changed, 20 insertions, 22 deletions

diff --git a/NEWS b/NEWS
index bd334fd6d..172889cad 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,10 @@ New in 1.11.0a:
 
 * WARNING: Future backward-incompatibilities!
 
+  - The support for ".log -> .html" conversion and the check-html and
+    recheck-html targets will be removed in the next major Automake
+    release (1.12).
+
   - The `lzma' compression format for distribution archives has been
     deprecated in favor of `xz' and `lzip', and will be removed in the
     next major Automake release (1.12).
diff --git a/doc/automake.texi b/doc/automake.texi
index 0c4dc0166..cb31053cd 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -8829,17 +8829,17 @@ by the tests, not the tests themselves.  Of course you can set
 @section Simple Tests using @samp{parallel-tests}
 @cindex @option{parallel-tests}, Using
 
-The option @option{parallel-tests} (@pxref{Options}) enables a test
-suite driver that is mostly compatible to the simple test driver described
-in the previous section, but provides a few more features and slightly different
-semantics.  It features concurrent execution of tests with @code{make -j},
-allows to specify inter-test dependencies, lazy reruns of tests that
-have not completed in a prior run, summary and verbose output in
-@samp{RST} (reStructuredText) and @samp{HTML} format, and hard errors
-for exceptional failures.  Similar to the simple test driver,
-@code{TESTS_ENVIRONMENT}, @code{AM_COLOR_TESTS}, @code{XFAIL_TESTS}, and
-the @code{check_*} variables are honored, and the environment variable
-@env{srcdir} is set during test execution.
+The option @option{parallel-tests} (@pxref{Options}) enables a test suite
+driver that is mostly compatible to the simple test driver described in
+the previous section, but provides a few more features and slightly
+different semantics.  It features concurrent execution of tests with
+@code{make -j} and automatic collection of the test scripts output and
+summary thereof in @file{.log} files, and allows to specify inter-test
+dependencies, lazy reruns of tests that have not completed in a prior
+run, and hard errors for exceptional failures.  Similar to the simple
+test driver, @code{TESTS_ENVIRONMENT}, @code{AM_COLOR_TESTS},
+@code{XFAIL_TESTS}, and the @code{check_*} variables are honored,
+and the environment variable @env{srcdir} is set during test execution.
 
 This test driver is still experimental and may undergo changes in order
 to satisfy additional portability requirements.
@@ -8918,16 +8918,13 @@ intermingled output.  The output from failed tests is collected in the
 file is output after the summary.  For best results, the tests should be
 verbose by default now.
 
-@trindex mostlyclean
 @trindex check-html
 @vindex RST2HTML
 @vindex TEST_SUITE_HTML
-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
-@command{rst2html.py}.  The variable @samp{TEST_SUITE_HTML} contains the
-set of converted log files.  The log and HTML files are removed upon
-@code{make mostlyclean}.
+Previous versions of automake used to provide a @code{check-html} target
+to convert the log files to HTML.  This feature is now deprecated, and
+@emph{will be removed} in the next major Automake release, so don't rely
+on it anymore.
 
 @vindex DISABLE_HARD_ERRORS
 @cindex Exit status 99, special interpretation
@@ -9002,13 +8999,10 @@ env RECHECK_LOGS= make -e check
 
 @item
 @trindex recheck
-@trindex recheck-html
 You can ensure that all tests are rerun which have failed or passed
 unexpectedly, by running @code{make recheck} in the test directory.
 This convenience target will set @code{RECHECK_LOGS} appropriately
-before invoking the main test driver.  The @code{recheck-html} target
-does the same as @code{recheck} but again converts the resulting log
-file in HTML format, like the @code{check-html} target.
+before invoking the main test driver.
 @end itemize
 
 In order to guarantee an ordering between tests even with @code{make