[RFC] Towards translatable entities

[Paul W. Frields]

On Thu, 2006-02-23 at 03:12 -0600, Tommy Reynolds wrote:
> 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:

[...snip...]

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

Might I suggest a fourth possibility (one which I'm not sure will work,
and is therefore inherently less cool than what Tommy has done)?

4)  Provide a custom DTD to be used for all docs files, which references
an i18n tree somewhere in docs-common/common, for instance.  This would
"wrap" the DTD for our preferred DocBook (looks like V4.4 currently) and
provide general ("parsed"?) entities for each language.  So John Q.
Public would use the following declarations for his original XML file in
"en" language:

<!DOCTYPE article PUBLIC "-//Fedora//DTD Documentation V4.4//en"
"http://fedoraproject.org/some/canonical/fdp-en.dtd">

That DTD would contain or reference (doesn't really matter which) the
general entities for English.  Our scripts could fix the rest because
the tools are aware of DOCTYPE, only not entities that are added to the
DTD after the initial declaration.  (For instance, after running xml2po,
a very simple XSL stylesheet could be used with xsltproc to rewrite the
DOCTYPE and keep the rest of the infoset exactly the same.)

The DTDs themselves could be contained in docs-common somewhere and
published to the canonical location to provide updates when necessary.
Alternately, we could use the same magic we use for the rpm-info DTD and
simply make the SYSTEM URI point to the local docs-common (either in the
user's CVS checkout, or /usr/share/fedora/doc/docs-common for people
using the (soon to emerge) fedora-doc-common RPM.

Please, poke holes in this idea.  Call me crazy.  Call me a dreamer.
Call me for dinner!

-- 
Paul W. Frields, RHCE                          http://paul.frields.org/
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
 Fedora Documentation Project: http://fedora.redhat.com/projects/docs/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 191 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20060224/a01e8c64/attachment.sig>