[ << Documentation work ]	[Top][Contents]	[ Website work >> ]
[ < Updating translation committishes ]	[ Up : Documentation translation maintenance ]	[ Technical background > ]

---

Maintaining without updating translations

Keeping translations up to date under heavy changes in the documentation in English may be almost impossible, especially when a lot of contributors brings changes.

It is possible — and even recommended — to perform some maintenance 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 output 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 add the marker for untranslated status @untranslated on a single line. 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, keep obsolete (sub)subsections in the translation, marking them with a line @c obsolete just before the node.

   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, just 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 using incremental search: 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. Note that every cursor move exits incremental search, and hitting C-s twice starts incremental search with the text entered in previous incremental search.
   • 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 sections finished in the English documentation; check sections status at

   https://lilypondwiki.tuxfamily.org/index.php?title=Documentation_coordination.
   

5. Update documentation PO. It is recommended not to update strings which come from documentation that is currently deeply revised in English, to avoid doing the work more than once.
6. Fix broken cross-references by running (from Documentation/)

   make ISOLANG=YOUR-LANGUAGE fix-xrefs
   

   This step requires a successful documentation build (with make doc). 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.
• This just makes translated documentation take advantage of the new organization, which is 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 ‘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.