[PATCH] describe --local-dir option in documentation

[Ben Pfaff]

I couldn't find a description of how or why to use --local-dir,
so I wrote this up.  OK to push it?

Thanks,

Ben.

--8<--------------------------cut here-------------------------->8--

>From e5c8b4f4b93bef75db1680d4473958337ebfbd07 Mon Sep 17 00:00:00 2001
From: Ben Pfaff <address@hidden>
Date: Mon, 7 Jun 2010 22:35:00 -0700
Subject: [PATCH] Update 'gnulib-tool' documentation.

* doc/gnulib-tool.texi (Local changes): New section.
* doc/gnulib-intro.texi (Openness): Add cross-reference to new section.
---
 ChangeLog             |    7 +++++++
 doc/gnulib-intro.texi |    4 ++--
 doc/gnulib-tool.texi  |   32 ++++++++++++++++++++++++++++++++
 3 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 40bd312..e723303 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2010-06-07  Ben Pfaff  <address@hidden>
+
+       Update 'gnulib-tool' documentation.
+       * doc/gnulib-tool.texi (Local changes): New section.
+       * doc/gnulib-intro.texi (Openness): Add cross-reference to new
+       section.
+
 2010-05-23  Ben Pfaff  <address@hidden>
 
        Update maintainer documentation for 'relocatable-prog' module.
diff --git a/doc/gnulib-intro.texi b/doc/gnulib-intro.texi
index 4cb86b8..aa5f9ca 100644
--- a/doc/gnulib-intro.texi
+++ b/doc/gnulib-intro.texi
@@ -346,5 +346,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{Local changes}).
diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
index 02bb89a..09415be 100644
--- a/doc/gnulib-tool.texi
+++ b/doc/gnulib-tool.texi
@@ -48,6 +48,7 @@ a real run without changing anything.
 * Localization::                Handling Gnulib's own message translations.
 * VCS Issues::                  Integration with Version Control Systems.
 * Unit tests::                  Bundling the unit tests of the Gnulib modules.
+* Local changes::               Patching Gnulib to suit your project.
 @end menu
 
 
@@ -672,3 +673,34 @@ Note: In packages which use more than one invocation of 
@code{gnulib-tool}
 in the scope of the same @code{configure.ac}, you cannot use
 @samp{--with-tests}.  You will have to use a separate @code{configure.ac}
 in this case.
+
+
address@hidden Local changes
address@hidden Patching Gnulib to suit your project
+
+Gnulib modules are intended to be suitable for widespread use.  Most
+problems with Gnulib can and should be fixed in a generic way, so that all
+of Gnulib's users can benefit from the change.  But occasionally a problem
+arises that is difficult or undesirable to fix generically, or a project
+that uses Gnulib may need to work around an issue before the Gnulib
+maintainers commit a final fix.
+
+Whatever the reason, the @address@hidden option to
address@hidden may be used to apply and maintain local changes to
+Gnulib modules.  If this option is specified, then @command{gnulib-tool}
+looks in @address@hidden whenever it reads a file from the Gnulib
+directory.  Suppose @command{gnulib-tool} is looking for @var{file}.  Then:
+
address@hidden @bullet
address@hidden
+If @address@hidden/@var{file}} exists, then @samp{gnulib-tool} uses
+it instead of the file included in Gnulib.
+
address@hidden
+Otherwise, if @address@hidden/@var{file}.diff} exists, then
address@hidden uses the file from Gnulib after applying the diff
+using the @command{patch} program.
+
address@hidden
+Otherwise, @command{gnulib-tool} uses the file included in Gnulib.
address@hidden itemize
-- 
1.7.1



-- 
RMS on DRM: "This ought to be a crime. And, if we had governments of the
people, by the people, for the people, then the executives of those companies
would be in prison.  But they're not in prison, and the reason is that we have
government of the people, by the sell-outs, for the corporations."