--- a/ChangeLog	Sun Apr 23 13:18:16 2017 +0200
+++ b/ChangeLog	Sun Apr 23 18:06:19 2017 +0200
@@ -1,3 +1,9 @@
+2017-04-23  Bruno Haible  <bruno@clisp.org>
+
+	doc: New section "Modules that modify the way other modules work".
+	* doc/gnulib.texi (Modules that modify the way other modules work): New
+	section.
+
 2017-04-23  Bruno Haible  <bruno@clisp.org>
 
 	stat-time: Update comments.

--- a/doc/gnulib.texi	Sun Apr 23 13:18:16 2017 +0200
+++ b/doc/gnulib.texi	Sun Apr 23 18:06:19 2017 +0200
@@ -723,6 +723,7 @@
 * Out of memory handling::
 * Obsolete modules::
 * Extra tests modules::
+* Modules that modify the way other modules work::
 * A C++ namespace for gnulib::      A different way of using Gnulib in C++
 * Library version handling::
 * Windows sockets::
@@ -870,6 +871,77 @@
 @code{foo-extra-tests} with the particular status attribute.
 
 
+@node Modules that modify the way other modules work
+@section Modules that modify the way other modules work
+
+The normal way to design modules is that each module has its own code,
+and the module dependencies provide the facilities on which this code
+can rely.  But sometimes it is necessary to use more advanced
+techniques.  For example:
+@itemize
+@item
+You may want to have optional module dependencies: Let module A use
+facilities provided by module B, if module B is present, but without
+requiring that module B is present.
+@item
+A module can indicate support for particular behaviours.  For example,
+Gnulib has a module @samp{sigpipe} that requests POSIX compatible
+SIGPIPE behaviour from all other modules -- something that is not
+enabled by default.  Or consider the @samp{nonblocking} module, that is
+an indicator that all I/O functions should handle non-blocking file
+descriptors -- something that, equally, is not enabled by default.
+@item
+A module can indicate to other modules that they can rely on certain
+guarantees, and thus omit specific code.  For example, when Gnulib's
+@samp{malloc-gnu} module is present, you can omit code that test
+@code{n} against zero when you call @code{malloc (n)}.
+@end itemize
+
+Be aware that these advanced techniques likely cause breakage in the
+situation of multiple @code{gnulib-tool} invocations in the scope of a
+single @code{configure} file.  This is because the question ``is module
+B present?'' does not have a unique answer in such situations.
+@code{gnulib-tool} has support for these techniques in the situation of
+@code{--create-testdir --single-configure}, which basically has two
+@code{gnulib-tool} invocations, one for a set of modules that end up in
+@code{gllib}, and one for the set of modules that end up in
+@code{gltests}.  But you should be aware that this does not cover the
+general situation.
+
+Which technique to use, depends on the answer to the question: ``If my
+module occurs among the modules of @code{gltests}, should it have an
+effect on the modules in @code{gllib}?''
+
+If the answer is ``no'', your module description should invoke the
+Autoconf macro @code{gl_MODULE_INDICATOR}.  This Autoconf macro takes
+one argument: the name of your module.  The effect of
+@code{gl_MODULE_INDICATOR([@var{my-module}])} is to define, in
+@code{config.h}, a C macro @code{GNULIB_@var{MY_MODULE}} that indicates
+whether your macro is considered to be present.  This works even when
+your macro is used in @code{gltests}: @code{GNULIB_@var{MY_MODULE}}
+will then evaluate to 1 in @code{gltests} but to 0 in @code{gllib}.
+
+If the answer is ``yes'', you have two techniques available.  The first
+one is to invoke a similar Autoconf macro, named
+@code{gl_MODULE_INDICATOR_FOR_TESTS}.  It works similarly.  However,
+when your macro is used in @code{gltests}, @code{GNULIB_@var{MY_MODULE}}
+will evaluate to 1 both in @code{gltests} and in @code{gllib}.
+
+The second one is to define a shell variable in the @code{configure}
+file that tells whether your module is present, through use of
+@code{m4_divert_text}.  The Autoconf macros of a dependency module will
+initialize this shell variable, through
+@samp{m4_divert_text([DEFAULTS], [@var{my_shell_var}=no])}.  The
+Autoconf macros of your module will override this value, through
+@samp{m4_divert_text([INIT_PREPARE], [@var{my_shell_var}=yes])}.  Then
+you can use @code{@var{my_shell_var}} in the Autoconf macros of both
+modules.  You can find more details about this technique in the Gnulib
+module @code{getopt-gnu}.
+
+Reminder: These techniques are advanced.  They have the potential to
+cause lots of headaches if you apply them incorrectly.
+
+
 @node A C++ namespace for gnulib
 @section A C++ namespace for gnulib