📄 catalog.html
字号:
<?xml version="1.0" encoding="ISO-8859-1"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><link rel="SHORTCUT ICON" href="/favicon.ico" /><style type="text/css">TD {font-family: Verdana,Arial,Helvetica}BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em}H1 {font-family: Verdana,Arial,Helvetica}H2 {font-family: Verdana,Arial,Helvetica}H3 {font-family: Verdana,Arial,Helvetica}A:link, A:visited, A:active { text-decoration: underline }</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="http://xmlsoft.org/wiki">Wiki</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 & 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://www.blastwave.org/packages.php/libxml2">Solaris binaries</a></li><li><a href="http://www.zveno.com/open_source/libxml2xslt.html">MacOsX binaries</a></li><li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal 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><li><a href="General2">General overview</a></li> <li><a href="#definition">The definition</a></li> <li><a href="#Simple">Using catalogs</a></li> <li><a href="#Some">Some examples</a></li> <li><a href="#reference">How to tune catalog usage</a></li> <li><a href="#validate">How to debug catalog processing</a></li> <li><a href="#Declaring">How to create and maintain catalogs</a></li> <li><a href="#implemento">The implementor corner quick review of the API</a></li> <li><a href="#Other">Other resources</a></li></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(a file or a remote resource) references another entity. The catalog lookupis inserted between the moment the reference is recognized by the software(XML parser, stylesheet processing, or even images referenced for inclusionin a rendering) and the time where loading that resource is actuallystarted.</p><p>It is basically used for 3 things:</p><ul><li>mapping from "logical" names, the public identifiers and a more concrete name usable for download (and URI). For example it can associate the logical name <p>"-//OASIS//DTD DocBook XML V4.1.2//EN"</p> <p>of the DocBook 4.1.2 XML DTD with the actual URL where it can be downloaded</p> <p>http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd</p> </li> <li>remapping from a given URL to another one, like an HTTP indirection saying that <p>"http://www.oasis-open.org/committes/tr.xsl"</p> <p>should really be looked at</p> <p>"http://www.oasis-open.org/committes/entity/stylesheets/base/tr.xsl"</p> </li> <li>providing a local cache mechanism allowing to load the entities associated to public identifiers or remote resources, this is a really important feature for any significant deployment of XML or SGML since it allows to avoid the aleas and delays associated to fetching remote resources.</li></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><li>the older SGML catalogs, the official spec is SGML Open Technical Resolution TR9401:1997, but is better understood by reading <a href="http://www.jclark.com/sp/catalog.htm">the SP Catalog page</a> from James Clark. This is relatively old and not the preferred mode of operation of libxml.</li> <li><a href="http://www.oasis-open.org/committees/entity/spec.html">XML Catalogs</a> is far more flexible, more recent, uses an XML syntax and should scale quite better. This is the default option of libxml.</li></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 acatalog in /etc/xml/catalog, and assuming it has been correctly populated,the processing is completely transparent to the document user. To take aconcrete example, suppose you are authoring a DocBook document, this onestarts with the following DOCTYPE definition:</p><pre><?xml version='1.0'?><!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN" "http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd"></pre><p>When validating the document with libxml, the catalog will beautomatically consulted to lookup the public identifier "-//Norman Walsh//DTDDocBk XML V3.1.4//EN" and the system identifier"http://nwalsh.com/docbook/xml/3.1.4/db3xml.dtd", and if these entities havebeen installed on your system and the catalogs actually point to them, libxmlwill fetch them from the local disk.</p><p style="font-size: 10pt"><strong>Note</strong>: Really don't use thisDOCTYPE 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 anentity, this includes DTD, external parsed entities, stylesheets, etc ... Ifyour system is correctly configured all the authoring phase and processingshould use only local files, even if your document stays portable because ituses 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 earlyregression tests in <code>test/catalogs</code> :</p><pre><?xml version="1.0"?><!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"><catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> <public publicId="-//OASIS//DTD DocBook XML V4.1.2//EN" uri="http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"/>...</pre><p>This is the beginning of a catalog for DocBook 4.1.2, XML Catalogs arewritten in XML, there is a specific namespace for catalog elements"urn:oasis:names:tc:entity:xmlns:xml:catalog". The first entry in thiscatalog is a <code>public</code> mapping it allows to associate a PublicIdentifier with an URI.</p><pre>... <rewriteSystem systemIdStartString="http://www.oasis-open.org/docbook/" rewritePrefix="file:///usr/share/xml/docbook/"/>...</pre><p>A <code>rewriteSystem</code> is a very powerful instruction, it says thatany URI starting with a given prefix should be looked at another URIconstructed by replacing the prefix with an new one. In effect this acts likea cache system for a full area of the Web. In practice it is extremely usefulwith a file prefix if you have installed a copy of those resources on yourlocal system.</p><pre>...<delegatePublic publicIdStartString="-//OASIS//DTD XML Catalog //" catalog="file:///usr/share/xml/docbook.xml"/><delegatePublic publicIdStartString="-//OASIS//ENTITIES DocBook XML" catalog="file:///usr/share/xml/docbook.xml"/><delegatePublic publicIdStartString="-//OASIS//DTD DocBook XML" catalog="file:///usr/share/xml/docbook.xml"/><delegateSystem systemIdStartString="http://www.oasis-open.org/docbook/" catalog="file:///usr/share/xml/docbook.xml"/><delegateURI uriStartString="http://www.oasis-open.org/docbook/" catalog="file:///usr/share/xml/docbook.xml"/>...</pre><p>Delegation is the core features which allows to build a tree of catalogs,easier to maintain than a single catalog, based on Public Identifier, SystemIdentifier or URI prefixes it instructs the catalog software to look upentries in another resource. This feature allow to build hierarchies ofcatalogs, the set of entries presented should be sufficient to redirect theresolution of all DocBook references to the specific catalog in<code>/usr/share/xml/docbook.xml</code> this one in turn could delegate allreferences for DocBook 4.2.1 to a specific catalog installed at the same timeas 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 queriesto its own set of catalogs, this can be done by setting the<code>XML_CATALOG_FILES</code> environment variable to a list of catalogs, anempty one should deactivate loading the default <code>/etc/xml/catalog</code>default 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 willmake libxml2 output debugging informations for each catalog operations, forexample:</p><pre>orchis:~/XML -> xmllint --memory --noout test/ent2warning: failed to load external entity "title.xml"orchis:~/XML -> export XML_DEBUG_CATALOG=orchis:~/XML -> xmllint --memory --noout test/ent2Failed to parse catalog /etc/xml/catalogFailed to parse catalog /etc/xml/catalogwarning: failed to load external entity "title.xml"Catalogs cleanuporchis:~/XML -> </pre><p>The test/ent2 references an entity, running the parser from memory makesthe base URI unavailable and the the "title.xml" entity cannot be loaded.Setting up the debug environment variable allows to detect that an attempt ismade to load the <code>/etc/xml/catalog</code> but since it's not present theresolution fails.</p><p>But the most advanced way to debug XML catalog processing is to use the<strong>xmlcatalog</strong> command shipped with libxml2, it allows to loadcatalogs and make resolution queries to see what is going on. This is alsoused for the regression tests:</p><pre>orchis:~/XML -> ./xmlcatalog test/catalogs/docbook.xml \ "-//OASIS//DTD DocBook XML V4.1.2//EN"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -