2005-08-18  Ralf Wildenhues  <address@hidden>,
	    Stepan Kasal  <address@hidden>

        * lib/autoconf/status.m4 (_AC_CONFIG_REGISTER_DEST): When the
	first header appears, define AH_HEADER.
        * doc/autoconf.texi (Configuration Headers): Document AH_HEADER.
	Update limitations about when to call AC_CONFIG_HEADERS.
	(Configuration Commands): Document that AC_CONFIG_COMMANDS_PRE
	parameter can call AC_SUBST, AC_DEFINE, or AC_CONFIG_FOOS; explain
	that AC_CONFIG_COMMANDS_PRE and AC_CONFIG_COMMANDS_POST are not
	``Configuration Actions''; fix their index entries.

Index: doc/autoconf.texi
===================================================================
RCS file: /cvsroot/autoconf/autoconf/doc/autoconf.texi,v
retrieving revision 1.925
diff -u -r1.925 autoconf.texi
--- doc/autoconf.texi	6 Jul 2005 21:39:31 -0000	1.925
+++ doc/autoconf.texi	18 Aug 2005 13:02:00 -0000
@@ -2648,8 +2648,9 @@
 operating systems.  As an alternative to passing @option{-D} options to
 the compiler, @command{configure} scripts can create a C header file
 containing @samp{#define} directives.  The @code{AC_CONFIG_HEADERS}
-macro selects this kind of output.  It should be called right after
address@hidden
+macro selects this kind of output.  Though it can be called anywhere
+between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call
+it right after @code{AC_INIT}.
 
 The package should @samp{#include} the configuration header file before
 any other header files, to prevent inconsistencies in declarations (for
@@ -2697,6 +2698,19 @@
 to prepend and/or append boilerplate to the file.
 @end defmac
 
address@hidden AH_HEADER
+This macro is defined as the name of the first declared config header
+and undefined if no config headers have been declared up to this point.
+A third-party macro may, for example, require use of a config header
+without invoking AC_CONFIG_HEADERS twice, like this:
+
address@hidden
+AC_CONFIG_COMMANDS_PRE(
+	[m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])])
address@hidden example
+
address@hidden defmac
+
 @xref{Configuration Actions}, for more details on @var{header}.
 
 @menu
@@ -2970,13 +2984,23 @@
 @end example
 @end defmac
 
+The following two macros look similar, but in fact they are not of the same
+breed: they are executed directly by @file{configure}, so you cannot use
address@hidden to re-run them.
+
address@hidden Yet it is good to leave them here.  The user sees them together and
address@hidden decides which best fits their needs.
+
 @defmac AC_CONFIG_COMMANDS_PRE (@var{cmds})
address@hidden
address@hidden
 Execute the @var{cmds} right before creating @file{config.status}.
+
+This macro presents the last opportunity to call @code{AC_SUBST},
address@hidden, or @code{AC_CONFIG_FOOS} macros. 
 @end defmac
 
 @defmac AC_CONFIG_COMMANDS_POST (@var{cmds})
address@hidden
address@hidden
 Execute the @var{cmds} right after creating @file{config.status}.
 @end defmac
 
Index: lib/autoconf/status.m4
===================================================================
RCS file: /cvsroot/autoconf/autoconf/lib/autoconf/status.m4,v
retrieving revision 1.73
diff -u -r1.73 status.m4
--- lib/autoconf/status.m4	16 Aug 2005 09:11:06 -0000	1.73
+++ lib/autoconf/status.m4	18 Aug 2005 13:02:01 -0000
@@ -258,9 +258,14 @@
 # With CONFIG_LINKS, reject DEST=., because it is makes it hard for ./config.status
 # to guess the links to establish (`./config.status .').
 #
+# Save the name of the first config header to AH_HEADER.
+#
 m4_define([_AC_CONFIG_REGISTER_DEST],
 [_AC_CONFIG_UNIQUE([$1], [$3])dnl
-m4_if([$1 $3], [LINKS .], [AC_FATAL([invalid destination of a config link: `.'])])dnl
+m4_if([$1 $3], [LINKS .],
+      [AC_FATAL([invalid destination of a config link: `.'])])dnl
+m4_if([$1], [HEADERS],
+      [m4_define_default([AH_HEADER], [$3])])dnl
 dnl
 dnl Recognize TAG as an argument to config.status:
 dnl