XML resources publication guidelines

Linux 4gvps.4gvps.com 3.10.0-1127.18.2.vz7.163.46 #1 SMP Fri Nov 20 21:47:55 MSK 2020 x86_64
SOFT : Apache PHP : 7.4.33
/usr/share/doc/libxml2-devel-2.9.1/

38.135.39.45

[ NAME ]	[ SIZE ]	[ PERM ]	[ DATE ]	[ ACT ]
+FILE +DIR
examples	dir	drwxr-xr-x	2025-06-12 01:21	R D
html	dir	drwxr-xr-x	2025-06-12 01:21	R D
tutorial	dir	drwxr-xr-x	2025-06-12 01:21	R D
APIchunk0.html	29.384 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk1.html	36.614 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk10.html	62.818 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk11.html	32.428 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk12.html	85.95 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk13.html	62.372 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk14.html	44.632 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk15.html	43.199 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk16.html	35.448 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk17.html	52.79 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk18.html	41.746 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk19.html	35.798 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk2.html	39.792 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk20.html	31.978 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk21.html	36.93 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk22.html	56.599 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk23.html	62.125 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk24.html	92.134 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk25.html	40.752 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk26.html	31.368 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk27.html	33.186 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk28.html	56.492 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk29.html	13.099 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk3.html	35.345 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk4.html	35.34 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk5.html	29.043 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk6.html	28.34 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk7.html	32.077 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk8.html	29.517 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIchunk9.html	28.025 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIconstructors.html	58.105 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIfiles.html	320.544 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIfunctions.html	211.936 KB	-rw-r--r--	2013-04-19 07:28	R E G D
APIsymbols.html	317.849 KB	-rw-r--r--	2013-04-19 07:28	R E G D
AUTHORS	0.203 KB	-rw-r--r--	2009-07-30 15:24	R E G D
Copyright	1.259 KB	-rw-r--r--	2013-02-27 05:08	R E G D
DOM.gif	3.092 KB	-rw-r--r--	2009-07-30 15:24	R E G D
DOM.html	6.462 KB	-rw-r--r--	2013-03-27 08:08	R E G D
FAQ.html	20.571 KB	-rw-r--r--	2013-03-27 08:08	R E G D
Libxml2-Logo-180x168.gif	8.003 KB	-rw-r--r--	2009-07-30 15:24	R E G D
Libxml2-Logo-90x34.gif	2.998 KB	-rw-r--r--	2009-07-30 15:24	R E G D
NEWS	93.596 KB	-rw-r--r--	2013-02-27 05:08	R E G D
README	1.161 KB	-rw-r--r--	2013-02-27 05:08	R E G D
XMLinfo.html	6.638 KB	-rw-r--r--	2013-03-27 08:08	R E G D
XSLT.html	5.64 KB	-rw-r--r--	2013-03-27 08:08	R E G D
architecture.html	6.699 KB	-rw-r--r--	2013-03-27 08:08	R E G D
bugs.html	10 KB	-rw-r--r--	2013-03-27 08:08	R E G D
catalog.gif	5.962 KB	-rw-r--r--	2009-07-30 15:24	R E G D
catalog.html	23.077 KB	-rw-r--r--	2013-03-27 08:08	R E G D
contribs.html	7.495 KB	-rw-r--r--	2013-03-27 08:08	R E G D
docs.html	7.439 KB	-rw-r--r--	2013-03-27 08:08	R E G D
downloads.html	8.066 KB	-rw-r--r--	2013-03-27 08:08	R E G D
encoding.html	18.926 KB	-rw-r--r--	2013-03-27 08:08	R E G D
entities.html	9.222 KB	-rw-r--r--	2013-03-27 08:08	R E G D
example.html	12.795 KB	-rw-r--r--	2013-03-27 08:08	R E G D
guidelines.html	17.248 KB	-rw-r--r--	2009-07-30 15:24	R E G D
help.html	6.17 KB	-rw-r--r--	2013-03-27 08:08	R E G D
index.html	16.46 KB	-rw-r--r--	2013-03-27 08:08	R E G D
interface.html	8.015 KB	-rw-r--r--	2013-03-27 08:08	R E G D
intro.html	7.035 KB	-rw-r--r--	2013-03-27 08:08	R E G D
library.html	14.605 KB	-rw-r--r--	2013-03-27 08:08	R E G D
libxml.gif	7.512 KB	-rw-r--r--	2009-07-30 15:24	R E G D
libxml2-api.xml.gz	157.778 KB	-rw-r--r--	2025-05-08 14:26	R E G D
namespaces.html	8.142 KB	-rw-r--r--	2013-03-27 08:08	R E G D
news.html	125.522 KB	-rw-r--r--	2013-03-27 08:08	R E G D
python.html	19.46 KB	-rw-r--r--	2013-03-27 08:08	R E G D
redhat.gif	0.681 KB	-rw-r--r--	2009-07-30 15:24	R E G D
searches.html	7.382 KB	-rw-r--r--	2009-07-30 15:24	R E G D
smallfootonly.gif	2.707 KB	-rw-r--r--	2009-07-30 15:24	R E G D
structure.gif	5.429 KB	-rw-r--r--	2009-07-30 15:24	R E G D
threads.html	6.94 KB	-rw-r--r--	2013-03-27 08:08	R E G D
tree.html	7.726 KB	-rw-r--r--	2013-03-27 08:08	R E G D
upgrade.html	12.344 KB	-rw-r--r--	2013-03-27 08:08	R E G D
w3c.png	1.98 KB	-rw-r--r--	2009-07-30 15:24	R E G D
xml.html	264.822 KB	-rw-r--r--	2013-03-23 02:31	R E G D
xmlcatalog_man.html	8.893 KB	-rw-r--r--	2013-02-27 05:08	R E G D
xmldtd.html	13.301 KB	-rw-r--r--	2013-03-27 08:08	R E G D
xmlio.html	12.483 KB	-rw-r--r--	2013-03-27 08:08	R E G D
xmllint.html	15.124 KB	-rw-r--r--	2009-07-30 15:24	R E G D
xmlmem.html	14.082 KB	-rw-r--r--	2013-03-27 08:08	R E G D
xmlreader.html	19.667 KB	-rw-r--r--	2009-07-30 15:24	R E G D
REQUEST EXIT

The goal of this document is to provide a set of guidelines and tips helping the publication and deployment of XML resources for the GNOME project. However it is not tied to GNOME and might be helpful more generally. I welcome feedback on this document.

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:

Design guidelines

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:

Reuse existing formats:

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, DocBook 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.

DTD rules:

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:

Versioning:

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:

Other design parts:

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.

Namespace:

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 XML namespace 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:

An easy way to use them is to make them the default namespace on the root element of the XML instance like:

In that document, structure and all descendant elements like data are in the given namespace.

Canonical URL

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).

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:

Similarly, the document instance may reference the XSLT stylesheets needed to process it to generate HTML, and the canonical URL should be used:

Defining the canonical URL for the resources needed should obey a few simple rules similar to those used to design namespace names:

Catalog setup

How catalogs work:

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. XML Catalogs are anchored in the root catalog (usually /etc/xml/catalog 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.

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: Picture describing the catalog

Usual catalog setup:

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 XHTML1 DTDs, only 3 items are added to the root catalog:

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 /usr/share/sgml/xhtml1/xmlcatalog 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

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 "http://www.w3.org/TR/xhtml1/DTD" 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.

A subcatalog example:

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

Package integration

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:

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.

Similarly, the script for the post-uninstall just remove the rules from the catalog:

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

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.