Common snippets

[Paul W. Frields]

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 =   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="http://www.w3.org/2001/XInclude"
      href="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