Re: SGML/XML proposals for Linux Standard Base

[Dan Scott <dan.scott@acm.org>]

On 16 Nov 2000, Jorge Godoy wrote:

(CUT)
> (CUT)
> 
> >> Would someone within the LDP be interested in DocBook formatting
> >> and supporting this chapter of the LSB?
> 
> I'm a member of LDP and I'd be available to do such markup if needed
> for the LSB team. 
> 

Thanks Jorge, but I've already marked it up (and started to do some
low-level editing).

I'll attach the marked-up drafts, and appreciate any comments more
experienced DocBookers may have...

Thanks again,
Dan

-- 
Dan Scott,
Friend of the abnormal.
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<chapter id="sgmloverview">
<title>LSB PROPOSAL: SGML & XML proposal overview</title>
<abstract>
<para>
This document explains the rationale for the recommendations to LSB about DocBook.
The actual recommendations are presented in a separate document.
</para>
</abstract>

<sect1 id="sgmloverintro">
<title>Introduction</title>
<para>
<comment>This paragraph is counter-productive; what you're really saying is
"Here's my new-born baby, it almost killed me (or my wife) to deliver him,
now how cute do you think he is?". So of course you won't get good feedback
with this paragraph; you're actively dissuading it.</comment>
There are hundreds of man-hours behind those recommendations. They really
costed blood, sweat and tears. Each line was discussed many times and
the global architecture changed quite often. We really tried to hear
what everyone add to say. So we would like to encourage LSB in being
very careful if they want to modify them.
</para>
<para>
The general philosophy was to keep the <quote>historical</quote> choices everywhere
it had no consequences, and the <quote>best</quote> technical choice wherever it was
interesting. We have attempted to design a very simple but also powerful
architecture, in full respect of the <acronym>FHS</acronym> (File system Hierarchy Standard).
</para>
<para>
Another general principal of design was to think about the 
practical concerns of the user instead of the theory.
There were many models that would have been much more
intellectually satisfying&mdash;but they were all too complex for
everyday's use.
</para>
</sect1>

<sect1 id="overdefinitions">
<title>Definitions</title>
<para>
Why these definitions? Because we realized we were speaking about
different things with the same words. One example is <quote>SGML application</quote>:
it can refer either to a specific DTD, or to a computer program meant to
process some SGML or XML document. Both definitions are perfectly
correct, but to avoid confusion we chose the one we needed.
</para>
<para>
Some definitions like <quote>helper</quote>, <quote>backend</quote> and <quote>frontend</quote> are not even
necessary to read the rest of the document. We left them because we
needed them to provide a reference implementation.
</para>
</sect1>

<sect1 id="overR001">
<title>R001&mdash;SGML Directory layout</title>
<para>
Some existing projects place files in <filename class="directory">/usr/lib/sgml</filename>.
Other projects place files in <filename class="directory">/usr/local/share/sgml</filename>.
Strictly speaking, those files are neither libraries nor local to a system, so we chose 
<filename class="directory">/usr/share/sgml</filename>.
</para>
<para>
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 <filename class="directory">/etc</filename>.
</para>
<para>
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.
</para>
<para>
While <filename class="directory">/usr/share/sgml</filename> does
not explicitly reflect this, we found that it was still better than
<filename class="directory">/usr/share/markup</filename> (what about TeX then?),
<filename class="directory">/usr/share/ml</filename>, or other proposals.
</para>
<para>
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.
</para>
<para>
We chose a dtd-and-package-oriented architecture, instead of a
file-type-oriented structure.
</para>
<para>
This was probably the most controversial issue. The <quote>natural</quote> 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.
</para>
<para>
A file-type-oriented architecture would have lead to a directory structure like:
<simplelist>
<member><filename class="directory">/usr/share/sgml/USA-DOD/DTD_Table_Model_951010/EN/</filename></member>
<member><filename class="directory">/usr/share/sgml/OASIS/DTD_DocBook_V3.1/EN/</filename></member>
<member><filename class="directory">/usr/share/sgml/OASIS/ELEMENTS_DocBook_Information_Pool_V3.1/EN/</filename></member>
<member><filename class="directory">/usr/share/sgml/OASIS/ELEMENTS_DocBook_Document_Hierarchy_V3.1/EN/</filename></member>
<member><filename class="directory">/usr/share/sgml/OASIS/ENTITIES_DocBook_Additional_General_Entities_V3.1/EN/</filename></member>
<member><filename class="directory">/usr/share/sgml/OASIS/ENTITIES_DocBook_Notations_V3.1/EN/</filename></member>
<member><filename class="directory">/usr/share/sgml/OASIS/ENTITIES_DocBook_Character_Entities_V3.1/EN/</filename></member>
</simplelist>
or something further away from the FPIs like:
<simplelist>
<member><filename class="directory">/usr/share/sgml/sgml-dtd/hal/docbook/2.4/</filename></member>
<member><filename class="directory">/usr/share/sgml/sgml-dtd/davenport/docbook/3.0/</filename></member>
<member><filename class="directory">/usr/share/sgml/sgml-dtd/davenport/docbook/3.0/</filename></member>
<member><filename class="directory">/usr/share/sgml/sgml-dtd/oasis/docbook/3.1/</filename></member>
<member><filename class="directory">/usr/share/sgml/xml-dtd/oasis/docbook/4.0/</filename></member>
<member><filename class="directory">/usr/share/sgml/dssl-stylesheets/nwalsh/docbook/3.1/</filename></member>
<member><filename class="directory">/usr/share/sgml/xsl-stylesheets/nwalsh/docbook/4.0/</filename></member>
<member><filename class="directory">/usr/share/sgml/sgml-dtd/ietf/html/2.0/</filename></member>
<member><filename class="directory">/usr/share/sgml/sgml-dtd/w3c/html/3.2/</filename></member>
</simplelist>

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.
</para>
<para>
The user does not think in terms of file types, whereas SGML specialists
do. The user only thinks <quote>I want to do some MathML</quote> or <quote>I want to do some
XHTML</quote> or <quote>I want to do some TEI</quote>. 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&hellip;
</para>
</sect1>

<sect1 id="overR002">
<title>R002&mdash;DocBook Directory layout</title>
<para>
Maybe the document seems confused because it mixes recommendations
for SGML and XML with recommendations for DocBook. It would somehow
have been good to separate it into two documents. On the other hand,
this allowed to think in very practical terms.
</para>
<para>
There is only one lower level of directories. The directory names are
vaguely defined as holding one <quote>package</quote>. One advantage is that the
relation to any RPM or DEB package is very close. The other advantage
is that we have a very flat tree, thus easing both hacking, packaging
and maintenance by system administrators.
</para>
<para>
The lower level directories are version-numbered. This unusual naming
scheme is intended to permit documents that are written using several
versions of the same DTD to coexist on the same system.
</para>
</sect1>

<sect1 id="overR003">
<title>R003&mdash;Open Catalog usage for SGML</title>
<para>
Why focusing so much on catalogs in these recommendations? Because
they are the key to your directory structure and give a strong working
infrastructure that every SGML or XML tool can count on.
</para>
<para>
Open catalogs have very often been resented because they lead to problems
like conflicting SGMLDECLs. However, those problems do not appear if
you use them carefully. One of the keys is to avoid putting everything
in the same bag, and to have centralized catalogs that are specific to
a given DTD.
</para>
<para>
The fact that they are DTD-specific has a number of advantages:
<itemizedlist>
<listitem><para>avoid SGMLDECL conflicts without assuming DTDDECL or
DELEGATE support, which many tools do not yet support</para></listitem>
<listitem><para>avoid duplicate FPI declarations</para></listitem>
<listitem><para>allow to point to the right version of a given DTD
and to the corresponding entities and style sheets from only one place</para></listitem>
</itemizedlist>
</para>
<para>
When splitting your CATALOG pointers in one file per DTD, you also somehow
lose a global vision on all the catalogs that are installed on your
system. This is why we have introduced the super-catalog, which points to all
of the centralized catalogs on your system. It eases many scripting issues.
</para>
<para>
The super catalog may be used as a default centralized catalog, for
example when the DTD is not known, however it cannot be guaranteed that
there will not be any declaration conflicts if an application chooses to
use this functionality.
</para>
<para>
OASIS says that all the catalogs should be named <filename>CATALOG</filename> or
<filename>catalog</filename>. This was impossible to respect in <filename class="directory">/etc/sgml</filename>
where you will have the centralized catalogs, because many files cannot hold the same
name. Somehow it does not break those directives that much, because all
the ordinary catalogs on your system would still be named <filename>catalog</filename>.
</para>
<para>
We also chose to specify <filename>catalog</filename> rather than <filename>CATALOG</filename>,
while OASIS leaves the choice open. We considered that we should encourage one of both
versions, whichever it should be, because it is simpler for
everyone (scripts, maintainers, packagers, tools authors, &hellip;). In this
respect, LSB implementations could be considered as conformant to OASIS,
while the contrary would not be true.
</para>
</sect1>


<sect1 id="overR004">
<title>R004&mdash;Open Catalog usage for DocBook</title>
<para>
Directories like the ones holding Jade's or OpenJade's declarations and
the ISO entities are on top level because they are not specific to any
given DTD and can be used by two or more of them.
</para>
<para>
Of course one may argue that Jade's or OpenJade's declarations contain the
document type definition of what DSSSL is. But again what is important
is the usage, not the formal definition, so it has no reason to go to
a <filename class="directory">dsssl/</filename> directory
(which would also encourage packagers to put the stylesheets in,
away from their DTD, which is not what we want).
</para>
</sect1>

<sect1 id="overR005">
<title>R005&mdash;Configuration files</title>
<para>
This recommendation is voluntarily vague, to ease as much as possible the
possibility to create SGML applications with not creativity restrictions
with respect to configuration files&mdash;the catalog layout solves anyhow
one of their major problems: find the files.
</para>
</sect1>


<sect1 id="overR006">
<title>R006&mdash;Iso-entities</title>
<para>
So far, the most confusion has been with the file names holding these
very basic character entities. We have seen the following naming schemes:
<itemizedlist>
<listitem><para><filename>ISOamsa</filename> <filename>ISOamsb</filename> &hellip;</para></listitem>
<listitem><para><filename>ISOamsa.ent</filename> <filename>ISOamsb.ent</filename> &hellip;</para></listitem>
<listitem><para><filename>iso-amsa</filename> <filename>iso-amsb</filename> &hellip;</para></listitem>
<listitem><para><filename>iso-amsa.gml</filename> <filename>iso-amsb.gml</filename> &hellip;</para></listitem>
</itemizedlist>
etc&hellip;
</para>
<para>
There was a similar confusion for the Formal public identifiers describing
these files. We have seen the following naming schemes:
<itemizedlist>
<listitem><para><literal>"ISO 8879:1986//ENTITIES Added Math Symbols: Arrow Relations//EN"</literal></para></listitem>
<listitem><para><literal>"ISO 8879-1986//ENTITIES Added Math Symbols: Arrow Relations//EN"</literal></para></listitem>
</itemizedlist>
</para>
<para>
Again, we chose to avoid deciding not to decide. We had a lot of feedback
from users suffering from this indecision. Even if technical workarounds
exist, we would like to encourage one of these forms to emerge.
</para>
</sect1>

<sect1 id="overR007">
<title>R007&mdash;Packages</title>
<para>
We are very far from providing inter-distribution compatibility at the
package level, and it is likely that someone will get broken dependencies
if he/she mixes packages coming from different distributions.
</para>
<para>
This document will not try to fix package names nor proposed dependency
declarations for DocBook distributions. We however wanted to point out
a problem that may be encountered when packaging SGML or XML: the package
numbering scheme.
</para>
</sect1>
</chapter>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<chapter id="lsbsgml">
<title>LSB PROPOSAL: SGML & XML written specification addendum</title>

<abstract>
<para>
Enclosed is a proposal, submitted by Eric Bischoff,  for the LSB regarding
SGML & XML. A more general proposal has been submitted to the Filesystem
Heiarchy Specification workgroup to be adopted. It is proposed that the
enclosed detailed draft be adopted as an addendum to the LSB written
specification.  A new Sourceforge CVS module would be created so this
document would be initially maintained separately from the ongoing API/ABI
written specification.
</para>
</abstract>

<sect1 id="sgmlintro">
<title>Introduction</title>

<para>
In a normalisation effort, about thirty people, including packagers
of some Linux distributions, and developers of SGML related tools such
as the SGML-Tools and DocBook Tools project, discussed informally and
agreed on a series of recommendations that will be submitted as a draft
to the Linux Standard Base project. A reference implementation will also
be done as part of the DocBook-tools project.
</para>
<para>
This document's redaction started as an attempt to end the nightmare
of DocBook distributions, but it appeared quickly to be generic enough
to apply to any SGML or XML DTD. Explanations about the reasons
for all our choices are given in a separate document.
</para>

<para>
Following a list of definitions, you will find a set of recommendations:
<simplelist>
  <member>R001&mdash;SGML Directory layout</member>
  <member>R002&mdash;DocBook Directory layout (standard names for directories, their contents)</member>
  <member>R003&mdash;Open Catalogs usage for SGML</member>
  <member>R004&mdash;Open Catalogs usage for DocBook (for the centralized catalogs and for the individual catalogs)</member>
  <member>R005&mdash;Configuration files (other <filename class="directory">/etc/sgml</filename> files)</member>
  <member>R006&mdash;ISO-entities (file names and <acronym>FPI</acronym> declarations)</member>
  <member>R007&mdash;Packages (how to package this type of material)</member>
</simplelist>
</para>

<para>
We'd like to thank the following people who have participated intensively
in this normalisation effort:
<itemizedlist>
  <listitem>
  <para>Camille Begnis (MandrakeSoft) <email>camille@mandrakesoft.com</email></para>
  </listitem>
  <listitem>
  <para>Eric Bischoff (Caldera, KDE) <email>eric@caldera.de</email></para>
  </listitem>
  <listitem>
  <para>Karl Eichwalder (SuSE) <email>ke@suse.de</email></para>
  </listitem>
  <listitem>
  <para>Mark Galassi (DocBook-tools) <email>rosalia@lanl.gov</email></para>
  </listitem>
  <listitem>
  <para>Jorge Godoy (Conectiva) <email>godoy@conectiva.com.br</email></para>
  </listitem>
  <listitem>
  <para>Cees de Groot (SGML-tools) <email>cg@cdegroot.com</email></para>
  </listitem>
  <listitem>
  <para>Jochem Huhmann <email>joh@revier.com</email></para>
  </listitem>
  <listitem>
  <para>David Mason (RedHat, Gnome) <email>dcm@redhat.com</email></para>
  </listitem>
  <listitem>
  <para>Manoj Srivastava (Debian) <email>srivasta@datasync.com</email></para>
  </listitem>
  <listitem>
  <para>Norman Walsh (Sun, OASIS) <email>ndw@nwalsh.com</email></para>
  </listitem>
</itemizedlist>
and all the other many people that helped with their own contribution.
</para>

<glossary id="sgmlgloss">
<title>Definitions</title>

<para>
In the scope of this document, we will use the following terms:
</para>

  <glossentry><glossterm>backend</glossterm>
  <glossdef>
  <para>
       A part of a SGML converter used to analyse the output format
  </para>
  </glossdef>
  </glossentry>

  <glossentry><glossterm>Centralized catalog</glossterm>
  <glossdef>
  <para>
       An Open Catalog that includes only comments and CATALOG
       directives pointing to other catalogs (or DELEGATE directives
       if supported).
  </para>
  </glossdef>
  </glossentry>

  <glossentry><glossterm>frontend</glossterm>
  <glossdef>
  <para>
       A part of a SGML converter used to analyse the input format
  </para>
  </glossdef>
  </glossentry>

  <glossentry><glossterm>helper</glossterm>
  <glossdef>
  <para>
       A stand-alone application used by a SGML converter to accomplish
       the conversion itself.
  </para>
  </glossdef>
  </glossentry>

  <glossentry><glossterm>Open Catalog</glossterm>
  <glossdef>
  <para>
       A set of directives defined by OASIS, mostly used for defining
       equivalences between <acronym>FPI</acronym>s (Formal Public Identifiers) and real
       file names (see TR9401:1997 on <ulink url="http://www.oasis-open.org";>http://www.oasis-open.org</ulink>).
  </para>
  </glossdef>
  </glossentry>

  <glossentry><glossterm>Package</glossterm>
  <glossdef>
  <para>
       A set of files assembled together for distribution. It includes
       RPMs, DEBs and any other kind of packaging system.
  </para>
  </glossdef>
  </glossentry>

  <glossentry><glossterm>SGML application</glossterm>
  <glossdef>
  <para>
       Any program used to view, edit, convert, process or apply any
       kind of treatment to a document written using a SGML or XML DTD
       (Document Type Definition). This includes command-line utilities
       as well as GUI-based applications.
  </para>
  </glossdef>
  </glossentry>

  <glossentry><glossterm>SGML converter</glossterm>
  <glossdef>
  <para>
       A SGML application, or a part of a bigger SGML application,
       used to convert from a given SGML-based input format to a given
       output format.
  </para>
  </glossdef>
  </glossentry>

  <glossentry><glossterm>Style sheets</glossterm>
  <glossdef>
  <para>
       Declarations or scripts that define formatting during the
       conversion process.  They can be written in any style sheets
       language: DSSSL, FOSIs, XSL, &hellip;
  </para>
  </glossdef>
  </glossentry>

  <glossentry><glossterm>Super catalog</glossterm>
  <glossdef>
  <para>
       An Open Catalog pointing to all the centralized catalogs.
  </para>
  </glossdef>
  </glossentry>

</glossary>
</sect1>

<sect1 id="R001">
<title>R001&mdash;SGML Directory layout</title>

<variablelist>
<varlistentry>
<term><filename class="directory">/etc/sgml/</filename></term>
<listitem>
<para>
     Configuration files, including centralized catalogs.
</para>
<para>
     It includes:
<simplelist>
  <member><filename>*.conf</filename>: generic configuration files</member>
  <member><filename>sgml-docbook.cat</filename>, <filename>tei.cat</filename>, &hellip;: DTD-specific centralized catalogs</member>
  <member><filename>catalog</filename>: the super catalog</member>
  <member>&hellip;</member>
</simplelist>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><filename class="directory">/usr/share/sgml/</filename></term>
<listitem>
<para>
     Architecture-independent files used by SGML applications: Open
     Catalogs (not the centralized ones), DTDs, entities, style sheets,
     and other declarative files, if any.
</para>

<para>
     It is organized into DTD-specific subdirectories:
<simplelist>
  <member><filename class="directory">docbook/</filename></member>
  <member><filename class="directory">tei/</filename></member>
  <member><filename class="directory">html/</filename></member>
  <member>&hellip;</member>
</simplelist>
</para>
</listitem>
</varlistentry>
</variablelist>

<para>
At least for the present, all XML documents are also SGML
documents, so it seems unnecessary to create 
<filename class="directory">/usr/share/xml</filename> and <filename class="directory">/etc/xml</filename>.
</para>
</sect1>


<sect1 id="R002">
<title>R002&mdash;DocBook Directory layout</title>
<para>
This is the layout for a Jade-based or an Openjade-based system. DocBook
applications based on other parsers, or even any other SGML application,
can be based on this layout as well.
</para>
<para>
In <filename class="directory">/usr/share/sgml</filename>, the upper level directories identify the DTD that
is concerned. Things that are not DTD-specific go directly into
<filename class="directory">/usr/share/sgml</filename> under their own directory.
</para>
<para>

The lower level directories are package-related. They are
also version-numbered.

<variablelist>
  <varlistentry>
    <term><filename class="directory">/usr/share/sgml/</filename></term>
    <listitem>
    <para>
      <simplelist>
        <member><filename class="directory">sgml-iso-entities-8879.1986/</filename></member>
        <member><filename class="directory">xml-iso-entities-8879.1986/</filename></member>
        <member>(the ISO entities)</member>
        <member><filename class="directory">jade-1.2.1/</filename></member>
        <member><filename class="directory">openjade-1.3/</filename></member>
        <member>&hellip;</member>
        <member>(the parsers and DSSSL engines architecture-independent files)</member>
        <member>&hellip;</member>
      </simplelist>
    </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term><filename class="directory">/usr/share/sgml/docbook/</filename></term>
    <listitem>
    <para>
      <simplelist>
        <member><filename class="directory">sgml-dtd-3.1/</filename></member>
        <member><filename class="directory">sgml-dtd-4.0/</filename></member>
        <member><filename class="directory">xml-dtd-4.0/</filename> (the DocBook DTD)</member>
        <member><filename class="directory">dsssl-stylesheets-1.54/</filename></member>
        <member><filename class="directory">xsl-stylesheets-1.12/</filename> (DSSSL style sheets for DocBook)</member>
        <member><filename class="directory">kde-customization-0.1/</filename></member>
        <member><filename class="directory">gnome-customization-0.1/</filename></member>
        <member><filename class="directory">ldp-customization-0.1/</filename> (customized DTDs, entities and style sheets for the various projects)</member>
        <member>&hellip;</member>
      </simplelist>
      (version number examples are arbitrary in this list)
    </para>
    </listitem>
  </varlistentry>
</variablelist>

</para>
</sect1>

<sect1 id="R003">
<title>R003&mdash;Open Catalog usage for SGML</title>
<para>
Open Catalog files include:
<itemizedlist>
  <listitem>
    <para>the individual catalogs provided with the DTDs, sylesheets or entities.</para>
  </listitem>
  <listitem>
    <para>
    the centralized catalogs used as central source of information
    that is specific to docbook, tei, or any other DTD
    </para>
  </listitem>
  <listitem>
    <para>
    the super catalog that references indirectly all the available
    catalog files
    </para>
  </listitem>
</itemizedlist>

</para>
<para>
The centralized catalog file names must end in .cat and reside in
<filename class="directory">/etc/sgml</filename>.
They contain only comments and CATALOG directives pointing
to the <quote>real</quote> catalogs, like:
<programlisting>
     -- sample contents of /etc/sgml/foo-1.05.cat --
     CATALOG /usr/share/sgml/foo/xml-dtd-1.05/catalog
     CATALOG /usr/share/sgml/foo/xsl-stylesheets-0.1/catalog
</programlisting>

One can use DELEGATE instead of CATALOG if this directive is known to
be supported.

</para>
<para>
The centralized catalogs are DTD-specific and can be version-numbered.

</para>
<para>
Here are examples of such centralized catalogs:

<variablelist>
  <varlistentry>
  <term><filename class="directory">/etc/sgml/</filename></term>
  <listitem>
  <para>
    <simplelist>
       <member><filename>sgml-docbook.cat</filename></member>
       <member><filename>sgml-docbook-3.1.cat</filename></member>
       <member><filename>sgml-docbook-4.0.cat</filename></member>
       <member><filename>xml-docbook-4.0.cat</filename></member>
    </simplelist>
  </para>
  </listitem>
  </varlistentry>
</variablelist>

Version-less centralized catalogs could be only symbolic links to the
latest version (or to any other older version).

</para>
<para>
<filename class="directory">/etc/sgml/catalog</filename>
is the <quote>super catalog</quote>. It contains CATALOG pointers
to all the centralized catalogs:

<programlisting>
     -- sample contents of /etc/sgml/catalog --
     CATALOG /etc/sgml/sgml-docbook.cat
     CATALOG /etc/sgml/xhtml.cat
     CATALOG /etc/sgml/mathml.cat
</programlisting>

One can use DELEGATE instead of CATALOG if this directive is known to
be supported.

</para>
<para>
It should not point to centralized catalogs that are merely symbolic links
and therefore are already mentioned.

</para>
<para>
Users should be able to define their own centralized catalogs and
their own super catalog in their home directories:
<simplelist>
     <member><filename><envar>$HOME</envar>/.sgml-docbook.cat</filename></member>
     <member><filename><envar>$HOME</envar>/.catalog</filename></member>
</simplelist>

</para>
<para>
The SGML applications are not supposed to use centralized catalogs,
although their use is strongly encouraged: if other mechanisms allow
one to locate the real catalogs, they can be used as well. However
distribution packagers should always take care of feeding the right
entries into the super catalog and the centralized catalogs. The interface
for a script named <command>install-catalog</command>
that does these maintenance tasks is described here:

<cmdsynopsis>
  <command>install-catalog</command>
  <group><arg>--add</arg><arg>--remove</arg></group>
  <arg><replaceable>centralized_catalog</replaceable></arg>
  <arg><replaceable>ordinary_catalog</replaceable></arg>
</cmdsynopsis>

Example:

<informalexample>
<screen>
bash# install-catalog --add \
  /etc/sgml/sgml-docbook-3.1 \
  /usr/share/sgml/docbook/dsssl-stylesheets-1.54/catalog
</screen>
</informalexample>

The other catalogs should be placed in subdirectories of <filename class="directory">/usr/share/sgml</filename>.
They should all be named <filename>catalog</filename>. They are the ones who do the real
work of mapping the <acronym>FPI</acronym>s to file names (among other tasks).


</para>
</sect1>

<sect1 id="R004">
<title>R004&mdash;Open Catalog usage for DocBook</title>
<para>
This recomendation is merely a consequence of the preceeding
recomendations.
</para>
<para>
For a distribution of DocBook based on Jade or OpenJade, we suggest the
following names. Again, other SGML or XML DTDs can be based on this
structure.

<variablelist>
  <varlistentry>
    <term><filename class="directory">/etc/sgml/</filename></term>
    <listitem>
    <para>
      <simplelist>
        <member><filename>sgml-docbook.cat</filename></member>
        <member><filename>xml-docbook.cat</filename></member>
        <member><filename>sgml-docbook-3.0.cat</filename></member>
        <member><filename>sgml-docbook-3.1.cat</filename></member>
        <member><filename>sgml-docbook-4.0.cat</filename></member>
        <member><filename>xml-docbook-4.0.cat</filename></member>
      </simplelist>
    </para>
    </listitem>
  </varlistentry>
</variablelist>

<simplelist>
  <member><filename>/usr/share/sgml/sgml-iso-entities-8879.1986/catalog</filename></member>
  <member><filename>/usr/share/sgml/xml-iso-entities-8879.1986/catalog</filename></member>

  <member><filename>/usr/share/sgml/jade-1.2.1/catalog</filename></member>

  <member><filename>/usr/share/sgml/openjade-1.0/catalog</filename></member>

  <member><filename>/usr/share/sgml/docbook/sgml-dtd-3.0/catalog</filename></member>
  <member><filename>/usr/share/sgml/docbook/sgml-dtd-3.1/catalog</filename></member>
  <member><filename>/usr/share/sgml/docbook/sgml-dtd-4.0/catalog</filename></member>
  <member><filename>/usr/share/sgml/docbook/xsl-dtd-4.0/catalog</filename></member>

  <member><filename>/usr/share/sgml/docbook/dsssl-stylesheets-1.54/catalog</filename></member>
  <member><filename>/usr/share/sgml/docbook/xsl-stylesheets-1.12/catalog</filename></member>
</simplelist>


</para>
</sect1>

<sect1 id="R005">
<title>R005&mdash;Configuration files</title>
<para>

Other configuration files may also reside in <filename class="directory">/etc/sgml</filename>, either
DTD-specific or application-specific. Their name should end in <quote>.conf</quote> and
they should follow ordinary rules for files residing in <filename class="directory">/etc</filename> 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.


</para>
</sect1>

<sect1 id="R006">
<title>R006&mdash;Iso-entities</title>
<para>

The file names should be fixed to:
<simplelist type="horiz">
  <member><filename>ISOamsa.ent</filename></member>
  <member><filename>ISOamsb.ent</filename></member>
  <member>&hellip;</member>
</simplelist>

</para>
<para>
The identifiers should be fixed to:
     <literal>"ISO 8879:1986//ENTITIES Added Math Symbols: Arrow Relations//EN"</literal>

</para>
<para>
During the transitory period, symbolic links and duplicate declarations will
be allowed as a means of preserving compatibility with previous naming
schemes.


</para>
</sect1>

<sect1 id="R007">
<title>R007&mdash;Packages</title>
<para>

C programs can get compiled with any version of a given compiler. SGML
documents can't use any version of a given DTD. They need the
corresponding DTD to reside on the same system, or at least to be
reachable. The various versions of a given DTD in turn may imply certain
versions of the style sheets.
</para>
<para>
This leads to a unusual situation where the old DTDs and style sheets
should not be replaced during a package update.
</para>
<para>
We would like to make distribution packagers aware of the suggested solutions.
They may choose to:
<itemizedlist>
  <listitem>
  <para>put the version number in the package name field
   (example: <filename>docbook-dtd-3.1-1.0.rpm</filename>)
  </para>
  </listitem>
  <listitem>
  <para>not put the version number and use subpackages for each version
  </para>
  </listitem>
</itemizedlist>

</para>
</sect1>
</chapter>