[RFC] Towards translatable entities

[Tommy Reynolds]

Hi Ya'll

<<<DO NOT CHANGE ANY OF YOUR FILES BASED ON THIS EMAIL!>>>

What follows is an approach to a thorny problem the translators are
encountering.  ALL DOCUMENT AUTHORS should read this too, because a
small amount of re-editing will be necessary if this approach is
adopted.  I think it will be a one-line change to the
"${PRI_LANG}/${DOCBASE}.xml" file.

Currently, each document hard-codes the filename needed to include
the FDP entities:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
 <!ENTITY % FEDORA-ENTITIES-EN SYSTEM 
 	"../../docs-common/common/fedora-entities-en.ent">
%FEDORA-ENTITIES-EN;
<!ENTITY DOCNAME "example-tutorial">
<!ENTITY DOCVERSION "0.14.1"> <!-- change version here -->
<!ENTITY DOCDATE "2006-01-21"> <!-- change revision date here -->
<!ENTITY DOCID "&DOCNAME;-&DOCVERSION; (&DOCDATE;)">
<!ENTITY BUG-NUM "000000"> <!-- use this only while in draft stage
-->
]>

In addition, several additional entities, such as "&DOCDATE;", must
be manually edited each time the document is rebuilt.

This technique of using entities makes effective translations
difficult because filename paths and entities are outside the scope
of the text addressed by the translation tools.  Thus, it is not
currently possible to have completely automated I18N support.

By re-using the same tools and techniques already in place for the
document body translation, it should be possible to:

1)  Place all entity definitions for a single locale into an XML file 
    described by a custom DTD.  Utilize .POT and .PO files, in
    conjunction with an XSL stylesheet, to automatically derive
    non-English, aka ${OTHERS}, XML files.  Just like we can do for
    the document body files.

2)  Instead of referencing a locale-specific href in the <DOCTYPE>
    declaration, reference a fixed filename "entities.ent" that will
    actually be a symbolic link (or an equivalent method) to the
    translated entity file produced above.  The building system
    "Makefile.common" should be able to do this transparently to
    document authors.

3)  Dynamic entities like "&DOCDATE;" can easily be implemented by
    "Makefile.common" and XSL stylesheet surgery.  This will
    eliminate the in-document entity definitions in favor of entities
    that we can derive from the "rpm-info.xml" file.

So far, I've sketched out a preliminary framework.  The DTD, a sample
entity definition XML file, an XSL stylesheet and a Makefile are
available at my ftp://ftp.megacoder.com/pub/entities/ site.  

Please take a look at this proof-of-concept and post your comments
and suggestions.

Cheers

-- 
I'm already an anomaly, I shall soon be an anachronism, and I have
every intention of dying an abuse!