Doc: AC_CHECK_HEADER

[Akim Demaille]

Index: ChangeLog
from  Akim Demaille  <address@hidden>

        * doc/autoconf.texi (Generic Headers): More information on how to
        use AC_CHECK_HEADERS.

Index: NEWS
===================================================================
RCS file: /cvsroot/autoconf/autoconf/NEWS,v
retrieving revision 1.270
diff -u -u -r1.270 NEWS
--- NEWS 22 Oct 2002 12:34:21 -0000 1.270
+++ NEWS 25 Oct 2002 08:42:20 -0000
@@ -1,6 +1,11 @@
 * Major changes in Autoconf 2.54a                       -*- outline -*-
 
 
+** Documentation
+
+- AC_CHECK_HEADER, AC_CHECK_HEADERS
+  More information on proper use.
+
 ** autoreconf
 
 - Is more robust to different Gettext installations.
Index: doc/autoconf.texi
===================================================================
RCS file: /cvsroot/autoconf/autoconf/doc/autoconf.texi,v
retrieving revision 1.695
diff -u -u -r1.695 autoconf.texi
--- doc/autoconf.texi 23 Oct 2002 07:42:13 -0000 1.695
+++ doc/autoconf.texi 25 Oct 2002 08:42:25 -0000
@@ -4493,13 +4493,8 @@
 header file is available, consider using @code{AC_CHECK_HEADERS}
 instead.
 
-Previous versions of Autoconf merely checked whether the header was
-accepted by the preprocessor.  This was changed because the old test
-was inappropriate for typical uses.  Headers are typically used to
-compile, not merely to preprocess, and the old behavior sometimes
-accepted headers that clashed at compile-time.  If you need to check
-whether a header is preprocessable, you can use @code{AC_TRY_CPP} or
-one of its variants (@pxref{Examining Declarations}).
+For compatibility issues with older versions of Autoconf, please read
+below.
 @end defmac
 
 @defmac AC_CHECK_HEADERS (@address@hidden, @ovar{action-if-found}, 
@ovar{action-if-not-found}, @dvar{includes, default-includes})
@@ -4512,7 +4507,34 @@
 files is found.  You can give it a value of @samp{break} to break out of
 the loop on the first match.  If @var{action-if-not-found} is given, it
 is executed when one of the header files is not found.
+
+For compatibility issues with older versions of Autoconf, please read
+below.
 @end defmac
+
+Previous versions of Autoconf merely checked whether the header was
+accepted by the preprocessor.  This was changed because the old test was
+inappropriate for typical uses.  Headers are typically used to compile,
+not merely to preprocess, and the old behavior sometimes accepted
+headers that clashed at compile-time.  If you need to check whether a
+header is preprocessable, you can use @code{AC_TRY_CPP} or one of its
+variants (@pxref{Examining Declarations}).
+
+This scheme, which improves the robustness of the test, also requires
+that you make sure that headers that must be included before the
address@hidden be part of the @var{includes}, (@pxref{Default
+Includes}).  If looking for @file{bar.h}, which requires that
address@hidden be included before if it exists, we suggest the following
+scheme:
+
address@hidden
+AC_CHECK_HEADERS([foo.h])
+AC_CHECK_HEADERS([bar.h], [], [],
+[#if HAVE_FOO_H
+# include <foo.h>
+# endif
+])
address@hidden verbatim
 
 @node Declarations
 @section Declarations