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

List:       kde-i18n-doc
Subject:    Re: Generating docs for kdeextragear
From:       Krzysztof Lichota <krzysiek () lichota ! net>
Date:       2005-06-21 6:26:16
Message-ID: 42B7B308.50606 () lichota ! net
[Download RAW message or body]

Nicolas Goutte wrote:
> On Tuesday 21 June 2005 00:17, Krzysztof Lichota wrote:
> 
>>Sebastian Trueg (author of K3b) reported that docs for my language
>>(Polish) cannot be compiled (i.e. index.cache created) on some systems.
>>This is, as I understand, due to missing proper entities in kdelibs 3.2
>>(they are part of kdelibs/kdoctools).
>>
>>This is general problem with docs I have already reported many times
>>(showing more clearly with kdeextragear apps, as they support many
>>kdelibs) - entities should be part of i18n module, so that they can be
>>compiled together with docs.
>>
>>I think that expanding entites during generation of docs would solve the
>>problem as there would be no external entities, but as far as I can see
>>meinproc is not able to do so.
> 
> 
> It depends what you called "generation".
> 
> If you mean "writing docs", then it means returning to the old KDE behaviour, 
> when there were no entities in docbooks.
> 
> If you mean "compiling", that is the time point when 
> kdelibs's entities are needed. (Once the doc is transformed into HTML, there 
> are no other entities than at most the HTML ones.)

No, I mean the middle step. Currently the process of generation is as 
follows (as far as I understand it):
Step 1 (generation)- .po and original docbook are merged into translated 
docbook. This step is done by translation coordinator/translator, who 
commits translated files to docs/ directory.
Step 2 (compiling) - translated docbook is compiled using meinproc into 
index.cache.bz2 and docbooks/images/index.cache is installed in system. 
This step is done by user, who compiles and installs application in the 
system.
Step 3 (displaying) - khelpcenter transforms docbooks using XSLT into 
HTML and displays them.

Entities are needed in step 2 and 3. I would like to move expanding them 
into step 1, so that they are not necessary later.


>>Any other ideas what to do with this problem?
> 
> 
> Personally I would have two ideas:
> 
> - write again author names, emails etc in full instead of using an entity for 
> such critical docs. (However this is also again going back to the old KDE 
> behaviour.)

This is rather radical. I would prefer to have entites expanded 
automatically during generation of docbooks, as I described above.

> - the translation should have the possibility to 
> manipulate the !DOCTYPE, so that translators can add entities there. (As far 
> as I know, this is not possible currently.)

But it means we would have to add all possible entites to headers of all 
translated docbooks? It would be a lot of work to keep it consistent 
everywhere. I think this was the reason why common entities were introduced.

Regards

	Krzysztof Lichota (Polish team)
[prev in list] [next in list] [prev in thread] [next in thread]