[kde-doc-english]update

Mon Dec 2 15:27:00 CET 2002

| 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.

Generalisation?  Increased markup quality and consistency?  Easy
checking of email addresses and name correctness in the
documentation?

| 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!

Why do you think I proposed it now? ;-)

[...]

| > 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 ?

These entities are to be defined in a set of files.
- authors, programmers, ... (everyone whose name will appear in the
  original and all translations): defined in entities/contributor.entities
- translators, ... (everyone whose name will only appear in one or
  more translations): defined in $LANG/contributor.entities

All these files only contain two entities for everyone: name and
mail.  Entities like &traducteurEricBischoff; I would still
define in $LANG/user.entities, to keep the definition of the
contributor files straightforward across all of KDE.

For someone like you, &Eric.Bischoff; and &Eric.Bischoff.mail;
are defined in entities/contributor.entities.  In
fr/contributor.entities, one adds the following line:

And in fr/user.entities: one adds the definitions for 
&translatorEricBischoff; and &proofreaderEricBischoff;, using
&Eric.Bischoff; and &Eric.Bischoff.mail; in their definitions.
People who only translate have their name and mail entities
defined in fr/contributor.entities only.

It could also be considered to define _all_ names in the general
contributor.entities file.  That may be simpler, but it increases
the number of defined entities.  Opinions on this are welcome
(before I start adding contributor.entities for the languages,
'cause that teeeedious ;-).

[...]

| >  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

[...]

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

With the proposed method, there isn't either, and you only have
to define your name and email once.

Yes, it can ;-)

Yes, it does.  You just shove the personname entity (and e-mail)
inside authorname, and you keep contrib.  Bob's your uncle.

| ---------------------------------------
| 
| 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>"

If you really want to write it like this, you may, but I don't
see you wouldn't defined entities for this: 

<!ENTITY translatorJoelleCornavin '
<othercredit role=\"translator\">&nameJoelleCornavin; 
&mailJoelleCornavin; 
<contrib>French translation</contrib>
</othercredit>'>

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

The same here: the building blocks are the same.

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

No ;-)  OK, it introduces an extra level into the setup of the
French translation.  But since I really think it can benefit all
of the KDE documentation, is it not worthwhile?

| 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 ;-).

Similar treatment for all person names in KDE's documentation?
No need for the authors to remember how the name markup went, and
no need for the reviewers to insert it?  Not to speak of email
address correction and spelling mistakes in the names?

As to a naming scheme, I propose to use the full name as written
in the text, separated by dots.  For namesakes, we still have to
find a solution, but I'm not aware of any as yet.

Frederik