Recommendations for DocBook, SGML and XML processing
----------------------------------------------------

Introduction
------------

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.

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.

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

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


Definitions
-----------

In the scope of this document, we will use the following terms:

SGML application:
	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.

SGML converter:
	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.

frontend:
	A part of a SGML converter used to analyse the input format

backend:
	A part of a SGML converter used to analyse the output format

helper:
	A stand-alone application used by a SGML converter to accomplish
	the conversion itself.

Style sheets:
	Declarations or scripts that define formatting during the
	conversion process.  They can be written in any style sheets
	language: DSSSL, FOSIs, XSL, ...

Open Catalog:
	A set of directives defined by OASIS, mostly used for defining
	equivalences between FPIs (Formal Public Identifiers) and real
	file names (see TR9401:1997 on <A  HREF="http://www.oasis-open.org">http://www.oasis-open.org</A>).

Centralized catalog:
	An Open Catalog that includes only comments and CATALOG
	directives pointing to other catalogs (or DELEGATE directives
	if supported).

Super catalog:
	An Open Catalog pointing to all the centralized catalogs.

Package:
	A set of files assembled together for distribution. It includes
	RPMs, DEBs and any other kind of packaging system.


R001 - SGML Directory layout
----------------------------

/etc/sgml/
	Configuration files, including centralized catalogs.

	It includes:
	*.conf: generic configuration files
	sgml-docbook.cat, tei.cat, ...: DTD-specific centralized catalogs
	catalog: the super catalog
	...
	
/usr/share/sgml/
	Architecture-independent files used by SGML applications: Open
	Catalogs (not the centralized ones), DTDs, entities, style sheets,
	and other declarative files, if any.

	It is organized into DTD-specific subdirectories:
	docbook/
	tei/
	html/
	...

At least for the present, all XML documents are also SGML
documents, so it seems unnecessary to create /usr/share/xml and /etc/xml.


R002 - DocBook Directory layout
-------------------------------

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.

In /usr/share/sgml, the upper level directories identify the DTD that
is concerned. Things that are not DTD-specific go directly into
/usr/share/sgml under their own directory.

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

/usr/share/sgml/
	sgml-iso-entities-8879.1986/
	xml-iso-entities-8879.1986/
		(the ISO entities)
	jade-1.2.1/
	openjade-1.3/
	...
                (the parsers and DSSSL engines
		 architecture-independent files)
	...

/usr/share/sgml/docbook/
        sgml-dtd-3.1/
        sgml-dtd-4.0/
        xml-dtd-4.0/
                (the DocBook DTD)
        dsssl-stylesheets-1.54/
        xsl-stylesheets-1.12/
                (DSSSL style sheets for DocBook)
        kde-customization-0.1/
        gnome-customization-0.1/
        ldp-customization-0.1/
                (customized DTDs, entities and style sheets for
		 the various projects)
	...

(version number examples are arbitrary in this list)


R003 - Open Catalog usage for SGML
----------------------------------

Open Catalog files include:
- the individual catalogs provided with the DTDs, sylesheets or entities.
- the centralized catalogs used as central source of information
  that is specific to docbook, tei, or any other DTD
- the super catalog that references indirectly all the available
  catalog files

The centralized catalog file names must end in .cat and reside in
/etc/sgml.  They contain only comments and CATALOG directives pointing
to the "real" catalogs, like:

	-- 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

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

The centralized catalogs are DTD-specific and can be version-numbered.

Here are examples of such centralized catalogs:
/etc/sgml/
	sgml-docbook.cat
	sgml-docbook-3.1.cat
	sgml-docbook-4.0.cat
	xml-docbook-4.0.cat

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

/etc/sgml/catalog is the "super catalog". It contains CATALOG pointers
to all the centralized catalogs:

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

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

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

The users should be able to define their own centralized catalogs and
their own super catalog in their home directories:
	$HOME/.sgml-docbook.cat
	$HOME/.catalog

The SGML applications are not supposed to use centralized catalogs,
although their use is stronlgy 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 "install-catalog" that does these maintenance tasks
is described here:
	
        install-catalog --add|--remove &lt;centralized_catalog&gt; &lt;ordinary_catalog&gt;

Example:

        install-catalog --add \
		/etc/sgml/sgml-docbook-3.1 \
		/usr/share/sgml/docbook/dsssl-stylesheets-1.54/catalog

The other catalogs should be placed in subdirectories of /usr/share/sgml.
They should all be named "catalog". They are the ones who do the real
work of mapping the FPIs to file names (among other tasks).


R004 - Open Catalog usage for DocBook
-------------------------------------

This recomendation is merely a consequence of the preceeding
recomendations.

For a Jade- or Openjade-based distribution of DocBook, we suggest the
following names. Again, other SGML or XML DTDs can be based on this
structure.

/etc/sgml/
	sgml-docbook.cat
	xml-docbook.cat
	sgml-docbook-3.0.cat
	sgml-docbook-3.1.cat
	sgml-docbook-4.0.cat
	xml-docbook-4.0.cat

/usr/share/sgml/sgml-iso-entities-8879.1986/catalog
/usr/share/sgml/xml-iso-entities-8879.1986/catalog

/usr/share/sgml/jade-1.2.1/catalog

/usr/share/sgml/openjade-1.0/catalog

/usr/share/sgml/docbook/sgml-dtd-3.0/catalog
/usr/share/sgml/docbook/sgml-dtd-3.1/catalog
/usr/share/sgml/docbook/sgml-dtd-4.0/catalog
/usr/share/sgml/docbook/xsl-dtd-4.0/catalog

/usr/share/sgml/docbook/dsssl-stylesheets-1.54/catalog
/usr/share/sgml/docbook/xsl-stylesheets-1.12/catalog


R005 - Configuration files
--------------------------

Other configuration files may also reside in /etc/sgml, either
DTD-specific or application-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.


R006 - Iso-entities
-------------------

The file names should be fixed to:
	ISOamsa.ent ISOamsb.ent ...

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

In the transitory period, symbolic links and duplicate declarations will
be allowed as a means to preserve the compatibility with previous naming
schemes.


R007 - Packages
---------------

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.

This leads to a unusual situation where the old DTDs and style sheets
should not be replaced during a package update.

We would like to make the solutions to achieve this aware to distribution
packagers. They may choose to:
 - put the version number in the package name field
   (example: docbook-dtd-3.1-1.0.rpm)
 - not put the version number and use subpackages for each version