2.3. SGML Subdirectory Layout/Creation Guidelines

New directories under /usr/share/sgml/ should only be created when installing a set of resources that has accompanying stylesheets and/or a significant number of associated files.

Other major packages (such as jade) may also create directories.

When a new directory is created under /usr/share/sgml/, its name should use only lowercase letters and should not contain any version numbers. (Though it may have version-numbered subdirectories.)

For concreteness, all the examples that follow use DocBook as the sample cases.

Example 2.1. Debian docbook Directory Layout

This layout is faithful in spirit to the LSB spec, but uses top-level directories to provide more organization to the structure.

There are three main docbook directories:

/usr/share/sgml/docbook/
custom/
dtd/
stylesheet/

A similar structure would also apply to other major DTDs, such as TEI. More info on these subdirectories is given below.

Directory Descriptions and Usage

custom/

All packages derived from customizations of a "main" DTD or stylesheet distribution (or both) are placed in subdirectories of custom, thus simplifying packaging of DTD/stylesheet combinations.

These customization packages put their files in a non-versioned subdirectory of custom. The package directory itself may or may not have versioned subdirectories; package maintainers can determine the structure as they see fit.

dtd/

Subdivided into xml and sgml subdirectories, upstream source files are placed in a versioned subdirectory of xml or sgml, whichever is appropriate. Furthermore, the name of the versioned subdirectory is the DTD version number itself, as in 4.1.2/ or 1.0b4/.

stylesheet/

Subdivided into dsssl and xsl subdirectories, stylesheet distributions are placed in a subdirectory with names derived from the upstream source (e.g. nwalsh/, onshore/). These directory names must not contain version numbers.

2.3.1. Version-numbered Subdirectories

When a package contains multiple versions, each version should be placed in a separate version-numbered directory. The docbook-xml package provides a good example.

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

Some General Notes

  • DTD packages that include customization layers, such as Simplified DocBook (aka docbook-simple), should not be placed in this hierarchy. They should reside in the /usr/share/docbook/custom/ directory.

  • For backward compatibility, symlinks for older DTD versions can be created in the package directory and should point to a newer DTD version.

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

Example 2.2. Versioned Subdirectories for the DocBook XML DTD

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

Catalog File Names

Upstream catalog files placed in these directories should retain their original, upstream names. Catalog files created by the maintainer should be named catalog

2.3.2. Subdirectories for Customization Packages

The definition of a customization package needs to be stated before the purpose and layout of this directory can be described.

Definition: Customization Packages

Customization Packages

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 DTD files is a customization of an installed DTD.

Purpose and Layout

Customization packages should place their files in a non-versioned subdirectory of custom/. (In the DocBook case, the files would be installed in a subdirectory of /usr/share/sgml/docbook/custom/.) Maintainers may create versioned subdirectories of the package directories, but are not required to do so.

All packages derived from customizations of another DTD or stylesheet distribution (or both) are placed in subdirectories of custom/, thus simplifying the packaging of DTD/stylesheet combinations.

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

Example 2.3. Gnome DocBook Customization DTD and Stylesheet

/usr/share/sgml/docbook/custom/gnome/version/
catalog
gnome-customization.dtd
gnome-customization.dsl

In the above, version/ represents the optional version number, for the case when multiple versions are installed.

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

Note

The above definition implies that DTD-only or stylesheet-only customizations are also defined as customization packages, and are therefore installed into a subdirectory of /usr/share/sgml/RESOURCE-NAME/custom/ [1].

2.3.3. Non-versioned Stylesheet Subdirectories

Package maintainers should be able install the upstream files directly into the appropriate subdirectory of, say, /usr/share/sgml/docbook/stylesheet/upstream-name/, without changes. Where upstream-name/ is something like nwalsh/ or onshore/, and typically indicates the upstream source.

Here is a typical example:

Subdirectory Layout

/usr/share/sgml/docbook/stylesheet/
nwalsh/[package files go here]
onshore/[package files go here]

Subdirectory Descriptions and Usage

  • Installation directories are named after the upstream source (e.g. nwalsh/).

  • CSS files are often 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/ subdirectory in the installation.

  • Stylesheet directories do not contain version numbers.

2.3.4. Summary: docbook/ Subdirectory Descriptions and Usage

In the summary below, the ellipsis "..." refers to /usr/share/sgml/

.../docbook/custom/

Packages that contain customizations of the main DocBook SGML DTDs or dsssl stylesheets should be placed in the custom/ directory. The Gnome and LDP customizations serve as examples here.

.../docbook/dtd/

Upstream source files are placed in a versioned subdirectory of .../docbook/dtd/. Furthermore, the name of the versioned subdirectory is the DTD version number itself, as in 4.1.2/ or 3.1.7/.

.../docbook/stylesheet/

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



[1] To understand why these packages should be placed 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 placement policy.