2.5. XML Application Directories

Major, well-known DTDs and schema often have other types of resources (such as stylesheets) associated with them. These collections of resources are often extensive enough to warrant their own separate directory in /usr/share/xml in which to install their resources. These special directories are called Application Directories.

These application-specific directories in /usr/share/xml are created for related collections of XML resources, or for packages that install a large number of files. For example, /usr/share/xml/docbook contains a collection of DocBook-related resources, such as schema, stylesheets, and their customizations.

New directories under /usr/share/xml (i.e. application directories) should only be created when installing a set of related resources (e.g. a schema that has accompanying stylesheets) or a significant number of associated files.

Minor DTDs, declarations, and entities should be installed in the infrastructure directories /usr/share/xml/{declaration, entities, misc, schema}, as appropriate.

When a new application directory is created under /usr/share/xml, its name should use only lowercase letters and should not contain version numbers. It may, however, have version-numbered subdirectories.

The recommended layout for application directories is described below.

2.5.1. FHS-required Application Directories

The Filesystem Hierarchy Standard (FHS) requires some specific XML application directories:

/usr/share/xml/
docbook
mathml
xhtml

FIXME: It is not yet clear which package (xml-core?), if any, should create these directories. However, this issue will certainly be worked out during the "Working Draft" status of this document.

2.5.2. Application Directory Layout

It is recommended that all application directories employ a layout consisting of the following four top-level directories: custom, misc, schema, stylesheet. Visually, the layout looks like this:

/usr/share/xml/application-dir/
custom
misc
schema
stylesheet

The docbook application directory provides a typical example of an application directory layout.

Example 2.4. docbook Application Directory Layout

There are four main docbook subdirectories:

/usr/share/xml/docbook/
custom
misc
schema
stylesheet

A similar structure would also apply to other major DTDs, such as TEI.

More info on these subdirectories (esp. the custom subdirectory) is given below.

(The ellipsis "..." below is an abbreviation for /usr/share/xml.)

.../docbook/custom

Packages that contain customizations of the main DocBook XML schema or XSL stylesheets should be placed in the custom directory. Simplified DocBook and DocBook Website serve as examples here.

.../docbook/misc

The misc directory is intended to provide a location to install application files that don't belong in one of the other application subdirectories.

.../docbook/schema

Subdivided into dtd and other subdirectories as appropriate, upstream source files are placed in a versioned subdirectory of schema/schema-type, where schema-type could be dtd, rng (RELAX NG), rnc (RELAX NG, Compact Syntax), etc. Furthermore, the name of the versioned subdirectory is the DTD or schema version number itself, as in 4.1.2 or 4.3.

.../docbook/stylesheet

Subdivided into subdirectories whose names are derived from the upstream source (e.g. nwalsh, ldp), these directories must not contain version-numbered subdirectories.