Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / libxml2 / b16cc96a8cd5ca92d61b336392f48f558a24f18b / . / doc / catalog.html
blob: 3d5bbe1c82972973f71edbf3d88979e7ae04cc83 [file] [log] [blame]
Daniel Veillardd2190fa2010-09-30 13:58:22 +0200[diff] [blame]1<?xml version="1.0" encoding="UTF-8"?>
Daniel Veillard1177ca42003-04-26 22:29:54 +0000[diff] [blame]2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Daniel Veillardd2190fa2010-09-30 13:58:22 +0200[diff] [blame]3<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><link rel="SHORTCUT ICON" href="/favicon.ico" /><style type="text/css">
Daniel Veillard373a4752002-02-21 14:46:29 +0000[diff] [blame]4TD {font-family: Verdana,Arial,Helvetica}
5BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em}
6H1 {font-family: Verdana,Arial,Helvetica}
7H2 {font-family: Verdana,Arial,Helvetica}
8H3 {font-family: Verdana,Arial,Helvetica}
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]9A:link, A:visited, A:active { text-decoration: underline }
Daniel Veillarde38217a2013-05-10 15:40:13 +0800[diff] [blame]10</style><title>Catalog support</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><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></td><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"><h1>The XML C parser and toolkit of Gnome</h1><h2>Catalog support</h2></td></tr></table></td></tr></table></td></tr></table><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><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html">Home</a></li><li><a href="html/index.html">Reference Manual</a></li><li><a href="intro.html">Introduction</a></li><li><a href="FAQ.html">FAQ</a></li><li><a href="docs.html" style="font-weight:bold">Developer Menu</a></li><li><a href="bugs.html">Reporting bugs and getting help</a></li><li><a href="help.html">How to help</a></li><li><a href="downloads.html">Downloads</a></li><li><a href="news.html">Releases</a></li><li><a href="XMLinfo.html">XML</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="xmldtd.html">Validation &amp; DTDs</a></li><li><a href="encoding.html">Encodings support</a></li><li><a href="catalog.html">Catalog support</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="contribs.html">Contributions</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="html/index.html" style="font-weight:bold">API Menu</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="ChangeLog.html">Recent Changes</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://opencsw.org/packages/libxml2">Solaris binaries</a></li><li><a href="http://www.explain.com.au/oss/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://lxml.de/">lxml Python bindings</a></li><li><a href="http://cpan.uwinnipeg.ca/dist/XML-LibXML">Perl bindings</a></li><li><a href="http://libxmlplusplus.sourceforge.net/">C++ bindings</a></li><li><a href="http://www.zend.com/php5/articles/php5-xmlphp.php#Heading4">PHP bindings</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li><li><a href="http://libxml.rubyforge.org/">Ruby bindings</a></li><li><a href="http://tclxml.sourceforge.net/">Tcl bindings</a></li><li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml2">Bug Tracker</a></li></ul></td></tr></table></td></tr></table></td><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"><p>Table of Content:</p><ol>
11 <li><a href="General2">General overview</a></li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]12 <li><a href="#definition">The definition</a></li>
13 <li><a href="#Simple">Using catalogs</a></li>
14 <li><a href="#Some">Some examples</a></li>
15 <li><a href="#reference">How to tune catalog usage</a></li>
16 <li><a href="#validate">How to debug catalog processing</a></li>
17 <li><a href="#Declaring">How to create and maintain catalogs</a></li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]18 <li><a href="#implemento">The implementor corner quick review of the
19 API</a></li>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]20 <li><a href="#Other">Other resources</a></li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]21</ol><h3><a name="General2" id="General2">General overview</a></h3><p>What is a catalog? Basically it's a lookup mechanism used when an entity
22(a file or a remote resource) references another entity. The catalog lookup
23is inserted between the moment the reference is recognized by the software
24(XML parser, stylesheet processing, or even images referenced for inclusion
25in a rendering) and the time where loading that resource is actually
Daniel Veillarde38217a2013-05-10 15:40:13 +0800[diff] [blame]26started.</p><p>It is basically used for 3 things:</p><ul>
27 <li>mapping from "logical" names, the public identifiers and a more
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]28 concrete name usable for download (and URI). For example it can associate
29 the logical name
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]30 <p>"-//OASIS//DTD DocBook XML V4.1.2//EN"</p>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]31 <p>of the DocBook 4.1.2 XML DTD with the actual URL where it can be
32 downloaded</p>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]33 <p>http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd</p>
34 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]35 <li>remapping from a given URL to another one, like an HTTP indirection
36 saying that
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]37 <p>"http://www.oasis-open.org/committes/tr.xsl"</p>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]38 <p>should really be looked at</p>
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]39 <p>"http://www.oasis-open.org/committes/entity/stylesheets/base/tr.xsl"</p>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]40 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]41 <li>providing a local cache mechanism allowing to load the entities
42 associated to public identifiers or remote resources, this is a really
43 important feature for any significant deployment of XML or SGML since it
44 allows to avoid the aleas and delays associated to fetching remote
45 resources.</li>
Daniel Veillarde38217a2013-05-10 15:40:13 +0800[diff] [blame]46</ul><h3><a name="definition" id="definition">The definitions</a></h3><p>Libxml, as of 2.4.3 implements 2 kind of catalogs:</p><ul>
47 <li>the older SGML catalogs, the official spec is SGML Open Technical
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]48 Resolution TR9401:1997, but is better understood by reading <a href="http://www.jclark.com/sp/catalog.htm">the SP Catalog page</a> from
49 James Clark. This is relatively old and not the preferred mode of
50 operation of libxml.</li>
51 <li><a href="http://www.oasis-open.org/committees/entity/spec.html">XML
52 Catalogs</a> is far more flexible, more recent, uses an XML syntax and
53 should scale quite better. This is the default option of libxml.</li>
54</ul><p></p><h3><a name="Simple" id="Simple">Using catalog</a></h3><p>In a normal environment libxml2 will by default check the presence of a
55catalog in /etc/xml/catalog, and assuming it has been correctly populated,
56the processing is completely transparent to the document user. To take a
57concrete example, suppose you are authoring a DocBook document, this one
58starts with the following DOCTYPE definition:</p><pre>&lt;?xml version='1.0'?&gt;
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]59&lt;!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]60 "http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd"&gt;</pre><p>When validating the document with libxml, the catalog will be
61automatically consulted to lookup the public identifier "-//Norman Walsh//DTD
62DocBk XML V3.1.4//EN" and the system identifier
63"http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd", and if these entities have
64been installed on your system and the catalogs actually point to them, libxml
65will fetch them from the local disk.</p><p style="font-size: 10pt"><strong>Note</strong>: Really don't use this
66DOCTYPE example it's a really old version, but is fine as an example.</p><p>Libxml2 will check the catalog each time that it is requested to load an
67entity, this includes DTD, external parsed entities, stylesheets, etc ... If
68your system is correctly configured all the authoring phase and processing
69should use only local files, even if your document stays portable because it
70uses the canonical public and system ID, referencing the remote document.</p><h3><a name="Some" id="Some">Some examples:</a></h3><p>Here is a couple of fragments from XML Catalogs used in libxml2 early
71regression tests in <code>test/catalogs</code> :</p><pre>&lt;?xml version="1.0"?&gt;
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]72&lt;!DOCTYPE catalog PUBLIC
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]73 "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
74 "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"&gt;
75&lt;catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"&gt;
76 &lt;public publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
77 uri="http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"/&gt;
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]78...</pre><p>This is the beginning of a catalog for DocBook 4.1.2, XML Catalogs are
79written in XML, there is a specific namespace for catalog elements
80"urn:oasis:names:tc:entity:xmlns:xml:catalog". The first entry in this
81catalog is a <code>public</code> mapping it allows to associate a Public
82Identifier with an URI.</p><pre>...
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]83 &lt;rewriteSystem systemIdStartString="http://www.oasis-open.org/docbook/"
84 rewritePrefix="file:///usr/share/xml/docbook/"/&gt;
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]85...</pre><p>A <code>rewriteSystem</code> is a very powerful instruction, it says that
86any URI starting with a given prefix should be looked at another URI
87constructed by replacing the prefix with an new one. In effect this acts like
88a cache system for a full area of the Web. In practice it is extremely useful
89with a file prefix if you have installed a copy of those resources on your
90local system.</p><pre>...
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]91&lt;delegatePublic publicIdStartString="-//OASIS//DTD XML Catalog //"
92 catalog="file:///usr/share/xml/docbook.xml"/&gt;
93&lt;delegatePublic publicIdStartString="-//OASIS//ENTITIES DocBook XML"
94 catalog="file:///usr/share/xml/docbook.xml"/&gt;
95&lt;delegatePublic publicIdStartString="-//OASIS//DTD DocBook XML"
96 catalog="file:///usr/share/xml/docbook.xml"/&gt;
97&lt;delegateSystem systemIdStartString="http://www.oasis-open.org/docbook/"
98 catalog="file:///usr/share/xml/docbook.xml"/&gt;
99&lt;delegateURI uriStartString="http://www.oasis-open.org/docbook/"
100 catalog="file:///usr/share/xml/docbook.xml"/&gt;
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]101...</pre><p>Delegation is the core features which allows to build a tree of catalogs,
102easier to maintain than a single catalog, based on Public Identifier, System
103Identifier or URI prefixes it instructs the catalog software to look up
104entries in another resource. This feature allow to build hierarchies of
105catalogs, the set of entries presented should be sufficient to redirect the
106resolution of all DocBook references to the specific catalog in
107<code>/usr/share/xml/docbook.xml</code> this one in turn could delegate all
108references for DocBook 4.2.1 to a specific catalog installed at the same time
109as the DocBook resources on the local machine.</p><h3><a name="reference" id="reference">How to tune catalog usage:</a></h3><p>The user can change the default catalog behaviour by redirecting queries
110to its own set of catalogs, this can be done by setting the
111<code>XML_CATALOG_FILES</code> environment variable to a list of catalogs, an
112empty one should deactivate loading the default <code>/etc/xml/catalog</code>
113default catalog</p><h3><a name="validate" id="validate">How to debug catalog processing:</a></h3><p>Setting up the <code>XML_DEBUG_CATALOG</code> environment variable will
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]114make libxml2 output debugging information for each catalog operations, for
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]115example:</p><pre>orchis:~/XML -&gt; xmllint --memory --noout test/ent2
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]116warning: failed to load external entity "title.xml"
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]117orchis:~/XML -&gt; export XML_DEBUG_CATALOG=
118orchis:~/XML -&gt; xmllint --memory --noout test/ent2
119Failed to parse catalog /etc/xml/catalog
120Failed to parse catalog /etc/xml/catalog
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]121warning: failed to load external entity "title.xml"
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]122Catalogs cleanup
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]123orchis:~/XML -&gt; </pre><p>The test/ent2 references an entity, running the parser from memory makes
124the base URI unavailable and the the "title.xml" entity cannot be loaded.
125Setting up the debug environment variable allows to detect that an attempt is
126made to load the <code>/etc/xml/catalog</code> but since it's not present the
127resolution fails.</p><p>But the most advanced way to debug XML catalog processing is to use the
128<strong>xmlcatalog</strong> command shipped with libxml2, it allows to load
129catalogs and make resolution queries to see what is going on. This is also
130used for the regression tests:</p><pre>orchis:~/XML -&gt; ./xmlcatalog test/catalogs/docbook.xml \
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]131 "-//OASIS//DTD DocBook XML V4.1.2//EN"
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]132http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]133orchis:~/XML -&gt; </pre><p>For debugging what is going on, adding one -v flags increase the verbosity
134level to indicate the processing done (adding a second flag also indicate
135what elements are recognized at parsing):</p><pre>orchis:~/XML -&gt; ./xmlcatalog -v test/catalogs/docbook.xml \
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]136 "-//OASIS//DTD DocBook XML V4.1.2//EN"
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]137Parsing catalog test/catalogs/docbook.xml's content
138Found public match -//OASIS//DTD DocBook XML V4.1.2//EN
139http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
140Catalogs cleanup
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]141orchis:~/XML -&gt; </pre><p>A shell interface is also available to debug and process multiple queries
142(and for regression tests):</p><pre>orchis:~/XML -&gt; ./xmlcatalog -shell test/catalogs/docbook.xml \
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]143 "-//OASIS//DTD DocBook XML V4.1.2//EN"
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]144&gt; help
145Commands available:
146public PublicID: make a PUBLIC identifier lookup
147system SystemID: make a SYSTEM identifier lookup
148resolve PublicID SystemID: do a full resolver lookup
149add 'type' 'orig' 'replace' : add an entry
150del 'values' : remove values
151dump: print the current catalog state
152debug: increase the verbosity level
153quiet: decrease the verbosity level
154exit: quit the shell
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]155&gt; public "-//OASIS//DTD DocBook XML V4.1.2//EN"
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]156http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
157&gt; quit
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]158orchis:~/XML -&gt; </pre><p>This should be sufficient for most debugging purpose, this was actually
159used heavily to debug the XML Catalog implementation itself.</p><h3><a name="Declaring" id="Declaring">How to create and maintain</a> catalogs:</h3><p>Basically XML Catalogs are XML files, you can either use XML tools to
160manage them or use <strong>xmlcatalog</strong> for this. The basic step is
161to create a catalog the -create option provide this facility:</p><pre>orchis:~/XML -&gt; ./xmlcatalog --create tst.xml
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]162&lt;?xml version="1.0"?&gt;
163&lt;!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
164 "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"&gt;
165&lt;catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"/&gt;
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]166orchis:~/XML -&gt; </pre><p>By default xmlcatalog does not overwrite the original catalog and save the
167result on the standard output, this can be overridden using the -noout
168option. The <code>-add</code> command allows to add entries in the
169catalog:</p><pre>orchis:~/XML -&gt; ./xmlcatalog --noout --create --add "public" \
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]170 "-//OASIS//DTD DocBook XML V4.1.2//EN" \
Daniel Veillardb8cfbd12001-10-25 10:53:28 +0000[diff] [blame]171 http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd tst.xml
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]172orchis:~/XML -&gt; cat tst.xml
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]173&lt;?xml version="1.0"?&gt;
174&lt;!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" \
175 "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"&gt;
176&lt;catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"&gt;
177&lt;public publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
178 uri="http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"/&gt;
Daniel Veillarde7ead2d2001-08-22 23:44:09 +0000[diff] [blame]179&lt;/catalog&gt;
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]180orchis:~/XML -&gt; </pre><p>The <code>-add</code> option will always take 3 parameters even if some of
181the XML Catalog constructs (like nextCatalog) will have only a single
182argument, just pass a third empty string, it will be ignored.</p><p>Similarly the <code>-del</code> option remove matching entries from the
183catalog:</p><pre>orchis:~/XML -&gt; ./xmlcatalog --del \
Daniel Veillard024f1992003-12-10 16:43:49 +0000[diff] [blame]184 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" tst.xml
185&lt;?xml version="1.0"?&gt;
186&lt;!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
187 "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"&gt;
188&lt;catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"/&gt;
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]189orchis:~/XML -&gt; </pre><p>The catalog is now empty. Note that the matching of <code>-del</code> is
190exact and would have worked in a similar fashion with the Public ID
191string.</p><p>This is rudimentary but should be sufficient to manage a not too complex
192catalog tree of resources.</p><h3><a name="implemento" id="implemento">The implementor corner quick review of the
193API:</a></h3><p>First, and like for every other module of libxml, there is an
194automatically generated <a href="html/libxml-catalog.html">API page for
195catalog support</a>.</p><p>The header for the catalog interfaces should be included as:</p><pre>#include &lt;libxml/catalog.h&gt;</pre><p>The API is voluntarily kept very simple. First it is not obvious that
196applications really need access to it since it is the default behaviour of
197libxml2 (Note: it is possible to completely override libxml2 default catalog
198by using <a href="html/libxml-parser.html">xmlSetExternalEntityLoader</a> to
Daniel Veillarde38217a2013-05-10 15:40:13 +0800[diff] [blame]199plug an application specific resolver).</p><p>Basically libxml2 support 2 catalog lists:</p><ul>
200 <li>the default one, global shared by all the application</li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]201 <li>a per-document catalog, this one is built if the document uses the
202 <code>oasis-xml-catalog</code> PIs to specify its own catalog list, it is
203 associated to the parser context and destroyed when the parsing context
204 is destroyed.</li>
205</ul><p>the document one will be used first if it exists.</p><h4>Initialization routines:</h4><p>xmlInitializeCatalog(), xmlLoadCatalog() and xmlLoadCatalogs() should be
206used at startup to initialize the catalog, if the catalog should be
207initialized with specific values xmlLoadCatalog() or xmlLoadCatalogs()
208should be called before xmlInitializeCatalog() which would otherwise do a
209default initialization first.</p><p>The xmlCatalogAddLocal() call is used by the parser to grow the document
210own catalog list if needed.</p><h4>Preferences setup:</h4><p>The XML Catalog spec requires the possibility to select default
211preferences between public and system delegation,
212xmlCatalogSetDefaultPrefer() allows this, xmlCatalogSetDefaults() and
213xmlCatalogGetDefaults() allow to control if XML Catalogs resolution should
214be forbidden, allowed for global catalog, for document catalog or both, the
215default is to allow both.</p><p>And of course xmlCatalogSetDebug() allows to generate debug messages
216(through the xmlGenericError() mechanism).</p><h4>Querying routines:</h4><p>xmlCatalogResolve(), xmlCatalogResolveSystem(), xmlCatalogResolvePublic()
217and xmlCatalogResolveURI() are relatively explicit if you read the XML
218Catalog specification they correspond to section 7 algorithms, they should
219also work if you have loaded an SGML catalog with a simplified semantic.</p><p>xmlCatalogLocalResolve() and xmlCatalogLocalResolveURI() are the same but
220operate on the document catalog list</p><h4>Cleanup and Miscellaneous:</h4><p>xmlCatalogCleanup() free-up the global catalog, xmlCatalogFreeLocal() is
221the per-document equivalent.</p><p>xmlCatalogAdd() and xmlCatalogRemove() are used to dynamically modify the
222first catalog in the global list, and xmlCatalogDump() allows to dump a
223catalog state, those routines are primarily designed for xmlcatalog, I'm not
224sure that exposing more complex interfaces (like navigation ones) would be
225really useful.</p><p>The xmlParseCatalogFile() is a function used to load XML Catalog files,
226it's similar as xmlParseFile() except it bypass all catalog lookups, it's
227provided because this functionality may be useful for client tools.</p><h4>threaded environments:</h4><p>Since the catalog tree is built progressively, some care has been taken to
228try to avoid troubles in multithreaded environments. The code is now thread
229safe assuming that the libxml2 library has been compiled with threads
230support.</p><p></p><h3><a name="Other" id="Other">Other resources</a></h3><p>The XML Catalog specification is relatively recent so there isn't much
Daniel Veillarde38217a2013-05-10 15:40:13 +0800[diff] [blame]231literature to point at:</p><ul>
232 <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
William M. Brack43a87292007-02-15 20:41:02 +0000[diff] [blame]233 need for catalogs</a>, it provides a lot of context information even if
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]234 I don't agree with everything presented. Norm also wrote a more recent
235 article <a href="http://wwws.sun.com/software/xml/developers/resolver/article/">XML
236 entities and URI resolvers</a> describing them.</li>
237 <li>An <a href="http://home.ccil.org/~cowan/XML/XCatalog.html">old XML
238 catalog proposal</a> from John Cowan</li>
239 <li>The <a href="http://www.rddl.org/">Resource Directory Description
240 Language</a> (RDDL) another catalog system but more oriented toward
241 providing metadata for XML namespaces.</li>
242 <li>the page from the OASIS Technical <a href="http://www.oasis-open.org/committees/entity/">Committee on Entity
243 Resolution</a> who maintains XML Catalog, you will find pointers to the
244 specification update, some background and pointers to others tools
245 providing XML Catalog support</li>
246 <li>There is a <a href="buildDocBookCatalog">shell script</a> to generate
247 XML Catalogs for DocBook 4.1.2 . If it can write to the /etc/xml/
248 directory, it will set-up /etc/xml/catalog and /etc/xml/docbook based on
249 the resources found on the system. Otherwise it will just create
250 ~/xmlcatalog and ~/dbkxmlcatalog and doing:
Daniel Veillard8594de92003-04-25 10:08:44 +0000[diff] [blame]251 <p><code>export XML_CATALOG_FILES=$HOME/xmlcatalog</code></p>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]252 <p>should allow to process DocBook documentations without requiring
253 network accesses for the DTD or stylesheets</p>
Daniel Veillard0b28e882002-07-24 23:47:05 +0000[diff] [blame]254 </li>
Daniel Veillardf781dba2006-06-09 13:34:49 +0000[diff] [blame]255 <li>I have uploaded <a href="ftp://xmlsoft.org/libxml2/test/dbk412catalog.tar.gz">a
256 small tarball</a> containing XML Catalogs for DocBook 4.1.2 which seems
257 to work fine for me too</li>
258 <li>The <a href="http://www.xmlsoft.org/xmlcatalog_man.html">xmlcatalog
259 manual page</a></li>
260</ul><p>If you have suggestions for corrections or additions, simply contact
261me:</p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>