Re: DOCBOOK-APPS: XML catalog question and comment

[Eric Richardson <eric dot richardson at milagrosoft dot com>]

Bob Stayton wrote:

> On Tue, Apr 16, 2002 at 12:26:13PM -0700, Eric Richardson wrote:
> 
>>Hi,
>>
>>I got the new catalog resolver working. In the documentation, it does 
>>not state if there are default values for verbosity etc. I also was 
>>wondering in there was a resolution protocol for using a properties file 
>>and a system property? I would think that the system one would override 
>>the property file one. Thanks for adding the system properties Norm. It 
>>made integration with Ant easier so I don't need to change properties in 
>>two places.
>>
>>The second question I have is about the actual catalog. I have the 
>>following based on previous usage of just pointing to the catalog.
>><catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
>>
>>   <public publicId="-//OASIS//DTD XML DocBook V4.1.2//EN"
>>     uri="docbook-dtd/docbook.cat"/>
>>   <!-- docbookx.dtd? -->
>></catalog>
>>
> 
> Your comment is on the right track.
> You currently have the public ID for the Docbook DTD resolving
> to the SGML catalog file.  That won't load the DTD.
> You want to resolve the public ID to the main dtd file:
> 
>     <public publicId="-//OASIS//DTD XML DocBook V4.1.2//EN"
>       uri="docbook-dtd/docbookx.dtd"/>


Okay, I see. I thought maybe there were other components included in the 
.cat file that were needed such as CALS etc. but I see now that it comes 
along either way.


>  
> You don't need the rest of the docbook.cat because
> the XML dtd has SYSTEM identifiers that resolve to
> the relative filenames dbpoolx.mod, etc.  Those are resolved
> relative to docbookx.dtd, so all you have to do is
> locate docbookx.dtd with your XML catalog.
> 
> 
>>The old one pointed at docbook.cat so I'm not sure if I should use 
>>following tag instead.
>><nextCatalog
>>   id = id
>>   catalog = uri-reference
>>   xml:base = uri-reference />
>>
> 
> You would use nextCatalog to include another XML Catalog,
> not the SGML catalog.
> 
> 
>>Also about the import on the customization xsl which points to the 
>>stylesheets for docbook; does somebody have an example. Should I use 
>>rewrite or are there more than one way to do it?
>>
> 
> There are many ways to do it, depending on what
> you want to do.  Here is one way of doing it.
> 
> I keep my catalog in a location parallel to the
> stylesheets. I want to be able to refer to different
> stylesheets (chunk, fo, etc.):
> 
> /usr/share/xml/catalog/catalog.xml
> /usr/share/xml/xsl/docbook-xsl-1.49/html/docbook.xsl
>                                    /html/chunk.xsl
>                                    /fo/docbook.xsl
> 
> and I want portable references in my Makefiles
> that work regardless of where the files are
> located or if the stylesheets are updated to
> a new release.  So I use a stable "virtual" path in the
> Makefile command, which the catalog resolves to the
> actual location of the installed XSL files.
> 
> The catalog looks like this:
> 
> <?xml version="1.0"?>
> <!DOCTYPE catalog PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog 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">
>   <group id="docbook-xsl" xml:base="../xsl/">
> 
>        <rewriteSystem id="docbook-xsl-file"
>          systemIdStartString="/tools/xsl/docbook/"
>          rewritePrefix="docbook-xsl-1.49/"/>
> 
>        <rewriteURI id="docbook-xsl-uri"
>          uriStartString="/tools/xsl/docbook/"
>          rewritePrefix="docbook-xsl-1.49/"/>
> 
>   </group>
> </catalog>
> 
> I use both rewriteURI and rewriteSystem because some
> tools use URIs and some use system identifiers.


Is there any significance to the id="docbook-xsl-file" or -uri above?

I use the following that works out good for finding the stylesheets.
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog" xml:base=".">
   <!-- for import driver files, one for each stylesheet used -->
   <uri name="xhtml/docbook.xsl" uri="docbook-xsl/xhtml/docbook.xsl"/>
   <uri name="xhtml/chunk.xsl" uri="docbook-xsl/xhtml/chunk.xsl"/>
...
</catalog>

This was used to make sure the following is found relative to the 
catalog.xml file.
<xsl:import href="xhtml/docbook.xsl"/>

maps to "./docbook-xsl/xhtml/docbook.xsl" which means that the 
stylesheets can be found from any customization(driver file) on the 
system. This way each document can use a default customization file or 
if the document needs its own the imported stylesheet can still be found.

Do you do something similar?

Obvious the rewrite is much better as only two rules are needed. Just 
have to make sure the mapping are unique.


> 
> Then I point the XSL processor to the catalog location.
> The catalog can resolve pathnames relative to
> the catalog file location.
> The command in the Makefile looks like this:
> 
> XML_CATALOG_FILES=/usr/share/xml/catalog/catalog.xml \
>   xsltproc  /tools/xsl/docbook/html/chunk.xsl  input.xml


xsltproc has it's own implementation?

> 
> The "/tools/xsl/docbook" directory doesn't actually exist.
> The catalog resolves the stylesheet reference as follows:
> 
> 1.  /tools/xsl/docbook/chunk.xsl matches the StartString
> "/tools/xsl/docbook" in the catalog.
> 
> 2.  That item rewrites that prefix to be "docbook-xsl-1.49",
> so now I have "docbook-xsl-1.49/html/chunk.xsl".
> 
> 3.  The <group> element adds a base of "../xsl", so
> now I have "../xsl/docbook-xsl-1.49/html/chunk.xsl".
> 
> 4.  This path resolves relative to the catalog file location,
> so now I have
> "/usr/share/xml/catalog/../xsl/docbook-xsl-1.49/html/chunk.xsl"
> which is really just:
> "/usr/share/xml/xsl/docbook-xsl-1.49/html/chunk.xsl"
> when you resolve the "../catalog" part.


I put the xml:base="." in the catalog and mine doesn't seem to require 
the ../ as you explain. My dir structure:
catalog.xml
docbook-xsl

It finds the stylesheets inside the docbook-xsl directory.


> 
> Voila, I've got a full path to the xsl file.
> 
> If I want the fo stylesheet, my stylesheet reference
> is /tools/xsl/docbook/fo/docbook.xsl, which resolves
> in a similar manner.
> 
> When the 1.50 stylesheets pass muster, I install them in
> /usr/share/xml/xsl/docbook-xsl-1.50.0 and change
> the catalog entry to point to that directory:
> 
>        <rewriteSystem id="docbook-xsl-file"
>          systemIdStartString="/tools/xsl/docbook/"
>          rewritePrefix="docbook-xsl-1.50.0/"/>
> 
> I don't have to edit dozens of Makefiles.
> 
> XML catalogs are way cool for doing this kind of stuff.
> 
> BTW, if you are using xsltproc, you'll want
> to initially set the env variable XML_DEBUG_CATALOG=1 so you can
> see how each reference is being resolved.  Very helpful
> for debugging unresolved references.


You obviously have a great system here. I never thought of using the 
resolver to resolve URIs passed to the processor.

Perhaps some of this info could be donated to the FAQ as I would have 
never figured out the rewrite and the docs for the Resolver don't have 
examples like this AFAIK.

Thanks for the excellent explanation.
Eric