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

---

Maintaining without updating translations

Keeping translations up to date if the English documentation has been heavily changed is a hard task, especially when a lot of contributors submit changes.

It is possible – and even recommended – to perform some maintenance that keeps translated documentation usable and eases future translation updating.

The following tasks are listed in decreasing priority order; a rationale is given after the list.

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 directly call the check-translation.py script on individual files, see Check state of translation.
3. In .itely files, match sections and .itely file names with those from the English documentation files, which possibly involves moving the contents of complete node blocks between files (without updating the documentation itself). In other words, the ‘game’ is to find out where each section has been moved to. In case there are completely new sections, copy @node and @section commands from the English documentation files and add the marker for untranslated status (@untranslated, on a line of its own). Note that it is often not possible to exactly match subsections or subsubsections of the English documentation when its contents has been deeply revised; in this case, keep obsolete (sub)subsections in the translation and mark them with a line @c obsolete just before the node.

   The Emacs editor with its Texinfo mode makes this step easier; here are some tips in case you are using it.

   • Without the AUCTeX package for Emacs installed, the key sequence C-c C-s shows the structure of the current Texinfo file in a new buffer called *Occur*. To show the structure of two files simultaneously, first split the Emacs window in 4 tiles (with C-x 1 and C-x 2), then press C-c C-s to show the structure of one file (e.g., the translated file), copy the contents of *Occur* into the *Scratch* buffer, then press C-c C-s for the other file.

     If you happen to have AUCTeX installed, there is a function for this, which you can call with M-x texinfo-show-structure. You can also create a key binding in your ~/.emacs configuration file by adding the four following lines:

     (add-hook 'Texinfo-mode-hook
               '(lambda ()
                  (define-key Texinfo-mode-map "\C-cs"
                   'texinfo-show-structure)))
     

     After restarting Emacs you can then obtain the structure in the *Occur* buffer with C-c s.

   • Do not bother updating @menu commands when all menu entries are in the same file, just do C-c C-u C-a (“update all menus”) when you are done with updating the file.
   • Moving to the next or previous node can be easily done with 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 the next node or C-r to move to the previous node. Similar operation can be used to move to the next or 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 to set a mark, 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. While working on Documentation/po/MY-LANGUAGE.po it is recommended not to update strings located in English documentation files that are actively revised. Instead, wait until the ‘dust has settled’ to avoid doing the work more than once.
5. Check and fix broken cross-references by changing to directory Documentation/ and running

   make ISOLANG=MY-LANGUAGE check-xrefs
   make ISOLANG=MY-LANGUAGE fix-xrefs
   

   This step requires a successful in-tree documentation build (with make doc). Some cross-references might be broken because they point to nodes that exist in the English documentation, and which have 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 miss the exact spot in an existing page but still point to this page.

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 as soon as possible.

• The work must be done sooner or later anyway (before updating the translation of documentation contents), and in most cases it is not needed to repeat the process later since sections in the English documentation are mostly revised once. Of course, this might not be true sometimes, and then you really have to repeat the process.
• It makes the translation take advantage of the new documentation structure, which is better than staying with the old one.
• Moving and renaming sections to match the sectioning of English documentation simplifies future updating work: it allows updating the translation using a 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 are in English, so you can do it just fine.