guidelines.html

xml开源解析代码.版本为libxml2-2.6.29,可支持GB3212.网络消息发送XML时很有用.

<ul>
  <li>use a DNS name you know is associated to the project and will be
    available on the long term</li>
  <li>within that server space, reserve the right to the subtree where you
    intend to keep those data</li>
  <li>version the URL so that multiple concurrent versions of the resources
    can be hosted simultaneously</li>
</ul>

<h2><a name="Catalog">Catalog setup</a></h2>

<h3>How catalogs work:</h3>

<p>The catalogs are the technical mechanism which allow the XML processing
tools to use a local copy of the resources if it is available even if the
instance document references the canonical URL. <a
href="http://www.oasis-open.org/committees/entity/">XML Catalogs</a> are
anchored in the root catalog (usually <code>/etc/xml/catalog</code> or
defined by the user). They are a tree of XML documents defining the mappings
between the canonical naming space and the local installed ones, this can be
seen as a static cache structure.</p>

<p>When the XML processor is asked to process a resource it will
automatically test for a locally available version in the catalog, starting
from the root catalog, and possibly fetching sub-catalog resources until it
finds that the catalog has that resource or not. If not the default
processing of fetching the resource from the Web is done, allowing in most
case to recover from a catalog miss. The key point is that the document
instances are totally independent of the availability of a catalog or from
the actual place where the local resource they reference may be installed.
This greatly improves the management of the documents in the long run, making
them independent of the platform or toolchain used to process them. The
figure below tries to express that  mechanism:<img src="catalog.gif"
alt="Picture describing the catalog "></p>

<h3>Usual catalog setup:</h3>

<p>Usually catalogs for a project are setup as a 2 level hierarchical cache,
the root catalog containing only "delegates" indicating a separate subcatalog
dedicated to the project. The goal is to keep the root catalog clean and
simplify the maintenance of the catalog by using separate catalogs per
project. For example when creating a catalog for the <a
href="http://www.w3.org/TR/xhtml1">XHTML1</a> DTDs, only 3 items are added to
the root catalog:</p>
<pre>  &lt;delegatePublic publicIdStartString="-//W3C//DTD XHTML 1.0"
                  catalog="file:///usr/share/sgml/xhtml1/xmlcatalog"/&gt;
  &lt;delegateSystem systemIdStartString="http://www.w3.org/TR/xhtml1/DTD"
                  catalog="file:///usr/share/sgml/xhtml1/xmlcatalog"/&gt;
  &lt;delegateURI uriStartString="http://www.w3.org/TR/xhtml1/DTD"
                  catalog="file:///usr/share/sgml/xhtml1/xmlcatalog"/&gt;</pre>

<p>They are all "delegates" meaning that if the catalog system is asked to
resolve a reference corresponding to them, it has to lookup a sub catalog.
Here the subcatalog was installed as
<code>/usr/share/sgml/xhtml1/xmlcatalog</code> in the local tree. That
decision is left to the sysadmin or the packager for that system and may
obey different rules, but the actual place on the filesystem (or on a
resource cache on the local network) will not influence the processing as
long as it is available. The first rule indicate that if the reference uses a
PUBLIC identifier beginning with the</p>

<p><code>"-//W3C//DTD XHTML 1.0"</code></p>

<p>substring, then the catalog lookup should be limited to the specific given
lookup catalog. Similarly the second and third entries indicate those
delegation rules for SYSTEM, DOCTYPE or normal URI references when the URL
starts with the <code>"http://www.w3.org/TR/xhtml1/DTD"</code> substring
which indicates the location on the W3C server where the XHTML1 resources are
stored. Those are the beginning of all Canonical URLs for XHTML1 resources.
Those three rules are sufficient in practice to capture all references to XHTML1
resources and direct the processing tools to the right subcatalog.</p>

<h3>A subcatalog example:</h3>

<p>Here is the complete subcatalog used for XHTML1:</p>
<pre>&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="-//W3C//DTD XHTML 1.0 Strict//EN"
          uri="xhtml1-20020801/DTD/xhtml1-strict.dtd"/&gt;
  &lt;public publicId="-//W3C//DTD XHTML 1.0 Transitional//EN"
          uri="xhtml1-20020801/DTD/xhtml1-transitional.dtd"/&gt;
  &lt;public publicId="-//W3C//DTD XHTML 1.0 Frameset//EN"
          uri="xhtml1-20020801/DTD/xhtml1-frameset.dtd"/&gt;
  &lt;rewriteSystem systemIdStartString="http://www.w3.org/TR/xhtml1/DTD"
          rewritePrefix="xhtml1-20020801/DTD"/&gt;
  &lt;rewriteURI uriStartString="http://www.w3.org/TR/xhtml1/DTD"
          rewritePrefix="xhtml1-20020801/DTD"/&gt;
&lt;/catalog&gt;</pre>

<p>There are a few things to notice:</p>
<ul>
  <li>this is an XML resource, it points to the DTD using Canonical URLs, the
    root element defines a namespace (but based on an URN not an HTTP
  URL).</li>
  <li>it contains 5 rules, the 3 first ones are direct mapping for the 3
    PUBLIC identifiers defined by the XHTML1 specification and associating
    them with the local resource containing the DTD, the 2 last ones are
    rewrite rules allowing to build the local filename for any URL based on
    "http://www.w3.org/TR/xhtml1/DTD", the local cache simplifies the rules by
    keeping the same structure as the on-line server at the Canonical URL</li>
  <li>the local resources are designated using URI references (the uri or
    rewritePrefix attributes), the base being the containing sub-catalog URL,
    which means that in practice the copy of the XHTML1 strict DTD is stored
    locally in
    <code>/usr/share/sgml/xhtml1/xmlcatalog/xhtml1-20020801/DTD/xhtml1-strict.dtd</code></li>
</ul>

<p>Those 5 rules are sufficient to cover all references to the resources held
at the Canonical URL for the XHTML1 DTDs.</p>

<h2><a name="Package">Package integration</a></h2>

<p>Creating and removing catalogs should be handled as part of the process of
(un)installing the local copy of the resources. The catalog files being XML
resources should be processed with XML based tools to avoid problems with the
generated files, the xmlcatalog command coming with libxml2 allows you to create
catalogs, and add or remove rules at that time. Here is a complete example
coming from the RPM for the XHTML1 DTDs post install script. While this example
is platform and packaging specific, this can be useful as a an example in
other contexts:</p>
<pre>%post
CATALOG=/usr/share/sgml/xhtml1/xmlcatalog
#
# Register it in the super catalog with the appropriate delegates
#
ROOTCATALOG=/etc/xml/catalog

if [ ! -r $ROOTCATALOG ]
then
    /usr/bin/xmlcatalog --noout --create $ROOTCATALOG
fi

if [ -w $ROOTCATALOG ]
then
        /usr/bin/xmlcatalog --noout --add "delegatePublic" \
                "-//W3C//DTD XHTML 1.0" \
                "file://$CATALOG" $ROOTCATALOG
        /usr/bin/xmlcatalog --noout --add "delegateSystem" \
                "http://www.w3.org/TR/xhtml1/DTD" \
                "file://$CATALOG" $ROOTCATALOG
        /usr/bin/xmlcatalog --noout --add "delegateURI" \
                "http://www.w3.org/TR/xhtml1/DTD" \
                "file://$CATALOG" $ROOTCATALOG
fi</pre>

<p>The XHTML1 subcatalog is not created on-the-fly in that case, it is
installed as part of the files of the packages. So the only work needed is to
make sure the root catalog exists and register the delegate rules.</p>

<p>Similarly, the script for the post-uninstall just remove the rules from the
catalog:</p>
<pre>%postun
#
# On removal, unregister the xmlcatalog from the supercatalog
#
if [ "$1" = 0 ]; then
    CATALOG=/usr/share/sgml/xhtml1/xmlcatalog
    ROOTCATALOG=/etc/xml/catalog

    if [ -w $ROOTCATALOG ]
    then
            /usr/bin/xmlcatalog --noout --del \
                    "-//W3C//DTD XHTML 1.0" $ROOTCATALOG
            /usr/bin/xmlcatalog --noout --del \
                    "http://www.w3.org/TR/xhtml1/DTD" $ROOTCATALOG
            /usr/bin/xmlcatalog --noout --del \
                    "http://www.w3.org/TR/xhtml1/DTD" $ROOTCATALOG
    fi
fi</pre>

<p>Note the test against $1, this is needed to not remove the delegate rules
in case of upgrade of the package.</p>

<p>Following the set of guidelines and tips provided in this document should
help deploy the XML resources in the GNOME framework without much pain and
ensure a smooth evolution of the resource and instances.</p>

<p><a href="mailto:[e-mail]">Daniel Veillard</a></p>

<p>$Id: guidelines.html 2912 2004-12-26 21:01:48Z veillard $</p>

<p></p>
</body>
</html>