ANNOUNCE: DocBook 5 XSL 1.72.0 released

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

The DocBook Project announces the first release of the DocBook 5 XSL 
Stylesheets in the SourceForge downloads area. The Docbook 5 XSL 1.72.0 
package is available for download from the project website:

  http://docbook.sf.net/files/docbook5-xsl/latest
  http://sourceforge.net/projects/docbook

The DocBook 5 XSL Stylesheets are the same as the regular 1.72.0 stylesheet 
release except that the templates match on elements in the DocBook 
namespace.  Below is the README included with the package.


DocBook 5 XSL stylesheets
===========================================
This package contains a release of XSL stylesheets
for processing DocBook 5 documents.  The stylesheets are
the same as the concurrent stylesheet release except that
the templates match on elements in the DocBook namespace.

Note, the stylesheets in these directories have
not yet been converted to use the DocBook 5 namespace:

  slides
  website
  roundtrip


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 a DocBook XSL
snapshot.  Each xsl file was processed with a
Perl script and its output placed in a parallel
directory tree.  Any non-xsl files were simply copied
into place.

Perl was used because of its excellent regular expression
handling, and because Perl is able to preserve all whitespace.
This retains the pretty-printed format that makes
the stylesheets easier to read and understand.

The stylesheet transforms each XSL match, select, test,
count, from, use, and elements 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
--------------------------------
A DocBook 5 document has the DocBook namespace declaration
in the root element, along with the version attribute:

  <book xslns="http://docbook.org/ns/docbook"; version="5.0">

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 (except for slides, website,
and roundtrip).

If you happen to process a DocBook document whose root 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.


Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs@sagehill.net