Prepare for reordering sections in the manual.

* doc/gnulib.texi: Move several sections to separate files. Include
these files.
* doc/out-of-memory.texi: New file, extracted from doc/gnulib.texi.
* doc/obsolete.texi: Likewise.
* doc/extra-tests.texi: Likewise.
* doc/transversal.texi: Likewise.
* doc/namespace.texi: Likewise.
* doc/check-version.texi: Likewise.
* doc/windows-sockets.texi: Likewise.
* doc/windows-libtool.texi: Likewise.
* doc/licenses-texi.texi: Likewise.
* doc/build-automation.texi: Likewise.
* doc/c-locale.texi: Likewise.

13 files changed, 516 insertions, 497 deletions

diff --git a/ChangeLog b/ChangeLog
index 314767e1a4..8def009d11 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,22 @@
 2017-05-10 Bruno Haible  <bruno@clisp.org>
 
+	Prepare for reordering sections in the manual.
+	* doc/gnulib.texi: Move several sections to separate files. Include
+	these files.
+	* doc/out-of-memory.texi: New file, extracted from doc/gnulib.texi.
+	* doc/obsolete.texi: Likewise.
+	* doc/extra-tests.texi: Likewise.
+	* doc/transversal.texi: Likewise.
+	* doc/namespace.texi: Likewise.
+	* doc/check-version.texi: Likewise.
+	* doc/windows-sockets.texi: Likewise.
+	* doc/windows-libtool.texi: Likewise.
+	* doc/licenses-texi.texi: Likewise.
+	* doc/build-automation.texi: Likewise.
+	* doc/c-locale.texi: Likewise.
+
+2017-05-10 Bruno Haible  <bruno@clisp.org>
+
 	Fix instructions how to update manual on www.gnu.org.
 	* doc/README: Add -I option, so that texi2dvi finds texinfo.tex.
 
diff --git a/doc/build-automation.texi b/doc/build-automation.texi
new file mode 100644
index 0000000000..c9ceee5aee
--- /dev/null
+++ b/doc/build-automation.texi
@@ -0,0 +1,57 @@
+@node Build robot for gnulib
+@section Build robot for gnulib
+
+To simplify testing on a wide set of platforms, gnulib is built on
+many platforms every day and the results are uploaded to:
+
+@url{http://autobuild.josefsson.org/gnulib/}
+
+If you wish to help the gnulib development effort with build logs for
+your favorite platform, you may perform these steps:
+
+@enumerate
+
+@item Create gnulib directory
+
+On a machine with GNU development tools installed and with a gnulib
+git checkout, use
+
+@example
+gnulib-tool --create-megatestdir --with-tests --dir=...
+@end example
+
+Note: The created directory uses ca. 512 MB on disk.
+
+@item Transfer gnulib directory
+
+Transfer this directory to a build machine (HP-UX, Cygwin, or
+whatever).  Often it is easier to transfer one file, and this can be
+achieved by running, inside the directory the following commands:
+
+@example
+./configure
+make dist
+@end example
+
+And then transferring the @file{dummy-0.tar.gz} file.
+
+@item Build modules
+
+On the build machine, run ./do-autobuild (or "nohup ./do-autobuild").
+It creates a directory @file{logs/} with a log file for each module.
+
+@item Submit build logs
+
+Submit each log file to Simon's site, either through a
+
+@example
+mail `echo gnulib__at__autobuild.josefsson.org | sed -e s/__at__/@@/`
+@end example
+
+or through netcat
+
+@example
+autobuild-submit logs/*
+@end example
+
+@end enumerate
diff --git a/doc/c-locale.texi b/doc/c-locale.texi
new file mode 100644
index 0000000000..63d11384bd
--- /dev/null
+++ b/doc/c-locale.texi
@@ -0,0 +1,51 @@
+@node String Functions in C Locale
+@section Character and String Functions in C Locale
+
+The functions in this section are similar to the generic string functions
+from the standard C library, except that
+@itemize
+@item
+They behave as if the locale was set to the "C" locale, even when the
+locale is different, and/or
+@item
+They are specially optimized for the case where all characters are plain
+ASCII characters.
+@end itemize
+
+@menu
+* c-ctype::
+* c-strcase::
+* c-strcaseeq::
+* c-strcasestr::
+* c-strstr::
+* c-strtod::
+* c-strtold::
+@end menu
+
+@node c-ctype
+@subsection c-ctype
+@include c-ctype.texi
+
+@node c-strcase
+@subsection c-strcase
+@include c-strcase.texi
+
+@node c-strcaseeq
+@subsection c-strcaseeq
+@include c-strcaseeq.texi
+
+@node c-strcasestr
+@subsection c-strcasestr
+@include c-strcasestr.texi
+
+@node c-strstr
+@subsection c-strstr
+@include c-strstr.texi
+
+@node c-strtod
+@subsection c-strtod
+@include c-strtod.texi
+
+@node c-strtold
+@subsection c-strtold
+@include c-strtold.texi
diff --git a/doc/check-version.texi b/doc/check-version.texi
new file mode 100644
index 0000000000..f22266b50c
--- /dev/null
+++ b/doc/check-version.texi
@@ -0,0 +1,53 @@
+@node Library version handling
+@section Library version handling
+
+The module @samp{check-version} can be useful when your gnulib
+application is a system library.  You will typically wrap the call to
+the @code{check_version} function through a library API, your library
+header file may contain:
+
+@example
+#define STRINGPREP_VERSION "0.5.18"
+...
+  extern const char *stringprep_check_version (const char *req_version);
+@end example
+
+To avoid ELF symbol collisions with other libraries that use the
+@samp{check-version} module, add to @file{config.h} through a
+AC_DEFINE something like:
+
+@example
+AC_DEFINE(check_version, stringprep_check_version,
+          [Rename check_version.])
+@end example
+
+The @code{stringprep_check_version} function will thus be implemented
+by the @code{check_version} module.
+
+There are two uses of the interface.  The first is a way to provide
+for applications to find out the version number of the library it
+uses.  The application may contain diagnostic code such as:
+
+@example
+  printf ("Stringprep version: header %s library %s",
+          STRINGPREP_VERSION,
+          stringprep_check_version (NULL));
+@end example
+
+Separating the library and header file version can be useful when
+searching for version mismatch related problems.
+
+The second uses is as a rudimentary test of proper library version, by
+making sure the application get a library version that is the same, or
+newer, than the header file used when building the application.  This
+doesn't catch all problems, libraries may change backwards incompatibly
+in later versions, but enable applications to require a certain
+minimum version before it may proceed.
+
+Typical uses look like:
+
+@example
+       /* Check version of libgcrypt. */
+       if (!gcry_check_version (GCRYPT_VERSION))
+         die ("version mismatch\n");
+@end example
diff --git a/doc/extra-tests.texi b/doc/extra-tests.texi
new file mode 100644
index 0000000000..fcbad12d17
--- /dev/null
+++ b/doc/extra-tests.texi
@@ -0,0 +1,73 @@
+@node Extra tests modules
+@section Extra tests modules
+
+@cindex Extra tests modules
+@cindex C++ tests modules
+@cindex tests modules, C++
+@cindex long-running tests modules
+@cindex tests modules, long-running
+@cindex privileged tests modules
+@cindex tests modules, privileged
+@cindex unportable tests modules
+@cindex tests modules, unportable
+Test modules can be marked with some special status attributes.  When a
+test module has such an attribute, @code{gnulib-tool --import} will not
+include it by default.
+
+The supported status attributes are:
+
+@table @code
+@item c++-test
+Indicates that the test is testing C++ interoperability.  Such a test is
+useful in a C++ or mixed C/C++ package, but is useless in a C package.
+
+@item longrunning-test
+Indicates that the test takes a long time to compile or execute (more
+than five minutes or so).  Such a test is better avoided in a release
+that is made for the general public.
+
+@item privileged-test
+Indicates that the test will request special privileges, for example,
+ask for the superuser password.  Such a test may hang when run
+non-interactively and is therefore better avoided in a release that is
+made for the general public.
+
+@item unportable-test
+Indicates that the test is known to fail on some systems, and that
+there is no workaround about it.  Such a test is better avoided in a
+release that is made for the general public.
+@end table
+
+@code{gnulib-tool --import --with-tests} will not include tests marked with
+these attributes by default.  When @code{gnulib-tool} is invoked with one
+of the options @code{--with-c++-tests}, @code{--with-longrunning-tests},
+@code{--with-privileged-tests}, @code{--with-unportable-tests}, it
+will include tests despite the corresponding special status attribute.
+When @code{gnulib-tool} receives the option @code{--with-all-tests},
+it will include all tests regardless of their status attributes.
+
+@code{gnulib-tool --create-testdir --with-tests} and
+@code{gnulib-tool --create-megatestdir --with-tests} by default include all
+tests of modules specified on the command line, regardless of their status
+attributes.  Tests of modules occurring as dependencies are not included
+by default if they have one of these status attributes.  The options
+@code{--with-c++-tests}, @code{--with-longrunning-tests},
+@code{--with-privileged-tests}, @code{--with-unportable-tests} are
+recognized here as well.  Additionally, @code{gnulib-tool} also
+understands the options @code{--without-c++-tests},
+@code{--without-longrunning-tests}, @code{--without-privileged-tests},
+@code{--without-unportable-tests}.
+
+In order to mark a module with a status attribute, you need to add it
+to the module description, like this:
+
+@example
+Status:
+longrunning-test
+@end example
+
+If only a part of a test deserves a particular status attribute, you
+can split the module into a primary and a secondary test module,
+say @code{foo-tests} and @code{foo-extra-tests}.  Then add a dependency
+from @code{foo-tests} to @code{foo-extra-tests}, and mark the
+@code{foo-extra-tests} with the particular status attribute.
diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index 86e9f107ef..023ddc8440 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -715,7 +715,6 @@ hold back modifications you make to Gnulib macros in cases it may be
 better to share them.
 
 
-
 @node Miscellaneous Notes
 @chapter Miscellaneous Notes
 
@@ -732,461 +731,26 @@ better to share them.
 * Build robot for gnulib::
 @end menu
 
+@include out-of-memory.texi
 
-@node Out of memory handling
-@section Out of memory handling
-
-@cindex Out of Memory handling
-@cindex Memory allocation failure
-The gnulib API does not have a standard error code for the out of memory
-error condition.  Instead of adding a non-standard error code, gnulib
-has chosen to adopt a different strategy.  Out of memory handling
-happens in rare situations, but performing the out of memory error
-handling after almost all API function invocations pollute your source
-code and might make it harder to spot more serious problems.  The
-strategy chosen improves code readability and robustness.
-
-@cindex Aborting execution
-For most applications, aborting the application with an error message
-when the out of memory situation occurs is the best that can be wished
-for.  This is how the library behaves by default (using
-the @samp{xalloc-die} module).
-
-@vindex xalloc_die
-However, we realize that some applications may not want to abort
-execution in any situation.  Gnulib supports a hook to let the
-application regain control and perform its own cleanups when an out of
-memory situation has occurred.  The application can define a function
-(having a @code{void} prototype, i.e., no return value and no
-parameters) and set the library variable
-@code{xalloc_die} to that function.  The variable should be
-declared as follows.
-
-@example
-extern void (*xalloc_die) (void);
-@end example
-
-Gnulib will invoke this function if an out of memory error occurs.  Note
-that the function should not return.  Of course, care must be taken to
-not allocate more memory, as that will likely also fail.
-
-
-@node Obsolete modules
-@section Obsolete modules
-
-@cindex Obsolete modules
-Modules can be marked obsolete.  This means that the problems they fix
-don't occur any more on the platforms that are reasonable porting targets
-now.  @code{gnulib-tool} warns when obsolete modules are mentioned on the
-command line, and by default ignores dependencies from modules to obsolete
-modules.  When you pass the option @code{--with-obsolete} to
-@code{gnulib-tool}, dependencies to obsolete modules will be included,
-however, unless blocked through an @code{--avoid} option.  This option
-is useful if your package should be portable even to very old platforms.
-
-In order to mark a module obsolete, you need to add this to the module
-description:
-
-@example
-Status:
-obsolete
-
-Notice:
-This module is obsolete.
-@end example
-
-
-@node Extra tests modules
-@section Extra tests modules
-
-@cindex Extra tests modules
-@cindex C++ tests modules
-@cindex tests modules, C++
-@cindex long-running tests modules
-@cindex tests modules, long-running
-@cindex privileged tests modules
-@cindex tests modules, privileged
-@cindex unportable tests modules
-@cindex tests modules, unportable
-Test modules can be marked with some special status attributes.  When a
-test module has such an attribute, @code{gnulib-tool --import} will not
-include it by default.
-
-The supported status attributes are:
-
-@table @code
-@item c++-test
-Indicates that the test is testing C++ interoperability.  Such a test is
-useful in a C++ or mixed C/C++ package, but is useless in a C package.
-
-@item longrunning-test
-Indicates that the test takes a long time to compile or execute (more
-than five minutes or so).  Such a test is better avoided in a release
-that is made for the general public.
-
-@item privileged-test
-Indicates that the test will request special privileges, for example,
-ask for the superuser password.  Such a test may hang when run
-non-interactively and is therefore better avoided in a release that is
-made for the general public.
-
-@item unportable-test
-Indicates that the test is known to fail on some systems, and that
-there is no workaround about it.  Such a test is better avoided in a
-release that is made for the general public.
-@end table
-
-@code{gnulib-tool --import --with-tests} will not include tests marked with
-these attributes by default.  When @code{gnulib-tool} is invoked with one
-of the options @code{--with-c++-tests}, @code{--with-longrunning-tests},
-@code{--with-privileged-tests}, @code{--with-unportable-tests}, it
-will include tests despite the corresponding special status attribute.
-When @code{gnulib-tool} receives the option @code{--with-all-tests},
-it will include all tests regardless of their status attributes.
-
-@code{gnulib-tool --create-testdir --with-tests} and
-@code{gnulib-tool --create-megatestdir --with-tests} by default include all
-tests of modules specified on the command line, regardless of their status
-attributes.  Tests of modules occurring as dependencies are not included
-by default if they have one of these status attributes.  The options
-@code{--with-c++-tests}, @code{--with-longrunning-tests},
-@code{--with-privileged-tests}, @code{--with-unportable-tests} are
-recognized here as well.  Additionally, @code{gnulib-tool} also
-understands the options @code{--without-c++-tests},
-@code{--without-longrunning-tests}, @code{--without-privileged-tests},
-@code{--without-unportable-tests}.
-
-In order to mark a module with a status attribute, you need to add it
-to the module description, like this:
-
-@example
-Status:
-longrunning-test
-@end example
-
-If only a part of a test deserves a particular status attribute, you
-can split the module into a primary and a secondary test module,
-say @code{foo-tests} and @code{foo-extra-tests}.  Then add a dependency
-from @code{foo-tests} to @code{foo-extra-tests}, and mark the
-@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
-
-The function definitions provided by Gnulib (@code{.c} code) are meant
-to be compiled by a C compiler.  The header files (@code{.h} files),
-on the other hand, can be used in either C or C++.
-
-By default, when used in a C++ compilation unit, the @code{.h} files
-declare the same symbols and overrides as in C mode, except that functions
-defined by Gnulib or by the system are declared as @samp{extern "C"}.
-
-It is also possible to indicate to Gnulib to provide many of its symbols
-in a dedicated C++ namespace.  If you define the macro
-@code{GNULIB_NAMESPACE} to an identifier, many functions will be defined
-in the namespace specified by the identifier instead of the global
-namespace.  For example, after you have defined
-@smallexample
-#define GNULIB_NAMESPACE gnulib
-@end smallexample
-@noindent
-at the beginning of a compilation unit, Gnulib's @code{<fcntl.h>} header
-file will make available the @code{open} function as @code{gnulib::open}.
-The symbol @code{open} will still refer to the system's @code{open} function,
-with its platform specific bugs and limitations.
-
-The symbols provided in the Gnulib namespace are those for which the
-corresponding header file contains a @code{_GL_CXXALIAS_RPL} or
-@code{_GL_CXXALIAS_SYS} macro invocation.
-
-The benefits of this namespace mode are:
-@itemize
-@item
-Gnulib defines fewer symbols as preprocessor macros.  For example, on a
-platform where @code{open} has to be overridden, Gnulib normally does
-@code{#define open rpl_open}.  If your package has a class with a member
-@code{open}, for example a class @code{foo} with a method @code{foo::open},
-then if you define this member in a compilation unit that includes
-@code{<fcntl.h>} and use it in a compilation unit that does not include
-@code{<fcntl.h>}, or vice versa, you will get a link error.  Worse: You
-will not notice this problem on the platform where the system's @code{open}
-function works fine.  This problem goes away in namespace mode.
-
-@item
-It provides a safety check whether the set of modules your package requests
-from Gnulib is sufficient.  For example, if you use the function
-@code{gnulib::open} in your code, and you forgot to request the module
-@samp{open} from Gnulib, you will get a compilation error (regardless of
-the platform).
-@end itemize
-
-The drawback of this namespace mode is that the system provided symbols in
-the global namespace are still present, even when they contain bugs that
-Gnulib fixes.  For example, if you call @code{open (...)} in your code,
-it will invoke the possibly buggy system function, even if you have
-requested the module @samp{open} from gnulib-tool.
-
-You can turn on the namespace mode in some compilation units and keep it
-turned off in others.  This can be useful if your package consists of
-an application layer that does not need to invoke POSIX functions and
-an operating system interface layer that contains all the OS function
-calls.  In such a situation, you will want to turn on the namespace mode
-for the application layer---to avoid many preprocessor macro
-definitions---and turn it off for the OS interface layer---to avoid
-the drawback of the namespace mode, mentioned above.
-
-
-@node Library version handling
-@section Library version handling
-
-The module @samp{check-version} can be useful when your gnulib
-application is a system library.  You will typically wrap the call to
-the @code{check_version} function through a library API, your library
-header file may contain:
-
-@example
-#define STRINGPREP_VERSION "0.5.18"
-...
-  extern const char *stringprep_check_version (const char *req_version);
-@end example
-
-To avoid ELF symbol collisions with other libraries that use the
-@samp{check-version} module, add to @file{config.h} through a
-AC_DEFINE something like:
-
-@example
-AC_DEFINE(check_version, stringprep_check_version,
-          [Rename check_version.])
-@end example
-
-The @code{stringprep_check_version} function will thus be implemented
-by the @code{check_version} module.
-
-There are two uses of the interface.  The first is a way to provide
-for applications to find out the version number of the library it
-uses.  The application may contain diagnostic code such as:
-
-@example
-  printf ("Stringprep version: header %s library %s",
-          STRINGPREP_VERSION,
-          stringprep_check_version (NULL));
-@end example
-
-Separating the library and header file version can be useful when
-searching for version mismatch related problems.
-
-The second uses is as a rudimentary test of proper library version, by
-making sure the application get a library version that is the same, or
-newer, than the header file used when building the application.  This
-doesn't catch all problems, libraries may change backwards incompatibly
-in later versions, but enable applications to require a certain
-minimum version before it may proceed.
-
-Typical uses look like:
-
-@example
-       /* Check version of libgcrypt. */
-       if (!gcry_check_version (GCRYPT_VERSION))
-         die ("version mismatch\n");
-@end example
-
-
-@node Windows sockets
-@section Windows sockets
-
-There are several issues when building applications that should work
-under Windows.  The most problematic part is for applications that use
-sockets.
-
-Hopefully, we can add helpful notes to this section that will help you
-port your application to Windows using gnulib.
-
-@subsection Getaddrinfo and WINVER
-
-This was written for the getaddrinfo module, but may be applicable to
-other functions too.
-
-The getaddrinfo function exists in ws2tcpip.h and -lws2_32 on Windows
-XP.  The function declaration is present if @code{WINVER >= 0x0501}.
-Windows 2000 does not have getaddrinfo in its @file{WS2_32.DLL}.
-
-Thus, if you want to assume Windows XP or later, you can add
-AC_DEFINE(WINVER, 0x0501) to avoid compiling the (partial) getaddrinfo
-implementation.
-
-If you want to support Windows 2000, don't do anything.  The
-replacement function will open @file{WS2_32.DLL} during run-time to
-see if there is a getaddrinfo function available, and use it when
-available.
-
-@node Libtool and Windows
-@section Libtool and Windows
-
-If you want it to be possible to cross-compile your program to MinGW
-and you use Libtool, you need to use the @code{win32-dll} option of
-@code{LT_INIT}. In other words, put:
-
-@example
-LT_INIT([win32-dll])
-@end example
-
-in your @file{configure.ac}.  This sets the correct names for the
-@code{OBJDUMP}, @code{DLLTOOL}, and @code{AS} tools for the build.
+@include obsolete.texi
 
-If you are building a library, you will also need to pass
-@code{-no-undefined} to make sure Libtool produces a DLL for your
-library.  From a @file{Makefile.am}:
-
-@example
-libgsasl_la_LDFLAGS += -no-undefined
-@end example
-
-
-@node License Texinfo sources
-@section License Texinfo sources
-
-Gnulib provides copies of the GNU GPL, GNU LGPL, and GNU FDL licenses
-in Texinfo form.  (The master location is
-@url{http://www.gnu.org/licenses/}).  These Texinfo documents do not
-have any node names and structures built into them; for your manual,
-you should @code{@@include} them in an appropriate @code{@@node}.
-
-The conventional name for the GPL node is @samp{Copying} and for the FDL
-@samp{GNU Free Documentation License}.  The LGPL doesn't seem to have
-a conventional node name.
-
-Of course the license texts themselves should not be changed at all.
+@include extra-tests.texi
 
+@include transversal.texi
 
-@node Build robot for gnulib
-@section Build robot for gnulib
+@include namespace.texi
 
-To simplify testing on a wide set of platforms, gnulib is built on
-many platforms every day and the results are uploaded to:
+@include check-version.texi
 
-@url{http://autobuild.josefsson.org/gnulib/}
+@include windows-sockets.texi
 
-If you wish to help the gnulib development effort with build logs for
-your favorite platform, you may perform these steps:
+@include windows-libtool.texi
 
-@enumerate
-
-@item Create gnulib directory
-
-On a machine with GNU development tools installed and with a gnulib
-git checkout, use
-
-@example
-gnulib-tool --create-megatestdir --with-tests --dir=...
-@end example
+@include licenses-texi.texi
 
-Note: The created directory uses ca. 512 MB on disk.
+@include build-automation.texi
 
-@item Transfer gnulib directory
-
-Transfer this directory to a build machine (HP-UX, Cygwin, or
-whatever).  Often it is easier to transfer one file, and this can be
-achieved by running, inside the directory the following commands:
-
-@example
-./configure
-make dist
-@end example
-
-And then transferring the @file{dummy-0.tar.gz} file.
-
-@item Build modules
-
-On the build machine, run ./do-autobuild (or "nohup ./do-autobuild").
-It creates a directory @file{logs/} with a log file for each module.
-
-@item Submit build logs
-
-Submit each log file to Simon's site, either through a
-
-@example
-mail `echo gnulib__at__autobuild.josefsson.org | sed -e s/__at__/@@/`
-@end example
-
-or through netcat
-
-@example
-autobuild-submit logs/*
-@end example
-
-@end enumerate
 
 @node POSIX Substitutes Library
 @chapter Building the ISO C and POSIX Substitutes
@@ -6788,57 +6352,7 @@ This list of functions is sorted according to the header that declares them.
 
 @include extern-inline.texi
 
-@node String Functions in C Locale
-@section Character and String Functions in C Locale
-
-The functions in this section are similar to the generic string functions
-from the standard C library, except that
-@itemize
-@item
-They behave as if the locale was set to the "C" locale, even when the
-locale is different, and/or
-@item
-They are specially optimized for the case where all characters are plain
-ASCII characters.
-@end itemize
-
-@menu
-* c-ctype::
-* c-strcase::
-* c-strcaseeq::
-* c-strcasestr::
-* c-strstr::
-* c-strtod::
-* c-strtold::
-@end menu
-
-@node c-ctype
-@subsection c-ctype
-@include c-ctype.texi
-
-@node c-strcase
-@subsection c-strcase
-@include c-strcase.texi
-
-@node c-strcaseeq
-@subsection c-strcaseeq
-@include c-strcaseeq.texi
-
-@node c-strcasestr
-@subsection c-strcasestr
-@include c-strcasestr.texi
-
-@node c-strstr
-@subsection c-strstr
-@include c-strstr.texi
-
-@node c-strtod
-@subsection c-strtod
-@include c-strtod.texi
-
-@node c-strtold
-@subsection c-strtold
-@include c-strtold.texi
+@include c-locale.texi
 
 @include quote.texi
 
diff --git a/doc/licenses-texi.texi b/doc/licenses-texi.texi
new file mode 100644
index 0000000000..325e2efdd8
--- /dev/null
+++ b/doc/licenses-texi.texi
@@ -0,0 +1,14 @@
+@node License Texinfo sources
+@section License Texinfo sources
+
+Gnulib provides copies of the GNU GPL, GNU LGPL, and GNU FDL licenses
+in Texinfo form.  (The master location is
+@url{http://www.gnu.org/licenses/}).  These Texinfo documents do not
+have any node names and structures built into them; for your manual,
+you should @code{@@include} them in an appropriate @code{@@node}.
+
+The conventional name for the GPL node is @samp{Copying} and for the FDL
+@samp{GNU Free Documentation License}.  The LGPL doesn't seem to have
+a conventional node name.
+
+Of course the license texts themselves should not be changed at all.
diff --git a/doc/namespace.texi b/doc/namespace.texi
new file mode 100644
index 0000000000..4214ba169e
--- /dev/null
+++ b/doc/namespace.texi
@@ -0,0 +1,64 @@
+@node A C++ namespace for gnulib
+@section A C++ namespace for gnulib
+
+The function definitions provided by Gnulib (@code{.c} code) are meant
+to be compiled by a C compiler.  The header files (@code{.h} files),
+on the other hand, can be used in either C or C++.
+
+By default, when used in a C++ compilation unit, the @code{.h} files
+declare the same symbols and overrides as in C mode, except that functions
+defined by Gnulib or by the system are declared as @samp{extern "C"}.
+
+It is also possible to indicate to Gnulib to provide many of its symbols
+in a dedicated C++ namespace.  If you define the macro
+@code{GNULIB_NAMESPACE} to an identifier, many functions will be defined
+in the namespace specified by the identifier instead of the global
+namespace.  For example, after you have defined
+@smallexample
+#define GNULIB_NAMESPACE gnulib
+@end smallexample
+@noindent
+at the beginning of a compilation unit, Gnulib's @code{<fcntl.h>} header
+file will make available the @code{open} function as @code{gnulib::open}.
+The symbol @code{open} will still refer to the system's @code{open} function,
+with its platform specific bugs and limitations.
+
+The symbols provided in the Gnulib namespace are those for which the
+corresponding header file contains a @code{_GL_CXXALIAS_RPL} or
+@code{_GL_CXXALIAS_SYS} macro invocation.
+
+The benefits of this namespace mode are:
+@itemize
+@item
+Gnulib defines fewer symbols as preprocessor macros.  For example, on a
+platform where @code{open} has to be overridden, Gnulib normally does
+@code{#define open rpl_open}.  If your package has a class with a member
+@code{open}, for example a class @code{foo} with a method @code{foo::open},
+then if you define this member in a compilation unit that includes
+@code{<fcntl.h>} and use it in a compilation unit that does not include
+@code{<fcntl.h>}, or vice versa, you will get a link error.  Worse: You
+will not notice this problem on the platform where the system's @code{open}
+function works fine.  This problem goes away in namespace mode.
+
+@item
+It provides a safety check whether the set of modules your package requests
+from Gnulib is sufficient.  For example, if you use the function
+@code{gnulib::open} in your code, and you forgot to request the module
+@samp{open} from Gnulib, you will get a compilation error (regardless of
+the platform).
+@end itemize
+
+The drawback of this namespace mode is that the system provided symbols in
+the global namespace are still present, even when they contain bugs that
+Gnulib fixes.  For example, if you call @code{open (...)} in your code,
+it will invoke the possibly buggy system function, even if you have
+requested the module @samp{open} from gnulib-tool.
+
+You can turn on the namespace mode in some compilation units and keep it
+turned off in others.  This can be useful if your package consists of
+an application layer that does not need to invoke POSIX functions and
+an operating system interface layer that contains all the OS function
+calls.  In such a situation, you will want to turn on the namespace mode
+for the application layer---to avoid many preprocessor macro
+definitions---and turn it off for the OS interface layer---to avoid
+the drawback of the namespace mode, mentioned above.
diff --git a/doc/obsolete.texi b/doc/obsolete.texi
new file mode 100644
index 0000000000..90280ce392
--- /dev/null
+++ b/doc/obsolete.texi
@@ -0,0 +1,23 @@
+@node Obsolete modules
+@section Obsolete modules
+
+@cindex Obsolete modules
+Modules can be marked obsolete.  This means that the problems they fix
+don't occur any more on the platforms that are reasonable porting targets
+now.  @code{gnulib-tool} warns when obsolete modules are mentioned on the
+command line, and by default ignores dependencies from modules to obsolete
+modules.  When you pass the option @code{--with-obsolete} to
+@code{gnulib-tool}, dependencies to obsolete modules will be included,
+however, unless blocked through an @code{--avoid} option.  This option
+is useful if your package should be portable even to very old platforms.
+
+In order to mark a module obsolete, you need to add this to the module
+description:
+
+@example
+Status:
+obsolete
+
+Notice:
+This module is obsolete.
+@end example
diff --git a/doc/out-of-memory.texi b/doc/out-of-memory.texi
new file mode 100644
index 0000000000..bd33964b97
--- /dev/null
+++ b/doc/out-of-memory.texi
@@ -0,0 +1,36 @@
+@node Out of memory handling
+@section Out of memory handling
+
+@cindex Out of Memory handling
+@cindex Memory allocation failure
+The gnulib API does not have a standard error code for the out of memory
+error condition.  Instead of adding a non-standard error code, gnulib
+has chosen to adopt a different strategy.  Out of memory handling
+happens in rare situations, but performing the out of memory error
+handling after almost all API function invocations pollute your source
+code and might make it harder to spot more serious problems.  The
+strategy chosen improves code readability and robustness.
+
+@cindex Aborting execution
+For most applications, aborting the application with an error message
+when the out of memory situation occurs is the best that can be wished
+for.  This is how the library behaves by default (using
+the @samp{xalloc-die} module).
+
+@vindex xalloc_die
+However, we realize that some applications may not want to abort
+execution in any situation.  Gnulib supports a hook to let the
+application regain control and perform its own cleanups when an out of
+memory situation has occurred.  The application can define a function
+(having a @code{void} prototype, i.e., no return value and no
+parameters) and set the library variable
+@code{xalloc_die} to that function.  The variable should be
+declared as follows.
+
+@example
+extern void (*xalloc_die) (void);
+@end example
+
+Gnulib will invoke this function if an out of memory error occurs.  Note
+that the function should not return.  Of course, care must be taken to
+not allocate more memory, as that will likely also fail.
diff --git a/doc/transversal.texi b/doc/transversal.texi
new file mode 100644
index 0000000000..6c814a9a8f
--- /dev/null
+++ b/doc/transversal.texi
@@ -0,0 +1,69 @@
+@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.
diff --git a/doc/windows-libtool.texi b/doc/windows-libtool.texi
new file mode 100644
index 0000000000..d6eb314a1a
--- /dev/null
+++ b/doc/windows-libtool.texi
@@ -0,0 +1,21 @@
+@node Libtool and Windows
+@section Libtool and Windows
+
+If you want it to be possible to cross-compile your program to MinGW
+and you use Libtool, you need to use the @code{win32-dll} option of
+@code{LT_INIT}. In other words, put:
+
+@example
+LT_INIT([win32-dll])
+@end example
+
+in your @file{configure.ac}.  This sets the correct names for the
+@code{OBJDUMP}, @code{DLLTOOL}, and @code{AS} tools for the build.
+
+If you are building a library, you will also need to pass
+@code{-no-undefined} to make sure Libtool produces a DLL for your
+library.  From a @file{Makefile.am}:
+
+@example
+libgsasl_la_LDFLAGS += -no-undefined
+@end example
diff --git a/doc/windows-sockets.texi b/doc/windows-sockets.texi
new file mode 100644
index 0000000000..bdace46bd5
--- /dev/null
+++ b/doc/windows-sockets.texi
@@ -0,0 +1,27 @@
+@node Windows sockets
+@section Windows sockets
+
+There are several issues when building applications that should work
+under Windows.  The most problematic part is for applications that use
+sockets.
+
+Hopefully, we can add helpful notes to this section that will help you
+port your application to Windows using gnulib.
+
+@subsection Getaddrinfo and WINVER
+
+This was written for the getaddrinfo module, but may be applicable to
+other functions too.
+
+The getaddrinfo function exists in ws2tcpip.h and -lws2_32 on Windows
+XP.  The function declaration is present if @code{WINVER >= 0x0501}.
+Windows 2000 does not have getaddrinfo in its @file{WS2_32.DLL}.
+
+Thus, if you want to assume Windows XP or later, you can add
+AC_DEFINE(WINVER, 0x0501) to avoid compiling the (partial) getaddrinfo
+implementation.
+
+If you want to support Windows 2000, don't do anything.  The
+replacement function will open @file{WS2_32.DLL} during run-time to
+see if there is a getaddrinfo function available, and use it when
+available.