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" />

[Karsten Wade]

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