Appendix A. Installation

One way to set up a catalog for DocBook is install the DocBook stylesheets (see Section 1.3, “Installing the DocBook Stylesheets”), which also sets up a catalog. You can also use the sample catalog from the schema distribution, which can be found at: http://docbook.org/xml/5.0/catalog.xml. The sample is a starting place, but it will almost surely not work out of the box. To make it work, you need to make the catalog available to your tools, and you will also need to update the catalog entries to point to the right location on your system. Here is an example based on the sample file:

1 |<catalog prefer="public"
  |       xml:base="file:///usr/share/xml/docbook/schema/rng/5.0/">
  |  <public publicId="-//OASIS//DTD DocBook XML 5.0//EN"
  |          uri="dtd/docbook.dtd"/>
5 |  <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"/>
  |</catalog>

In this example, the public and system elements describe where to find the DTD associated with named public and system identifiers. The uri element describes where to find the RELAX NG schema. In all three cases, the uri attribute identifies a relative path to the file. The absolute path is constructed by concatenating the value of the xml:base attribute on the catalog element to the value of the uri attribute. If there is no xml:base attribute, the value of the uri attribute is used as is.

To make the catalog work on your system, set the xml:base attribute to the directory on your system that contains the schema directories. That should be the only change you need to make to the sample catalog.

If you already have other XML schemas installed, you probably already have a catalog file. On Linux systems, this is often in /etc/xml/catalog.xml. In that case, you can add the following line to that file, replacing /usr/share/xml/docbook/catalog.xml with the location of the DocBook catalog file on your system:

  |<nextCatalog catalog="file:///usr/share/xml/docbook/catalog.xml"> 

Some XML and XSL applications use the environment variable XML_CATALOG_FILES, which contains a delimited list of catalog filenames. Here is an example:

  |XML_CATALOG_FILES=/usr/share/xml/docbook/catalog.xml:/etc/xml/catalog

(On a Windows system, use semicolons instead of colons to delimit the filenames.)

Many applications also provide a configuration option that allows you to set the location of a catalog file. Check the documentation for your tool for details.

This description only scratches the surface of XML Catalogs. For a full description, go to the XML Catalogs: OASIS Standard V1.1 XML-CAT or Bob Stayton’s DocBook XSL: The Complete Guide Stayton07.

Modern schema languages (including RELAX NG and W3X XML Schema) do not include the ISO Entity Sets. Therefore, you need to use other means if you want to use these or other sets of entities. For the ISO Entity Sets, some editors give you the ability to easily select needed characters and insert them into a document.

You can also directly include entity definitions in the prolog of your document. The World Wide Web Consortium (W3C) maintains the ISO Entity Set Definitions and you can reference them from the document prolog as shown here:

1 |<?xml version="1.0" encoding="utf-8"?>
  |<!DOCTYPE article [
  |<!ENTITY % isopub SYSTEM "http://www.w3.org/2003/entities/iso8879/isopub.ent">
  |%isopub;
5 |]>
  |<article xmlns="http://docbook.org/ns/docbook" version="5.0">
  |<title>DocBook V5.0 &ndash; the superb documentation format</title>
  |…
  |</article>

For your convenience there is also a flattened entity definition file which contains all entity definitions.

1 |<?xml version="1.0" encoding="utf-8"?>
  |<!DOCTYPE article [
  |<!ENTITY % allent SYSTEM "http://www.w3.org/2003/entities/2007/w3centities-f.ent">
  |%allent;
5 |]>
  |<article xmlns="http://docbook.org/ns/docbook" version="5.0">
  |<title>DocBook V5.0 &ndash; the superb documentation format</title>
  |…
  |</article>