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
Attachment:
signature.asc
Description: This is a digitally signed message part
-- fedora-docs-list mailing list fedora-docs-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-docs-list
