X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib-intro.texi;h=09ac675eeacdfb800f1153343f0cdb1d92b0ace4;hb=349396ebfcce12ee8f927fedf82067414c427093;hp=63137fefc03a502ed87cccba0d0bdde8120f20d5;hpb=85392f85300352373c54186bdd503c8a28f16359;p=gnulib.git

diff --git a/doc/gnulib-intro.texi b/doc/gnulib-intro.texi
index 63137fefc..09ac675ee 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
@@ -35,7 +69,7 @@ that.
 Similarly, Gnulib has a facility for executing a command in a
 subprocess.  It is at the same time a portability enhancement (it
 works on GNU, Unix, and Windows, compared to the classical
-@code{fork()}/@code{exec()} which is not portable to Windows), as well
+@code{fork}/@code{exec} idiom which is not portable to Windows), as well
 as an application aid: it takes care of redirecting stdin and/or
 stdout if desired, and emits an error message if the subprocess
 failed.
@@ -175,7 +209,7 @@ C++ language or from the Linux kernel.
 @subsection Interfaces to external libraries
 
 Examples are the @samp{iconv} module, which interfaces to the
-@code{iconv()} facility, regardless whether it is contained in libc or in
+@code{iconv} facility, regardless whether it is contained in libc or in
 an external @code{libiconv}.  Or the @samp{readline} module, which
 interfaces to the GNU readline library.
 
@@ -250,19 +284,22 @@ 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
 
 If you want to use some Gnulib modules under LGPL, you can do so by
 passing the option @samp{--lgpl} to @code{gnulib-tool}.  This will
 replace the GPL header with an LGPL header while copying the source
-files to your package.
+files to your package.  Similarly, if you want some Gnulib modules
+under LGPLv2+ (Lesser GPL version 2.1 or newer), you can do so by
+passing the option @samp{--lgpl=2} to @code{gnulib-tool}.
 
 Keep in mind that when you submit patches to files in Gnulib, you should
 license them under a compatible license.  This means that sometimes the