From stickster at gmail.com Thu Jun 4 22:12:36 2015 Content-Type: multipart/mixed; boundary="===============1828942197215678816==" MIME-Version: 1.0 From: Paul W. Frields To: docs at lists.fedoraproject.org Subject: Common snippets Date: Fri, 06 Apr 2007 13:41:36 -0400 Message-ID: <1175881296.13525.33.camel@localhost.localdomain> --===============1828942197215678816== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable So today's realization of using xml:base triggered thoughts of a proper strategy for dealing with snippets. "Snippets" are what we've usually called the small pieces of XML that would be common across many documents, such as: * instructions for using CVS * legal notice in a variety of element structures * special notices such as how to report bugs A snippet might look like this: Reporting Bugs Use Bugzilla and be forever in our hearts! I am working on changing all common snippets into gettext form -- that is, using one basic XML (the en_US canonical version) and POT/PO to translate it. This is the same way we treat all other documents and the common entities. PROBLEM: = --------- The location of a snippet is a URI that appears in a @href attribute in an element. That means it can't be translated. But the @href must point to the proper locale version of a file, say, "legalnotice-en_US.xml" versus "legalnotice-pt_BR.xml". How do we ensure the @href points to the right place, in a sane, XML-compliant way? HYPOTHETICAL SOLUTION: ----------------------- 1. Use a new ${XMLSNIPPETS} variable in the document-specific Makefile, which is defined as one or more names of XML snippet files, separated by proper whitespace: XMLSNIPPETS =3D cvs.xml \ bug-reporting.xml \ legalnotice.xml 2. ${XMLSNIPPETS} file contents are not included in the POT for the specific document -- rather, they are translated in their common location, which only needs to be done once, and again whenever those actual snippets change content. 3. ${XMLSNIPPETS} files are included in the ${XMLDEPFILES} list of dependencies for the validation of the entire XML document. 4. ${XMLSNIPPETS} related targets are added to the Makefile.common to treat these files in a special way -- changing context to the ${FDPCOMMONDIR}/common folder and making any required targets for the indicated locale, then copying those target files (if updated) back to the document-specific locale folder. (In other words, these targets are created in much the same way as project-wide common entities files.) 5. A document author who wants to use a snippet inserts the appropriate XInclude in the document, and updates ${XMLSNIPPETS} in the document-specific Makefile. For an example file "snippet.xml", the XInclude looks like this and works throughout all locales: -- = Paul W. Frields, RHCE http://paul.frields.org/ gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717 Fedora Project: http://fedoraproject.org/wiki/PaulWFrields irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug --===============1828942197215678816== Content-Type: application/pgp-signature MIME-Version: 1.0 Content-Transfer-Encoding: base64 Content-Disposition: attachment; filename="signature.asc" LS0tLS1CRUdJTiBQR1AgU0lHTkFUVVJFLS0tLS0KVmVyc2lvbjogR251UEcgdjEuNC43IChHTlUv TGludXgpCgppRDhEQlFCR0ZvWlFyTnZKTjcwUk54Y1JBZ3ppQUtEUEtuNWdWd216SmpzOHV2bkdS RitjWGhoQWJRQ2VJQkNLCmR2Q3Y2WkFjdUJKYlFuSy9vRzQ1eEk0PQo9ZEdmQgotLS0tLUVORCBQ R1AgU0lHTkFUVVJFLS0tLS0K --===============1828942197215678816==-- From kwade at redhat.com Thu Jun 4 22:12:38 2015 Content-Type: multipart/mixed; boundary="===============6507883021468624267==" MIME-Version: 1.0 From: Karsten Wade To: docs at lists.fedoraproject.org Subject: Re: Common snippets Date: Wed, 11 Apr 2007 10:25:40 -0700 Message-ID: <1176312340.5208.56.camel@erato.phig.org> In-Reply-To: 1175881296.13525.33.camel@localhost.localdomain --===============6507883021468624267== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Fri, 2007-04-06 at 13:41 -0400, Paul W. Frields wrote: > HYPOTHETICAL SOLUTION: Paul, we really need to attract some more XML geeks to this project. :) I'll work through your solution a few times until I grok, then send replies. - Karsten -- = Karsten Wade, RHCE, 108 Editor ^ Fedora Documentation Project = Sr. Developer Relations Mgr. | fedoraproject.org/wiki/DocsProject quaid.108.redhat.com | gpg key: AD0E0C41 ////////////////////////////////// \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ --===============6507883021468624267== Content-Type: application/pgp-signature MIME-Version: 1.0 Content-Transfer-Encoding: base64 Content-Disposition: attachment; filename="signature.asc" LS0tLS1CRUdJTiBQR1AgU0lHTkFUVVJFLS0tLS0KVmVyc2lvbjogR251UEcgdjEuNC42IChHTlUv TGludXgpCgppRDhEQlFCR0hSb1UyWklPQnEwT0RFRVJBdGIzQUo5OStMQ3lyYU1oanE4NWV3NkVI RHIwOUk1RktBQ2ZlK28wCnlEQTErYkFhc0g4VHdoNnZEUkNUTEx3PQo9WlM3TwotLS0tLUVORCBQ R1AgU0lHTkFUVVJFLS0tLS0K --===============6507883021468624267==--