doc: Add tips to maintain PO files in the repository

* gettext.texi (Translations under Version Control): New section.

2 files changed, 62 insertions, 6 deletions

diff --git a/gettext-tools/doc/ChangeLog b/gettext-tools/doc/ChangeLog
index 4c8cd46..79b5e17 100644
--- a/gettext-tools/doc/ChangeLog
+++ b/gettext-tools/doc/ChangeLog
@@ -1,5 +1,9 @@
 2014-05-05  Daiki Ueno  <ueno@gnu.org>
 
+	* gettext.texi (Translations under Version Control): New section.
+
+2014-05-05  Daiki Ueno  <ueno@gnu.org>
+
 	* gettext.texi (Version Control Issues): Rename from "CVS Issues";
 	talk about generic issues when using version control systems.
 
diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index 5fcb5b0..680b420 100644
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -372,8 +372,9 @@ Autoconf macros for use in @file{configure.ac}
 
 Integrating with Version Control Systems
 
-* Distributed Development::     
-* Files under Version Control::  
+* Distributed Development::     Avoiding version mismatch in distributed development
+* Files under Version Control::  Files to put under version control
+* Translations under Version Control::  Put PO Files under Version Control
 * autopoint Invocation::        Invoking the @code{autopoint} Program
 
 Other Programming Languages
@@ -8649,8 +8650,9 @@ uses of @code{gettextize}, @code{autopoint} and @code{autoconf} on
 version controlled files.
 
 @menu
-* Distributed Development::     
-* Files under Version Control::  
+* Distributed Development::     Avoiding version mismatch in distributed development
+* Files under Version Control::  Files to put under version control
+* Translations under Version Control::  Put PO Files under Version Control
 * autopoint Invocation::        Invoking the @code{autopoint} Program
 @end menu
 
@@ -8693,7 +8695,7 @@ version.  For example, it is possible that a platform specific bug goes
 undiscovered due to this constellation.
 @end itemize
 
-@node Files under Version Control, autopoint Invocation, Distributed Development, Version Control Issues
+@node Files under Version Control, Translations under Version Control, Distributed Development, Version Control Issues
 @subsection Files to put under version control
 
 There are basically three ways to deal with generated files in the
@@ -8773,7 +8775,57 @@ into @code{AM_GNU_GETTEXT_VERSION(0.12.1)}, and all other developers that
 use the CVS will henceforth need to have GNU @code{gettext} 0.12.1 or newer
 installed.
 
-@node autopoint Invocation,  , Files under Version Control, Version Control Issues
+@node Translations under Version Control, autopoint Invocation, Files under Version Control, Version Control Issues
+@subsection Put PO Files under Version Control
+
+Since translations are valuable assets as well as the source code, it
+would make sense to put them under version control.  The GNU gettext
+infrastructure supports two ways to deal with translations in the
+context of a version controlled repository.
+
+@enumerate
+@item
+Both POT file and PO files are committed into the repository.
+
+@item
+Only PO files are committed into the repository.
+
+@end enumerate
+
+If a POT file is absent when building, it will be generated by
+scanning the source files with @code{xgettext}, and then the PO files
+are regenerated as a dependency.  On the other hand, some maintainers
+want to keep the POT file unchanged during the development phase.  So,
+even if a POT file is present, it won't be updated automatically, even
+if the POT file is older than the source code.  You can manually
+update it with @code{make $(DOMAIN).pot-update}, and commit it at
+certain point.
+
+Special advices for particular version control systems:
+
+@itemize @bullet
+@item
+Recent version control systems, Git for instance, ignore file's
+timestamp.  In that case, PO files can be accidentally updated even if
+a POT file is not updated.  To prevent this, you can set
+@samp{PO_DEPENDS_ON_POT} variable to @code{no} in the @file{Makevars}
+file and do @code{make update-po} manually.
+
+@item
+Location comments such as @code{#: lib/error.c:116} are sometimes
+annoying, since these comments are volatile and may introduce unwanted
+change to the working copy when building.  To mitigate this, you can
+decide to omit those comments from the PO files in the repository.
+
+This is possible with the @code{--no-location} option of the
+@code{msgmerge} command @footnote{you can also use it through the
+@samp{MSGMERGE_OPTIONS} option from @file{Makevars}}.  The drawback is
+that, if the location information is needed, translators have to
+recover the location comments by running @code{msgmerge} again.
+
+@end itemize
+
+@node autopoint Invocation,  , Translations under Version Control, Version Control Issues
 @subsection Invoking the @code{autopoint} Program
 
 @include autopoint.texi