automake: new variable AM_DISTCHECK_DVI_TARGET to override "dvi".

This change fixes https://bugs.gnu.org/8289.

* lib/am/distdir.am (AM_DISTCHECK_DVI_TARGET): define as dvi.
(distcheck): use it, isntead of hardcoding dvi.
* lib/Automake/Variable.pm (%_silent_variable_override): add
AM_DISTCHECK_DVI_TARGET.
* t/distcheck-override-dvi.sh: new test.
* t/list-of-tests.mk (handwritten_TESTS): add it.
* doc/automake.texi (Checking the Distribution): document this.
(Third-Party Makefiles): explicitly mention that
EMPTY_AUTOMAKE_TARGETS is not a built-in or special name.
Various other index entries and wording tweaks.
* NEWS (Distribution): mention this.

6 files changed, 118 insertions, 17 deletions

diff --git a/NEWS b/NEWS
index 172265a49..fc3f2dede 100644
--- a/NEWS
+++ b/NEWS
@@ -72,6 +72,11 @@ New in ?.?.?:
 
   - valac argument matching more precise, to avoid garbage in DIST_COMMON.
 
+* Distribution
+
+  - new variable AM_DISTCHECK_DVI_TARGET, to allow overriding the
+    "make dvi" that is done as part of distcheck.
+
 * Miscellaneous changes
 
   - Removed function up_to_date_p in lib/Automake/FileUtils.pm.
diff --git a/doc/automake.texi b/doc/automake.texi
index adc44f5b9..7cc7bcbca 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -1231,7 +1231,7 @@ work:
 @itemize @bullet
 @item
 It attempts a full compilation of the package (@pxref{Basic
-Installation}), unpacking the newly constructed tarball, running
+Installation}): unpacking the newly constructed tarball, running
 @code{make}, @code{make dvi}, @code{make check}, @code{make install},
 as well as @code{make installcheck}, and even @code{make dist},
 @item
@@ -1243,12 +1243,13 @@ uninstall} do not omit any file (@pxref{Standard Targets}),
 and it checks that @code{DESTDIR} installations work (@pxref{DESTDIR}).
 @end itemize
 
-All of these actions are performed in a temporary directory, so that no
-root privileges are required.  Please note that the exact location and the
-exact structure of such a subdirectory (where the extracted sources are
-placed, how the temporary build and install directories are named and how
-deeply they are nested, etc.) is to be considered an implementation detail,
-which can change at any time; so do not rely on it.
+All of these actions are performed in a temporary directory, so that
+no root privileges are required.  The exact location and the exact
+structure of such a subdirectory (where the extracted sources are
+placed, how the temporary build and install directories are named and
+how deeply they are nested, etc.) is to be considered an
+implementation detail, which can change at any time; so do not rely on
+it.
 
 Releasing a package that fails @code{make distcheck} means that one of
 the scenarios we presented will not work and some users will be
@@ -8045,7 +8046,6 @@ The name of the command that builds a @file{.ps} file out of a
 @file{.dvi} file.  This defaults to @samp{dvips}.
 
 @item TEXINFO_TEX
-
 If your package has Texinfo files in many directories, you can use the
 variable @code{TEXINFO_TEX} to tell Automake where to find the canonical
 @file{texinfo.tex} for your package.  The value of this variable should
@@ -8569,12 +8569,14 @@ dist} was run, not to any sub-packages involved.
 Automake also generates a @code{distcheck} rule that can be of help
 to ensure that a given distribution will actually work.  Simplifying
 a bit, we can say this rule first makes a distribution, and then,
-@emph{operating from it}, takes the following steps:
+@emph{operating from it}, takes the following steps (in this order):
 @itemize
 @item
 tries to do a @code{VPATH} build (@pxref{VPATH Builds}), with the
 @code{srcdir} and all its content made @emph{read-only};
 @item
+tries to make the printable documentation, if any (with @command{make dvi}),
+@item
 runs the test suite (with @command{make check}) on this fresh build;
 @item
 installs the package in a temporary directory (with @command{make
@@ -8588,12 +8590,12 @@ finally, makes another tarball to ensure the distribution is
 self-contained.
 @end itemize
 
-All of these actions are performed in a temporary directory.  Please
-note that the exact location and the exact structure of such a directory
-(where the read-only sources are placed, how the temporary build and
-install directories are named and how deeply they are nested, etc.) is
-to be considered an implementation detail, which can change at any time;
-so do not rely on it.
+All of these actions are performed in a temporary directory.  The
+exact location and the exact structure of such a directory (where the
+read-only sources are placed, how the temporary build and install
+directories are named and how deeply they are nested, etc.) is to be
+considered an implementation detail, which can change at any time; so
+do not rely on it.
 
 @vindex AM_DISTCHECK_CONFIGURE_FLAGS
 @vindex DISTCHECK_CONFIGURE_FLAGS
@@ -8627,6 +8629,30 @@ 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 dvi
+@subheading dvi and distcheck
+@cindex @code{eps} images
+Ordinarily, @command{make distcheck} runs @command{make dvi}.  It does
+nothing if the distribution contains no Texinfo sources.  If the
+distribution does contain a Texinfo manual, by default the @code{dvi}
+target will run @TeX{} to make sure it can be successfully processed
+(@pxref{Texinfo}).
+
+However, you may wish to test the manual by producing @code{pdf}
+(e.g., if your manual uses images in formats other than @code{eps}),
+@code{html} (if you don't have @TeX{} at all), some other format, or
+just skip the test entirely (not recommended).  You can change the
+target that is run by setting the variable
+@code{AM_DISTCHECK_DVI_TARGET} in your @code{Makefile.am}; for
+example,
+
+@example
+AM_DISTCHECK_DVI_TARGET = pdf
+@end example
+
+To make @code{dvi} into a do-nothing target, see the example for
+@code{EMPTY_AUTOMAKE_TARGETS} in @ref{Third-Party Makefiles}.
+
 @trindex distcheck-hook
 @subheading distcheck-hook
 If the @code{distcheck-hook} rule is defined in your top-level
@@ -11440,12 +11466,21 @@ OK to have a rule that does nothing, so if you are integrating a
 third-party project with no documentation or tag support, you could
 simply augment its @file{Makefile} as follows:
 
+@vindex EMPTY_AUTOMAKE_TARGETS
+@cindex Automake targets, no-op
+@cindex do-nothing Automake targets
+@cindex empty Automake targets
+@cindex no-op Automake targets
+@cindex targets, making into no-op
 @example
 EMPTY_AUTOMAKE_TARGETS = dvi pdf ps info html tags ctags
 .PHONY: $(EMPTY_AUTOMAKE_TARGETS)
 $(EMPTY_AUTOMAKE_TARGETS):
 @end example
 
+To be clear, there is nothing special about the variable name
+@code{EMPTY_AUTOMAKE_TARGETS}; the name could be anything.
+
 Another aspect of integrating third-party build systems is whether
 they support VPATH builds (@pxref{VPATH Builds}).  Obviously if the
 subpackage does not support VPATH builds the whole package will not
diff --git a/lib/Automake/Variable.pm b/lib/Automake/Variable.pm
index 72872a3a9..363a3e0ed 100644
--- a/lib/Automake/Variable.pm
+++ b/lib/Automake/Variable.pm
@@ -198,7 +198,8 @@ my $configure_ac;
 
 # Variables that can be overridden without complaint from -Woverride
 my %_silent_variable_override =
-  (AM_MAKEINFOHTMLFLAGS => 1,
+  (AM_DISTCHECK_DVI_TARGET => 1,
+   AM_MAKEINFOHTMLFLAGS => 1,
    AR => 1,
    ARFLAGS => 1,
    DEJATOOL => 1,
diff --git a/lib/am/distdir.am b/lib/am/distdir.am
index 26212413a..774d08b91 100644
--- a/lib/am/distdir.am
+++ b/lib/am/distdir.am
@@ -425,6 +425,9 @@ if %?SUBDIRS%
 AM_RECURSIVE_TARGETS += distcheck
 endif %?SUBDIRS%
 
+# Exists only to be overridden by the user if desired.
+AM_DISTCHECK_DVI_TARGET = dvi
+
 # This target untars the dist file and tries a VPATH configuration.  Then
 # it guarantees that the distribution is self-contained by making another
 # tarfile.
@@ -490,7 +493,7 @@ distcheck: dist
 ## (in corner-case usages); see automake bug#14991.
 	    --srcdir=../.. --prefix="$$dc_install_base" \
 	  && $(MAKE) $(AM_MAKEFLAGS) \
-	  && $(MAKE) $(AM_MAKEFLAGS) dvi \
+	  && $(MAKE) $(AM_MAKEFLAGS) $(AM_DISTCHECK_DVI_TARGET) \
 	  && $(MAKE) $(AM_MAKEFLAGS) check \
 	  && $(MAKE) $(AM_MAKEFLAGS) install \
 	  && $(MAKE) $(AM_MAKEFLAGS) installcheck \
diff --git a/t/distcheck-override-dvi.sh b/t/distcheck-override-dvi.sh
new file mode 100644
index 000000000..8d83d7e18
--- /dev/null
+++ b/t/distcheck-override-dvi.sh
@@ -0,0 +1,56 @@
+#! /bin/sh
+# Copyright (C) 2011-2020 Free Software Foundation, Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+# Check that we can override the 'dvi' target run as part of distcheck,
+# specifically to be 'html', so that TeX is not required.
+# Related to automake bug#8289.
+
+# TeX and texi2dvi should not be needed or invoked.
+TEX=false TEXI2DVI=false
+export TEX TEXI2DVI
+
+required='makeinfo'
+. test-init.sh
+
+cat >> configure.ac << 'END'
+AC_OUTPUT
+END
+
+cat > Makefile.am << 'END'
+AM_DISTCHECK_DVI_TARGET = html
+info_TEXINFOS = main.texi
+END
+
+# Protect with leading " # " to avoid spurious maintainer-check failures.
+sed 's/^ *# *//' > main.texi << 'END'
+ # \input texinfo
+ # @setfilename main.info
+ # @settitle main
+ #
+ # @node Top
+ # Hello.
+ # @bye
+END
+
+$ACLOCAL
+$AUTOMAKE -a
+$AUTOCONF
+
+./configure
+$MAKE
+$MAKE distcheck
+
+:
diff --git a/t/list-of-tests.mk b/t/list-of-tests.mk
index aab33dca7..43ea245a9 100644
--- a/t/list-of-tests.mk
+++ b/t/list-of-tests.mk
@@ -431,6 +431,7 @@ t/distcheck-writable-srcdir.sh \
 t/distcheck-missing-m4.sh \
 t/distcheck-outdated-m4.sh \
 t/distcheck-no-prefix-or-srcdir-override.sh \
+t/distcheck-override-dvi.sh \
 t/distcheck-override-infodir.sh \
 t/distcheck-pr9579.sh \
 t/distcheck-pr10470.sh \