Add a comment.

[gnulib.git] / doc / gnulib-tool.texi

diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
index 9d9ec56..17d5265 100644 (file)
--- a/doc/gnulib-tool.texi
+++ b/doc/gnulib-tool.texi
@@ -32,6 +32,7 @@ a real run without changing anything.
 * Modified imports::            Changing the import specification.
 * Simple update::               Tracking Gnulib development.
 * Source changes::              Impact of Gnulib on your source files.
+* gettextize and autopoint::    Caveat: @code{gettextize} and @code{autopoint} users!
 * Localization::                Handling Gnulib's own message translations.
 * VCS Issues::                  Integration with Version Control Systems.
 @end menu
@@ -371,6 +372,56 @@ used to set system dependent flags (such as @code{_GNU_SOURCE} on GNU systems),
 and these flags have no effect after any system header file has been included.
 
 
+@node gettextize and autopoint
+@section Caveat: @code{gettextize} and @code{autopoint} users
+
+@cindex gettextize, caveat
+@cindex autopoint, caveat
+The programs @code{gettextize} and @code{autopoint}, part of
+GNU @code{gettext}, import or update the internationalization infrastructure.
+Some of this infrastructure, namely ca.@: 20 autoconf macro files and the
+@file{config.rpath} file, is also contained in Gnulib and may be imported
+by @code{gnulib-tool}.  The use of @code{gettextize} or @code{autopoint}
+will therefore overwrite some of the files that @code{gnulib-tool} has
+imported, and vice versa.
+
+Avoiding to use @code{gettextize} (manually, as package maintainer) or
+@code{autopoint} (as part of a script like @code{autoreconf} or
+@code{autogen.sh}) is not the solution: These programs also import the
+infrastructure in the @file{po/} and optionally in the @file{intl/} directory.
+
+The copies of the conflicting files in Gnulib are more up-to-date than
+the copies brought in by @code{gettextize} and @code{autopoint}.  When a
+new @code{gettext} release is made, the copies of the files in Gnulib will
+be updated immediately.
+
+The solution is therefore:
+
+@enumerate
+@item
+When you run @code{gettextize}, always use the @code{gettextize} from the
+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}.
+
+@item
+When a script of yours run @code{autopoint}, invoke @code{gnulib-tool}
+afterwards.
+
+@item
+If you get an error message like
+@code{*** error: gettext infrastructure mismatch:
+using a Makefile.in.in from gettext version ...
+but the autoconf macros are from gettext version ...},
+it means that a new GNU gettext release was made, and its autoconf macros
+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}.
+@end enumerate
+
+
 @node Localization
 @section Handling Gnulib's own message translations
 
@@ -462,10 +513,11 @@ In projects which commit all source files, whether generated or not, into
 their VCS, the @code{gnulib-tool} generated files should all be committed.
 
 Gnulib also contains files generated by @command{make} (and removed by
-@code{make clean}), using information determined by @command{configure}
+@code{make clean}), using information determined by @command{configure}.
 They should not be checked into the VCS, but instead added to
-@file{.cvsignore}.  When you have a Gnulib source file of the form
-@file{lib/foo_.h}, the corresponding @file{lib/foo.h} is such a file.
+@file{.gitignore} or @file{.cvsignore}.
+When you have a Gnulib source file of the form @file{lib/foo.in.h}, the
+corresponding @file{lib/foo.h} is such a file.
 
 @item
 In projects which customarily omit from their VCS all files that are generated