2.3. General Directory Naming and File Placement Policy

This section describes policy that is common to both infrastructure and application directories, such as package directory layouts, version-numbering directories, and the handling and definition of customization packages.

2.3.1. Version-numbered Directories

When a package contains multiple versions of a resource, such as a DTD, each version must be placed in a separate version-numbered subdirectory. The docbook-xml package provides a good example.

The DTD files are placed in versioned subdirectories of /usr/share/xml/docbook/schema/dtd.

Example 2.1. Version-numbered Directories for the DocBook XML DTD

/usr/share/xml/docbook/schema/dtd/
3.0 (symlink to 3.1.7)
3.1 (symlink to 3.1.7)
3.1.7/
*.dtd
*.mod
catalog.xml
4.0 (symlink to 4.1.2)
4.1 (symlink to 4.1.2)
4.1.1 (symlink to 4.1.2)
4.1.2/
*.dtd
*.mod
catalog.xml

DTD packages that include customization layers, such as Simplified DocBook (aka docbook-simple), should not install their files in this hierarchy, they should instead install them in /usr/share/xml/docbook/custom/simple. For more info, see the Customization Packages section.

Some General Notes

  • If used at all, version-numbered directories are only allowed as subdirectories of a package directory. Package directories themselves are never allowed to have version numbers in their names.

  • For backward compatibility, symlinks for older DTD versions can be created in the package directory and should point to a newer DTD version. These symlinks should only be created when the newer version is backward-compatible with the older version.

  • The bottom-level directories containing the DTD files are named according to the version of the DTD they contain. That is, the directory names are literally version numbers.

  • Stylesheets are never placed in version-numbered directories. The reason for this is that Debian only allows a single version of a given stylesheet package to be installed at any time, and that stylesheet packages do not contain multiple versions.

  • Non-stylesheet packages that contain only a single version of a resource may or may not install their files into version-numbered subdirectory, at the discretion of the package maintainer. For example, package foo, version 1.1 may install its files directly into /usr/share/xml/.../foo or into /usr/share/xml/.../foo/1.1.

More detailed, context-specific information about version-numbered directories can be found in the XML Infrastructure Directories and XML Application Directories chapters.

2.3.2. Non Version-numbered Directories

Many packages have no need for version-numbered directories and should therefore not use them. Stylesheet installations are the only case where version-numbered directories are expressly forbidden.

For the DocBook XSL stylesheets, package maintainers should install the upstream files directly into /usr/share/xml/docbook/stylesheet/upstream-name, without changes. upstream-name is something like nwalsh or ldp, and typically indicates the upstream source, or, at the very least, is a unique name. Note that there is no xsl subdirectory, as was the case when XML resources were installed under /usr/share/sgml.

Example 2.2. DocBook Stylesheet Directory Layout

Here is a typical example:

/usr/share/xml/docbook/stylesheet/
nwalsh/ [package files go here]
ldp/ [package files go here]

Stylesheet Directory Summary

  • Installation (or package) directories are typically named after the upstream source (e.g. nwalsh).

  • CSS files are generally part of a stylesheet distribution and should therefore be installed in the same directory as the stylesheet distribution. If they wish, package maintainers may create a css directory into which these files can be installed.

  • Stylesheet directories do not contain version numbers.

2.3.3. General Customization Package Directories

All packages derived from customizations of another schema (DTD) or stylesheet distribution (or both) must, of course, not only install their files in an XML application directory, they must install their files into a special subdirectory. This subdirectory is known as a General Customization Package Directory and is always given the name custom.

For example, the docbook-simple package contains a number of Simplified DocBook DTDs, some of which are customizations of the full DocBook DTD. The docbook-simple package (version 1.0) therefore installs its files into /usr/share/xml/docbook/custom/simple/1.0.

In fact, application directories are recommended to use the following layout:

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

For more detailed information on this layout, see the XML Application Directories chapter.

The notion of a General Customization Package Directory naturally leads to the definition of a Customization Package.

Customization Package

A package is a customization package if it meets any of the following criteria:

  1. At least one of the stylesheet files is a customization of an installed stylesheet or stylesheet distribution.

  2. At least one of the schema files is a customization of an installed schema.

Summary

Customization packages should place their files in a non-versioned subdirectory of custom, such as /usr/share/xml/resource-name/custom/foo. (In the DocBook case, the files would be installed in a subdirectory of /usr/share/xml/docbook/custom, such as /usr/share/xml/docbook/custom/website, for example.) Maintainers may create versioned subdirectories of the package directories, but are not required to do so unless multiple versions of a resource are installed.

Example 2.3. DocBook Website Customization Installation

For example, the DocBook Website package has a DTD that is a customization of the DocBook XML DTD and also contains XSL stylesheets that are customizations of the DocBook XSL stylesheets. The layout of the package files preserves the upstream layout and look something like this:

/usr/share/xml/docbook/custom/website/version/      
                                               catalog.xml
                                               VERSION
                                               css/*
                                               extensions/*
                                               xsl/*
                                               schema/
                                                      dtd/*
                                                      relaxng/*
        

In the above, version represents an optional version-numbered directory. If multiple versions of the website DTD are to be installed, then the version-numbered directory is not optional.

This policy is consistent with the LSB goal to simplify the packaging of DTD and/or stylesheet customizations.

Note

According to the above definition, DTD-only or stylesheet-only customizations are also defined as customization packages, and are therefore installed into a subdirectory of /usr/share/xml/resource-name/custom [1].



[1] To understand why these package files should also be installed in the custom directory, consider the result of not putting them there:

For example, the DocBook Website contains both DTDs and stylesheets, and so would be placed in a subdirectory of custom, such as /usr/share/xml/docbook/custom/website. Suppose we also packaged some custom website stylesheets distributed by ACME. If these stylesheets were not installed under custom, they would go someplace like /usr/share/xml/docbook/stylesheet/acme/website, resulting in an inconsistent stylesheet placement policy.