openSUSE:Packaging XML Schemas and Stylesheets

Packaging

General Guidelines · Naming Guidelines · Specfile Guidelines · Patches Guidelines · Security Guidelines · RPM Group Guidelines
Build Service Tutorial · Tips & Tricks · Cross Distribution Howto · Packaging checks
Desktop menu categories · RPM Macros · Scriptlets · Init scripts · How to write good changes

The Packaging XML Schemas and Stylesheets is a step by step introduction on how to build packages for openSUSE which XML catalog support using the openSUSE Build Service.

Purpose

This page is intended to define a common set of rules for packaging XML schemas and stylesheets which have a public URI or identifier.

XML Catalogs

Accessing resources as paths can give you some problems:

• Paths are platform dependant.
• Some (older) operating systems does not distinguish between uppercase or lowercase paths.
• Paths can change

XML catalogs solve these problems. They are meant as a "mapping table" between URIs and local paths. With XML catalogs you gain the following benefits:

• Speed: You don't download resources each time you process your XML documents, but are redirected to a local path.
• Exchangeability: it makes exchange between different operating systems much easier as you can rely on general URIs.
• Centralization: with XML catalogs, you have one central place to configure your generic URIs

For example, the official public identifier for DocBook V4.5 is "-//OASIS//DTD DocBook XML V4.5//EN". However, this is an identifier which does not define where the DTD is really stored. To get the real path, query the XML catalog and use the command xmlcatalog:

$ xmlcatalog /etc/xml/catalog "-//OASIS//DTD DocBook XML V4.5//EN"
file:/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd

Whenever a XML document refers to this public identifier, it will receive the local path /usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd.

Concept

The XML catalog concept on SUSE consists of three catalogs:

• a main catalog, located in /etc/xml/catalog. Normally, you don't touch this.
• subcatalogs, which are placed under the directory /etc/xml/catalog.d/. The subcatalogs are usually named after their package names to distinguish them (PACKAGENAME.xml). This is the place where you add all your identifiers.
• a generated XML catalog /etc/xml/catalog-d.xml which is rewritten during installation, update, and removal. Never touch this catalog!

Normally, any XML tools on Linux query the main catalog, but not any subcatalogs. This is an implementation detail and is different on each Linux distribution—even sometimes between different openSUSE releases.

Add XML Catalog Support

Use the following steps to add XML catalog support to your package:

Step 1: Prepare Your XML Catalog

1. Create a XML catalog file and name it like your RPM package. For example, if your RPM package is foo, name your catalog file foo.xml.
2. Insert the URIs, public identifiers etc. in your catalog. See docbook_5.xml as an example. It's recommended to use a <group element and add all identifiers as child elements.

Step 2: Change your Spec File

1. Add another source line with the name of your XML catalog file, for example:

   Source1:        %{name}.xml

2. Require at least sgml-skel >= 0.7:

   Requires:       sgml-skel >= 0.7
   Requires(post): sgml-skel >= 0.7
   Requires(postun): sgml-skel >= 0.7

3. Add %post and %postun sections:

   %post
   update-xml-catalog
   %postun
   update-xml-catalog

4. Add the XML catalog as %config in the %files section:

   %config %{xml_sysconf_dir}/catalog.d/%{name}.xml

Step 3: Build and Test it

1. Install your RPM package and query the catalog with xmlcatalog (see above).
2. Rebuild the RPM package and reinstall it. Query again the main catalog, there should not be any changes.
3. Remove the RPM package. When you query the main catalog, your URIs or identifiers should not be accessible anymore.