Document some more things the gnulib user must be aware of.

diff --git a/ChangeLog b/ChangeLog
index 88b3d03ad0f12bb5c7d2831862e659fa3ec6d074..a3dbe421024361a7576a5d3c3d9a9fe01c4434ea 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2007-10-27  Bruno Haible  <bruno@clisp.org>
+
+       * doc/gnulib.texi: Invoke @firstparagraphindent.
+       * doc/gnulib-tool.texi (Simple update): Mention possible incompatible
+       changes in gnulib.
+       (Source changes): New section.
+
 2007-10-26  Bruno Haible  <bruno@clisp.org>
 
        * m4/gnulib-common.m4 (AC_C_RESTRICT): New overriding definition,

diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
index 9021e62a8c3e592acfb0aba69ae286ceae3360b7..8af4a054821e6955d2e4c573b2fc2f559df38e51 100644 (file)
--- a/doc/gnulib-tool.texi
+++ b/doc/gnulib-tool.texi
@@ -31,6 +31,7 @@ a real run without changing anything.
 * Initial import::              First import of Gnulib modules.
 * Modified imports::            Changing the import specification.
 * Simple update::               Tracking Gnulib development.
+* Source changes::              Impact of Gnulib on your source files.
 * VCS Issues::                  Integration with Version Control Systems.
 @end menu
 
@@ -322,6 +323,7 @@ The argument is the prefix to use for macros in the @file{gnulib-comp.m4}
 file.  Corresponds to the @samp{--macro-prefix} command line argument.
 @end table
 
+
 @node Simple update
 @section Simple update
 
@@ -333,8 +335,39 @@ does it:
 $ gnulib-tool --import
 @end smallexample
 
+@noindent
 This will create, update or remove files, as needed.
 
+Note: From time to time, changes are made in Gnulib that are not backward
+compatible.  When updating to a more recent Gnulib, you should consult
+Gnulib's @file{NEWS} file to check whether the incompatible changes affect
+your project.
+
+
+@node Source changes
+@section Changing your sources for use with Gnulib
+
+Gnulib contains some header file overrides.  This means that when building
+on systems with deficient header files in @file{/usr/include/}, it may create
+files named @file{string.h}, @file{stdlib.h}, @file{stdint.h} or similar in
+the build directory.  In the other source directories of your package you
+will usually pass @samp{-I} options to the compiler, so that these Gnulib
+substitutes are visible and take precedence over the files in
+@file{/usr/include/}.
+
+These Gnulib substitute header files rely on @file{<config.h>} being
+already included.  Furthermore @file{<config.h>} must be the first include
+in every compilation unit.  This means that to @emph{all your source files}
+and likely also to @emph{all your tests source files} you need to add an
+@samp{#include <config.h>} at the top.  Which source files are affected?
+Exactly those whose compilation includes a @samp{-I} option that refers to
+the Gnulib library directory.
+
+This is annoying, but inevitable: On many systems, @file{<config.h>} is
+used to set system dependent flags (such as @code{_GNU_SOURCE} on GNU systems),
+and these flags have no effect after any system header file has been included.
+
+
 @node VCS Issues
 @section Issues with Version Control Systems
 

diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index e30f6cdb2a8e31a7b1f5eff59a0c936161299fb1..ca52fdc9c74d91604849b0f064149ee0f2589ea7 100644 (file)
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -5,6 +5,9 @@
 @settitle GNU Gnulib
 @syncodeindex fn cp
 @syncodeindex pg cp
+@ifclear texi2html
+@firstparagraphindent insert
+@end ifclear
 @comment %**end of header
 
 @set UPDATED $Date: 2007-09-09 13:20:45 $