X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib-intro.texi;h=2a32c81643a21373184058f5b66f30f7953c5b3b;hb=44eed1636c3f148a816776f4d5788ce8233592cd;hp=c42a2080349893b71e36beb7d1afbe5328e6518e;hpb=f0081f71b5ac063b48f242d6f770d7826f2ec196;p=gnulib.git

diff --git a/doc/gnulib-intro.texi b/doc/gnulib-intro.texi
index c42a20803..2a32c8164 100644
--- a/doc/gnulib-intro.texi
+++ b/doc/gnulib-intro.texi
@@ -1,4 +1,38 @@
-@node Library vs. Reusable Code
+@node Benefits
+@section Benefits of using Gnulib
+
+Gnulib is useful to enhance various aspects of a package:
+
+@itemize @bullet
+@item
+Portability: With Gnulib, a package maintainer can program against the
+POSIX and GNU libc APIs and nevertheless expect good portability to
+platforms that don't implement POSIX.
+
+@item
+Maintainability: When a package uses modules from Gnulib instead of code
+written specifically for that package, the maintainer has less code to
+maintain.
+
+@item
+Security: Gnulib provides functions that are immune against vulnerabilities
+that plague the uses of the corresponding commonplace functions. For
+example, @code{asprintf}, @code{canonicalize_file_name} are not affected
+by buffer sizing problems that affect @code{sprintf}, @code{realpath}.
+@code{openat} does not have the race conditions that @code{open} has. Etc.
+
+@item
+Reliability: Gnulib provides functions that combine a call to a system
+function with a check of the result. Examples are @code{xalloc},
+@code{xprintf}, @code{xstrtod}, @code{xgetcwd}.
+
+@item
+Structure: Gnulib offers a way to structure code into modules, typically
+one include file, one source code file, and one autoconf macro for each
+functionality. Modularity helps maintainability.
+@end itemize
+
+@node Library vs Reusable Code
 @section Library vs. Reusable Code
 
 Classical libraries are installed as binary object code.  Gnulib is
@@ -140,7 +174,8 @@ itself).
 For header files, such as @code{stdbool.h} or @code{stdint.h}, we provide
 the substitute only if the system doesn't provide a correct one.  The
 template of this replacement is distributed in a slightly different name,
-with an added underscore, so that on systems which do provide a correct
+with @samp{.in} inserted before the @samp{.h} extension, so that on
+systems which do provide a correct
 header file the system's one is used.
 
 @subsection Enhancements of ISO C or POSIX functions
@@ -250,12 +285,13 @@ not a problem, since compiled tests are not installed by ``make install''.
 Documentation files are under this copyright:
 
 @quotation
-Copyright @copyright{} 200X-200Y Free Software Foundation, Inc.@*
+Copyright @copyright{} 2004-200Y Free Software Foundation, Inc.@*
 Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
+under the terms of the GNU Free Documentation License, Version 1.3 or
 any later version published by the Free Software Foundation; with no
-Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
-Texts.
+Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+copy of the license is included in the section entitled ``GNU Free
+Documentation License''.
 @end quotation
 @end table
 
@@ -277,10 +313,23 @@ information in the corresponding module description.
 
 Gnulib modules are continually adapted, to match new practices, to be
 consistent with newly added modules, or simply as a response to build
-failure reports.  We don't make releases, but instead recommend to use the
-newest version of Gnulib from the Git repository, except in periods of major
-changes.  The source tree can also be fetched from a read-only CVS that
-mirrors the Git repository.
+failure reports.  Gnulib is available in two qualities:
+
+@itemize
+@item
+There is the newest version of Gnulib from the Git repository.  The
+source tree can also be fetched from a read-only CVS that mirrors the Git
+repository.
+
+@item
+We also make stable releases every two months, at
+@url{http://erislabs.net/ianb/projects/gnulib/}.
+@end itemize
+
+If you are willing to report an occasional regression, we recommend to
+use the newest version always, except in periods of major changes.  Most
+Gnulib users do this.  If you prefer stable releases, please use the
+newest stable release.
 
 @node Openness
 @section Openness
@@ -298,5 +347,5 @@ locally add modules that are treated like Gnulib modules by
 @code{gnulib-tool}.
 @end enumerate
 
-This is achieved by the @samp{--local-dir} option of @code{gnulib-tool}.
-
+This is achieved by the @samp{--local-dir} option of @code{gnulib-tool}
+(@pxref{Extending Gnulib}).