libxml2/doc/catalog.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   5 <link rel="SHORTCUT ICON" href="/favicon.ico">
   6 <style type="text/css"><!--
   7 TD {font-family: Verdana,Arial,Helvetica}
   8 BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em}
   9 H1 {font-family: Verdana,Arial,Helvetica}
  10 H2 {font-family: Verdana,Arial,Helvetica}
  11 H3 {font-family: Verdana,Arial,Helvetica}
  12 A:link, A:visited, A:active { text-decoration: underline }
  13 --></style>
  14 <title>Catalog support</title>
  15 </head>
  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">
  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>
  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>
  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>
  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>
  43 <li><a href="XMLinfo.html">XML</a></li>
  44 <li><a href="XSLT.html">XSLT</a></li>
  45 <li><a href="python.html">Python and bindings</a></li>
  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>
  58 <li><a href="threads.html">Thread safety</a></li>
  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>
  62 <li><a href="xmlreader.html">The Reader Interface</a></li>
  63 <li><a href="tutorial/index.html">Tutorial</a></li>
  64 <li><a href="guidelines.html">XML Guidelines</a></li>
  65 <li>
  66 <a href="xml.html">flat page</a>, <a href="site.xsl">stylesheet</a>
  67 </li>
  68 </ul>
  69 </td></tr>
  70 </table>
  71 <table width="100%" border="0" cellspacing="1" cellpadding="3">
  72 <tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr>
  73 <tr><td bgcolor="#fffacd"><ul>
  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>
  76 <li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li>
  77 <li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li>
  78 <li><a href="ftp://xmlsoft.org/">FTP</a></li>
  79 <li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li>
  80 <li><a href="http://garypennington.net/libxml2/">Solaris binaries</a></li>
  81 <li><a href="http://www.zveno.com/open_source/libxml2xslt.html">MacOsX binaries</a></li>
  82 <li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li>
  83 <li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml&amp;product=libxml2">Bug Tracker</a></li>
  84 </ul></td></tr>
  85 </table>
  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>
  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">
  98 <p>Table of Content:</p>
  99 <ol>
 100 <li><a href="General2">General overview</a></li>
 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
 108   API</a></li>
 109   <li><a href="#Other">Other resources</a></li>
 110 </ol>
 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
 114 is inserted between the moment the reference is recognized by the software
 115 (XML parser, stylesheet processing, or even images referenced for inclusion
 116 in a rendering) and the time where loading that resource is actually
 117 started.</p>
 118 <p>It is basically used for 3 things:</p>
 119 <ul>
 120 <li>mapping from &quot;logical&quot; names, the public identifiers and a more
 121     concrete name usable for download (and URI). For example it can associate
 122     the logical name
 123     <p>&quot;-//OASIS//DTD DocBook XML V4.1.2//EN&quot;</p>
 124     <p>of the DocBook 4.1.2 XML DTD with the actual URL where it can be
 125     downloaded</p>
 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
 129     saying that
 130     <p>&quot;http://www.oasis-open.org/committes/tr.xsl&quot;</p>
 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
 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
 137     allows to avoid the aleas and delays associated to fetching remote
 138     resources.</li>
 139 </ul>
 140 <h3><a name="definition">The definitions</a></h3>
 141 <p>Libxml, as of 2.4.3 implements 2 kind of catalogs:</p>
 142 <ul>
 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
 145     James Clark. This is relatively old and not the preferred mode of
 146     operation of libxml.</li>
 147   <li>
 148 <a href="http://www.oasis-open.org/committees/entity/spec.html">XML
 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>
 151 </ul>
 152 <p></p>
 153 <h3><a name="Simple">Using catalog</a></h3>
 154 <p>In a normal environment libxml will by default check the presence of a
 155 catalog in /etc/xml/catalog, and assuming it has been correctly populated,
 156 the processing is completely transparent to the document user. To take a
 157 concrete example, suppose you are authoring a DocBook document, this one
 158 starts with the following DOCTYPE definition:</p>
 159 <pre>&lt;?xml version='1.0'?&gt;
 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>
 162 <p>When validating the document with libxml, the catalog will be
 163 automatically consulted to lookup the public identifier &quot;-//Norman Walsh//DTD
 164 DocBk 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
 166 been installed on your system and the catalogs actually point to them, libxml
 167 will fetch them from the local disk.</p>
 168 <p style="font-size: 10pt">
 169 <strong>Note</strong>: Really don't use this
 170 DOCTYPE example it's a really old version, but is fine as an example.</p>
 171 <p>Libxml will check the catalog each time that it is requested to load an
 172 entity, this includes DTD, external parsed entities, stylesheets, etc ... If
 173 your system is correctly configured all the authoring phase and processing
 174 should use only local files, even if your document stays portable because it
 175 uses the canonical public and system ID, referencing the remote document.</p>
 176 <h3><a name="Some">Some examples:</a></h3>
 177 <p>Here is a couple of fragments from XML Catalogs used in libxml early
 178 regression tests in <code>test/catalogs</code> :</p>
 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;
 186 ...</pre>
 187 <p>This is the beginning of a catalog for DocBook 4.1.2, XML Catalogs are
 188 written in XML,  there is a specific namespace for catalog elements
 189 &quot;urn:oasis:names:tc:entity:xmlns:xml:catalog&quot;. The first entry in this
 190 catalog is a <code>public</code> mapping it allows to associate a Public
 191 Identifier with an URI.</p>
 192 <pre>...
 193     &lt;rewriteSystem systemIdStartString=&quot;http://www.oasis-open.org/docbook/&quot;
 194                    rewritePrefix=&quot;file:///usr/share/xml/docbook/&quot;/&gt;
 195 ...</pre>
 196 <p>A <code>rewriteSystem</code> is a very powerful instruction, it says that
 197 any URI starting with a given prefix should be looked at another  URI
 198 constructed by replacing the prefix with an new one. In effect this acts like
 199 a cache system for a full area of the Web. In practice it is extremely useful
 200 with a file prefix if you have installed a copy of those resources on your
 201 local system.</p>
 202 <pre>...
 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;
 213 ...</pre>
 214 <p>Delegation is the core features which allows to build a tree of catalogs,
 215 easier to maintain than a single catalog, based on Public Identifier, System
 216 Identifier or URI prefixes it instructs the catalog software to look up
 217 entries in another resource. This feature allow to build hierarchies of
 218 catalogs, the set of entries presented should be sufficient to redirect the
 219 resolution of all DocBook references to the specific catalog in
 220 <code>/usr/share/xml/docbook.xml</code> this one in turn could delegate all
 221 references for DocBook 4.2.1 to a specific catalog installed at the same time
 222 as the DocBook resources on the local machine.</p>
 223 <h3><a name="reference">How to tune catalog usage:</a></h3>
 224 <p>The user can change the default catalog behaviour by redirecting queries
 225 to 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
 227 empty one should deactivate loading the default <code>/etc/xml/catalog</code>
 228 default catalog</p>
 229 <h3><a name="validate">How to debug catalog processing:</a></h3>
 230 <p>Setting up the <code>XML_DEBUG_CATALOG</code> environment variable will
 231 make libxml output debugging informations for each catalog operations, for
 232 example:</p>
 233 <pre>orchis:~/XML -&gt; xmllint --memory --noout test/ent2
 234 warning: failed to load external entity &quot;title.xml&quot;
 235 orchis:~/XML -&gt; export XML_DEBUG_CATALOG=
 236 orchis:~/XML -&gt; xmllint --memory --noout test/ent2
 237 Failed to parse catalog /etc/xml/catalog
 238 Failed to parse catalog /etc/xml/catalog
 239 warning: failed to load external entity &quot;title.xml&quot;
 240 Catalogs cleanup
 241 orchis:~/XML -&gt; </pre>
 242 <p>The test/ent2 references an entity, running the parser from memory makes
 243 the base URI unavailable and the the &quot;title.xml&quot; entity cannot be loaded.
 244 Setting up the debug environment variable allows to detect that an attempt is
 245 made to load the <code>/etc/xml/catalog</code> but since it's not present the
 246 resolution fails.</p>
 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
 249 catalogs and make resolution queries to see what is going on. This is also
 250 used for the regression tests:</p>
 251 <pre>orchis:~/XML -&gt; ./xmlcatalog test/catalogs/docbook.xml \
 252                    &quot;-//OASIS//DTD DocBook XML V4.1.2//EN&quot;
 253 http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
 254 orchis:~/XML -&gt; </pre>
 255 <p>For debugging what is going on, adding one -v flags increase the verbosity
 256 level to indicate the processing done (adding a second flag also indicate
 257 what elements are recognized at parsing):</p>
 258 <pre>orchis:~/XML -&gt; ./xmlcatalog -v test/catalogs/docbook.xml \
 259                    &quot;-//OASIS//DTD DocBook XML V4.1.2//EN&quot;
 260 Parsing catalog test/catalogs/docbook.xml's content
 261 Found public match -//OASIS//DTD DocBook XML V4.1.2//EN
 262 http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
 263 Catalogs cleanup
 264 orchis:~/XML -&gt; </pre>
 265 <p>A shell interface is also available to debug and process multiple queries
 266 (and for regression tests):</p>
 267 <pre>orchis:~/XML -&gt; ./xmlcatalog -shell test/catalogs/docbook.xml \
 268                    &quot;-//OASIS//DTD DocBook XML V4.1.2//EN&quot;
 269 &gt; help
 270 Commands available:
 271 public PublicID: make a PUBLIC identifier lookup
 272 system SystemID: make a SYSTEM identifier lookup
 273 resolve PublicID SystemID: do a full resolver lookup
 274 add 'type' 'orig' 'replace' : add an entry
 275 del 'values' : remove values
 276 dump: print the current catalog state
 277 debug: increase the verbosity level
 278 quiet: decrease the verbosity level
 279 exit:  quit the shell
 280 &gt; public &quot;-//OASIS//DTD DocBook XML V4.1.2//EN&quot;
 281 http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
 282 &gt; quit
 283 orchis:~/XML -&gt; </pre>
 284 <p>This should be sufficient for most debugging purpose, this was actually
 285 used heavily to debug the XML Catalog implementation itself.</p>
 286 <h3>
 287 <a name="Declaring">How to create and maintain</a> catalogs:</h3>
 288 <p>Basically XML Catalogs are XML files, you can either use XML tools to
 289 manage them or use  <strong>xmlcatalog</strong> for this. The basic step is
 290 to create a catalog the -create option provide this facility:</p>
 291 <pre>orchis:~/XML -&gt; ./xmlcatalog --create tst.xml
 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;
 296 orchis:~/XML -&gt; </pre>
 297 <p>By default xmlcatalog does not overwrite the original catalog and save the
 298 result on the standard output, this can be overridden using the -noout
 299 option. The <code>-add</code> command allows to add entries in the
 300 catalog:</p>
 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
 304 orchis:~/XML -&gt; cat tst.xml
 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;
 311 &lt;/catalog&gt;
 312 orchis:~/XML -&gt; </pre>
 313 <p>The <code>-add</code> option will always take 3 parameters even if some of
 314 the XML Catalog constructs (like nextCatalog) will have only a single
 315 argument, just pass a third empty string, it will be ignored.</p>
 316 <p>Similarly the <code>-del</code> option remove matching entries from the
 317 catalog:</p>
 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;
 324 orchis:~/XML -&gt; </pre>
 325 <p>The catalog is now empty. Note that the matching of <code>-del</code> is
 326 exact and would have worked in a similar fashion with the Public ID
 327 string.</p>
 328 <p>This is rudimentary but should be sufficient to manage a not too complex
 329 catalog tree of resources.</p>
 330 <h3><a name="implemento">The implementor corner quick review of the
 331 API:</a></h3>
 332 <p>First, and like for every other module of libxml, there is an
 333 automatically generated <a href="html/libxml-catalog.html">API page for
 334 catalog support</a>.</p>
 335 <p>The header for the catalog interfaces should be included as:</p>
 336 <pre>#include &lt;libxml/catalog.h&gt;</pre>
 337 <p>The API is voluntarily kept very simple. First it is not obvious that
 338 applications really need access to it since it is the default behaviour of
 339 libxml (Note: it is possible to completely override libxml default catalog by
 340 using <a href="html/libxml-parser.html">xmlSetExternalEntityLoader</a> to
 341 plug an application specific resolver).</p>
 342 <p>Basically libxml support 2 catalog lists:</p>
 343 <ul>
 344 <li>the default one, global shared by all the application</li>
 345   <li>a per-document catalog, this one is built if the document uses the
 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>
 350 <p>the document one will be used first if it exists.</p>
 351 <h4>Initialization routines:</h4>
 352 <p>xmlInitializeCatalog(), xmlLoadCatalog() and xmlLoadCatalogs() should be
 353 used at startup to initialize the catalog, if the catalog should be
 354 initialized with specific values xmlLoadCatalog()  or xmlLoadCatalogs()
 355 should be called before xmlInitializeCatalog() which would otherwise do a
 356 default initialization first.</p>
 357 <p>The xmlCatalogAddLocal() call is used by the parser to grow the document
 358 own catalog list if needed.</p>
 359 <h4>Preferences setup:</h4>
 360 <p>The XML Catalog spec requires the possibility to select default
 361 preferences between  public and system delegation,
 362 xmlCatalogSetDefaultPrefer() allows this, xmlCatalogSetDefaults() and
 363 xmlCatalogGetDefaults() allow to control  if XML Catalogs resolution should
 364 be forbidden, allowed for global catalog, for document catalog or both, the
 365 default is to allow both.</p>
 366 <p>And of course xmlCatalogSetDebug() allows to generate debug messages
 367 (through the xmlGenericError() mechanism).</p>
 368 <h4>Querying routines:</h4>
 369 <p>xmlCatalogResolve(), xmlCatalogResolveSystem(), xmlCatalogResolvePublic()
 370 and xmlCatalogResolveURI() are relatively explicit if you read the XML
 371 Catalog specification they correspond to section 7 algorithms, they should
 372 also work if you have loaded an SGML catalog with a simplified semantic.</p>
 373 <p>xmlCatalogLocalResolve() and xmlCatalogLocalResolveURI() are the same but
 374 operate on the document catalog list</p>
 375 <h4>Cleanup and Miscellaneous:</h4>
 376 <p>xmlCatalogCleanup() free-up the global catalog, xmlCatalogFreeLocal() is
 377 the per-document equivalent.</p>
 378 <p>xmlCatalogAdd() and xmlCatalogRemove() are used to dynamically modify the
 379 first catalog in the global list, and xmlCatalogDump() allows to dump a
 380 catalog state, those routines are primarily designed for xmlcatalog, I'm not
 381 sure that exposing more complex interfaces (like navigation ones) would be
 382 really useful.</p>
 383 <p>The xmlParseCatalogFile() is a function used to load XML Catalog files,
 384 it's similar as xmlParseFile() except it bypass all catalog lookups, it's
 385 provided because this functionality may be useful for client tools.</p>
 386 <h4>threaded environments:</h4>
 387 <p>Since the catalog tree is built progressively, some care has been taken to
 388 try to avoid troubles in multithreaded environments. The code is now thread
 389 safe assuming that the libxml library has been compiled with threads
 390 support.</p>
 391 <p></p>
 392 <h3><a name="Other">Other resources</a></h3>
 393 <p>The XML Catalog specification is relatively recent so there isn't much
 394 literature to point at:</p>
 395 <ul>
 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
 397     need for catalogs</a>, it provides a lot of context informations even if
 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>
 401   <li>An <a href="http://home.ccil.org/~cowan/XML/XCatalog.html">old XML
 402     catalog proposal</a> from John Cowan</li>
 403   <li>The <a href="http://www.rddl.org/">Resource Directory Description
 404     Language</a> (RDDL) another catalog system but more oriented toward
 405     providing metadata for XML namespaces.</li>
 406   <li>the page from the OASIS Technical <a href="http://www.oasis-open.org/committees/entity/">Committee on Entity
 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>
 410   <li>Here is a <a href="buildDocBookCatalog">shell script</a> to generate
 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:
 415     <p><code>export XMLCATALOG=$HOME/xmlcatalog</code></p>
 416     <p>should allow to process DocBook documentations without requiring
 417     network accesses for the DTD or stylesheets</p>
 418   </li>
 419   <li>I have uploaded <a href="ftp://xmlsoft.org/test/dbk412catalog.tar.gz">a
 420     small tarball</a> containing XML Catalogs for DocBook 4.1.2 which seems
 421     to work fine for me too</li>
 422   <li>The <a href="http://www.xmlsoft.org/xmlcatalog_man.html">xmlcatalog
 423     manual page</a>
 424 </li>
 425 </ul>
 426 <p>If you have suggestions for corrections or additions, simply contact
 427 me:</p>
 428 <p><a href="bugs.html">Daniel Veillard</a></p>
 429 </td></tr></table></td></tr></table></td></tr></table></td>
 430 </tr></table></td></tr></table>
 431 </body>
 432 </html>