Re: Detecting stylesheets and DTDs

[Daniel Veillard <veillard redhat com>]

On Sat, Jan 19, 2002 at 08:35:37PM -0700, John Fleck wrote:
> On Sat, Jan 19, 2002 at 07:02:42PM -0500, Havoc Pennington wrote:
> > 
> > Hi,
> > 
> > Is the real root problem that we don't have a canonical upstream
> > stylesheet/dtd package, and that these packages therefore seem to vary
> > by distribution?
> > 
> 
> Yes.

  But it should not matter how/where they are installed as long as they are
registered in the XML Catalog (rooted in /etc/xml/catalog). 
All distributions provides those stylesheets, none build the catalog yet,
though we expect next versions to integrate this.

  The main problem is that most people writing documentation hardcode the
paths in the stylesheets, DTD and documents. They took the habit of
doing direct references to /usr/share/foo/bar/docbookx.dtd for example
and of course this is not portable. The right way is to keep canonical
Public ID (like "-//OASIS//DTD DocBook XML V4.1.2//EN") and System ID/URIs
(like "http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl";)
and have the catalog system do the lookup.

  All libxml2 and libxslt recent releases have automatic support for the
XML Catalog system. there is also the xmlcatalog tool used to query and
maintain (add/remove entries) the Catalog tree.

  If like Jody suggest a document author wants a specific customization
of the stylesheet the rules are simple:
   1/ keep the customization in the application part of the install
      tree like /usr/share/gnumeric/styesheets
   2/ force the author to USE CANONONICAL NAMES Public ID/System ID/URIs when
      referencing other parts of the infrastructure (DTd and stylesheets).
      If you're putting $prefix/foo/bar/my.xsl in the system IDs or URIs
      of those document, there is *no* way to make them reliable, and
      I don't want to take any bug report or long term help commitment
      on the whole documentation infrastructure. It DOES NOT WORK, if you
      don't believe me at least read what Norman Walsh has to say about this !
      http://www.arbortext.com/Think_Tank/XML_Resources/Issue_Three/issue_three.html
      (the examples are about SGML catalogs but the principle is the same).
   3/ if general customization for the Gnome project are needed then
      give them Canonical Public ID/System ID/URIs (rooted in the 
      http://gnome.org/ URI space, and making sure they are available on-line)
      and register them in the Catalog system

  The script simply fills the missing part from the distribution level of
adding the DocBook resources in the XML Catalog. It is possible to query
if the XML Catalog has those resources (using xmlcatalog). If not the script
should be sufficient to add them and have a reliable and portable
infrastructure to build our XML documentation.

  Related resources:
     - the libxml documentation on XML Catalog
       http://xmlsoft.org/catalog.html
       which itself points to more related resources
     - the xmlcatalog tool man page
       http://www.xmlsoft.org/xmlcatalog_man.html
     - LSB SGML/XML mailing list archives
       https://lists.dulug.duke.edu/pipermail/lsb-xml-sgml/
     - the XML Catalog specification
       http://www.oasis-open.org/committees/entity/spec-2001-08-06.html

Daniel

-- 
Daniel Veillard      | Red Hat Network https://rhn.redhat.com/
veillard redhat com  | libxml Gnome XML XSLT toolkit  http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/