XML Catalog Policy Draft 1

[Mark Johnson <mrj@debian.org>]

For the sake of clarity, I'll try to keep this as terse as possible. We can
debate the particulars in the resulting follow-up discussion. I'll also split
these ideas into a number of messages, in the interest of readability.

I'll save mention of the xml-core package content and maintainer scripts until
the last post. There I'll also address concerns regarding the addition of TR9401
elements to some catalogs. 

Note also that use of the "group" element isn't recommended. The reason being
that AFAIK neither /usr/bin/xmlcatalog nor John Cowan's script to convert SGML
to XML catalogs support the "group" element. (May no longer be true...)

  BTW, the SGML-->XML catalog conversion script automatically generates elements
  that are part of the TR9401-extended dtd, which is the reason the extended dtd
  may be useful. The script can be used in the postinst to generate an XML
  catalog if only an SGML (aka TR9401) exists. Otherwise the /usr/bin/xmlcatalog
  script that ships with libxml2 can be used to generate the Package Catalogs
  and to update the Root Catalog.


This post defines some basic terminology, goals, and an implementation (with an
example) of the xml "Super Catalog" - aka "Root Catalog".

To avoid confusion with the current/pending LSB-SGML policy, I introduce some
new terminology. We can change it as needed later.

Terminology:    Root Catalog:      /etc/xml/xcatalog
============    -------------
                Package Catalogs:  /etc/xml/$package.xcat
                ----------------- 
                Local Catalogs:    /usr/share/xml/DTD-DIR/catalog.xml
                ---------------

Goals:   - Minimize catalog parsing: the only fully parsed catalog entry files
======     should only be the "Local Catalogs", i.e. those associated with a 
           given dtd.

         - Allow for designation of xsl stylesheet shortcuts, e.g. the
           capability to provide "db-chunk.xsl" as input to an XSLT processor,
           rather than having to type
           "/usr/share/xml/docbook/stylesheets/nwalsh/html/chunk.xsl"

        The above result in Package Catalogs (/etc/xml/$package.xcat) that are
        quite different for dtds than for stylesheets, since the latter don't
        have catalogs. At any rate, I'll give examples of each in the next post.


General Implementation Issues
=============================

  Root Catalog (/etc/xml/xcatalog)
  ------------
   Purpose:

   The primary role of the Root Catalog is to delegate entity searches to the
   appropriate Package Catalog (/etc/xml/$package.xcat). As such, it should only
   contain <delegate* ...> elements: 

     - delegatePublic, 
     - delegateSystem, and 
     - delegateURI.

     [*Note: I'm not clear when to use delegateSystem (as opposed to
      delegateURI) elements; aren't all system identifiers URIs?]

   Also, depending on how we (eventually:) add support for caching resources
   fetched from the network, the Root Catalog may also contain a "nextCatalog"
   element. [Else catalogs for cached resources can be constructed similarly to
   packaged resources. But IMO that discussion should probably be put on hold
   until we settle on the basics.]

  To get a better sense of the elements in the DTD, see the content models I've
  posted at:

    http://klecker.debian.org/~mrj/oasis/catalog/xml/content-models/catalog.dtd/
    
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

   -- BEGIN Root Catalog Example (fragment) --

<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD XML Catalogs V1.0//EN" 
  "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd";>        

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">

  <!-- ===== BEGIN xml-core entries ===== -->
  <delegatePublic publicIdStartString="-//OASIS//DTD XML Catalogs"
    catalog="xml-core.xcat"/>

  <delegateSystem systemIdStartString="http://www.oasis-open.org/committees/entity/"; 
    catalog="xml-core.xcat"/>
  <!-- ===== END xml-core entries ===== -->


  <!-- ===== BEGIN docbook-xml entries ===== -->

  <!--  docbook-xml V4.x  -->  
  <delegatePublic publicIdStartString="-//OASIS//DTD DocBook XML"
    catalog="docbook-xml.xcat"/>

  <delegateSystem systemIdStartString="http://www.oasis-open.org/docbook/xml/4"; 
    catalog="docbook-xml.xcat"/>

  <!-- docbook-xml V3.x  -->  
  <delegatePublic publicIdStartString="-//Norman Walsh//DTD DocBk XML V3"
    catalog="docbook-xml.xcat"/>

  <delegateSystem systemIdStartString="http://www.nwalsh.com/docbook/xml/3"; 
    catalog="docbook-xml.xcat"/>
  <!-- ===== END docbook-xml entries ===== -->


  <!-- ===== BEGIN docbook-xsl entries ===== -->
  <delegateSystem
    systemIdStartString="http://docbook.sourceforge.net/release/xsl/";
    catalog="docbook-xsl.xcat"/>

  <delegateSystem
    systemIdStartString="http://docbook.sf.net/release/xsl/";
    catalog="docbook-xsl.xcat"/>

  <delegateSystem systemIdStartString="db-chunk.xsl" catalog="docbook-xsl.xcat"/>

  <delegateSystem systemIdStartString="db-fo.xsl" catalog="docbook-xsl.xcat"/>

  <delegateSystem systemIdStartString="db-htmlhelp.xsl" catalog="docbook-xsl.xcat"/>
  <!-- ===== END docbook-xsl entries ===== -->

</catalog>

   -- END Root Catalog Example (fragment) --

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

More to come...

Cheers,
Mark


-- 
_____________________________________
Mark Johnson        <mark@duke.edu>
Debian XML/SGML     <mrj@debian.org>
Home Page:          <http://dulug.duke.edu/~mark/>
GPG fp: 50DF A22D 5119 3485 E9E4  89B2 BCBC B2C8 2BE2 FE81