Re: regression in autoconf-2.62 vs. 2.61

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to Stepan Kasal on 6/18/2008 10:17 AM:

[wow - a month in my inbox]

|
| I tried to write something, and I ended up with a different version.
| I have also removed a trivial example; IMHO, it does not belong to
| this node and I guess the information is available elsewhere in the
| manual.
|
| Please find the proposal attached to this mail.  Eric, could you
| please merge the two and check for errors?  (Then toss it back to me
| or commit.)
|
| Comments from others are very welcome, too, of course.

Here's what I committed.  Thanks again, Stepan, for tackling the initial
effort; and feel free to review or propose yet more changes to make this
section crystal clear.

- --
Don't work too hard, make some time for fun as well!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkh/6nAACgkQ84KuGfSFAYDJ1gCg1Wp8sRWKoyGgvuNsLZP/3XzO
XzgAoMpKARBDAExNXl9sZzx49SpB/xKN
=WzL6
-----END PGP SIGNATURE-----

>From 6d04538831ab9e02826bbb951de43ff62ccd72e6 Mon Sep 17 00:00:00 2001
From: Stepan Kasal <address@hidden>
Date: Thu, 17 Jul 2008 18:55:51 -0600
Subject: [PATCH] Improve documentation of config.h.in template rules.

* doc/autoconf.texi (Header Templates): Mention rules on comments
and whitespace, and that the user cannot rely on #undef to survive
through config.status.

Signed-off-by: Eric Blake <address@hidden>
---
 ChangeLog         |    8 ++++++
 doc/autoconf.texi |   62 +++++++++++++++++++++++++++++++++++-----------------
 2 files changed, 50 insertions(+), 20 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index ecf547b..da65cc7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2008-07-17  Stepan Kasal  <address@hidden>
+       and Eric Blake  <address@hidden>
+
+       Improve documentation of config.h.in template rules.
+       * doc/autoconf.texi (Header Templates): Mention rules on comments
+       and whitespace, and that the user cannot rely on #undef to survive
+       through config.status.
+
 2008-07-16  Eric Blake  <address@hidden>
 
        Revert m4_prepend; it is less efficient, and unused by bison.
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index a785471..bfe5c1b 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -3082,10 +3082,9 @@ AC_CHECK_HEADERS([unistd.h])
 @end example
 
 @noindent
-Then you could have code like the following in @file{conf.h.in}.  On
-systems that have @file{unistd.h}, @command{configure} defines
address@hidden to 1.  On other systems, the whole line is
-commented out (in case the system predefines that symbol).
+Then you could have code like the following in @file{conf.h.in}.
+The @file{conf.h} created by @command{configure} defines @samp{HAVE_UNISTD_H}
+to 1, if and only if the system has @file{unistd.h}.
 
 @example
 @group
@@ -3094,29 +3093,52 @@ commented out (in case the system predefines that 
symbol).
 @end group
 @end example
 
-Pay attention that @samp{#undef} is in the first column, and there is
-nothing after @samp{HAVE_UNISTD_H}, not even white space.  You can
-then decode the configuration header using the preprocessor directives:
+The format of the template file is stricter than what the C preprocessor
+is required to accept.  A directive line should contain only whitespace,
address@hidden, and @samp{HAVE_UNISTD_H}.  The use of @samp{#define}
+instead of @samp{#undef}, or of comments on the same line as
address@hidden, is strongly discouraged.  Each hook should only be listed
+once.  Other preprocessor lines, such as @samp{#ifdef} or
address@hidden, are copied verbatim from the template into the
+generated header.
+
+Since it is a tedious task to keep a template header up to date, you may
+use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
+
+During the instantiation of the header, each @samp{#undef} line in the
+template file for each symbol defined by @samp{AC_DEFINE} is changed to an
+appropriate @samp{#define}. If the corresponding @samp{AC_DEFINE} has not
+been executed during the @command{configure} run, the @samp{#undef} line is
+commented out.  (This is important, e.g., for @samp{_POSIX_SOURCE}:
+on many systems, it can be implicitly defined by the compiler, and
+undefining it in the header would then break compilation of subsequent
+headers.)
+
+Currently, @emph{all} remaining @samp{#undef} lines in the header
+template are commented out, whether or not there was a corresponding
address@hidden for the macro name; but this behavior is not guaranteed
+for future releases of Autoconf.
+
+Generally speaking, since you should not use @samp{#define}, and you
+cannot guarantee whether a @samp{#undef} directive in the header
+template will be converted to a @samp{#define} or commented out in the
+generated header file, the template file cannot be used for conditional
+definition effects.  Consequently, if you need to use the construct
 
 @example
 @group
-#include <conf.h>
-
-#ifdef HAVE_UNISTD_H
-# include <unistd.h>
-#else
-/* We are in trouble.  */
+#ifdef THIS
+# define THAT
 #endif
 @end group
 @end example
 
-The use of old form templates, with @samp{#define} instead of
address@hidden is strongly discouraged.  Similarly with old templates
-with comments on the same line as the @samp{#undef}.  Anyway, putting
-comments in preprocessor macros has never been a good idea.
-
-Since it is a tedious task to keep a template header up to date, you may
-use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
address@hidden
+you must place it outside of the template.
+If you absolutely need to hook it to the config header itself, please put
+the directives to a separate file, and @samp{#include} that file from the
+config header template.  If you are using @command{autoheader}, you would
+probably use @samp{AH_BOTTOM} to append the @samp{#include} directive.
 
 
 @node autoheader Invocation
-- 
1.5.6