Changes to the Security Guide.ent file

[Ruediger Landmann]

  On 10/06/2010 05:48 AM, Eric "Sparks" Christensen wrote:
> A couple of nights ago we were talking about changes that were needed in
> the Security Guide.ent file.  We got disconnected and I need to know
> what changes need to be made so I can open up the F14 version for
> translation.  What are your thoughts?

The only entities that are safe to use in Fedora documentation -- ever 
-- are as follows:

&PRODUCT; -- the Bugzilla product, used in the brand Feedback.xml, which 
must be set to "Fedora Documentation"
&BOOKID; -- the Bugzilla component, used in the brand Feedback.xml, 
which takes the form "foo-guide"
&YEAR; -- the current year, used in the legal notice, eg "2010"
&HOLDER; -- the copyright holder, used in the legal notice, which must 
be set to "Red Hat, Inc. and others"
&PRODVER; -- the version of Fedora to which this documentation applies, 
for example "14"
&PREVVER; -- the version of Fedora previous to the one to which this 
documentation applies, for example "13"

The first four entities must exist under the names exactly as given 
above. You could  use different names for the two version number 
entities, but these two are the most widely-used across Fedora 
documentation, and consistency is probably good to have.

========
Specific problems with the entities currently in the Security Guide are 
illustrative of the dangers of entities in documentation that is to be 
translated:

<!ENTITY PRODUCT "Fedora">
Incorrect Bugzilla product; and this name with its "a" ending causes 
problems for languages that inflect nouns; for example, Slavic 
languages. The Publican User Guide includes a long illustration of the 
havoc this causes: http://tinyurl.com/37n5tht

Furthermore, translators in some languages prefer to transliterate the 
Latin characters of "Fedora" into their local alphabet. Setting an 
entity to represent "Fedora" precludes this.

<!ENTITY BOOKID "Security_Guide">
Incorrect Bugzilla component -- should be "security-guide"

<!ENTITY PROD "Fedora">
Never, ever include an entity for "Fedora" in the body text of a book. 
See comments on &PRODUCT; above.

<!ENTITY RHELVER "10">
Fine

<!ENTITY SEL "SELinux">
Precludes transliteration and grammatical inflection, and makes 
translation difficult since the meaning of the string is hidden. In many 
(perhaps most) languages, translators need to know the grammatical 
gender and grammatical number of a word to translate the surrounding 
text correctly. Setting entities like this forces translators to refer 
regularly to the entities file; to which they do not have easy access. 
In particular, Transifex does not make the entities file available.

<!ENTITY FORMAL-RHI "Fedora Core">
Probably harmless; but probably obsolete, precludes transliteration, and 
precludes grammatical inflection.

<!ENTITY RH "Red Hat">
Probably harmless; but precludes transliteration and precludes 
grammatical inflection

<!ENTITY RHSELINUXTOOL "&SEL; Administration Tool">
Very harmful! -- prevents translation of "Administration Tool" (and 
hides meaning from translators)

<!ENTITY CURRENTVER "10">
Fine

<!ENTITY HOLDER "Red Hat, Inc">
Fine to set, but if non-Red Hat employees have worked on this book (and 
I know they have!) it should be "Red Hat, Inc. and others"

<!ENTITY YEAR "2010">
Fine

<!ENTITY RHSECLEVELTOOL "Firewall Configuration Tool">
Very harmful! -- prevents translation of "Firewall Configuration Tool" 
(and hides meaning from translators)

<!ENTITY RHN "Red Hat Network">
Probably harmless; but precludes transliteration and precludes 
grammatical inflection (and hides meaning from translators)

========

Tangentially, I notice this book contains a customized Feedback.xml file 
that overrides the standard Feedback.xml of the brand. I think this is 
best avoided. We provide the Feedback.xml in the brand so that:

* it only needs to be translated once
* it can be updated across all books easily if necessary
* it provides consistent instructions for providing feedback for Fedora 
documentation

There could very well be overwhelming reasons why a particular book 
might benefit from a customized Feedback.xml file, but I don't see 
that's the case here IMHO. I recommend deleting this file from the book 
and letting the brand do its job.

Cheers
Rudi