Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / libxml2 / 8594de986901352eb73372c5783a0454085c1fe9 / . / doc / catalog.html
blob: f2395c2ebfea38e633fae6c9e8641874dc75231a [file] [log] [blame]
Daniel Veillard43d3f612001-11-10 11:57:23 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]2<html>
3<head>
Daniel Veillard7216cfd2002-11-08 15:10:00 +0000[diff] [blame]4<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
Daniel Veillardc332dab2002-03-29 14:08:27 +0000[diff] [blame]5<link rel="SHORTCUT ICON" href="/favicon.ico">
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]6<style type="text/css"><!--
Daniel Veillard373a4752002-02-21 14:46:29 +0000[diff] [blame]7TD {font-family: Verdana,Arial,Helvetica}
8BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em}
9H1 {font-family: Verdana,Arial,Helvetica}
10H2 {font-family: Verdana,Arial,Helvetica}
11H3 {font-family: Verdana,Arial,Helvetica}
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]12A:link, A:visited, A:active { text-decoration: underline }
13--></style>
14<title>Catalog support</title>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]15</head>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]16<body bgcolor="#8b7765" text="#000000" link="#000000" vlink="#000000">
17<table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr>
18<td width="180">
Daniel Veillard8f40f1e2002-08-28 21:18:45 +0000[diff] [blame]19<a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo"></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo"></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo"></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo"></a></div>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]20</td>
21<td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center">
22<h1>The XML C library for Gnome</h1>
23<h2>Catalog support</h2>
24</td></tr></table></td></tr></table></td>
25</tr></table>
26<table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr>
27<td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td>
28<table width="100%" border="0" cellspacing="1" cellpadding="3">
29<tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr>
Daniel Veillard4a603e42003-01-11 14:18:53 +0000[diff] [blame]30<tr><td bgcolor="#fffacd">
31<form action="search.php" enctype="application/x-www-form-urlencoded" method="GET">
32<input name="query" type="TEXT" size="20" value=""><input name="submit" type="submit" value="Search ...">
33</form>
34<ul>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]35<li><a href="index.html">Home</a></li>
36<li><a href="intro.html">Introduction</a></li>
37<li><a href="FAQ.html">FAQ</a></li>
38<li><a href="docs.html">Documentation</a></li>
39<li><a href="bugs.html">Reporting bugs and getting help</a></li>
40<li><a href="help.html">How to help</a></li>
41<li><a href="downloads.html">Downloads</a></li>
42<li><a href="news.html">News</a></li>
Daniel Veillard7b602b42002-01-08 13:26:00 +0000[diff] [blame]43<li><a href="XMLinfo.html">XML</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]44<li><a href="XSLT.html">XSLT</a></li>
Daniel Veillard6dbcaf82002-02-20 14:37:47 +0000[diff] [blame]45<li><a href="python.html">Python and bindings</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]46<li><a href="architecture.html">libxml architecture</a></li>
47<li><a href="tree.html">The tree output</a></li>
48<li><a href="interface.html">The SAX interface</a></li>
49<li><a href="xmldtd.html">Validation &amp; DTDs</a></li>
50<li><a href="xmlmem.html">Memory Management</a></li>
51<li><a href="encoding.html">Encodings support</a></li>
52<li><a href="xmlio.html">I/O Interfaces</a></li>
53<li><a href="catalog.html">Catalog support</a></li>
54<li><a href="library.html">The parser interfaces</a></li>
55<li><a href="entities.html">Entities or no entities</a></li>
56<li><a href="namespaces.html">Namespaces</a></li>
57<li><a href="upgrade.html">Upgrading 1.x code</a></li>
Daniel Veillard52dcab32001-10-30 12:51:17 +0000[diff] [blame]58<li><a href="threads.html">Thread safety</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]59<li><a href="DOM.html">DOM Principles</a></li>
60<li><a href="example.html">A real example</a></li>
61<li><a href="contribs.html">Contributions</a></li>
Daniel Veillard7b4b2f92003-01-06 13:11:20 +0000[diff] [blame]62<li><a href="xmlreader.html">The Reader Interface</a></li>
Daniel Veillardfc59c092002-06-05 14:48:26 +0000[diff] [blame]63<li><a href="tutorial/index.html">Tutorial</a></li>
Daniel Veillard7b4b2f92003-01-06 13:11:20 +0000[diff] [blame]64<li><a href="guidelines.html">XML Guidelines</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]65<li>
66<a href="xml.html">flat page</a>, <a href="site.xsl">stylesheet</a>
67</li>
Daniel Veillard5ede35e2002-10-01 11:37:35 +0000[diff] [blame]68</ul>
69</td></tr>
Daniel Veillard3bf65be2002-01-23 12:36:34 +0000[diff] [blame]70</table>
71<table width="100%" border="0" cellspacing="1" cellpadding="3">
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]72<tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr>
Daniel Veillard8acca112002-01-21 09:52:27 +0000[diff] [blame]73<tr><td bgcolor="#fffacd"><ul>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]74<li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li>
75<li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li>
Daniel Veillard4a859202002-01-08 11:49:22 +0000[diff] [blame]76<li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li>
Daniel Veillard2d347fa2002-03-17 10:34:11 +0000[diff] [blame]77<li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]78<li><a href="ftp://xmlsoft.org/">FTP</a></li>
Daniel Veillardc84f8b52002-12-19 22:12:47 +0000[diff] [blame]79<li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li>
Daniel Veillarddb9dfd92001-11-26 17:25:02 +0000[diff] [blame]80<li><a href="http://garypennington.net/libxml2/">Solaris binaries</a></li>
Daniel Veillardcb7543b2002-09-09 10:54:06 +0000[diff] [blame]81<li><a href="http://www.zveno.com/open_source/libxml2xslt.html">MacOsX binaries</a></li>
Daniel Veillarde6d8e202002-05-02 06:11:10 +0000[diff] [blame]82<li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li>
Daniel Veillard2d347fa2002-03-17 10:34:11 +0000[diff] [blame]83<li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml&amp;product=libxml2">Bug Tracker</a></li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]84</ul></td></tr>
85</table>
Daniel Veillard4a603e42003-01-11 14:18:53 +0000[diff] [blame]86<table width="100%" border="0" cellspacing="1" cellpadding="3">
87<tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>API Indexes</b></center></td></tr>
88<tr><td bgcolor="#fffacd"><ul>
89<li><a href="APIchunk0.html">Alphabetic</a></li>
90<li><a href="APIconstructors.html">Constructors</a></li>
91<li><a href="APIfunctions.html">Functions/Types</a></li>
92<li><a href="APIfiles.html">Modules</a></li>
93<li><a href="APIsymbols.html">Symbols</a></li>
94</ul></td></tr>
95</table>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]96</td></tr></table></td>
97<td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd">
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]98<p>Table of Content:</p>
99<ol>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]100<li><a href="General2">General overview</a></li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]101 <li><a href="#definition">The definition</a></li>
102 <li><a href="#Simple">Using catalogs</a></li>
103 <li><a href="#Some">Some examples</a></li>
104 <li><a href="#reference">How to tune catalog usage</a></li>
105 <li><a href="#validate">How to debug catalog processing</a></li>
106 <li><a href="#Declaring">How to create and maintain catalogs</a></li>
107 <li><a href="#implemento">The implementor corner quick review of the
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]108 API</a></li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]109 <li><a href="#Other">Other resources</a></li>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]110</ol>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]111<h3><a name="General2">General overview</a></h3>
112<p>What is a catalog? Basically it's a lookup mechanism used when an entity
113(a file or a remote resource) references another entity. The catalog lookup
114is inserted between the moment the reference is recognized by the software
115(XML parser, stylesheet processing, or even images referenced for inclusion
116in a rendering) and the time where loading that resource is actually
117started.</p>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]118<p>It is basically used for 3 things:</p>
119<ul>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]120<li>mapping from &quot;logical&quot; names, the public identifiers and a more
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]121 concrete name usable for download (and URI). For example it can associate
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]122 the logical name
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]123 <p>&quot;-//OASIS//DTD DocBook XML V4.1.2//EN&quot;</p>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]124 <p>of the DocBook 4.1.2 XML DTD with the actual URL where it can be
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]125 downloaded</p>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]126 <p>http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd</p>
127 </li>
128 <li>remapping from a given URL to another one, like an HTTP indirection
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]129 saying that
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]130 <p>&quot;http://www.oasis-open.org/committes/tr.xsl&quot;</p>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]131 <p>should really be looked at</p>
132 <p>&quot;http://www.oasis-open.org/committes/entity/stylesheets/base/tr.xsl&quot;</p>
133 </li>
134 <li>providing a local cache mechanism allowing to load the entities
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]135 associated to public identifiers or remote resources, this is a really
136 important feature for any significant deployment of XML or SGML since it
MDT 2001 John Fleck04685002001-09-03 16:11:47 +0000[diff] [blame]137 allows to avoid the aleas and delays associated to fetching remote
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]138 resources.</li>
139</ul>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]140<h3><a name="definition">The definitions</a></h3>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]141<p>Libxml, as of 2.4.3 implements 2 kind of catalogs:</p>
142<ul>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]143<li>the older SGML catalogs, the official spec is SGML Open Technical
144 Resolution TR9401:1997, but is better understood by reading <a href="http://www.jclark.com/sp/catalog.htm">the SP Catalog page</a> from
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]145 James Clark. This is relatively old and not the preferred mode of
146 operation of libxml.</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]147 <li>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]148<a href="http://www.oasis-open.org/committees/entity/spec.html">XML
Daniel Veillardaf43f632002-03-08 15:05:20 +0000[diff] [blame]149 Catalogs</a> is far more flexible, more recent, uses an XML syntax and
150 should scale quite better. This is the default option of libxml.</li>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]151</ul>
Daniel Veillard6581e1b2003-02-09 22:21:43 +0000[diff] [blame]152<p></p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]153<h3><a name="Simple">Using catalog</a></h3>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]154<p>In a normal environment libxml will by default check the presence of a
155catalog in /etc/xml/catalog, and assuming it has been correctly populated,
156the processing is completely transparent to the document user. To take a
157concrete example, suppose you are authoring a DocBook document, this one
158starts with the following DOCTYPE definition:</p>
159<pre>&lt;?xml version='1.0'?&gt;
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]160&lt;!DOCTYPE book PUBLIC &quot;-//Norman Walsh//DTD DocBk XML V3.1.4//EN&quot;
161 &quot;http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd&quot;&gt;</pre>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]162<p>When validating the document with libxml, the catalog will be
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]163automatically consulted to lookup the public identifier &quot;-//Norman Walsh//DTD
164DocBk XML V3.1.4//EN&quot; and the system identifier
165&quot;http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd&quot;, and if these entities have
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]166been installed on your system and the catalogs actually point to them, libxml
167will fetch them from the local disk.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]168<p style="font-size: 10pt">
169<strong>Note</strong>: Really don't use this
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]170DOCTYPE example it's a really old version, but is fine as an example.</p>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]171<p>Libxml will check the catalog each time that it is requested to load an
MDT 2001 John Fleck04685002001-09-03 16:11:47 +0000[diff] [blame]172entity, this includes DTD, external parsed entities, stylesheets, etc ... If
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]173your system is correctly configured all the authoring phase and processing
MDT 2001 John Fleck04685002001-09-03 16:11:47 +0000[diff] [blame]174should use only local files, even if your document stays portable because it
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]175uses the canonical public and system ID, referencing the remote document.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]176<h3><a name="Some">Some examples:</a></h3>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]177<p>Here is a couple of fragments from XML Catalogs used in libxml early
178regression tests in <code>test/catalogs</code> :</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]179<pre>&lt;?xml version=&quot;1.0&quot;?&gt;
180&lt;!DOCTYPE catalog PUBLIC
181 &quot;-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN&quot;
182 &quot;http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd&quot;&gt;
183&lt;catalog xmlns=&quot;urn:oasis:names:tc:entity:xmlns:xml:catalog&quot;&gt;
184 &lt;public publicId=&quot;-//OASIS//DTD DocBook XML V4.1.2//EN&quot;
185 uri=&quot;http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd&quot;/&gt;
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]186...</pre>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]187<p>This is the beginning of a catalog for DocBook 4.1.2, XML Catalogs are
188written in XML, there is a specific namespace for catalog elements
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]189&quot;urn:oasis:names:tc:entity:xmlns:xml:catalog&quot;. The first entry in this
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]190catalog is a <code>public</code> mapping it allows to associate a Public
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]191Identifier with an URI.</p>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]192<pre>...
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]193 &lt;rewriteSystem systemIdStartString=&quot;http://www.oasis-open.org/docbook/&quot;
194 rewritePrefix=&quot;file:///usr/share/xml/docbook/&quot;/&gt;
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]195...</pre>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]196<p>A <code>rewriteSystem</code> is a very powerful instruction, it says that
197any URI starting with a given prefix should be looked at another URI
198constructed by replacing the prefix with an new one. In effect this acts like
199a cache system for a full area of the Web. In practice it is extremely useful
200with a file prefix if you have installed a copy of those resources on your
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]201local system.</p>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]202<pre>...
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]203&lt;delegatePublic publicIdStartString=&quot;-//OASIS//DTD XML Catalog //&quot;
204 catalog=&quot;file:///usr/share/xml/docbook.xml&quot;/&gt;
205&lt;delegatePublic publicIdStartString=&quot;-//OASIS//ENTITIES DocBook XML&quot;
206 catalog=&quot;file:///usr/share/xml/docbook.xml&quot;/&gt;
207&lt;delegatePublic publicIdStartString=&quot;-//OASIS//DTD DocBook XML&quot;
208 catalog=&quot;file:///usr/share/xml/docbook.xml&quot;/&gt;
209&lt;delegateSystem systemIdStartString=&quot;http://www.oasis-open.org/docbook/&quot;
210 catalog=&quot;file:///usr/share/xml/docbook.xml&quot;/&gt;
211&lt;delegateURI uriStartString=&quot;http://www.oasis-open.org/docbook/&quot;
212 catalog=&quot;file:///usr/share/xml/docbook.xml&quot;/&gt;
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]213...</pre>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]214<p>Delegation is the core features which allows to build a tree of catalogs,
215easier to maintain than a single catalog, based on Public Identifier, System
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]216Identifier or URI prefixes it instructs the catalog software to look up
217entries in another resource. This feature allow to build hierarchies of
218catalogs, the set of entries presented should be sufficient to redirect the
219resolution of all DocBook references to the specific catalog in
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]220<code>/usr/share/xml/docbook.xml</code> this one in turn could delegate all
221references for DocBook 4.2.1 to a specific catalog installed at the same time
222as the DocBook resources on the local machine.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]223<h3><a name="reference">How to tune catalog usage:</a></h3>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]224<p>The user can change the default catalog behaviour by redirecting queries
225to its own set of catalogs, this can be done by setting the
226<code>XML_CATALOG_FILES</code> environment variable to a list of catalogs, an
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]227empty one should deactivate loading the default <code>/etc/xml/catalog</code>
228default catalog</p>
229<h3><a name="validate">How to debug catalog processing:</a></h3>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]230<p>Setting up the <code>XML_DEBUG_CATALOG</code> environment variable will
231make libxml output debugging informations for each catalog operations, for
232example:</p>
233<pre>orchis:~/XML -&gt; xmllint --memory --noout test/ent2
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]234warning: failed to load external entity &quot;title.xml&quot;
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]235orchis:~/XML -&gt; export XML_DEBUG_CATALOG=
236orchis:~/XML -&gt; xmllint --memory --noout test/ent2
237Failed to parse catalog /etc/xml/catalog
238Failed to parse catalog /etc/xml/catalog
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]239warning: failed to load external entity &quot;title.xml&quot;
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]240Catalogs cleanup
241orchis:~/XML -&gt; </pre>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]242<p>The test/ent2 references an entity, running the parser from memory makes
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]243the base URI unavailable and the the &quot;title.xml&quot; entity cannot be loaded.
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]244Setting up the debug environment variable allows to detect that an attempt is
245made to load the <code>/etc/xml/catalog</code> but since it's not present the
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]246resolution fails.</p>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]247<p>But the most advanced way to debug XML catalog processing is to use the
248<strong>xmlcatalog</strong> command shipped with libxml2, it allows to load
249catalogs and make resolution queries to see what is going on. This is also
250used for the regression tests:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]251<pre>orchis:~/XML -&gt; ./xmlcatalog test/catalogs/docbook.xml \
252 &quot;-//OASIS//DTD DocBook XML V4.1.2//EN&quot;
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]253http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
254orchis:~/XML -&gt; </pre>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]255<p>For debugging what is going on, adding one -v flags increase the verbosity
256level to indicate the processing done (adding a second flag also indicate
257what elements are recognized at parsing):</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]258<pre>orchis:~/XML -&gt; ./xmlcatalog -v test/catalogs/docbook.xml \
259 &quot;-//OASIS//DTD DocBook XML V4.1.2//EN&quot;
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]260Parsing catalog test/catalogs/docbook.xml's content
261Found public match -//OASIS//DTD DocBook XML V4.1.2//EN
262http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
263Catalogs cleanup
264orchis:~/XML -&gt; </pre>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]265<p>A shell interface is also available to debug and process multiple queries
266(and for regression tests):</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]267<pre>orchis:~/XML -&gt; ./xmlcatalog -shell test/catalogs/docbook.xml \
268 &quot;-//OASIS//DTD DocBook XML V4.1.2//EN&quot;
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]269&gt; help
270Commands available:
271public PublicID: make a PUBLIC identifier lookup
272system SystemID: make a SYSTEM identifier lookup
273resolve PublicID SystemID: do a full resolver lookup
274add 'type' 'orig' 'replace' : add an entry
275del 'values' : remove values
276dump: print the current catalog state
277debug: increase the verbosity level
278quiet: decrease the verbosity level
279exit: quit the shell
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]280&gt; public &quot;-//OASIS//DTD DocBook XML V4.1.2//EN&quot;
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]281http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
282&gt; quit
283orchis:~/XML -&gt; </pre>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]284<p>This should be sufficient for most debugging purpose, this was actually
MDT 2001 John Fleck04685002001-09-03 16:11:47 +0000[diff] [blame]285used heavily to debug the XML Catalog implementation itself.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]286<h3>
287<a name="Declaring">How to create and maintain</a> catalogs:</h3>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]288<p>Basically XML Catalogs are XML files, you can either use XML tools to
289manage them or use <strong>xmlcatalog</strong> for this. The basic step is
290to create a catalog the -create option provide this facility:</p>
291<pre>orchis:~/XML -&gt; ./xmlcatalog --create tst.xml
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]292&lt;?xml version=&quot;1.0&quot;?&gt;
293&lt;!DOCTYPE catalog PUBLIC &quot;-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN&quot;
294 &quot;http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd&quot;&gt;
295&lt;catalog xmlns=&quot;urn:oasis:names:tc:entity:xmlns:xml:catalog&quot;/&gt;
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]296orchis:~/XML -&gt; </pre>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]297<p>By default xmlcatalog does not overwrite the original catalog and save the
MDT 2001 John Fleck04685002001-09-03 16:11:47 +0000[diff] [blame]298result on the standard output, this can be overridden using the -noout
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]299option. The <code>-add</code> command allows to add entries in the
300catalog:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]301<pre>orchis:~/XML -&gt; ./xmlcatalog --noout --create --add &quot;public&quot; \
302 &quot;-//OASIS//DTD DocBook XML V4.1.2//EN&quot; \
303 http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd tst.xml
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]304orchis:~/XML -&gt; cat tst.xml
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]305&lt;?xml version=&quot;1.0&quot;?&gt;
306&lt;!DOCTYPE catalog PUBLIC &quot;-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN&quot; \
307 &quot;http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd&quot;&gt;
308&lt;catalog xmlns=&quot;urn:oasis:names:tc:entity:xmlns:xml:catalog&quot;&gt;
309&lt;public publicId=&quot;-//OASIS//DTD DocBook XML V4.1.2//EN&quot;
310 uri=&quot;http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd&quot;/&gt;
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]311&lt;/catalog&gt;
312orchis:~/XML -&gt; </pre>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]313<p>The <code>-add</code> option will always take 3 parameters even if some of
314the XML Catalog constructs (like nextCatalog) will have only a single
315argument, just pass a third empty string, it will be ignored.</p>
MDT 2001 John Fleck04685002001-09-03 16:11:47 +0000[diff] [blame]316<p>Similarly the <code>-del</code> option remove matching entries from the
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]317catalog:</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]318<pre>orchis:~/XML -&gt; ./xmlcatalog --del \
319 &quot;http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd&quot; tst.xml
320&lt;?xml version=&quot;1.0&quot;?&gt;
321&lt;!DOCTYPE catalog PUBLIC &quot;-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN&quot;
322 &quot;http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd&quot;&gt;
323&lt;catalog xmlns=&quot;urn:oasis:names:tc:entity:xmlns:xml:catalog&quot;/&gt;
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]324orchis:~/XML -&gt; </pre>
MDT 2001 John Fleck04685002001-09-03 16:11:47 +0000[diff] [blame]325<p>The catalog is now empty. Note that the matching of <code>-del</code> is
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]326exact and would have worked in a similar fashion with the Public ID
327string.</p>
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]328<p>This is rudimentary but should be sufficient to manage a not too complex
329catalog tree of resources.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]330<h3><a name="implemento">The implementor corner quick review of the
331API:</a></h3>
332<p>First, and like for every other module of libxml, there is an
333automatically generated <a href="html/libxml-catalog.html">API page for
334catalog support</a>.</p>
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]335<p>The header for the catalog interfaces should be included as:</p>
336<pre>#include &lt;libxml/catalog.h&gt;</pre>
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]337<p>The API is voluntarily kept very simple. First it is not obvious that
338applications really need access to it since it is the default behaviour of
339libxml (Note: it is possible to completely override libxml default catalog by
340using <a href="html/libxml-parser.html">xmlSetExternalEntityLoader</a> to
341plug an application specific resolver).</p>
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]342<p>Basically libxml support 2 catalog lists:</p>
343<ul>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]344<li>the default one, global shared by all the application</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]345 <li>a per-document catalog, this one is built if the document uses the
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]346 <code>oasis-xml-catalog</code> PIs to specify its own catalog list, it is
347 associated to the parser context and destroyed when the parsing context
348 is destroyed.</li>
349</ul>
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]350<p>the document one will be used first if it exists.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]351<h4>Initialization routines:</h4>
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]352<p>xmlInitializeCatalog(), xmlLoadCatalog() and xmlLoadCatalogs() should be
353used at startup to initialize the catalog, if the catalog should be
354initialized with specific values xmlLoadCatalog() or xmlLoadCatalogs()
355should be called before xmlInitializeCatalog() which would otherwise do a
356default initialization first.</p>
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]357<p>The xmlCatalogAddLocal() call is used by the parser to grow the document
358own catalog list if needed.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]359<h4>Preferences setup:</h4>
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]360<p>The XML Catalog spec requires the possibility to select default
361preferences between public and system delegation,
362xmlCatalogSetDefaultPrefer() allows this, xmlCatalogSetDefaults() and
363xmlCatalogGetDefaults() allow to control if XML Catalogs resolution should
364be forbidden, allowed for global catalog, for document catalog or both, the
365default is to allow both.</p>
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]366<p>And of course xmlCatalogSetDebug() allows to generate debug messages
367(through the xmlGenericError() mechanism).</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]368<h4>Querying routines:</h4>
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]369<p>xmlCatalogResolve(), xmlCatalogResolveSystem(), xmlCatalogResolvePublic()
370and xmlCatalogResolveURI() are relatively explicit if you read the XML
371Catalog specification they correspond to section 7 algorithms, they should
372also work if you have loaded an SGML catalog with a simplified semantic.</p>
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]373<p>xmlCatalogLocalResolve() and xmlCatalogLocalResolveURI() are the same but
374operate on the document catalog list</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]375<h4>Cleanup and Miscellaneous:</h4>
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]376<p>xmlCatalogCleanup() free-up the global catalog, xmlCatalogFreeLocal() is
377the per-document equivalent.</p>
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]378<p>xmlCatalogAdd() and xmlCatalogRemove() are used to dynamically modify the
379first catalog in the global list, and xmlCatalogDump() allows to dump a
380catalog state, those routines are primarily designed for xmlcatalog, I'm not
381sure that exposing more complex interfaces (like navigation ones) would be
382really useful.</p>
Daniel Veillard9f7b84b2001-08-23 15:31:19 +0000[diff] [blame]383<p>The xmlParseCatalogFile() is a function used to load XML Catalog files,
384it's similar as xmlParseFile() except it bypass all catalog lookups, it's
385provided because this functionality may be useful for client tools.</p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]386<h4>threaded environments:</h4>
Daniel Veillardffb120d2001-08-23 00:52:23 +0000[diff] [blame]387<p>Since the catalog tree is built progressively, some care has been taken to
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]388try to avoid troubles in multithreaded environments. The code is now thread
389safe assuming that the libxml library has been compiled with threads
390support.</p>
Daniel Veillard6581e1b2003-02-09 22:21:43 +0000[diff] [blame]391<p></p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]392<h3><a name="Other">Other resources</a></h3>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]393<p>The XML Catalog specification is relatively recent so there isn't much
MDT 2001 John Fleck04685002001-09-03 16:11:47 +0000[diff] [blame]394literature to point at:</p>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]395<ul>
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]396<li>You can find a good rant from Norm Walsh about <a href="http://www.arbortext.com/Think_Tank/XML_Resources/Issue_Three/issue_three.html">the
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]397 need for catalogs</a>, it provides a lot of context informations even if
Daniel Veillard93d3a472002-04-26 14:04:55 +0000[diff] [blame]398 I don't agree with everything presented. Norm also wrote a more recent
399 article <a href="http://wwws.sun.com/software/xml/developers/resolver/article/">XML
400 entities and URI resolvers</a> describing them.</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]401 <li>An <a href="http://home.ccil.org/~cowan/XML/XCatalog.html">old XML
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]402 catalog proposal</a> from John Cowan</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]403 <li>The <a href="http://www.rddl.org/">Resource Directory Description
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]404 Language</a> (RDDL) another catalog system but more oriented toward
405 providing metadata for XML namespaces.</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]406 <li>the page from the OASIS Technical <a href="http://www.oasis-open.org/committees/entity/">Committee on Entity
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]407 Resolution</a> who maintains XML Catalog, you will find pointers to the
408 specification update, some background and pointers to others tools
409 providing XML Catalog support</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]410 <li>Here is a <a href="buildDocBookCatalog">shell script</a> to generate
Daniel Veillard35e937a2002-01-19 22:21:54 +0000[diff] [blame]411 XML Catalogs for DocBook 4.1.2 . If it can write to the /etc/xml/
412 directory, it will set-up /etc/xml/catalog and /etc/xml/docbook based on
413 the resources found on the system. Otherwise it will just create
414 ~/xmlcatalog and ~/dbkxmlcatalog and doing:
Daniel Veillard8594de92003-04-25 10:08:44 +0000[diff] [blame^]415 <p><code>export XML_CATALOG_FILES=$HOME/xmlcatalog</code></p>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]416 <p>should allow to process DocBook documentations without requiring
Daniel Veillard63d83142002-05-20 06:51:05 +0000[diff] [blame]417 network accesses for the DTD or stylesheets</p>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]418 </li>
419 <li>I have uploaded <a href="ftp://xmlsoft.org/test/dbk412catalog.tar.gz">a
Daniel Veillard35e937a2002-01-19 22:21:54 +0000[diff] [blame]420 small tarball</a> containing XML Catalogs for DocBook 4.1.2 which seems
421 to work fine for me too</li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]422 <li>The <a href="http://www.xmlsoft.org/xmlcatalog_man.html">xmlcatalog
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]423 manual page</a>
424</li>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]425</ul>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]426<p>If you have suggestions for corrections or additions, simply contact
427me:</p>
Daniel Veillard3f4c40f2002-02-13 09:19:28 +0000[diff] [blame]428<p><a href="bugs.html">Daniel Veillard</a></p>
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]429</td></tr></table></td></tr></table></td></tr></table></td>
430</tr></table></td></tr></table>
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]431</body>
432</html>