[docbook-apps] XML catalogs on Cygwin

[Michael Smith <smith at xml-doc dot org>]

A few tips about using XML catalogs on Cygwin -

  - if you already have the Cygwin "docbook-xsl" and "docbook-xml42"
    packages installed via the Cygwin setup app, you already have a
    catalog at /etc/xml/catalog (those packages install and update it)

  - there's a small problem in the catalog entry that the current
    (v1.65.1) docbook-xsl package installs; the problem is, it has:

      <rewriteSystem systemIdStartString="http://docbook.sourceforge.net/release/xsl/current/"; rewritePrefix="/usr/share/docbook-xsl/"/>

    But it should have this:

      <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/current/"; rewritePrefix="/usr/share/docbook-xsl/"/>

    You can fix that by running this command:

      xmlcatalog --noout --add rewriteURI ?
        http://docbook.sourceforge.net/release/xsl/current/ ?
        /usr/share/docbook-xsl/ ?
        /etc/xml/catalog

  - once you've made that fix, if you use xsltproc, you don't need to do
    any additional config to enable catalog support for DocBook docs;
    just, if you have "local" URIs like href="/usr/local/share/xsl/..."
    in a stylesheet customization layer or whatever, replace them with
    href="http://docbook.sourceforge.net/release/xsl/current/";

  - if you're using Saxon or another Java-based XSLT engine, your engine
    won't understand the pathnames in your /etc/xml/catalog file --
    because java is a native Windows app, not (yet) complied for
    Cygwin; so there are a few more steps:

      - create a separate "Windows" catalog file; run the following
        commands:

          xmlcatalog --create > /etc/xml/catalog-windows

          xmlcatalog --noout --add rewriteURI ?
            http://docbook.sourceforge.net/release/xsl/current/ ?
            c:/cygwin/usr/share/docbook-xsl/ ?
            /etc/xml/catalog-windows

          xmlcatalog --noout --add rewriteSystem
            http://www.oasis-open.org/docbook/xml/4.2/
            c:/cygwin/usr/share/docbook-xml42/
            /etc/xml/catalog-windows

       (if your cygwin root isn't in the default "c:/cygwin" location,
       of course change that bit to whatever matches your Cygwin install)

     - to tell the xml-commons resolver where to find the catalog, you
       need to install a CatalogManager.properties file; do this:

          mkdir -p /etc/java/resolver
          cd /etc/java/resolver
          wget http://xml.apache.org/commons/components/resolver/CatalogManager.properties
          mv CatalogManager.properties CatalogManager.properties.old

          sed 's#^catalogs=.?+$#catalogs=c:/cygwin/etc/xml/catalog#; s#^verbosity=.?+$#verbosity=1#' ?
            CatalogManager.properties.old > CatalogManager.properties

       Then you'll need to make sure to add "c:/cygwin/etc/java/resolver/"
       to your Java classpath, either via the CLASSPATH environment
       variable, or the java -cp option (note: the resolver needs the
       *directory* name -- not the CatalogManager.properties filename;
       don't put "c:/cygwin/etc/java/resolver/CatalogManager.properties"

       From there on, just follow the instructions on Bob's book -

         http://sagehill.net/docbookxsl/UseCatalog.html#UsingCatalogsSaxon

Rune Enggaard Lausen <rune@enggaard-lausen.dk> writes:

> Paul A. Hoadley wrote:
> 
> >Hello,
> >
> >This is not a DocBook-specific question.  I have some DocBook XML
> >documents in a Subversion repository, and I want to be able to process
> >them on FreeBSD and WinXP/Cygwin machines.  A problem arises because
> >the customisation layer needs to know where the DocBook XSL
> >stylesheets are.  (Under Cygwin, the path is
> >"c:/cygwin/usr/local/share/xsl..." and under FreeBSD it is
> >"/usr/local/share/xsl...".  I cannot rely on a path relative to the
> >customisation file, as it can be checked out of Subversion anywhere.)
> >
> >My understanding is that the 'href' attribute of 'xsl:import' can't
> >take a parameter, so I can't pass in something system-specific from
> >the Makefile (which would have been clumsy but sufficient).  Is there
> >an XSL solution to this problem?  If not, has anyone solved this with
> >some pre-processing?
> 
> Have you considere using catalogs? We use generic paths (URLs) on all 
> imports, and then let an XML catalog resolve these to the correct 
> actual paths.
> 
> If you place the catalog file in the xsl-directory, all the resolved 
> paths to the stylesheets can be made relative.
> 
> See Bob Staytons excellent book:
> 
> http://sagehill.net/docbookxsl/
> 
> Specifically:
> 
> http://sagehill.net/docbookxsl/Catalogs.html
> 
> HTH!
> 
> Best regards,
> 
> 	Rune Lausen
>

Attachment: pgp00000.pgp
Description: PGP signature