[kde-doc-english]Re: entities

[Frederik Fouvry]

Hi all,

A reminder about the usage of the user.entities files for
documentation translators:

There is no absolutely no need to keep an *English* entity ,
e.g. &LMB;, in the translated documentation text!  An "English entity"
is one that is defined in kdoctools/customization/en/user.entities (or
whereever it is installed).  IMHO it is `translational madness' to
want to reuse English entities blindly in a translated text - even
though it may be very tempting (well, in some languages, you're not
tempted at all ;-).  &LMB; etc. were defined in en/user.entities for
_some_ reason, viz. to make clear that it is specific to English, and
other languages may not want them (or more likely they may not be able
to use them).

The entities in <lg>/user.entities should be defined from the
viewpoint of the language they are defined for.  Adding an entity to
the file "because the text doesn't compile otherwise" is not an
argument to add it.  You should replace the entity in the English
original by normal text in that case (but consult en/user.entities to
see if any additional markup is required).  (Perhaps Kbabel could be
made to expand certain entities on request of the user to make this
process easier? - This should only affect the general entities defined
in en/user.entities.)  

When might you want to define language-specific entities?  When you
have to repeat the same string (potentially including markup)
frequently.  If you are using entities, please make sure they are used
consistently: either everywhere, or nowhere.  (I'm happy to give
advice on this.)

The general entities in
kdoctools/customization/entities/general.entities are different and
should be usable by all languages.  If not, that's a bug.

Finally - if you don't know what this is all about, don't worry.
You probably don't need it ;-)

I hope this helps - and is not too confusing,

Frederik Fouvry
KDE DocBook