Subject: bug#11146: texinfo: could automake start using the '--tidy' option in its dvi and pdf rules?

From: Stefano Lattarini <[email-masked]>
Date: Sun, 01 Apr 2012 22:49:43 +0200

References:
  <http://debbugs.gnu.org/cgi/bugreport.cgi?bug=11146>
  <http://lists.gnu.org/archive/html/bug-bison/2012-04/msg00002.html>

On 04/01/2012 03:11 PM, Stefano Lattarini wrote:
> On 04/01/2012 02:30 PM, Stefano Lattarini wrote:
>>
>> Most importantly, is the '--tidy' option supported by all recently-ish
>> Texinfo releases, or has it been introduced too recently to mandate its
>> use in Automake-generated recipes?
>>
> I'll answer myself on this, by quoting the Texinfo NEWS file:
> 
>   4.9 (29 June 2007)
>   * GPLv3.
>   * texi2dvi:
>     . new mode --build=tidy which supports compilation in a separate
>       directory, where intermediate files are preserved.
> 
> So the option is almost five years old, and thus old enough to be
> required in Automake 1.12.
>
On a second thought, bumping the requirement is something better done
for Automake 1.13, after having given proper warnings in the NEWS file.
For Automake 1.12, we might simply explicitly add the '--clean' option
to the texi2dvi invocation.

I'll thus apply to two attached patches to master in a couple of days
if there is no objection.

Regards,
  Stefano

>From 7e7cc3350f6ee543a8546a72cc8e16f4f323885b Mon Sep 17 00:00:00 2001
Message-Id: <7e7cc3350[email-masked]>
From: Stefano Lattarini <[email-masked]>
Date: Sun, 1 Apr 2012 21:55:09 +0200
Subject: [PATCH 1/2] texinfo: don't clutter the builddir when using modern
 texi2dvi

In modern versions of texi2dvi (at least since version 1.135, which
comes with Texinfo 4.13) the '-o' option does not imply anymore the
'--clean' option.  As a consequence, lots of TeX-generated auxiliary
files are now left in the build directory by the 'pdf', 'ps' and
'dvi' rules.

This is especially annoying with non-recursive setups having the
'.texi' files in a subdirectory, as in:

  info_TEXINFOS = doc/foo.texi

In this case, the stray auxiliary files are left in the top build
directory (since TeX is run from there).  See for example:

 <http://lists.gnu.org/archive/html/bug-bison/2012-04/msg00002.html>

See also automake bug#11146.

* lib/am/texibuild.am: Call 'texi2dvi' and 'texi2pdf' with the
'--clean' option.  Update comments accordingly.
* tests/txinfo-noclutter.test: New test.
* tests/list-of-tests.mk: Add it.
* NEWS: Update.

Signed-off-by: Stefano Lattarini <[email-masked]>
---
 NEWS                         |    5 +++
 lib/am/texibuild.am          |   14 ++++++--
 tests/list-of-tests.mk       |    1 +
 tests/txinfo-no-clutter.test |   68 ++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 84 insertions(+), 4 deletions(-)
 create mode 100755 tests/txinfo-no-clutter.test

diff --git a/NEWS b/NEWS
index 0a38d1d..3e54207 100644
--- a/NEWS
+++ b/NEWS
@@ -181,6 +181,11 @@ New in 1.11a:
 
   - The 'dist' and 'dist-all' targets now can run compressors in parallel.
 
+  - The rules to create pdf, dvi and ps output from Texinfo files now
+    works better with modern 'texi2dvi' script, by explicitly passing
+    it the '--clean' option to ensure stray auxiliary files are not
+    left to clutter the build directory.
+
   - Automake can now generate silenced rules for texinfo outputs.
 
   - Some auxiliary files that are automatically distributed by Automake
diff --git a/lib/am/texibuild.am b/lib/am/texibuild.am
index 40f01e4..f77748a 100644
--- a/lib/am/texibuild.am
+++ b/lib/am/texibuild.am
@@ -68,8 +68,11 @@ INFO_DEPS += %DEST_INFO_PREFIX%%DEST_SUFFIX%
 ## Do not use '-o' unless necessary: it is only supported since Texinfo 4.1.
 ## texi2dvi doesn't silence everything with -q, redirect to /dev/null instead.
 ## We still want -q (%TEXIQUIET%) because it turns on batch mode.
-?GENERIC?	$(TEXI2DVI) %TEXIQUIET% %SOURCE% %TEXIDEVNULL%
-?!GENERIC?	$(TEXI2DVI) %TEXIQUIET% -o $@ `test -f '%SOURCE%' || echo '$(srcdir)/'`%SOURCE% %TEXIDEVNULL%
+## Use '--clean' to avoid leaving auxiliary files behind cluttering the build
+## directory (see automake bug#11146).  We should start using '--tidy' when we
+## can assume Texinf 4.9 or later.
+?GENERIC?	$(TEXI2DVI) %TEXIQUIET% --clean %SOURCE% %TEXIDEVNULL%
+?!GENERIC?	$(TEXI2DVI) %TEXIQUIET% --clean -o $@ `test -f '%SOURCE%' || echo '$(srcdir)/'`%SOURCE% %TEXIDEVNULL%
 
 ?GENERIC?%SOURCE_SUFFIX%.pdf:
 ?!GENERIC?%DEST_PREFIX%.pdf: %SOURCE% %DEPS% %DIRSTAMP%
@@ -80,8 +83,11 @@ INFO_DEPS += %DEST_INFO_PREFIX%%DEST_SUFFIX%
 ## Do not use '-o' unless necessary: it is only supported since Texinfo 4.1.
 ## texi2pdf doesn't silence everything with -q, redirect to /dev/null instead.
 ## We still want -q (%TEXIQUIET%) because it turns on batch mode.
-?GENERIC?	$(TEXI2PDF) %TEXIQUIET% %SOURCE% %TEXIDEVNULL%
-?!GENERIC?	$(TEXI2PDF) %TEXIQUIET% -o $@ `test -f '%SOURCE%' || echo '$(srcdir)/'`%SOURCE% %TEXIDEVNULL%
+## Use '--clean' to avoid leaving auxiliary files behind cluttering the build
+## directory (see automake bug#11146).  We should start using '--tidy' when we
+## can assume Texinf 4.9 or later.
+?GENERIC?	$(TEXI2PDF) %TEXIQUIET% --clean %SOURCE% %TEXIDEVNULL%
+?!GENERIC?	$(TEXI2PDF) %TEXIQUIET% --clean -o $@ `test -f '%SOURCE%' || echo '$(srcdir)/'`%SOURCE% %TEXIDEVNULL%
 
 ?GENERIC?%SOURCE_SUFFIX%.html:
 ?!GENERIC?%DEST_PREFIX%.html: %SOURCE% %DEPS% %DIRSTAMP%
diff --git a/tests/list-of-tests.mk b/tests/list-of-tests.mk
index de022a2..f5d847f 100644
--- a/tests/list-of-tests.mk
+++ b/tests/list-of-tests.mk
@@ -1180,6 +1180,7 @@ txinfo30.test \
 txinfo31.test \
 txinfo32.test \
 txinfo33.test \
+txinfo-no-clutter.test \
 txinfo-unrecognized-extension.test \
 transform.test \
 transform2.test \
diff --git a/tests/txinfo-no-clutter.test b/tests/txinfo-no-clutter.test
new file mode 100755
index 0000000..672b261
--- /dev/null
+++ b/tests/txinfo-no-clutter.test
@@ -0,0 +1,68 @@
+#! /bin/sh
+# Copyright (C) 2012 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 <http://www.gnu.org/licenses/>.
+
+# The pdf, ps and dvi targets shouldn't let clutter in the build directory.
+# Related to automake bug#11146.
+
+required='makeinfo tex texi2dvi-o dvips'
+. ./defs || Exit 1
+
+mkdir sub
+
+echo AC_OUTPUT >> configure.ac
+
+cat > Makefile.am << 'END'
+all-local: ps pdf dvi html
+info_TEXINFOS = foo.texi sub/bar.texi
+END
+
+cat > foo.texi << 'END'
+\input texinfo
+@setfilename foo.info
+@settitle main
+@node Top
+Hello walls.
+@include version.texi
+@bye
+END
+
+cat > sub/bar.texi << 'END'
+\input texinfo
+@setfilename bar.info
+@settitle bar
+@node Top
+Hello walls.
+@include version2.texi
+@bye
+END
+
+$ACLOCAL
+$AUTOMAKE --add-missing
+$AUTOCONF
+
+./configure
+
+# Try one by one, to ensure later targets don't involuntarily
+# clean up potential cruft left by earlier ones.
+for fmt in pdf ps dvi html all; do
+  ls -d foo* sub/bar* > lst
+  $EGREP -v '^(foo|sub/bar)\.(texi|dvi|ps|pdf|html)$' lst && Exit 1
+  $MAKE clean
+done
+
+$MAKE distcheck
+
+:
-- 
1.7.9

>From 660dc87a1d4f874f975b0ba8141692851f3e037a Mon Sep 17 00:00:00 2001
Message-Id: <660dc87a1[email-masked]>
In-Reply-To: <7e7cc3350[email-masked]>
References: <7e7cc3350[email-masked]>
From: Stefano Lattarini <[email-masked]>
Date: Sun, 1 Apr 2012 22:48:46 +0200
Subject: [PATCH 2/2] texinfo: warn about future use of '--tidy'

Starting from the next major release of Automake (likely 1.13) we
want to start passing the '--tidy' option to texi2dvi and texi2pdf
invocations, so that auxiliary TeX-generated files can be kept
around (thus speeding up rebuilding of DVI and PDF output) without
cluttering the build directory too much.

Since the '--tidy' option has only been introduced in Texinfo
4.9 (as documented in the Texinfo distribution's NEWS file), this
also means that Makefiles generated by future Automake versions
will require at least that version of Texinfo (at the time of
writing four years and nine months old).

The users should be warned about the planned behavioural change
and the new version requirement it will entail.

See also automake bug#11146.

* NEWS (Planned Backward Incompatibilities): Add entry about use
of the '--tidy' option and requirement of Texinfo 4.9.

Signed-off-by: Stefano Lattarini <[email-masked]>
---
 NEWS |    6 ++++++
 1 files changed, 6 insertions(+), 0 deletions(-)

diff --git a/NEWS b/NEWS
index 3e54207..1ed40da 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,12 @@ New in 1.11a:
 
 * WARNING: Future backward-incompatibilities!
 
+  - Starting from the next major Automake version (1.13), the rules to
+    build pdf, ps and dvi output from Texinfo input will use the '--tidy'
+    option by default.  Since such an option has only been introduced in
+    Texinfo 4.9, this means that Makefiles generated by future Automake
+    versions will require at least that version of Texinfo.
+
   - Starting from the next major Automake version (1.13), the parallel
     testsuite harness (previously only enabled by the 'parallel-tests'
     option) will become the default one; the older serial testsuite
-- 
1.7.9