On 10/06/2010 05:48 AM, Eric "Sparks" Christensen wrote: 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