doc: discuss AC_* ordering a little.

* doc/automake.texi (Optional): mention that AC_CONFIG_AUX_DIR
must be called before AM_INIT_AUTOMAKE, and recommend that other
AC_CONFIG_* macros be called after.  This seems to be the most
common practice.  Autoconf does not currently impose ordering:
https://savannah.gnu.org/support/?110416

diff --git a/doc/automake.texi b/doc/automake.texi
index 040172e667d76492ab1f985d0c61ae752d19a2bd..68b015151c4c0a7481c7d1facf9cdac99baeb673 100644 (file)
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -3045,6 +3045,12 @@ Automake will look for various helper scripts, such as
 Not all scripts are always searched for; some scripts
 will only be sought if the generated @file{Makefile.in} requires them.
 
+If @code{AC_CONFIG_AUX_DIR} is used, it must be given before the call
+to @code{AM_INIT_AUTOMAKE}; Automake will warn about this if it is not
+so.  All other @code{AC_CONFIG_...} macros are conventionally called
+after @code{AM_INIT_AUTOMAKE}, though they may or may not work in
+other locations, with or without warnings.
+
 If @code{AC_CONFIG_AUX_DIR} is not given, the scripts are looked for in
 their standard locations.  For @file{mdate-sh},
 @file{texinfo.tex}, and @file{ylwrap}, the standard location is the
@@ -3065,20 +3071,22 @@ macro.
 @item AC_CONFIG_HEADERS
 Automake will generate rules to rebuild these headers from the
 corresponding templates (usually, the template for a @file{foo.h}
-header being @file{foo.h.in}).  Older versions of Automake
-required the use of @code{AM_CONFIG_HEADER}; this is no longer
-the case, and that macro has indeed been removed.
+header being @file{foo.h.in}). 
 
 As with @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
 specification using shell variables will be ignored as far as
 cleaning, distributing, and rebuilding is concerned.
 
+Older versions of Automake required the use of
+@code{AM_CONFIG_HEADER}; this is no longer the case, and that macro
+has indeed been removed.
+
 @item AC_CONFIG_LINKS
 Automake will generate rules to remove @file{configure} generated
 links on @samp{make distclean} and to distribute named source files as
 part of @samp{make dist}.
 
-As for @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
+As with @code{AC_CONFIG_FILES} (@pxref{Requirements}), parts of the
 specification using shell variables will be ignored as far as cleaning
 and distributing is concerned.  (There are no rebuild rules for links.)
 
@@ -4665,7 +4673,6 @@ an otherwise equivalent set of variables without @samp{nobase_} prefix.
 @acindex AC_CONFIG_SUBDIRS
 @acindex AC_CONFIG_AUX_DIR
 
-
 In the GNU Build System, packages can be nested to arbitrary depth.
 This means that a package can embed other packages with their own
 @file{configure}, @file{Makefile}s, etc.