From stickster at gmail.com Thu Jun  4 22:12:36 2015
Content-Type: multipart/mixed; boundary="===============7931516077897328476=="
MIME-Version: 1.0
From: Paul W. Frields <stickster at gmail.com>
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>

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

    <tip>
      <title>Reporting Bugs</title>
      <para>Use Bugzilla and be forever in our hearts!</para>
    </tip>

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 <xi:include/> 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:

    <xi:include xmlns:xi=3D"http://www.w3.org/2001/XInclude"
      href=3D"snippet.xml" />


-- =

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

--===============7931516077897328476==
Content-Type: application/pgp-signature
MIME-Version: 1.0
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="signature.asc"

LS0tLS1CRUdJTiBQR1AgU0lHTkFUVVJFLS0tLS0KVmVyc2lvbjogR251UEcgdjEuNC43IChHTlUv
TGludXgpCgppRDhEQlFCR0ZvWlFyTnZKTjcwUk54Y1JBZ3ppQUtEUEtuNWdWd216SmpzOHV2bkdS
RitjWGhoQWJRQ2VJQkNLCmR2Q3Y2WkFjdUJKYlFuSy9vRzQ1eEk0PQo9ZEdmQgotLS0tLUVORCBQ
R1AgU0lHTkFUVVJFLS0tLS0K

--===============7931516077897328476==--