+Use this command with caution, and keep in mind it will not be really
+useful until translations are stabilized after the end of GDP.
+
+
+POLICY DURING GDP PROCESS
+or "How to maintain translations without updating them"
+
+During GDP progress, documentation changes so much, and translators are
+often involved in GDP too, so keeping translations up to date is very
+difficult. However, it is possible -- and even recommended -- to
+perform some maintaining that keeps translated documentation usable
+and eases future translation updating. The rationale below the tasks
+list motivates this plan.
+
+The following tasks are listed in decreasing priority order.
+
+1) Update macros.itexi. For each obsolete macro definition, if it is
+possible to update macro usage in documentation with an automatic text
+or regexp substitution, do it and delete the macro definition from
+macros.itexi; otherwise, mark this macro definition as obsolete with a
+comment, and keep it in macros.itexi until the documentation
+translation has been updated and no longer uses this macro.
+
+2) Update *.tely files completely with make check-translation -- you
+may want to redirect ouptput to a file because of overwhelming output,
+or call check-translation.py on individual files, see CHECK STATE OF
+TRANSLATION.
+
+3) in .itelys, match sections and .itely file names with those from
+English docs, which possibly involves moving nodes contents in block
+between files, without updating contents itself. In other words, the
+game is catching where has gone each section. In Learning manual, and
+in Notation Reference sections which have been revised in GDP, there
+may be completely new sections: in this case, copy @node and
+@section-command from English docs, and put the usual tricky line
+'UNTRANSLATED NODE: IGNORE ME'. Note that it is not possible to
+exactly match subsections or subsubsections of documentation in
+English, when contents has been deeply revised; in this case, kee
+obsolete (sub)subsections in the translation.
+
+* Hints for Emacs users (without Emacs AucTeX installed)
+
+Emacs with Texinfo mode makes this step easier:
+
+- without Emacs AucTeX installed, C-c C-s shows structure of current
+Texinfo file in a new buffer *Occur*; to show structure of two files
+simultaneously, first split Emacs window in 4 tiles (with C-x 1 and
+C-x 2), press C-c C-s to show structure of one file (e.g. the translated
+file), copy *Occur* contents into *Scratch*, then press C-c C-s for the
+other file.
+If you happen to have installed AucTeX, you can either call the macro
+by doing M-x texinfo-show-structure or create a key binding in your
+~/.emacs, by adding the four following lines:
+ (add-hook 'Texinfo-mode-hook
+ '(lambda ()
+ (define-key Texinfo-mode-map "\C-cs"
+ 'texinfo-show-structure)))
+and then obtain the structure in the *Occur* buffer with C-c s
+
+
+- Do not bother updating @menus when all menu entries are in the same
+file ; make sure there is at least a (possibly empty) @menu block
+everywhere it is needed, then do C-c C-u C-a ("update all menus") when
+you have updated all the rest of the file.
+
+- Moving to next or previous node: press C-s and type node (or C-s
+@node if the text contains the word 'node') then press C-s to move to
+next node or C-r to move to previous node. Similar operation can be
+used to move to the next/previous section.
+
+- Moving a whole node (or even a sequence of nodes): jump to beginning
+of the node (quit incremental search by pressing an arrow), press
+C-SPACE, press C-s node and repeat C-s until you have selected enough
+text, cut it with C-w or C-x, jump to the right place (moving between
+nodes with the previous hint is often useful) and paste with C-y or
+C-v.
+
+
+4) update documentation PO. Unless you have special interest in
+having all titles translated in the next development release, it is
+better to wait until step 3) has been completed, to avoid doing the
+work more than once.
+
+5) Fix broken cross-references by running (from Documentation/)
+
+ make ISOLANG=<YOUR-LANGUAGE> fix-xrefs
+
+This step requires a sucessful documentation build (with 'make web').
+Some cross-references are broken because they point to a node that
+exists in the documentation in English, which has not been added to
+the translation; in this case, do not fix the cross-reference but keep
+it "broken", so that the resulting HTML link will point to an existing
+page of documentation in English.
+
+Rationale
+
+You may wonder if it would not be better to leave translations as-is
+until you can really start updating translations. There are several
+reasons to do these maintenance tasks right now.
+
+- This will have to be done sooner or later anyway, before updating
+translation of documentation contents, and this can already be done
+without needing to be redone later, as sections of documentation in
+English are mostly revised once. However, note that not all
+documentation sectioning has been revised in one go, so all this
+maintenance plan has to be repeated whenever a big reorganization is
+made. Currently (in May 2008), only chapters 3-7 in Notation Reference
+and Application Usage have not been reorganized yet.
+
+- This just makes translated documentation take advantage of the new
+organization, which is far better than the old one.
+
+- Moving and renaming sections to match sectioning of documentation in
+English simplify future updating work: it allows updating the
+translation by side-by-side comparison, without bothering whether
+cross-reference names already exist in the translation.
+
+- Each maintenance task (except 4) updating PO files) can be done by
+the same person for all languages, which saves overall time spent by
+translators to achieve this task: the node names and section titles
+are in English, so you can do. It is important to take advantage of
+this now, as it will be more complicated (but still possible) to do
+step 3) in all languages when documentation is compiled with
+texi2html and node names are directly translated in source files.
+
+
+MANAGING TRANSLATIONS WITH GIT
+
+This policy explains how to manage Git branches and commit
+translations to Git.
+
+* Translation changes matching master branch are preferably made on
+lilypond/translation branch; they may be pushed directly on master
+only if they do not break compilation of LilyPond and its
+documentation, and in this case they should be pushed to
+lilypond/translation too. Similarly, changes matching stable/X.Y are
+preferably made on lilypond/X.Ytranslation.
projects / lilypond.git / blobdiff