[kde-doc-english][important] Making jobs of translators easier when splitting/sharing documentation parts

[Eric Bischoff]

Hi doc writers,


So-called "entities" make it easy:
- to split a documentation into several parts that can be edited and 
translated separately
- to use the same piece of documentation at several places in your top-level 
document


This mechanism, similar to the C/C++ "#include" construct, works in three 
stages:

1 - you put a piece of documentation into a separate file with .docbook 
extension (say for example: "piece-of-doc.docbook")

2 - you declare this file from the main document:

	<!ENTITY pieceofdoc SYSTEM "piece-of-doc.docbook">

3 - you include this piece where it should be used:

	<para>Don't forget to click on "Apply" when finished.</para>

	</sect1>

	&pieceofdoc;  <================= HERE

	<sect1 id="foo-bar">
	<title>Using the Foo Bar Dialog</title>


There are two important things you must know about the consequences on the 
translations :

A - Currently, xml2pot accepts only to process a section, a chapter or a 
book, so your piece of documentation should be at one of these levels. No 
collection of <para>s please. I don't know if Coolo plans to fix this in the 
next times.

B - When you split a file in two or more parts to make it easier to handle, 
please think that there might already be translations for this file. If you 
just split the English DocBook file, all the existing translations that move 
out of the main file will get lost next time Coolo's scripts are run, making 
a lot of translators unhappy. Let's take a real example to explain what you 
should do in such a case:

The author of ktuberling wants to split it in two parts, a main part and a 
technical reference on how his application is written: in the directory 
kdegames/doc/ktuberling, the file index.docbook is split into index.docbook 
and technical-reference.docbook.

The first step after splitting the file is to go to the directory
kde-i18n/templates/docs/kdegames/ and to duplicate the doc template by doing:
	cp ktuberling.pot ktuberling_technical-reference.pot
	cvs add ktuberling_technical-reference.pot
	cvs commit ktuberling_technical-reference.pot
(please note how underscores and dashes are used).

Next step is to locate how many translations already exist in the kde-i18n 
module:
	find kde-i18n/ -name ktuberling.po | grep docs
Let's say for example that there are already translations in Swedish, French 
and German:
	de/messages/docs/kdegames/ktuberling.po
	fr/messages/docs/kdegames/ktuberling.po
	sv/messages/docs/kdegames/ktuberling.po

Once you know how many translations already exist, for each of these 
translations, go to the corresponding directory (let's say for example 
de/messages/docs/kdegames/), and do a duplication similar to what you did for 
the templates:
	cp ktuberling.po ktuberling_technical-reference.po
	cvs add ktuberling_technical-reference.po
	cvs commit ktuberling_technical-reference.po

That's not as difficult as these explanations might look like. Just remember 
you need to duplicate the template and the translations. If you do that, then 
next time the scripts are run, the existing translations will automatically 
move to the right files !

Thanks a lot of having read this carefully.