Doc: Explain tricky updating of Snippets translations.

diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi
index 968715627e4dae78e542ebb7d9af68b8ac5f4523..03c93a1e1e41bd115ff8026b66567c11586cc7ff 100644 (file)
--- a/Documentation/contributor/doc-work.itexi
+++ b/Documentation/contributor/doc-work.itexi
@@ -1288,6 +1288,10 @@ All files should be encoded in UTF-8.
 
 @include contributor/doc-translation-list.itexi
 
+In addition, not listed above, Snippets' titles and descriptions
+should be translated; they are a part of the Notation Reference and
+therefore their priority is 5.
+
 @node Translating the Web site and other Texinfo documentation
 @unnumberedsubsubsec Translating the Web site and other Texinfo documentation
 
@@ -1442,7 +1446,7 @@ Then, you should get these translated strings into compiled snippets in
 @file{Documentation/snippets}, see @q{General guidelines} in @ref{Adding
 and editing snippets}.
 
-@code{@@example} blocs need not be verbatim copies, e.g. variable
+@code{@@example} blocks need not be verbatim copies, e.g. variable
 names, file names and comments should be translated.
 
 Finally, please carefully apply every rule exposed in @ref{Texinfo
@@ -1680,6 +1684,31 @@ by doing
 git rev-list HEAD |head -1
 @end example
 
+A special case is updating Snippet documentation strings in
+@file{Documentation/@var{MY-LANGUAGE}/texidocs}.  For these to be
+correctly marked as up-to-date, first run @code{makelsr.py} as
+explained in @ref{Adding and editing snippets}, and commit the
+resulting compiled snippets left in @file{Documentation/snippets/}.
+Say the SHA1 ID code of this commit is <C>.  Now edit again your
+translated files in @file{Documentation/@var{MY-LANGUAGE}/texidocs}
+adjusting the 40-digit committish that appears in the text to be <C>;
+finally, commit these updated files.  Not doing so would result in
+changes made both to your updates and original snippets to
+persistently appear in the check-translation output as if they were
+out of sync.
+
+This two-phase mechanism avoids the (practically) unsolvable problem
+of guessing what committish will have our update, and pretending to
+put this very committish on the files in the same commit.
+
+@c http://lists.gnu.org/archive/html/lilypond-devel/2009-01/msg00245.html
+@c contains a helper script which could be used to perform massive
+@c committish updates.
+
+
+@seealso
+@ref{LSR work}.
+
 
 @node Translations management policies
 @subsection Translations management policies

diff --git a/Documentation/contributor/lsr-work.itexi b/Documentation/contributor/lsr-work.itexi
index d9679f6f0058909827bfa0a139f105e08abf5c0a..94cf04ec1d5aa318a8591aa74383c52fcd3d02ba 100644 (file)
--- a/Documentation/contributor/lsr-work.itexi
+++ b/Documentation/contributor/lsr-work.itexi
@@ -61,7 +61,14 @@ scripts/auxiliar/makelsr.py
 
 @noindent
 This also copies translated texidoc fields and snippet titles into
-snippets in @file{Documentation/snippets}.
+snippets in @file{Documentation/snippets}.  Note: this, in turn, could
+make the translated texidoc fields to appear as out of sync when you
+run @code{make check-translation}, if the originals changed from the
+last translation update, even if the translations are also updated;
+see @ref{Documentation translation maintenance} for details about
+updating the docs; in particular, see @ref{Updating translation
+committishes} to learn how to mark these translated fields as fully
+updated.
 
 Be sure that @command{make doc} runs successfully before submitting a
 patch, to prevent breaking compilation.