[kde-doc-english]update

[Éric Bischoff]

Le Friday 29 November 2002 14:36, Frederik Fouvry a écrit:
> | So I suggest you reconsider method (1), so every team uses the current
> | French method.
>
> The two methods are not mutually exclusive.  Having an entity for
> people's names can help ensuring that they are marked up
> completely everywhere.

Yes, they are not mutually exclusive, but is there any gain in basing (2) on 
(1) ? The probability of a markup error looks the same to me in marking up 
(1) and (2). But as I said, this is another discussion.

Speaking about this, with DTD 4.1.2, it was not possible to use <firstname> as 
a child of <para>. This would have prevented from using method (1) at time of 
DTD 4.1.2. Can <personname> be a child of <para> ? Otherwise we will run into 
the same problem, and your method (1) will simply be invalid!

The Dutch team works around that problem by enclosing the whole <othercredit> 
in the CREDITS_FOR_TRANSLATORS. It works, as <othercredit> can be a direct 
child of <para>, but it brings other problems :
- the <contrib> text is duplicated by the explanations in full text about the 
person's role
- CREDITS_FOR_TRANSLATORS is clumsy when there is a collaboration between 
several individuals
- the resulting markup is quite heavy.

> From your description, it seems to make sense (not to say "is
> necessary") that more entities are needed for othercredit, and
> there's nothing against that.  I would also encourage to have
> those.  This does not require that you use the first method
> either.  You do as you like.

In fact, the problem behind that is that I don't know what you plan to do in 
your intervention. Do you just want to isolate the "persons" entities in a 
separate file ? Or do you plan to provide a more general framework ?

> For the authors and reviewers of original documents however, I
> would suggest that the entities are defined as well, which is
> currently not the case.

Sure. But this one is for Lauri to decide.

>  All I was thinking is that if you make
> author-level entities, you have to mark up person names extra
> when they occur in the text.  Just having the entity makes it
> simple in both cases.  (Translator names are quite different from
> the other names: they are much less likely to occur in the texts

I am one of these persons : I'm the author of ktuberling's documentation, as 
well as a French translator. Such cases are not that rare.

With method (2) I have no problem in such a case, as we would define several 
entities for one person:

&translatorEricBischoff;
&proofreaderEricBischoff;
&authorEricBischoff;

> - at least if the person is not a developer or documentation
> author as well, in which the global entity for that name can be
> used.)

No it can't.

The so-called global entity does not provide the whole markup mess which is 
the biggest part of the problem.

Method (1) addresses

	<personname>
	<firstname>
	<lastname>
	<email>

but it does not address

	<othercredit role="xxx"> (for translators and proofreaders)
	<authorname> (for authors)
	<affiliation> (okay, not needed anymore)
	<address> (okay, not needed anymore)
	<contrib>

---------------------------------------

Let's try a practical approch on the problem. Let's suppose that doc has been 
translated by Joëlle Cornavin and proofread by Gérard Delafond. Let's also 
assume that we don't mix up method (1) and method (2), which would give less 
caricatural results than below, of course. Finally, let's assume that French 
constant text is in English ;-).

Method (1)

msgid "ROLES_OF_TRANSLATORS"
msgstr "&translatorJoelleCornavin; &proofreaderGerardDelafond;"

msgid "CREDIT_FOR_TRANSLATORS"
msgstr ""
"<para>French translation by &JoelleCornavin; and &GerardDelafond;</para>"


Method (2)

msgid "ROLES_OF_TRANSLATORS"
msgstr ""
"<othercredit role=\"translator\">&nameJoelleCornavin; "
"&mailJoelleCornavin; "
"<contrib>French translation</contrib>"
"</othercredit>"
"<othercredit role=\"proofreader\">&nameGerardDelafond; "
"&mailGerardDelafond; "
"<contrib>Proofreading of French translation</contrib>"
"</othercredit>"

msgid "CREDIT_FOR_TRANSLATORS"
msgstr ""
"<para>French translation by &nameJoelleCornavin; &emailJoelleCornavin; "
"and &GerardDelafond; &emailGerardDelafond;.</para>"


Such reasoning could be repeated for authors. I think it is obvious which 
solution is the best one.

Okay, entities of method (2) can be based on entities of method (1). This is 
another debate. I don't see the advantage of such a solution right now, but 
there might be one. Just convince me ;-).

-- 
Journalist: "What do you think about occidental civilization?"
Gandhi: "That would be an excellent idea."