From 52c2cd2f06d1ed983abb9d86006ca45a75181b2e Mon Sep 17 00:00:00 2001
From: Bruno Haible <bruno@clisp.org>
Date: Sat, 6 Dec 2008 13:04:07 +0100
Subject: [PATCH] Advocacy documentation.

---
 ChangeLog             |  6 ++++++
 doc/gnulib-intro.texi | 34 ++++++++++++++++++++++++++++++++++
 doc/gnulib.texi       |  2 ++
 3 files changed, 42 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index d34dbab54d..26a393a4f7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2008-12-06  Bruno Haible  <bruno@clisp.org>
+
+	Advocacy documentation.
+	* doc/gnulib-intro.texi (Benefits): New section.
+	* doc/gnulib.texi: Update.
+
 2008-12-06  Bruno Haible  <bruno@clisp.org>
 
 	Document the 'manywarnings' module.
diff --git a/doc/gnulib-intro.texi b/doc/gnulib-intro.texi
index 169ca80547..fa282a4b29 100644
--- a/doc/gnulib-intro.texi
+++ b/doc/gnulib-intro.texi
@@ -1,3 +1,37 @@
+@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 plagues 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
 
diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index a93b64345e..8411c80a64 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -78,6 +78,7 @@ If you need this particular \thing\, you may write to
 @w{@code{<bug-gnulib at gnu dot org>}}.
 @end macro
 
+
 @node Introduction
 @chapter Introduction
 
@@ -96,6 +97,7 @@ Resources:
 @end itemize
 
 @menu
+* Benefits::
 * Library vs Reusable Code::
 * Portability and Application Code::
 * Modules::
-- 
2.30.2