--- a/doc/gnulib.texi	Sun Sep 09 13:19:42 2007 +0000
+++ b/doc/gnulib.texi	Sun Sep 09 13:20:45 2007 +0000
@@ -1,5 +1,5 @@
 \input texinfo   @c -*-texinfo-*-
-@comment $Id: gnulib.texi,v 1.43 2007-08-23 02:00:19 ericb Exp $
+@comment $Id: gnulib.texi,v 1.44 2007-09-09 13:20:45 haible Exp $
 @comment %**start of header
 @setfilename gnulib.info
 @settitle GNU Gnulib
@@ -7,7 +7,7 @@
 @syncodeindex pg cp
 @comment %**end of header
 
-@set UPDATED $Date: 2007-08-23 02:00:19 $
+@set UPDATED $Date: 2007-09-09 13:20:45 $
 
 @copying
 This manual is for GNU Gnulib (updated @value{UPDATED}),
@@ -51,7 +51,8 @@
 * Introduction::
 * Invoking gnulib-tool::
 * Miscellaneous Notes::
-* Header File Substitutes::
+* POSIX Substitutes Library::       Building as a separate substitutes library.
+* Header File Substitutes::         Overriding system headers.
 * Function Substitutes::            Replacing system functions.
 * Particular Modules::              Documentation of individual modules.
 * GNU Free Documentation License::  Copying and sharing this manual.
@@ -418,6 +419,35 @@
 
 @end enumerate
 
+@node POSIX Substitutes Library
+@chapter Building the ISO C and POSIX Substitutes
+
+This section shows a radically different way to use Gnulib.
+
+You can extract the ISO C / POSIX substitutes part of gnulib by running
+the command
+@smallexample
+gnulib-tool --create-testdir --source-base=lib \
+            --dir=/tmp/posixlib `posix-modules`
+@end smallexample
+
+@noindent
+The command @samp{posix-modules} is found in the same directory as
+@code{gnulib-tool}.
+
+The resulting directory can be built on a particular platform,
+independently of the program being ported.  Then you can configure and
+build any program, by setting @code{CPPFLAGS} and @code{LDFLAGS} at
+configure time accordingly: set @code{CPPFLAGS="-I.../posixlib/lib"}, plus
+any essential type definitions and flags that you find in
+@code{.../posixlib/config.h}, and set
+@code{LDFLAGS=".../posixlib/lib/libgnu.a"}.
+
+This way of using Gnulib is useful when you don't want to modify the program's
+source code, or when the program uses a mix between C and C++ sources
+(requiring separate builds of the @code{posixlib} for the C compiler and
+for the C++ compiler).
+
 @node Header File Substitutes
 @chapter ISO C and POSIX Header File Substitutes