--- a/ChangeLog	Wed Nov 12 00:28:23 2008 +0100
+++ b/ChangeLog	Wed Nov 12 12:14:55 2008 +0100
@@ -1,3 +1,8 @@
+2008-11-12  Simon Josefsson  <simon@josefsson.org>
+
+	* doc/warnings.texi: New file, from Bruno Haible <bruno@clisp.org>.
+	* doc/gnulib.texi: Add section for warnings.
+
 2008-11-11  Bruno Haible  <bruno@clisp.org>
 
 	* lib/sockets.h: Add a comment.

--- a/doc/gnulib.texi	Wed Nov 12 00:28:23 2008 +0100
+++ b/doc/gnulib.texi	Wed Nov 12 12:14:55 2008 +0100
@@ -5756,6 +5756,7 @@
 * Regular expressions::
 * Supporting Relocation::
 * func::
+* warnings::
 @end menu
 
 @node alloca
@@ -5837,6 +5838,8 @@
 
 @include func.texi
 
+@include warnings.texi
+
 
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/warnings.texi	Wed Nov 12 12:14:55 2008 +0100
@@ -0,0 +1,58 @@
+@node warnings
+@section warnings
+
+The @code{warnings} module allows to regularly build a package with more
+GCC warnings than the default warnings emitted by GCC.
+
+It provides the following functionality:
+
+@itemize @bullet
+@item
+You can select some warning options, such as @samp{-Wall}, to be enabled
+whenever building with a GCC version that supports these options.  The
+user can choose to override these warning options by providing the
+opposite options in the @code{CFLAGS} variable at configuration time.
+
+@item
+You can make these warnings apply to selected directories only.  In
+projects where subprojects are maintained by different people, or where
+parts of the source code are imported from external sources -- for example
+from gnulib --, it is useful to apply different warning options to
+different directories.
+
+@item
+It allows to use @samp{-Werror} at @samp{make distcheck} time, to verify
+that on the maintainer's system, no warnings remain.  (Note that use of
+@samp{-Werror} in @code{CFLAGS} does not work in general, because it may
+break autoconfiguration.)
+@end itemize
+
+To use this module, you need the following:
+
+@enumerate
+@item
+In @file{configure.ac}, use for example
+@smallexample
+gl_WARN_ADD([-Wall], [WARN_CFLAGS])
+gl_WARN_ADD([-Wpointer-arith], [WARN_CFLAGS])
+@end smallexample
+
+@item
+In the directories which shall use @code{WARN_CFLAGS}, use it in the
+definition of @code{AM_CFLAGS}, like this:
+@smallexample
+AM_CFLAGS = $(WARN_CFLAGS)
+@end smallexample
+
+Note that the @code{AM_CFLAGS} is used in combination with @code{CFLAGS}
+and before @code{CFLAGS} in build rules emitted by Automake.  This allows
+the user to provide @code{CFLAGS} that override the @code{WARN_CFLAGS}.
+@end enumerate
+
+Note that it is a bad idea to use @samp{gl_WARN_ADD([-Werror])}.  The
+warnings emitted by GCC depend, to some extent, on the contents of the
+system header files, on the size and signedness of built-in types, etc.
+Use of @samp{-Werror} would cause frustration to all users on platforms
+that the maintainer has not tested before the release.  It is better if
+maintainers use @samp{-Werror} only for themselves (for example, during
+@samp{make distcheck}, as mentioned above).