catalog.html

libxml,在UNIX/LINUX下非常重要的一个库,为XML相关应用提供方便.目前上载的是最新版本,若要取得最新版本,请参考里面的readme.

orchis:~/XML -&gt; </pre><p>For debugging what is going on, adding one -v flags increase the verbosity
level to indicate the processing done (adding a second flag also indicate
what elements are recognized at parsing):</p><pre>orchis:~/XML -&gt; ./xmlcatalog -v test/catalogs/docbook.xml \
                   "-//OASIS//DTD DocBook XML V4.1.2//EN"
Parsing catalog test/catalogs/docbook.xml's content
Found public match -//OASIS//DTD DocBook XML V4.1.2//EN
http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
Catalogs cleanup
orchis:~/XML -&gt; </pre><p>A shell interface is also available to debug and process multiple queries
(and for regression tests):</p><pre>orchis:~/XML -&gt; ./xmlcatalog -shell test/catalogs/docbook.xml \
                   "-//OASIS//DTD DocBook XML V4.1.2//EN"
&gt; help   
Commands available:
public PublicID: make a PUBLIC identifier lookup
system SystemID: make a SYSTEM identifier lookup
resolve PublicID SystemID: do a full resolver lookup
add 'type' 'orig' 'replace' : add an entry
del 'values' : remove values
dump: print the current catalog state
debug: increase the verbosity level
quiet: decrease the verbosity level
exit:  quit the shell
&gt; public "-//OASIS//DTD DocBook XML V4.1.2//EN"
http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd
&gt; quit
orchis:~/XML -&gt; </pre><p>This should be sufficient for most debugging purpose, this was actually
used 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
manage them or use  <strong>xmlcatalog</strong> for this. The basic step is
to create a catalog the -create option provide this facility:</p><pre>orchis:~/XML -&gt; ./xmlcatalog --create tst.xml
&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
         "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"&gt;
&lt;catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"/&gt;
orchis:~/XML -&gt; </pre><p>By default xmlcatalog does not overwrite the original catalog and save the
result on the standard output, this can be overridden using the -noout
option. The <code>-add</code> command allows to add entries in the
catalog:</p><pre>orchis:~/XML -&gt; ./xmlcatalog --noout --create --add "public" \
  "-//OASIS//DTD DocBook XML V4.1.2//EN" \
  http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd tst.xml
orchis:~/XML -&gt; cat tst.xml
&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" \
  "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"&gt;
&lt;catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"&gt;
&lt;public publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
        uri="http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"/&gt;
&lt;/catalog&gt;
orchis:~/XML -&gt; </pre><p>The <code>-add</code> option will always take 3 parameters even if some of
the XML Catalog constructs (like nextCatalog) will have only a single
argument, just pass a third empty string, it will be ignored.</p><p>Similarly the <code>-del</code> option remove matching entries from the
catalog:</p><pre>orchis:~/XML -&gt; ./xmlcatalog --del \
  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" tst.xml
&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
    "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"&gt;
&lt;catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"/&gt;
orchis:~/XML -&gt; </pre><p>The catalog is now empty. Note that the matching of <code>-del</code> is
exact and would have worked in a similar fashion with the Public ID
string.</p><p>This is rudimentary but should be sufficient to manage a not too complex
catalog tree of resources.</p><h3><a name="implemento" id="implemento">The implementor corner quick review of the
API:</a></h3><p>First, and like for every other module of libxml, there is an
automatically generated <a href="html/libxml-catalog.html">API page for
catalog 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
applications really need access to it since it is the default behaviour of
libxml2 (Note: it is possible to completely override libxml2 default catalog
by using <a href="html/libxml-parser.html">xmlSetExternalEntityLoader</a> to
plug an application specific resolver).</p><p>Basically libxml2 support 2 catalog lists:</p><ul><li>the default one, global shared by all the application</li>
  <li>a per-document catalog, this one is built if the document uses the
    <code>oasis-xml-catalog</code> PIs to specify its own catalog list, it is
    associated to the parser context and destroyed when the parsing context
    is destroyed.</li>
</ul><p>the document one will be used first if it exists.</p><h4>Initialization routines:</h4><p>xmlInitializeCatalog(), xmlLoadCatalog() and xmlLoadCatalogs() should be
used at startup to initialize the catalog, if the catalog should be
initialized with specific values xmlLoadCatalog()  or xmlLoadCatalogs()
should be called before xmlInitializeCatalog() which would otherwise do a
default initialization first.</p><p>The xmlCatalogAddLocal() call is used by the parser to grow the document
own catalog list if needed.</p><h4>Preferences setup:</h4><p>The XML Catalog spec requires the possibility to select default
preferences between  public and system delegation,
xmlCatalogSetDefaultPrefer() allows this, xmlCatalogSetDefaults() and
xmlCatalogGetDefaults() allow to control  if XML Catalogs resolution should
be forbidden, allowed for global catalog, for document catalog or both, the
default is to allow both.</p><p>And of course xmlCatalogSetDebug() allows to generate debug messages
(through the xmlGenericError() mechanism).</p><h4>Querying routines:</h4><p>xmlCatalogResolve(), xmlCatalogResolveSystem(), xmlCatalogResolvePublic()
and xmlCatalogResolveURI() are relatively explicit if you read the XML
Catalog specification they correspond to section 7 algorithms, they should
also work if you have loaded an SGML catalog with a simplified semantic.</p><p>xmlCatalogLocalResolve() and xmlCatalogLocalResolveURI() are the same but
operate on the document catalog list</p><h4>Cleanup and Miscellaneous:</h4><p>xmlCatalogCleanup() free-up the global catalog, xmlCatalogFreeLocal() is
the per-document equivalent.</p><p>xmlCatalogAdd() and xmlCatalogRemove() are used to dynamically modify the
first catalog in the global list, and xmlCatalogDump() allows to dump a
catalog state, those routines are primarily designed for xmlcatalog, I'm not
sure that exposing more complex interfaces (like navigation ones) would be
really useful.</p><p>The xmlParseCatalogFile() is a function used to load XML Catalog files,
it's similar as xmlParseFile() except it bypass all catalog lookups, it's
provided 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
try to avoid troubles in multithreaded environments. The code is now thread
safe assuming that the libxml2 library has been compiled with threads
support.</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
literature to point at:</p><ul><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
    need for catalogs</a>, it provides a lot of context informations even if
    I don't agree with everything presented. Norm also wrote a more recent
    article <a href="http://wwws.sun.com/software/xml/developers/resolver/article/">XML
    entities and URI resolvers</a> describing them.</li>
  <li>An <a href="http://home.ccil.org/~cowan/XML/XCatalog.html">old XML
    catalog proposal</a> from John Cowan</li>
  <li>The <a href="http://www.rddl.org/">Resource Directory Description
    Language</a> (RDDL) another catalog system but more oriented toward
    providing metadata for XML namespaces.</li>
  <li>the page from the OASIS Technical <a href="http://www.oasis-open.org/committees/entity/">Committee on Entity
    Resolution</a> who maintains XML Catalog, you will find pointers to the
    specification update, some background and pointers to others tools
    providing XML Catalog support</li>
  <li>There is a <a href="buildDocBookCatalog">shell script</a> to generate
    XML Catalogs for DocBook 4.1.2 . If it can write to the /etc/xml/
    directory, it will set-up /etc/xml/catalog and /etc/xml/docbook based on
    the resources found on the system. Otherwise it will just create
    ~/xmlcatalog and ~/dbkxmlcatalog and doing:
    <p><code>export XML_CATALOG_FILES=$HOME/xmlcatalog</code></p>
    <p>should allow to process DocBook documentations without requiring
    network accesses for the DTD or stylesheets</p>
  </li>
  <li>I have uploaded <a href="ftp://xmlsoft.org/test/dbk412catalog.tar.gz">a
    small tarball</a> containing XML Catalogs for DocBook 4.1.2 which seems
    to work fine for me too</li>
  <li>The <a href="http://www.xmlsoft.org/xmlcatalog_man.html">xmlcatalog
    manual page</a></li>
</ul><p>If you have suggestions for corrections or additions, simply contact
me:</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>