[kde-doc-english] reusing text blocks and snippets in the documentation + translation

[Burkhard Lück]

Hi translators and documentation writers,

we have a lot of duplicated text blocks and their translations spread over 
many documentations in KDE. 
E.g. the a11y.docbooks in koffice, documentation of the editor component for 
kate/kwrite, shortcut dialog and ...

It is impossible to keep all these duplicated text blocks up to date, so we 
should have a simple system for that:

write  + translate + maintain + keep it up to date once, but use it 
multiple times.

Sometimes a link to another documentation is not the apropriate solution for 
this, e.g. for smaller text blocks like a para, a variablelist or in case 
where the real application name should be used via &kappname;. 

Today we have the "catalog" solution with docbooks in the kdelibs folders 
lang/entities/ for this purpose:

cons:

* not flexible
To add a new docbook text block, this has to be done manually for all 45 teams 
with translated documentation:
add a translated docbook text block to lang/entities
add an entry for this docbook text block to lang/entities/catalog.xml

* not processed by scripty -> no automatic notification of changes for the 
translation teams.
cc'ing this list in commits for these docbook text blocks does not work.
install-compile.docbook was updated to cmake in november 2007, but today - 14 
months later - only 8 teams have a install-compile.docbook with cmake build 
system so far, 37 teams still ship their documentation for kde 4 with 
autoconf/automake as build system. Same is valid for help-menu.docbook.

pros:

* these entities are used at build time, so no language docbook generation is 
needed to get an up to date documentation in case of changed docbook 
text blocks.

What I have in mind is something like a "folder" solution:

* every docbook text block used more than once should go into a folder in 
kdelibs, maybe it's a para, a section, a chapter. whats else ...
* this folder is pulled into every kdemodul/doc/common-doc via svn externals
* same prodcedure for l10n-kde4/documentation/common-doc
* adapt l10n-kde4/scripts/update_xml 

cons:
* to get an up to date documentation the language docbooks have to be 
regenerated
* svn:externals for every kde module?

pros:
* doc writers just throw simply what ever they want to use more than once in 
the documentation docbooks into the kdelibs folder common-doc and add an 
entity for this into the header of their index.docbook. 

* now this is automatically processed by the i18n tool chain like any other  
documentation, just business as usual for the translation teams.

* changed / new docbook text blocks in kdelibs? Translation teams see this  
immediately in the stats and in lokalize. 

* Translation teams try to generate an updated documentation which is using a 
new/changed text block in kdelibs, but the teams forgot to update these  
translations? 
scripts/update_xml will simply refuse that! If the teams do not update of the 
translations of the text block in kdelibs, it is impossible for them to 
update of the translated documentation!

Comments or suggestions for a better solution?

-- 
Burkhard Lück