Appendix A. LSB Compliance

Table of Contents

A.1. Points of Departure
A.1.1. R001--SGML Directory layout
A.1.1.1. LSB Layout
A.1.1.2. Debian Layout
A.1.2. R002--DocBook Directory layout
A.1.2.1. LSB Layout
A.1.2.2. Debian Layout
A.1.3. R005--Configuration Files
A.1.3.1. LSB Policy
A.1.3.2. Debian Policy
A.1.4. R007--Packages
A.1.4.1. LSB Policy
A.1.4.2. Debian Policy

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.

A.1. Points of Departure

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.

A.1.1. R001--SGML Directory layout

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.

A.1.1.1. LSB Layout

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:

  1. Package-derived Names

    1. Based directly on package names

    2. Contain upstream version-numbers

  2. DTD-derived Names

    1. Based on generic DTD name

    2. Not version-numbered (but having subdirectories whose names comply with both A.1 and A.2)

The resulting structure looks like this:

/usr/share/sgml/
sgml-iso-entities-8879.1986/
xml-iso-entities-8879.1986/
jade-1.2.1/
openjade-1.3/
...
docbook/
tei/
html/
...

A.1.1.2. Debian Layout

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.

Note

Versioned directories rarely appear at the top level.

A generic example (sorted as above) might look something like this:

/usr/share/sgml/
...
docbook/
html/
sgmltools-lite/
tei/
...
declaration/
dtd/
entities/
misc/
stylesheet/
...
ArborText/
Hewlett-Packard/
ISO_8879:1986/
ISO_IEC_15445:2000/
...

See Section 2.1, “SGML Base Directories” for more detailed information on this structure.

A.1.2. R002--DocBook Directory layout

As with /usr/share/sgml/, the Debian layout makes use of a small number of general, top-level directories.

A.1.2.1. LSB Layout

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:

/usr/share/sgml/docbook/
sgml-dtd-3.1/
sgml-dtd-4.0/
xml-dtd-4.0/
dsssl-stylesheets-1.54/
xsl-stylesheets-1.12/
kde-customization-0.1/
gnome-customization-0.1/
ldp-customization-0.1/

A.1.2.2. Debian Layout

The Debian layout uses more general subdirectories:

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

Each of which has a well-defined subdirectory structure:

/usr/share/sgml/docbook/custom/
gnome/ [versioned subdirectories]
simple/ [versioned subdirectories]
website/[versioned subdirectories]
/usr/share/sgml/docbook/dtd/
[versioned subdirectories]
/usr/share/sgml/docbook/stylesheet/
[UPSTREAM-SOURCE]/ [non-versioned subdirectories, e.g. nwalsh/]

A.1.3. R005--Configuration Files

A.1.3.1. LSB Policy

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.

A.1.3.2. Debian Policy

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.

A.1.4. R007--Packages

FIXME: content here

A.1.4.1. LSB Policy

FIXME: content here

Use upstream version numbers in package names.

A.1.4.2. Debian Policy

FIXME: content here

Do NOT use upstream version numbers in package names.