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/