R001--SGML Directory layout

Some existing projects place files in /usr/lib/sgml. Other projects place files in /usr/local/share/sgml. Strictly speaking, those files are neither libraries nor local to a system, so we chose /usr/share/sgml.

Some projects used to put centralized catalogs at the same place as the other catalogs. Since they can be seen as system configuration files, it was logical to centralize them within /etc.

One very hard question was: should we separate SGML from XML? The relationship between one and the other is very strong, so we chose to keep them at the same place in the directory tree. This allows, for example, to have all DocBook stuff, both SGML and XML, at the very same place, which is obviously practical.

While /usr/share/sgml does not explicitly reflect this, we found that it was still better than /usr/share/markup (what about TeX then?), /usr/share/ml, or other proposals.

Why having fixed file paths while you could have got them from some configuration variables, autoconf mechanisms, etc? First because it's simpler: we wanted a very strong standard, given that the tools may still use such configuration variables or autoconf mechanisms to adapt to non-LSB platforms. We considered that a standard that does not specify enough is somehow encouraging the most bizarre variations.

We chose a dtd-and-package-oriented architecture, instead of a file-type-oriented structure.

This was probably the most controversial issue. The "natural" proposal for SGML and XML specialists is to have the FPIs map almost letter-per-letter in the directory names. However, this approach does not take profit of the catalogs mechanism that allow to map FPIs into file paths.

A file-type-oriented architecture would have lead to a directory structure like:

/usr/share/sgml/USA-DOD/DTD_Table_Model_951010/EN/

/usr/share/sgml/OASIS/DTD_DocBook_V3.1/EN/

/usr/share/sgml/OASIS/ELEMENTS_DocBook_Information_Pool_V3.1/EN/

/usr/share/sgml/OASIS/ELEMENTS_DocBook_Document_Hierarchy_V3.1/EN/

/usr/share/sgml/OASIS/ENTITIES_DocBook_Additional_General_Entities_V3.1/EN/

/usr/share/sgml/OASIS/ENTITIES_DocBook_Notations_V3.1/EN/

/usr/share/sgml/OASIS/ENTITIES_DocBook_Character_Entities_V3.1/EN/

or something further away from the FPIs like:

/usr/share/sgml/sgml-dtd/hal/docbook/2.4/

/usr/share/sgml/sgml-dtd/davenport/docbook/3.0/

/usr/share/sgml/sgml-dtd/davenport/docbook/3.0/

/usr/share/sgml/sgml-dtd/oasis/docbook/3.1/

/usr/share/sgml/xml-dtd/oasis/docbook/4.0/

/usr/share/sgml/dssl-stylesheets/nwalsh/docbook/3.1/

/usr/share/sgml/xsl-stylesheets/nwalsh/docbook/4.0/

/usr/share/sgml/sgml-dtd/ietf/html/2.0/

/usr/share/sgml/sgml-dtd/w3c/html/3.2/

but in all cases, the files would have been spread according to their file types in distant directories. We would probably have had entities somewhere, stylesheets somewhere else, DTDs in a third place, and SGML declarations in a fourth place. This would certainly have broken some relative paths, and required more packaging work.

The user does not think in terms of file types, whereas SGML specialists do. The user only thinks "I want to do some MathML" or "I want to do some XHTML" or "I want to do some TEI". This is why the basic unit is the DTD. This DTD-centered approach does not mean that first level directories are for DTDs. It just means that they hold everything related to a given DTD: stylesheets, enterprise-wide customizations, etc...