-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"\r
- "http://www.w3.org/TR/html4/loose.dtd">\r
-<html>\r
-<head>\r
- <meta http-equiv="Content-Type" content="text/html">\r
- <style type="text/css"></style>\r
-<!--\r
-TD {font-family: Verdana,Arial,Helvetica}\r
-BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em}\r
-H1 {font-family: Verdana,Arial,Helvetica}\r
-H2 {font-family: Verdana,Arial,Helvetica}\r
-H3 {font-family: Verdana,Arial,Helvetica}\r
-A:link, A:visited, A:active { text-decoration: underline }\r
- </style>\r
--->\r
- <title>XML resources publication guidelines</title>\r
-</head>\r
-\r
-<body bgcolor="#fffacd" text="#000000">\r
-<h1 align="center">XML resources publication guidelines</h1>\r
-\r
-<p></p>\r
-\r
-<p>The goal of this document is to provide a set of guidelines and tips\r
-helping the publication and deployment of <a\r
-href="http://www.w3.org/XML/">XML</a> resources for the <a\r
-href="http://www.gnome.org/">GNOME project</a>. However it is not tied to\r
-GNOME and might be helpful more generally. I welcome <a\r
-href="mailto:veillard@redhat.com">feedback</a> on this document.</p>\r
-\r
-<p>The intended audience is the software developers who started using XML\r
-for some of the resources of their project, as a storage format, for data\r
-exchange, checking or transformations. There have been an increasing number\r
-of new XML formats defined, but not all steps have been taken, possibly because of\r
-lack of documentation, to truly gain all the benefits of the use of XML.\r
-These guidelines hope to improve the matter and provide a better overview of\r
-the overall XML processing and associated steps needed to deploy it\r
-successfully:</p>\r
-\r
-<p>Table of contents:</p>\r
-<ol>\r
- <li><a href="#Design">Design guidelines</a></li>\r
- <li><a href="#Canonical">Canonical URL</a></li>\r
- <li><a href="#Catalog">Catalog setup</a></li>\r
- <li><a href="#Package">Package integration</a></li>\r
-</ol>\r
-\r
-<h2><a name="Design">Design guidelines</a></h2>\r
-\r
-<p>This part intends to focus on the format itself of XML. It may arrive\r
-a bit too late since the structure of the document may already be cast in\r
-existing and deployed code. Still, here are a few rules which might be helpful\r
-when designing a new XML vocabulary or making the revision of an existing\r
-format:</p>\r
-\r
-<h3>Reuse existing formats:</h3>\r
-\r
-<p>This may sounds a bit simplistic, but before designing your own format,\r
-try to lookup existing XML vocabularies on similar data. Ideally this allows\r
-you to reuse them, in which case a lot of the existing tools like DTD, schemas\r
-and stylesheets may already be available. If you are looking at a\r
-documentation format, <a href="http://www.docbook.org/">DocBook</a> should\r
-handle your needs. If reuse is not possible because some semantic or use case\r
-aspects are too different this will be helpful avoiding design errors like\r
-targeting the vocabulary to the wrong abstraction level. In this format\r
-design phase try to be synthetic and be sure to express the real content of\r
-your data and use the XML structure to express the semantic and context of\r
-those data.</p>\r
-\r
-<h3>DTD rules:</h3>\r
-\r
-<p>Building a DTD (Document Type Definition) or a Schema describing the\r
-structure allowed by instances is the core of the design process of the\r
-vocabulary. Here are a few tips:</p>\r
-<ul>\r
- <li>use significant words for the element and attributes names.</li>\r
- <li>do not use attributes for general textual content, attributes\r
- will be modified by the parser before reaching the application,\r
- spaces and line informations will be modified.</li>\r
- <li>use single elements for every string that might be subject to\r
- localization. The canonical way to localize XML content is to use\r
- siblings element carrying different xml:lang attributes like in the\r
- following:\r
- <pre><welcome>\r
- <msg xml:lang="en">hello</msg>\r
- <msg xml:lang="fr">bonjour</msg>\r
-</welcome></pre>\r
- </li>\r
- <li>use attributes to refine the content of an element but avoid them for\r
- more complex tasks, attribute parsing is not cheaper than an element and\r
- it is far easier to make an element content more complex while attribute\r
- will have to remain very simple.</li>\r
-</ul>\r
-\r
-<h3>Versioning:</h3>\r
-\r
-<p>As part of the design, make sure the structure you define will be usable\r
-for future extension that you may not consider for the current version. There\r
-are two parts to this:</p>\r
-<ul>\r
- <li>Make sure the instance contains a version number which will allow to\r
- make backward compatibility easy. Something as simple as having a\r
- <code>version="1.0"</code> on the root document of the instance is\r
- sufficient.</li>\r
- <li>While designing the code doing the analysis of the data provided by the\r
- XML parser, make sure you can work with unknown versions, generate a UI\r
- warning and process only the tags recognized by your version but keep in\r
- mind that you should not break on unknown elements if the version\r
- attribute was not in the recognized set.</li>\r
-</ul>\r
-\r
-<h3>Other design parts:</h3>\r
-\r
-<p>While defining you vocabulary, try to think in term of other usage of your\r
-data, for example how using XSLT stylesheets could be used to make an HTML\r
-view of your data, or to convert it into a different format. Checking XML\r
-Schemas and looking at defining an XML Schema with a more complete\r
-validation and datatyping of your data structures is important, this helps\r
-avoiding some mistakes in the design phase.</p>\r
-\r
-<h3>Namespace:</h3>\r
-\r
-<p>If you expect your XML vocabulary to be used or recognized outside of your\r
-application (for example binding a specific processing from a graphic shell\r
-like Nautilus to an instance of your data) then you should really define an <a\r
-href="http://www.w3.org/TR/REC-xml-names/">XML namespace</a> for your\r
-vocabulary. A namespace name is an URL (absolute URI more precisely). It is\r
-generally recommended to anchor it as an HTTP resource to a server associated\r
-with the software project. See the next section about this. In practice this\r
-will mean that XML parsers will not handle your element names as-is but as a\r
-couple based on the namespace name and the element name. This allows it to\r
-recognize and disambiguate processing. Unicity of the namespace name can be\r
-for the most part guaranteed by the use of the DNS registry. Namespace can\r
-also be used to carry versioning information like:</p>\r
-\r
-<p><code>"http://www.gnome.org/project/projectname/1.0/"</code></p>\r
-\r
-<p>An easy way to use them is to make them the default namespace on the\r
-root element of the XML instance like:</p>\r
-<pre><structure xmlns="http://www.gnome.org/project/projectname/1.0/">\r
- <data>\r
- ...\r
- </data>\r
-</structure></pre>\r
-\r
-<p>In that document, structure and all descendant elements like data are in\r
-the given namespace.</p>\r
-\r
-<h2><a name="Canonical">Canonical URL</a></h2>\r
-\r
-<p>As seen in the previous namespace section, while XML processing is not\r
-tied to the Web there is a natural synergy between both. XML was designed to\r
-be available on the Web, and keeping the infrastructure that way helps\r
-deploying the XML resources. The core of this issue is the notion of\r
-"Canonical URL" of an XML resource. The resource can be an XML document, a\r
-DTD, a stylesheet, a schema, or even non-XML data associated with an XML\r
-resource, the canonical URL is the URL where the "master" copy of that\r
-resource is expected to be present on the Web. Usually when processing XML a\r
-copy of the resource will be present on the local disk, maybe in\r
-/usr/share/xml or /usr/share/sgml maybe in /opt or even on C:\projectname\\r
-(horror !). The key point is that the way to name that resource should be\r
-independent of the actual place where it resides on disk if it is available,\r
-and the fact that the processing will still work if there is no local copy\r
-(and that the machine where the processing is connected to the Internet).</p>\r
-\r
-<p>What this really means is that one should never use the local name of a\r
-resource to reference it but always use the canonical URL. For example in a\r
-DocBook instance the following should not be used:</p>\r
-<pre><!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"<br>\r
-\r
-\r
- "/usr/share/xml/docbook/4.2/docbookx.dtd"></pre>\r
-\r
-<p>But always reference the canonical URL for the DTD:</p>\r
-<pre><!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"<br>\r
-\r
-\r
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> </pre>\r
-\r
-<p>Similarly, the document instance may reference the <a\r
-href="http://www.w3.org/TR/xslt">XSLT</a> stylesheets needed to process it to\r
-generate HTML, and the canonical URL should be used:</p>\r
-<pre><?xml-stylesheet\r
- href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"\r
- type="text/xsl"?></pre>\r
-\r
-<p>Defining the canonical URL for the resources needed should obey a few\r
-simple rules similar to those used to design namespace names:</p>\r
-<ul>\r
- <li>use a DNS name you know is associated to the project and will be\r
- available on the long term</li>\r
- <li>within that server space, reserve the right to the subtree where you\r
- intend to keep those data</li>\r
- <li>version the URL so that multiple concurrent versions of the resources\r
- can be hosted simultaneously</li>\r
-</ul>\r
-\r
-<h2><a name="Catalog">Catalog setup</a></h2>\r
-\r
-<h3>How catalogs work:</h3>\r
-\r
-<p>The catalogs are the technical mechanism which allow the XML processing\r
-tools to use a local copy of the resources if it is available even if the\r
-instance document references the canonical URL. <a\r
-href="http://www.oasis-open.org/committees/entity/">XML Catalogs</a> are\r
-anchored in the root catalog (usually <code>/etc/xml/catalog</code> or\r
-defined by the user). They are a tree of XML documents defining the mappings\r
-between the canonical naming space and the local installed ones, this can be\r
-seen as a static cache structure.</p>\r
-\r
-<p>When the XML processor is asked to process a resource it will\r
-automatically test for a locally available version in the catalog, starting\r
-from the root catalog, and possibly fetching sub-catalog resources until it\r
-finds that the catalog has that resource or not. If not the default\r
-processing of fetching the resource from the Web is done, allowing in most\r
-case to recover from a catalog miss. The key point is that the document\r
-instances are totally independent of the availability of a catalog or from\r
-the actual place where the local resource they reference may be installed.\r
-This greatly improves the management of the documents in the long run, making\r
-them independent of the platform or toolchain used to process them. The\r
-figure below tries to express that mechanism:<img src="catalog.gif"\r
-alt="Picture describing the catalog "></p>\r
-\r
-<h3>Usual catalog setup:</h3>\r
-\r
-<p>Usually catalogs for a project are setup as a 2 level hierarchical cache,\r
-the root catalog containing only "delegates" indicating a separate subcatalog\r
-dedicated to the project. The goal is to keep the root catalog clean and\r
-simplify the maintenance of the catalog by using separate catalogs per\r
-project. For example when creating a catalog for the <a\r
-href="http://www.w3.org/TR/xhtml1">XHTML1</a> DTDs, only 3 items are added to\r
-the root catalog:</p>\r
-<pre> <delegatePublic publicIdStartString="-//W3C//DTD XHTML 1.0"\r
- catalog="file:///usr/share/sgml/xhtml1/xmlcatalog"/>\r
- <delegateSystem systemIdStartString="http://www.w3.org/TR/xhtml1/DTD"\r
- catalog="file:///usr/share/sgml/xhtml1/xmlcatalog"/>\r
- <delegateURI uriStartString="http://www.w3.org/TR/xhtml1/DTD"\r
- catalog="file:///usr/share/sgml/xhtml1/xmlcatalog"/></pre>\r
-\r
-<p>They are all "delegates" meaning that if the catalog system is asked to\r
-resolve a reference corresponding to them, it has to lookup a sub catalog.\r
-Here the subcatalog was installed as\r
-<code>/usr/share/sgml/xhtml1/xmlcatalog</code> in the local tree. That\r
-decision is left to the sysadmin or the packager for that system and may\r
-obey different rules, but the actual place on the filesystem (or on a\r
-resource cache on the local network) will not influence the processing as\r
-long as it is available. The first rule indicate that if the reference uses a\r
-PUBLIC identifier beginning with the</p>\r
-\r
-<p><code>"-//W3C//DTD XHTML 1.0"</code></p>\r
-\r
-<p>substring, then the catalog lookup should be limited to the specific given\r
-lookup catalog. Similarly the second and third entries indicate those\r
-delegation rules for SYSTEM, DOCTYPE or normal URI references when the URL\r
-starts with the <code>"http://www.w3.org/TR/xhtml1/DTD"</code> substring\r
-which indicates the location on the W3C server where the XHTML1 resources are\r
-stored. Those are the beginning of all Canonical URLs for XHTML1 resources.\r
-Those three rules are sufficient in practice to capture all references to XHTML1\r
-resources and direct the processing tools to the right subcatalog.</p>\r
-\r
-<h3>A subcatalog example:</h3>\r
-\r
-<p>Here is the complete subcatalog used for XHTML1:</p>\r
-<pre><?xml version="1.0"?>\r
-<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"\r
- "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">\r
-<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">\r
- <public publicId="-//W3C//DTD XHTML 1.0 Strict//EN"\r
- uri="xhtml1-20020801/DTD/xhtml1-strict.dtd"/>\r
- <public publicId="-//W3C//DTD XHTML 1.0 Transitional//EN"\r
- uri="xhtml1-20020801/DTD/xhtml1-transitional.dtd"/>\r
- <public publicId="-//W3C//DTD XHTML 1.0 Frameset//EN"\r
- uri="xhtml1-20020801/DTD/xhtml1-frameset.dtd"/>\r
- <rewriteSystem systemIdStartString="http://www.w3.org/TR/xhtml1/DTD"\r
- rewritePrefix="xhtml1-20020801/DTD"/>\r
- <rewriteURI uriStartString="http://www.w3.org/TR/xhtml1/DTD"\r
- rewritePrefix="xhtml1-20020801/DTD"/>\r
-</catalog></pre>\r
-\r
-<p>There are a few things to notice:</p>\r
-<ul>\r
- <li>this is an XML resource, it points to the DTD using Canonical URLs, the\r
- root element defines a namespace (but based on an URN not an HTTP\r
- URL).</li>\r
- <li>it contains 5 rules, the 3 first ones are direct mapping for the 3\r
- PUBLIC identifiers defined by the XHTML1 specification and associating\r
- them with the local resource containing the DTD, the 2 last ones are\r
- rewrite rules allowing to build the local filename for any URL based on\r
- "http://www.w3.org/TR/xhtml1/DTD", the local cache simplifies the rules by\r
- keeping the same structure as the on-line server at the Canonical URL</li>\r
- <li>the local resources are designated using URI references (the uri or\r
- rewritePrefix attributes), the base being the containing sub-catalog URL,\r
- which means that in practice the copy of the XHTML1 strict DTD is stored\r
- locally in\r
- <code>/usr/share/sgml/xhtml1/xmlcatalog/xhtml1-20020801/DTD/xhtml1-strict.dtd</code></li>\r
-</ul>\r
-\r
-<p>Those 5 rules are sufficient to cover all references to the resources held\r
-at the Canonical URL for the XHTML1 DTDs.</p>\r
-\r
-<h2><a name="Package">Package integration</a></h2>\r
-\r
-<p>Creating and removing catalogs should be handled as part of the process of\r
-(un)installing the local copy of the resources. The catalog files being XML\r
-resources should be processed with XML based tools to avoid problems with the\r
-generated files, the xmlcatalog command coming with libxml2 allows you to create\r
-catalogs, and add or remove rules at that time. Here is a complete example\r
-coming from the RPM for the XHTML1 DTDs post install script. While this example\r
-is platform and packaging specific, this can be useful as a an example in\r
-other contexts:</p>\r
-<pre>%post\r
-CATALOG=/usr/share/sgml/xhtml1/xmlcatalog\r
-#\r
-# Register it in the super catalog with the appropriate delegates\r
-#\r
-ROOTCATALOG=/etc/xml/catalog\r
-\r
-if [ ! -r $ROOTCATALOG ]\r
-then\r
- /usr/bin/xmlcatalog --noout --create $ROOTCATALOG\r
-fi\r
-\r
-if [ -w $ROOTCATALOG ]\r
-then\r
- /usr/bin/xmlcatalog --noout --add "delegatePublic" \\r
- "-//W3C//DTD XHTML 1.0" \\r
- "file://$CATALOG" $ROOTCATALOG\r
- /usr/bin/xmlcatalog --noout --add "delegateSystem" \\r
- "http://www.w3.org/TR/xhtml1/DTD" \\r
- "file://$CATALOG" $ROOTCATALOG\r
- /usr/bin/xmlcatalog --noout --add "delegateURI" \\r
- "http://www.w3.org/TR/xhtml1/DTD" \\r
- "file://$CATALOG" $ROOTCATALOG\r
-fi</pre>\r
-\r
-<p>The XHTML1 subcatalog is not created on-the-fly in that case, it is\r
-installed as part of the files of the packages. So the only work needed is to\r
-make sure the root catalog exists and register the delegate rules.</p>\r
-\r
-<p>Similarly, the script for the post-uninstall just remove the rules from the\r
-catalog:</p>\r
-<pre>%postun\r
-#\r
-# On removal, unregister the xmlcatalog from the supercatalog\r
-#\r
-if [ "$1" = 0 ]; then\r
- CATALOG=/usr/share/sgml/xhtml1/xmlcatalog\r
- ROOTCATALOG=/etc/xml/catalog\r
-\r
- if [ -w $ROOTCATALOG ]\r
- then\r
- /usr/bin/xmlcatalog --noout --del \\r
- "-//W3C//DTD XHTML 1.0" $ROOTCATALOG\r
- /usr/bin/xmlcatalog --noout --del \\r
- "http://www.w3.org/TR/xhtml1/DTD" $ROOTCATALOG\r
- /usr/bin/xmlcatalog --noout --del \\r
- "http://www.w3.org/TR/xhtml1/DTD" $ROOTCATALOG\r
- fi\r
-fi</pre>\r
-\r
-<p>Note the test against $1, this is needed to not remove the delegate rules\r
-in case of upgrade of the package.</p>\r
-\r
-<p>Following the set of guidelines and tips provided in this document should\r
-help deploy the XML resources in the GNOME framework without much pain and\r
-ensure a smooth evolution of the resource and instances.</p>\r
-\r
-<p><a href="mailto:veillard@redhat.com">Daniel Veillard</a></p>\r
-\r
-<p>$Id: guidelines.html,v 1.6 2004/12/26 21:01:48 veillard Exp $</p>\r
-\r
-<p></p>\r
-</body>\r
-</html>\r
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
+ "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html">
+ <style type="text/css"></style>
+<!--
+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>XML resources publication guidelines</title>
+</head>
+
+<body bgcolor="#fffacd" text="#000000">
+<h1 align="center">XML resources publication guidelines</h1>
+
+<p></p>
+
+<p>The goal of this document is to provide a set of guidelines and tips
+helping the publication and deployment of <a
+href="http://www.w3.org/XML/">XML</a> resources for the <a
+href="http://www.gnome.org/">GNOME project</a>. However it is not tied to
+GNOME and might be helpful more generally. I welcome <a
+href="mailto:veillard@redhat.com">feedback</a> on this document.</p>
+
+<p>The intended audience is the software developers who started using XML
+for some of the resources of their project, as a storage format, for data
+exchange, checking or transformations. There have been an increasing number
+of new XML formats defined, but not all steps have been taken, possibly because of
+lack of documentation, to truly gain all the benefits of the use of XML.
+These guidelines hope to improve the matter and provide a better overview of
+the overall XML processing and associated steps needed to deploy it
+successfully:</p>
+
+<p>Table of contents:</p>
+<ol>
+ <li><a href="#Design">Design guidelines</a></li>
+ <li><a href="#Canonical">Canonical URL</a></li>
+ <li><a href="#Catalog">Catalog setup</a></li>
+ <li><a href="#Package">Package integration</a></li>
+</ol>
+
+<h2><a name="Design">Design guidelines</a></h2>
+
+<p>This part intends to focus on the format itself of XML. It may arrive
+a bit too late since the structure of the document may already be cast in
+existing and deployed code. Still, here are a few rules which might be helpful
+when designing a new XML vocabulary or making the revision of an existing
+format:</p>
+
+<h3>Reuse existing formats:</h3>
+
+<p>This may sounds a bit simplistic, but before designing your own format,
+try to lookup existing XML vocabularies on similar data. Ideally this allows
+you to reuse them, in which case a lot of the existing tools like DTD, schemas
+and stylesheets may already be available. If you are looking at a
+documentation format, <a href="http://www.docbook.org/">DocBook</a> should
+handle your needs. If reuse is not possible because some semantic or use case
+aspects are too different this will be helpful avoiding design errors like
+targeting the vocabulary to the wrong abstraction level. In this format
+design phase try to be synthetic and be sure to express the real content of
+your data and use the XML structure to express the semantic and context of
+those data.</p>
+
+<h3>DTD rules:</h3>
+
+<p>Building a DTD (Document Type Definition) or a Schema describing the
+structure allowed by instances is the core of the design process of the
+vocabulary. Here are a few tips:</p>
+<ul>
+ <li>use significant words for the element and attributes names.</li>
+ <li>do not use attributes for general textual content, attributes
+ will be modified by the parser before reaching the application,
+ spaces and line informations will be modified.</li>
+ <li>use single elements for every string that might be subject to
+ localization. The canonical way to localize XML content is to use
+ siblings element carrying different xml:lang attributes like in the
+ following:
+ <pre><welcome>
+ <msg xml:lang="en">hello</msg>
+ <msg xml:lang="fr">bonjour</msg>
+</welcome></pre>
+ </li>
+ <li>use attributes to refine the content of an element but avoid them for
+ more complex tasks, attribute parsing is not cheaper than an element and
+ it is far easier to make an element content more complex while attribute
+ will have to remain very simple.</li>
+</ul>
+
+<h3>Versioning:</h3>
+
+<p>As part of the design, make sure the structure you define will be usable
+for future extension that you may not consider for the current version. There
+are two parts to this:</p>
+<ul>
+ <li>Make sure the instance contains a version number which will allow to
+ make backward compatibility easy. Something as simple as having a
+ <code>version="1.0"</code> on the root document of the instance is
+ sufficient.</li>
+ <li>While designing the code doing the analysis of the data provided by the
+ XML parser, make sure you can work with unknown versions, generate a UI
+ warning and process only the tags recognized by your version but keep in
+ mind that you should not break on unknown elements if the version
+ attribute was not in the recognized set.</li>
+</ul>
+
+<h3>Other design parts:</h3>
+
+<p>While defining you vocabulary, try to think in term of other usage of your
+data, for example how using XSLT stylesheets could be used to make an HTML
+view of your data, or to convert it into a different format. Checking XML
+Schemas and looking at defining an XML Schema with a more complete
+validation and datatyping of your data structures is important, this helps
+avoiding some mistakes in the design phase.</p>
+
+<h3>Namespace:</h3>
+
+<p>If you expect your XML vocabulary to be used or recognized outside of your
+application (for example binding a specific processing from a graphic shell
+like Nautilus to an instance of your data) then you should really define an <a
+href="http://www.w3.org/TR/REC-xml-names/">XML namespace</a> for your
+vocabulary. A namespace name is an URL (absolute URI more precisely). It is
+generally recommended to anchor it as an HTTP resource to a server associated
+with the software project. See the next section about this. In practice this
+will mean that XML parsers will not handle your element names as-is but as a
+couple based on the namespace name and the element name. This allows it to
+recognize and disambiguate processing. Unicity of the namespace name can be
+for the most part guaranteed by the use of the DNS registry. Namespace can
+also be used to carry versioning information like:</p>
+
+<p><code>"http://www.gnome.org/project/projectname/1.0/"</code></p>
+
+<p>An easy way to use them is to make them the default namespace on the
+root element of the XML instance like:</p>
+<pre><structure xmlns="http://www.gnome.org/project/projectname/1.0/">
+ <data>
+ ...
+ </data>
+</structure></pre>
+
+<p>In that document, structure and all descendant elements like data are in
+the given namespace.</p>
+
+<h2><a name="Canonical">Canonical URL</a></h2>
+
+<p>As seen in the previous namespace section, while XML processing is not
+tied to the Web there is a natural synergy between both. XML was designed to
+be available on the Web, and keeping the infrastructure that way helps
+deploying the XML resources. The core of this issue is the notion of
+"Canonical URL" of an XML resource. The resource can be an XML document, a
+DTD, a stylesheet, a schema, or even non-XML data associated with an XML
+resource, the canonical URL is the URL where the "master" copy of that
+resource is expected to be present on the Web. Usually when processing XML a
+copy of the resource will be present on the local disk, maybe in
+/usr/share/xml or /usr/share/sgml maybe in /opt or even on C:\projectname\
+(horror !). The key point is that the way to name that resource should be
+independent of the actual place where it resides on disk if it is available,
+and the fact that the processing will still work if there is no local copy
+(and that the machine where the processing is connected to the Internet).</p>
+
+<p>What this really means is that one should never use the local name of a
+resource to reference it but always use the canonical URL. For example in a
+DocBook instance the following should not be used:</p>
+<pre><!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"<br>
+
+
+ "/usr/share/xml/docbook/4.2/docbookx.dtd"></pre>
+
+<p>But always reference the canonical URL for the DTD:</p>
+<pre><!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"<br>
+
+
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> </pre>
+
+<p>Similarly, the document instance may reference the <a
+href="http://www.w3.org/TR/xslt">XSLT</a> stylesheets needed to process it to
+generate HTML, and the canonical URL should be used:</p>
+<pre><?xml-stylesheet
+ href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"
+ type="text/xsl"?></pre>
+
+<p>Defining the canonical URL for the resources needed should obey a few
+simple rules similar to those used to design namespace names:</p>
+<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> <delegatePublic publicIdStartString="-//W3C//DTD XHTML 1.0"
+ catalog="file:///usr/share/sgml/xhtml1/xmlcatalog"/>
+ <delegateSystem systemIdStartString="http://www.w3.org/TR/xhtml1/DTD"
+ catalog="file:///usr/share/sgml/xhtml1/xmlcatalog"/>
+ <delegateURI uriStartString="http://www.w3.org/TR/xhtml1/DTD"
+ catalog="file:///usr/share/sgml/xhtml1/xmlcatalog"/></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><?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="-//W3C//DTD XHTML 1.0 Strict//EN"
+ uri="xhtml1-20020801/DTD/xhtml1-strict.dtd"/>
+ <public publicId="-//W3C//DTD XHTML 1.0 Transitional//EN"
+ uri="xhtml1-20020801/DTD/xhtml1-transitional.dtd"/>
+ <public publicId="-//W3C//DTD XHTML 1.0 Frameset//EN"
+ uri="xhtml1-20020801/DTD/xhtml1-frameset.dtd"/>
+ <rewriteSystem systemIdStartString="http://www.w3.org/TR/xhtml1/DTD"
+ rewritePrefix="xhtml1-20020801/DTD"/>
+ <rewriteURI uriStartString="http://www.w3.org/TR/xhtml1/DTD"
+ rewritePrefix="xhtml1-20020801/DTD"/>
+</catalog></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:veillard@redhat.com">Daniel Veillard</a></p>
+
+<p>$Id: guidelines.html,v 1.6 2004/12/26 21:01:48 veillard Exp $</p>
+
+<p></p>
+</body>
+</html>
projects / reactos.git / blobdiff