[PATCH] doc: recommendations on gettext version

[Eric Blake]

Based on the bootstrap fallout today.

* doc/gnulib-tool.texi (gettextize and autopoint): Document the
choice between versions.
* DEPENDENCIES (gettext): Cover both approaches.

Signed-off-by: Eric Blake <address@hidden>
---

I won't push this without review; and it probably needs some tweaks.
But it represents my understanding of the situation, after dealing
with bootstrap trying to cater to both bison (which, as a GNU project,
wants GCS compliance at whatever development cost) and libvirt (as
a non-GNU project, it cares more about ease-of-development on stable
enterprise systems).

 ChangeLog            |    5 +++++
 DEPENDENCIES         |    9 +++++++--
 doc/gnulib-tool.texi |   40 +++++++++++++++++++++++++++++++++++-----
 3 files changed, 47 insertions(+), 7 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 37cdb76..bfef8ec 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,10 @@
 2012-04-25  Eric Blake  <address@hidden>

+       doc: recommendations on gettext version
+       * doc/gnulib-tool.texi (gettextize and autopoint): Document the
+       choice between versions.
+       * DEPENDENCIES (gettext): Cover both approaches.
+
        bootstrap: only force latest Makefile.in.in for gettext module
        * build-aux/bootstrap (with_gettext): Only install latest
        Makefile.in.in for projects requesting bleeding edge gettext.
diff --git a/DEPENDENCIES b/DEPENDENCIES
index 91cd6c5..e19a37e 100644
--- a/DEPENDENCIES
+++ b/DEPENDENCIES
@@ -101,8 +101,13 @@ at any time.
     ftp://ftp.gnu.org/gnu/grep/

 * GNU gettext.
-  + Always use the newest available gettext release, see
-    
<http://www.gnu.org/software/gnulib/manual/html_node/gettextize-and-autopoint.html>.
+  + If your project wants to follow GNU Coding Standards:
+    + Always use the newest available gettext release, see
+      
<http://www.gnu.org/software/gnulib/manual/html_node/gettextize-and-autopoint.html>.
+    + Use the 'gettext' module.
+  + If your project cares more about ease of development on older platforms:
+    + gettext 0.17 or newer.
+    + Use the 'gettext-h' module.
   + Recommended.
     Needed if you use modules that use internationalization (many do).
   + Homepage:
diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
index 1b025c0..febb2fb 100644
--- a/doc/gnulib-tool.texi
+++ b/doc/gnulib-tool.texi
@@ -471,7 +471,9 @@ gettextize and autopoint
 new @code{gettext} release is made, the copies of the files in Gnulib will
 be updated immediately.

-The solution is therefore:
+The choice of which version of gettext to require depends on the needs
+of your package.  For a package that wants to comply to GNU Coding
+Standards, the steps are:

 @enumerate
 @item
@@ -479,12 +481,13 @@ gettextize and autopoint
 matching GNU gettext release.  For the most recent Gnulib checkout, this is
 the newest release found on @url{http://ftp.gnu.org/gnu/gettext/}.  For an
 older Gnulib snapshot, it is the release that was the most recent release
-at the time the Gnulib snapshot was taken.  Then, after @code{gettextize},
-invoke @code{gnulib-tool}.
+at the time the Gnulib snapshot was taken.

 @item
-When a script of yours run @code{autopoint}, invoke @code{gnulib-tool}
-afterwards.
+After running @code{gettextize}, invoke @code{gnulib-tool} and import
+the @code{gettext} module.  Also, copy the latest version of gnulib's
address@hidden/po/Makefile.in.in} to your @file{po/} directory (this
+is done for you if you use gnulib's @file{bootstrap} script).

 @item
 If you get an error message like
@@ -495,6 +498,33 @@ gettextize and autopoint
 were integrated into Gnulib and now mismatch the @file{po/} infrastructure.
 In this case, fetch and install the new GNU gettext release and run
 @code{gettextize} followed by @code{gnulib-tool}.
address@hidden enumerate
+
+On the other hand, if your package is not as concerned with compliance
+to the latest standards, but instead favors development on stable
+environments, the steps are:
+
address@hidden
address@hidden
+Determine the oldest version of @code{gettext} that you intend to
+support during development (at this time, gnulib recommends going no
+older than version 0.17).  Run @code{autopoint} (not
address@hidden) to copy infrastructure into place (newer versions
+of gettext will install the older infrastructure that you requested).
+at the time the Gnulib snapshot was taken.
+
address@hidden
+Invoke @code{gnulib-tool}, and import the @code{gettext-h} module.
address@hidden enumerate
+
+Regardless of which approach you used to get the infrastructure in
+place, the following steps must then be used to preserve that
+infrastructure (gnulib's @file{bootstrap} script follows these rules):
+
address@hidden
address@hidden
+When a script of yours run @code{autopoint}, invoke @code{gnulib-tool}
+afterwards.

 @item
 When you invoke @code{autoreconf} after @code{gnulib-tool}, make sure to
-- 
1.7.7.6