23-doc-acconfig-h.patch

[Akim Demaille]

Index: 0.493/ChangeLog
from  Akim Demaille  <address@hidden>
        The documentation is not clear about the obsoleteness of
        `acconfig.h', `config.h.top', and `config.h.bot'.
        Reported by Aharon Robbins.
        
        * doc/autoconf.texi (Making configure Scripts)
        (Automatic Remaking, Defining Symbols, Distributing): Forget about
        these files.
        (acconfig.h): Reword.
        Display the old scheme presenting the dependencies between input
        and output files.
        (Changed File Names): Clarify.
        
        
Index: 0.493/doc/autoconf.texi
--- 0.493/doc/autoconf.texi Wed, 01 Nov 2000 14:25:34 +0100 akim 
(ace/16_autoconf.t 1.61.2.84 666)
+++ 0.494(w)/doc/autoconf.texi Wed, 01 Nov 2000 15:26:50 +0100 akim 
(ace/16_autoconf.t 1.61.2.85 666)
@@ -556,21 +556,17 @@
 @noindent
 Files used in preparing a software package for distribution:
 @example
address@hidden
 your source files --> [autoscan*] --> [configure.scan] --> configure.in
 
-configure.in --.   .------> autoconf* -----> configure
-               +---+
-[aclocal.m4] --+   `---.
-[acsite.m4] ---'       |
-                       +--> [autoheader*] -> [config.h.in]
-[acconfig.h] ----.     |
-                 +-----'
-[config.h.top] --+
-[config.h.bot] --'
address@hidden
+configure.in --.
+               |   .------> autoconf* -----> configure
+[aclocal.m4] --+---+
+               |   `-----> [autoheader*] --> [config.h.in]
+[acsite.m4] ---'
address@hidden group
 
 Makefile.in -------------------------------> Makefile.in
address@hidden group
 @end example
 
 @noindent
@@ -1956,8 +1952,7 @@
 
 # autoheader might not change config.h.in, so touch a stamp file.
 $(srcdir)/config.h.in: stamp-h.in
-$(srcdir)/stamp-h.in: configure.in aclocal.m4 acconfig.h \
-    config.h.top config.h.bot
+$(srcdir)/stamp-h.in: configure.in aclocal.m4
         cd $(srcdir) && autoheader
         echo timestamp > $(srcdir)/stamp-h.in
 
@@ -5863,10 +5858,9 @@
 characters @samp{[} or @samp{]}), use @code{AC_DEFINE_UNQUOTED} instead.
 @var{description} is only useful if you are using
 @code{AC_CONFIG_HEADERS}.  In this case, @var{description} is put into
-the generated @file{config.h.in} as the comment before the macro define;
-the macro need not be mentioned in @file{acconfig.h}.  The following
-example defines the C preprocessor variable @code{EQUATION} to be the
-string constant @samp{"$a > $b"}:
+the generated @file{config.h.in} as the comment before the macro define.
+The following example defines the C preprocessor variable
address@hidden to be the string constant @samp{"$a > $b"}:
 
 @example
 AC_DEFINE(EQUATION, "$a > $b")
@@ -8077,33 +8071,48 @@
 @cindex @file{config.h.top}
 @cindex @file{config.h.bot}
 
address@hidden scans @file{configure.in} and figures out which C
-preprocessor symbols it might define.  It copies comments and
address@hidden and @code{#undef} statements from a file called
address@hidden in the current directory, if present.  This file used
-to be mandatory if you @code{AC_DEFINE} any additional symbols.  Now,
-you are encouraged to use the @code{AH} series of macros
-(@pxref{Autoheader Macros}).
-
-The file that @code{autoheader} creates contains mainly @code{#define}
-and @code{#undef} statements and their accompanying comments.  If
address@hidden/acconfig.h} contains the string @samp{@@TOP@@},
+In order to produce @file{config.h.in}, @command{autoheader} needs to
+build or to find templates for each symbol.  Modern releases of Autoconf
+use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader
+Macros}), but in older releases a file, @file{acconfig.h}, contained the
+list of needed templates.  @code{autoheader} copies comments and
address@hidden and @code{#undef} statements from @file{acconfig.h} in
+the current directory, if present.  This file used to be mandatory if
+you @code{AC_DEFINE} any additional symbols.
+
+Modern releases of Autoconf also provide @code{AH_TOP} and
address@hidden if you need to prepend/append some information to
address@hidden  Ancient versions of Autoconf had a similar feature:
+if @file{./acconfig.h} contains the string @samp{@@TOP@@},
 @code{autoheader} copies the lines before the line containing
 @samp{@@TOP@@} into the top of the file that it generates.  Similarly,
 if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@},
 @code{autoheader} copies the lines after that line to the end of the
-file it generates.  Either or both of those strings may be omitted.
+file it generates.  Either or both of those strings may be omitted.  An
+even older alternate way to produce the same effect in jurasik versions
+of Autoconf is to create the files @address@hidden (typically
address@hidden) and/or @address@hidden in the current
+directory.  If they exist, @code{autoheader} copies them to the
+beginning and end, respectively, of its output.
+
+In former versions of Autoconf, the files used in preparing a software
+package for distribution were:
address@hidden
address@hidden
+configure.in --.   .------> autoconf* -----> configure
+               +---+
+[aclocal.m4] --+   `---.
+[acsite.m4] ---'       |
+                       +--> [autoheader*] -> [config.h.in]
+[acconfig.h] ----.     |
+                 +-----'
+[config.h.top] --+
+[config.h.bot] --'
address@hidden group
address@hidden example
 
-An alternate way to produce the same effect is to create the files
address@hidden@var{file}.top} (typically @file{config.h.top}) and/or
address@hidden@var{file}.bot} in the current directory.  If they exist,
address@hidden copies them to the beginning and end, respectively, of
-its output.  Their use is discouraged because they have file names that
-contain two periods, and so cannot be stored on MS-DOS; also, they are
-two more files to clutter up the directory.  But if you use the
address@hidden@var{dir}} option to use an @file{acconfig.h} in
-another directory, they give you a way to put custom boilerplate in each
-individual @file{config.h.in}.
+Use only the @code{AH_} macros, @file{configure.in} should be
+self-contained, and should not depend upon @file{acconfig.h} etc.
 
 
 @node autoupdate Invocation, Obsolete Macros, acconfig.h, Obsolete Constructs
@@ -8935,9 +8944,9 @@
 create a file called @file{install} from it.  @code{AC_PROG_INSTALL}
 looks for the script under both names, but it is best to use the new name.
 
-If you were using @file{config.h.top} or @file{config.h.bot}, you still
-can, but you will have less clutter if you merge them into
address@hidden  @xref{autoheader Invocation}.
+If you were using @file{config.h.top}, @file{config.h.bot}, or
address@hidden, you still can, but you will have less clutter if you
+use the @code{AH_} macros.  @xref{Autoheader Macros}.
 
 @node Changed Makefiles, Changed Macros, Changed File Names, Autoconf 1
 @subsection Changed Makefiles
@@ -9116,12 +9125,11 @@
 
 Of the other files that might be used with @code{configure},
 @file{config.h.in} is under whatever copyright you use for your
address@hidden, since it is derived from that file and from the
-public domain file @file{acconfig.h}.  @file{config.sub} and
address@hidden have an exception to the GPL when they are used with
-an Autoconf-generated @code{configure} script, which permits you to
-distribute them under the same terms as the rest of your package.
address@hidden is from the X Consortium and is not copyrighted.
address@hidden  @file{config.sub} and @file{config.guess} have an
+exception to the GPL when they are used with an Autoconf-generated
address@hidden script, which permits you to distribute them under the
+same terms as the rest of your package.  @file{install-sh} is from the X
+Consortium and is not copyrighted.
 
 @node Why GNU m4, Bootstrapping, Distributing, Questions
 @section Why Require GNU M4?