Changes to the Security Guide.ent file

[Eric "Sparks" Christensen]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 10/06/2010 07:21 PM, Ruediger Landmann wrote:
>  On 10/06/2010 05:48 AM, Eric "Sparks" Christensen wrote:
> ========
> 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

This isn't showing up in any of the XML files.  I've changed this to
"Fedora Documentation" to fix the BZ information.


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

Verified and fixed.

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

Replaced &PROD; with Fedora throughout the guide.

> <!ENTITY RHELVER "10">
> Fine

Didn't see this used anywhere in the guide so I removed it.

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

Replaced &SEL; with SELinux throughout.

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

Another variable I couldn't find used anywhere in the guide so it has
been removed.

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

Same as FORMAL-RHI.

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

This has been searched and replaced throughout.

> 
> <!ENTITY CURRENTVER "10">
> Fine

Couldn't find this as being used anywhere in the guide and has been removed.

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

I added " and others" to the existing text.

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

Search and replaced.

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

Search and replaced.

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

Yeah, the one that was in there didn't make a lot of sense.  It has been
removed and the standard Feedback.xml is being used.

> Cheers
> Rudi

Thanks for the insight!

- --Eric


-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.10 (GNU/Linux)
Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org/

iQIcBAEBAgAGBQJMrUvKAAoJEDbiLlqcYamxXykQAKSzP+0Y6ncVIdquetnQtsXe
1G6yshot2bMH6B2uO87XUij6nR7ZrylSAuaLlpOi6KXr8D+u9pozA/Tm/qgpuEoy
g1/KMfW5j95uujTbvz0e9UnoIPiNH3ra6uSMRM4ZIxETAcRLaiNE9lGg7TZ+QCTG
tN9lCRNcZnm4BCgI3MaJPTsuyWVJEw2KBU2PCVRG7cFDGVWLttPDDYEjFnZHJdS/
lKfA3jWt8Kw063r7jcJqcxG8RVFE84DbySR8bWt4/fo1p/PigRXbLt483EY4/JcL
rykRGILuC70Sfe9VXrrjImhPDa+Cg4W0siApC3G2Q01N7szUkQbAp804Xrj7UmIH
VtH6L4I0r6K6fYd/PCn7yoDEea5StLomPmWacFKB7xoruybnIB0Vi947fBIFwvnz
XSeJLatU0LvA7b5Dp8ooRpvLgx8ZECk2hrK2CLGDkgd/d/kkf5HMuDL80Ezmc4Q+
pPELhehQKYOKPRPJxtnwlRk81GciTBADaEJA8dRlLlxicIhS1bAt7sxgDgbhAX5o
3aSXoOVrPWjtaMJKDYncWtD54fLJvfDD1z4Nrj6aPA8Fto+dYmgVgOY8TF79zI53
mUex1CNJZG6cMCPyCGDZzSgWSRY+CnB/kdMAThiiIcufQ3ThQAyJ8cs2T+QWUgea
5ztXOmh9y/SyEfyCz97V
=xitp
-----END PGP SIGNATURE-----