Experimental DocBook5 namespace-aware stylesheets

["Bob Stayton" <bobs@sagehill.net>]

I've put together a copy of the DocBook XSL stylesheets in which the 
DocBook V5 namespace is used in element matches.  These stylesheets handle 
the DocBook 5 namespace natively, rather than using the nodeset() function 
to strip it out so the elements can be processed with the existing 
namespace-free templates. Avoiding the nodeset step avoids losing the 
xml:base of the document, among other things.  Also, with these stylesheets 
you can write a customization layer that uses the namespace in element 
matches.

I did this because I wanted to get more experience writing customization 
layers for DocBook 5 documents, using the namespace directly.  I figured if 
we are going to have a namespace, let's use it!

This is an experimental release, available for download only from my 
website at this time:

http://www.sagehill.net/xml/docbook5ns/

I'll be curious to hear if others find this useful.
Here is the README that is included in the zip file:

Experimental DocBook 5 XSL stylesheets
===========================================
Bob Stayton
2 October 2006

This package contains an experimental set of XSL stylesheets
for processing DocBook 5 documents.  The stylesheets are
the same as the existing 1.71.0 stylesheets except that
the templates match on elements in the DocBook namespace.
The current set includes namespace-aware stylesheets for
html, xhtml, fo, htmlhelp, javahelp, manpages, profiling.


Background
-------------
DocBook 5 differs from preceding versions of DocBook because
its elements are in a namespace "http://docbook.org/ns/docbook";.
Because the elements are in a namespace, the regular
DocBook XSL templates do not match on the elements.
In XSLT, a match attribute must explicitly specify
the namespace prefix to match an element in that namespace
(the default namespace does not apply to pattern matches).

The regular stylesheets are able to process DocBook 5
documents now, because they preprocess a DB5 document to
remove the namespace.  When the regular stylesheet
detects that the root element is in the namespace, it
processes the document with mode="stripNS" to copy all
the nodes to a variable, but without the DocBook namespace.
Then it converts the variable to a nodeset, and processes
the nodeset with the regular templates.

The alternative approach is to create a set of templates
that match on the native namespace of DocBook 5 documents.
These stylesheets do that.

These stylesheets completely mimic the behavior of the
existing stylesheets.  These are not XSLT 2.0 stylesheets,
and they do not have any other significant changes than handling
the namespaced elements.

The two main advantages of these stylesheets are:

a. You can write customization layers using the DocBook namespace.

b. The xml:base of the root element is not lost during processing
(so things like images and the olink database can be found
more easily).


How these stylesheets were produced
----------------------------------------
These stylesheets were created from the DocBook XSL 1.71.0
distribution.  Each xsl file was processed with an
XSLT stylesheet and its output placed in a parallel
directory tree.  Any non-xsl files were simply copied
into place.

The stylesheet transforms each match, select, and test
attribute to add a "d:" prefix to each element referenced in
the attribute.  For example:

  <xsl:template match="para">

becomes:

  <xsl:template match="d:para">

In addition, each stylesheet file has a namespace declaration
added in its root element:

  <xsl:stylesheet  xslns:d="http://docbook.org/ns/docbook";

The combination of these two changes means that the templates
now recognize DocBook 5 elements in their native namespace.


How to use these stylesheets
--------------------------------
You can process a DocBook 5 document with these stylesheets
using any XSLT processor, including xsltproc, Saxon 6 or 8,
and Xalan.  Use these stylesheets as you would a stylesheet
from the regular distribution.

If you happen to process a DocBook document whose element
is without the namespace declaration, the stylesheet
does not fail.  Rather, it detects that the document
does not have the namespace, and preprocesses it to add the
namespace declaration to all elements in the document.
In a manner similar to stripNS, it copies the elements
to a variable while adding the namespace, converts the
variable to a nodeset, and then processes the nodeset with
the namespace-aware templates.

If the stylesheet encounters an element from your file
for which the stylesheet has no matching template,
it reports the unmatched element.  In these stylesheets,
it also reports the namespace URI that the element has.


Customizing these stylesheets
--------------------------------
These stylesheets are customized with a customization
layer in the same manner as for the regular stylesheets,
with two differences.

When you create a customization layer, you must do two things:

a.  Add the namespace declaration (with a prefix of your choice):

  <xsl:stylesheet  xslns:d="http://docbook.org/ns/docbook";

b.  Use the namespace prefix on all DocBook element names:

  <xsl:template match="d:formalpara">

Be sure to include the namespace prefix on all element
references, including those in match, select, and test
attributes, even when using an axis specifier.  Here are
some examples:

  <xsl:if test="d:title">

  <xsl:apply-templates select="d:title" mode="list.title.mode"/>

  <xsl:apply-templates
       select="*[not(self::d:listitem or self::d:title
               or self::d:titleabbrev)] |
               comment()[not(preceding-sibling::d:listitem)] |
               processing-instruction()[not(preceding-sibling::d:listitem)]"/>

Failure to add the prefix to an element name will cause
the stylesheet to silently not match the intended element,
with consequences that are most likely undesirable.


Report any problems
------------------------
These are experimental stylesheets and need thorough testing.
Please report any problems to bobs@sagehill.net.


Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs@sagehill.net