[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-i18n-doc
Subject:    Re: reusing text blocks and snippets in the documentation +
From:       Marek Laane <bald () smail ! ee>
Date:       2009-02-14 3:13:35
Message-ID: 200902140513.36399.bald () smail ! ee
[Download RAW message or body]

Saturday, 14. February 2009 01:38:56 kirjutas 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?

Well, I'm not essentially against it and I'm not sure how other translators 
are doing but I know from first hand that it's quite hard to have up-to-date 
kdelibs. I mean, I use some distro and it has, of course, kdelibs without 
needed entities and so on. So, I've to add them each time I'd like to 
regenerate documentation, by hand (because I've not found a way to have 
update_xml.to consider entities other than those in system places, even when 
I've translated entities in my local translation tree). Because of that I'm a 
little hesitating to give my approval, though your idea may in some 
circumstances really make it easier for translators, too.

Marek Laane
Estonian translator


[prev in list] [next in list] [prev in thread] [next in thread]