[PATCH 8/6] Docs: document newer, more correct remake rules.

[Stefano Lattarini]

A small documentation patch which records the new, more correct 
behaviour of automake-generated remake rules, and gives an example
to show why they can be very useful in practice.

Regards,
   Stefano

From 665f9c2c8d77cc07799b836e4ec80d45fb3b66da Mon Sep 17 00:00:00 2001
From: Stefano Lattarini <address@hidden>
Date: Mon, 23 Aug 2010 13:52:41 +0200
Subject: [PATCH] Docs: document newer, more correct remake rules.

* doc/automake.texi (Rebuilding Makefiles): State explicitly that
automake-generated rebuild rules honor the values of AUTOCONF and
AUTOM4TE given at configure time.  Add an example showing why this
can be useful.
---
 ChangeLog         |    6 ++++++
 doc/automake.texi |   14 ++++++++++++++
 2 files changed, 20 insertions(+), 0 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 067ff84..e86c8c2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,11 @@
 2010-08-21  Stefano Lattarini  <address@hidden>
 
+       Docs: document newer, more correct remake rules.
+       * doc/automake.texi (Rebuilding Makefiles): State explicitly that
+       automake-generated rebuild rules honor the values of AUTOCONF and
+       AUTOM4TE given at configure time.  Add an example showing why this
+       can be useful.
+
        Update NEWS w.r.t. better remake rules.
        * NEWS: Updated.
 
diff --git a/doc/automake.texi b/doc/automake.texi
index 4d29513..f015525 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -8847,6 +8847,20 @@ Automake generates rules to automatically rebuild 
@file{Makefile}s,
 If you are using @code{AM_MAINTAINER_MODE} in @file{configure.ac}, then
 these automatic rebuilding rules are only enabled in maintainer mode.
 
+These rules strive to honor the values of @code{AUTOCONF} and
address@hidden given at @file{configure} time.  This allows a
+developer to work seamlessly with different projects each requiring
+a different autoconf version, by doing e.g.:
+
address@hidden
+$ cd ~/src/project1 # this requires autoconf 2.65
+$ AUTOCONF=autoconf2.65 AUTOM4TE=autom4te2.65 autoreconf -vi
+$ ./configure AUTOCONF=autoconf2.65 AUTOM4TE=autom4te2.65
+$ cd ~/src/project2 # this requires autoconf 2.67
+$ AUTOCONF=autoconf2.67 AUTOM4TE=autom4te2.67 autoreconf -vi
+$ ./configure AUTOCONF=autoconf2.67 AUTOM4TE=autom4te2.67
address@hidden example
+
 @vindex ACLOCAL_AMFLAGS
 Sometimes you need to run @command{aclocal} with an argument like
 @option{-I} to tell it where to find @file{.m4} files.  Since
-- 
1.7.1