📄 guidelines.html
字号:
<!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 tipshelping the publication and deployment of <ahref="http://www.w3.org/XML/">XML</a> resources for the <ahref="http://www.gnome.org/">GNOME project</a>. However it is not tied toGNOME and might be helpful more generally. I welcome <ahref="mailto:veillard@redhat.com">feedback</a> on this document.</p><p>The intended audience is the software developers who started using XMLfor some of the resources of their project, as a storage format, for dataexchange, checking or transformations. There have been an increasing numberof new XML formats defined, but not all steps have been taken, possibly because oflack 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 ofthe overall XML processing and associated steps needed to deploy itsuccessfully:</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 arrivea bit too late since the structure of the document may already be cast inexisting and deployed code. Still, here are a few rules which might be helpfulwhen designing a new XML vocabulary or making the revision of an existingformat:</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 allowsyou to reuse them, in which case a lot of the existing tools like DTD, schemasand stylesheets may already be available. If you are looking at adocumentation format, <a href="http://www.docbook.org/">DocBook</a> shouldhandle your needs. If reuse is not possible because some semantic or use caseaspects are too different this will be helpful avoiding design errors liketargeting the vocabulary to the wrong abstraction level. In this formatdesign phase try to be synthetic and be sure to express the real content ofyour data and use the XML structure to express the semantic and context ofthose data.</p><h3>DTD rules:</h3><p>Building a DTD (Document Type Definition) or a Schema describing thestructure allowed by instances is the core of the design process of thevocabulary. 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 usablefor future extension that you may not consider for the current version. Thereare 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 yourdata, for example how using XSLT stylesheets could be used to make an HTMLview of your data, or to convert it into a different format. Checking XMLSchemas and looking at defining an XML Schema with a more completevalidation and datatyping of your data structures is important, this helpsavoiding some mistakes in the design phase.</p><h3>Namespace:</h3><p>If you expect your XML vocabulary to be used or recognized outside of yourapplication (for example binding a specific processing from a graphic shelllike Nautilus to an instance of your data) then you should really define an <ahref="http://www.w3.org/TR/REC-xml-names/">XML namespace</a> for yourvocabulary. A namespace name is an URL (absolute URI more precisely). It isgenerally recommended to anchor it as an HTTP resource to a server associatedwith the software project. See the next section about this. In practice thiswill mean that XML parsers will not handle your element names as-is but as acouple based on the namespace name and the element name. This allows it torecognize and disambiguate processing. Unicity of the namespace name can befor the most part guaranteed by the use of the DNS registry. Namespace canalso 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 theroot 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 inthe given namespace.</p><h2><a name="Canonical">Canonical URL</a></h2><p>As seen in the previous namespace section, while XML processing is nottied to the Web there is a natural synergy between both. XML was designed tobe available on the Web, and keeping the infrastructure that way helpsdeploying 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, aDTD, a stylesheet, a schema, or even non-XML data associated with an XMLresource, the canonical URL is the URL where the "master" copy of thatresource is expected to be present on the Web. Usually when processing XML acopy 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 beindependent 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 aresource to reference it but always use the canonical URL. For example in aDocBook 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 <ahref="http://www.w3.org/TR/xslt">XSLT</a> stylesheets needed to process it togenerate 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 fewsimple rules similar to those used to design namespace names:</p>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -