From 26f98e301e41c14c606d73e9ab6b7b17df510af9 Mon Sep 17 00:00:00 2001 From: Francisco Vila Date: Mon, 8 Feb 2010 02:13:40 +0100 Subject: [PATCH] Doc: Explain tricky updating of Snippets translations. --- Documentation/contributor/doc-work.itexi | 31 +++++++++++++++++++++++- Documentation/contributor/lsr-work.itexi | 9 ++++++- 2 files changed, 38 insertions(+), 2 deletions(-) diff --git a/Documentation/contributor/doc-work.itexi b/Documentation/contributor/doc-work.itexi index 968715627e..03c93a1e1e 100644 --- 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 . 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 ; +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 d9679f6f00..94cf04ec1d 100644 --- 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. -- 2.39.2