Table of Contents
This appendix is a direct outgrowth of the discussions and collective experience of the Debian SGML developers as they worked to implement the SGML component of the Linux Standard Base specification on Debian systems. It describes those aspects of the Debian implementation that differ from the LSB specification.
Over a four-month period, many of the policies described herein were repeatedly debated and revised as we worked out the details, always giving compliance a high priority. As we moved closer to consensus, it became clear that there were distinct sections of the specification from which the Debian implementation would necessarily depart. This document describes and provides rationale for these points of departure.
We identified several points in the proposed LSB layout for /usr/share/sgml/ with which we disagree:
|Flat directory structure||
As each non-DTD package creates its own directory, a large number of unrelated subdirectories will eventually populate /usr/share/sgml/. The result will be unecessarily cluttered and more difficult to manage. Furthermore, the resulting layout bears little resemblance to other parts of the Debian filesystem, thereby introducing an unneeded inconsistency.
|Version-numbered directory names||
Due to important packages (e.g. jade and various stylesheets) that will only be installed one version at a time, version numbering the directories will be unnecessary and would complicate the packaging of various tool wrappers by introducing version numbers in path components.
Sections R001 and R002 of the specification specify that the names assigned to the top-level directories under /usr/share/sgml/ be determined by one of the following schemes:
Based directly on package names
Contain upstream version-numbers
Based on generic DTD name
Not version-numbered (but having subdirectories whose names comply with both A.1 and A.2)
The resulting structure looks like this:
The Debian layout uses directory types derived from both the LSB spec and from previous Debian SGML implementations:
|Application/DTD-oriented directories (LSB)||
Such as docbook/, html/, jade/, and sgmltools-lite/
|SGML infrastructure directories (Debian)||
Such as declaration/, dtd/, and entities/
|Directory structures that map FPIs to paths(Debian)||
These directories must contain only symbolic links. Examples here would be ISBN_82-7640-000, ISO_8879:1986, and Sun_Microsystems_Corp.
Versioned directories rarely appear at the top level.
A generic example (sorted as above) might look something like this:
See Section 2.1, “SGML Base Directories” for more detailed information on this structure.
As with /usr/share/sgml/, the Debian layout makes use of a small number of general, top-level directories.
The recommended layout below docbook (or any dtd-based subdirectory) mirrors that of its parent directory, /usr/share/sgml/, using directory names that are package-based and version-numbered:
The Debian layout uses more general subdirectories:
Each of which has a well-defined subdirectory structure:
gnome/ [versioned subdirectories] simple/ [versioned subdirectories] website/[versioned subdirectories]
[UPSTREAM-SOURCE]/ [non-versioned subdirectories, e.g. nwalsh/]
The LSB Policy states that all configuration files should have names that end in .conf:
Other configuration files may also reside in /etc/sgml/, either DTD-specific or program-specific. Their name should end in .conf and they should follow ordinary rules for files residing in /etc as defined by LSB. The user should be able to redefine them in his/her home directory. Their syntax and purpose is not defined in this document.
In some cases, the original source files for DTD and/or stylesheet packages include configuration files such as the general entities module, dbgenent.mod, included in the DocBook XML distribution. Debian will place these type of files under /etc/sgml/ as recommended by the LSB spec, but will do so in ways that may depart from LSB in the following ways:
|Configuration file locations||
The upstream configuration files for <package>will be placed in the /etc/sgml subdirectory /etc/sgml/<package>/
Futhermore, a symbolic link with the same name as the configuration file will be placed in the directory where the majority of the packages files reside. This link will point to the configuration file in /etc/sgml/<package>/.
|Configuration file names||
These configuration files will retain their original upstream names, which usually do not end with .conf.