0 ?÷ XML resources publication guidelines

XML resources publication guidelines

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:

Table of contents:

Design guidelines
Canonical URL
Catalog setup
Package integration

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:

use significant words for the element and attributes names.
do not use attributes for general textual content, attributes will be modified by the parser before reaching the application, spaces and line information will be modified.
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:
```
<welcome>
  <msg xml:lang="en">hello</msg>
  <msg xml:lang="fr">bonjour</msg>
</welcome>
```
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 elemen