OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook-apps message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Subject: Re: DOCBOOK-APPS: XML catalog question and comment


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

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

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.

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.

-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
Caldera International, Inc.                 fax:   (831) 429-1887
                                            email: bobs@caldera.com


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Powered by eList eXpress LLC