4. The Oasis XML catalog
Prev Chapter 4. Customization Next

oXygen XML Editor

4. The Oasis XML catalog

This was, for me, a real niggle when I first started with docbook. It meant that I had always to be connected to the net when I used docbook. Then I found out that others had been similarly bothered, and had scratched the itch! This is it. The small Oasis group developed the idea of catalogs, first for SGML, then XML. For which I am very grateful.

The problem. External identifiers may require resources that are not always available. For example, a system identifier that points to a resource on another machine may be inaccessible if a network connection is not available.

External identifiers may require protocols that are not accessible to all of the vendors' tools on a single computer system. An external identifier that is addressed with the ftp: protocol, for example, is not accessible to a tool that does not support that protocol.

It is often convenient to access resources using system identifiers that point to local resources. Exchanging documents that refer to local resources with other systems is problematic at best and impossible at worst.

Those three are from the spec. The last one is the real nuisance. I get sick and tired of waiting for the docbook schema to be downloaded, so I change the reference to my local copy. Then I send you the instance... referring to the local copy on my disk! You curse me and change it, then send it to someone else. Same problem.

Catalogs solve this problem in a simple way. Firstly leave the reference to the web based location in your XML instance. Next 'translate' that web reference to your local copy using a line in the catalog. I have my catalog. You have yours. We are both happy.

Docbook v5 comes with a catalog all ready to use. xIncluded below and included with the zip file (See Chapter 6). Note the zip includes my catalog (catalog.xml) and also this one below, which is the one distributed with docbook v5. The latter is possibly a more general one for you to base yours on.


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

<!-- ............................................................ -->
<!-- XML Catalog for DocBook .................................... -->
<!-- File catalog.xml ........................................... -->

<!-- Please direct all questions, bug reports, or suggestions for
     changes to the docbook@lists.oasis-open.org mailing list.
     For more information, see http://www.oasis-open.org/.
-->

<!-- This is a catalog data file for DocBook. It is provided as a
     convenience in building your own catalog files. You need not
     use the filenames listed here, and need not use the filename
     method of identifying storage objects at all. See the
     documentation for detailed information on the files associated
     with the DocBook DTD. See XML Catalogs at
     http://www.oasis-open.org/committees/entity/ for detailed
     information on supplying and using catalog data.
-->

<public publicId="-//OASIS//DTD DocBook XML 5.0//EN" uri="dtd/docbook.dtd"/>

<system systemId="http://www.oasis-open.org/docbook/xml/5.0/dtd/docbook.dtd" uri="dtd/docbook.dtd"/>

<system systemId="http://docbook.org/xml/5.0/dtd/docbook.dtd" uri="dtd/docbook.dtd"/>

<uri name="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" uri="rng/docbook.rng"/>

<uri name="http://docbook.org/xml/5.0/rng/docbook.rng" uri="rng/docbook.rng"/>

<uri name="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" uri="rng/docbookxi.rng"/>

<uri name="http://docbook.org/xml/5.0/rng/docbookxi.rng" uri="rng/docbookxi.rng"/>

<uri name="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rnc" uri="rng/docbook.rnc"/>

<uri name="http://docbook.org/xml/5.0/rng/docbook.rnc" uri="rng/docbook.rnc"/>

<uri name="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rnc" uri="rng/docbookxi.rnc"/>

<uri name="http://docbook.org/xml/5.0/rng/docbookxi.rnc" uri="rng/docbookxi.rnc"/>

<uri name="http://www.oasis-open.org/docbook/xml/5.0/xsd/docbook.xsd" uri="xsd/docbook.xsd"/>

<uri name="http://docbook.org/xml/5.0/xsd/docbook.xsd" uri="xsd/docbook.xsd"/>

<uri name="http://www.oasis-open.org/docbook/xml/5.0/xsd/docbookxi.xsd" uri="xsd/docbookxi.xsd"/>

<uri name="http://docbook.org/xml/5.0/xsd/docbookxi.xsd" uri="xsd/docbookxi.xsd"/>

<uri name="http://www.oasis-open.org/docbook/xml/5.0/xsd/xi.xsd" uri="xsd/xi.xsd"/>

<uri name="http://docbook.org/xml/5.0/xsd/xi.xsd" uri="xsd/xi.xsd"/>

<uri name="http://www.oasis-open.org/docbook/xml/5.0/xsd/xlink.xsd" uri="xsd/xlink.xsd"/>

<uri name="http://docbook.org/xml/5.0/xsd/xlink.xsd" uri="xsd/xlink.xsd"/>

<uri name="http://www.oasis-open.org/docbook/xml/5.0/xsd/xml.xsd" uri="xsd/xml.xsd"/>

<uri name="http://docbook.org/xml/5.0/xsd/xml.xsd" uri="xsd/xml.xsd"/>

<uri name="http://www.oasis-open.org/docbook/xml/5.0/sch/docbook.sch" uri="sch/docbook.sch"/>

<uri name="http://docbook.org/xml/5.0/sch/docbook.sch" uri="sch/docbook.sch"/>

<uri name="http://www.oasis-open.org/docbook/xml/5.0/docbook.nvdl" uri="docbook.nvdl"/>

<uri name="http://docbook.org/xml/5.0/docbook.nvdl" uri="docbook.nvdl"/>

<!-- End of XML Catalog for DocBook ............................. -->
<!-- ............................................................ -->
</catalog> 

It contains lots of stuff, amongst which you'll find 

<uri 
  name="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng" 
  uri="rng/docbook.rng"/>

This informs the software that each time it sees the URL http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng it should retrieve the file found at (relative) rng/docbook.rng, i.e. use your local copy!

[Note]Note

The 'software' referred to is a part of the parser. the Java file resolver.jar actually does the resolution, using the catalog. The XSLT engine (Saxon in my examples) links through to this software using a file called the CatalogManager.properties file, which tells it where the catalog(s) are to be found.

Saxon has the command line parameter

  -r org.apache.xml.resolver.tools.CatalogResolver

which tells it to use the resolver

You'll need to read up a little on setting up your catalog, though be assured it is well worth doing, to save the annoyances we've all been through.

Finally, the CatalogManager.properties file. This is mine


  #Controls the operation of the xml catalog manager
#CatalogManager.properties

verbosity=0

relative-catalogs=yes

# Always use semicolons in this list
catalogs=/sgml/catalog.xml

prefer=public

static-catalog=yes

allow-oasis-xml-catalog-pi=yes

catalog-class-name=org.apache.xml.resolver.Resolver

# was com.sun.resolver.Resolver




 

Two points. Firstly the entry catalogs=/sgml/catalog.xml which points to the actual catalog. Next the entry verbosity=0 which takes a positive integer, and dumps more and more to the screen when resolving entries! Very useful.

Prev Up Next
3. Local (document specific) graphics Home 5. The customization stylesheet