SourceForge DocBook Project: DocBook 5 XSL Stylesheets

SourceForge DocBook Project Announces First Release of the DocBook 5 XSL Stylesheets

Date:      Wed, 24 Jan 2007 00:51:45 -0800
From:      Bob Stayton <bobs@sagehill.net>
To:        DocBook Apps <docbook-apps@lists.oasis-open.org>
Subject:   DocBook 5 XSL 1.72.0 released

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:

You can write customization layers using the DocBook namespace.
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

DocBook V5.x — "The version 5.0 release is a complete rewrite of DocBook in RELAX NG. The intent of this rewrite is to produce a schema that is true to the spirit of DocBook while simultaneously removing inconsistencies that have arisen as a natural consequence of DocBook's long, slow evolution. The Technical Committee has taken this opportunity to simplify a number of content models and tighten constraints where RELAX NG makes that possible. The Technical Committee provides the DocBook 5.0 schema in other schema languages, including W3C XML Schema and an XML DTD, but the RELAX NG Schema is the normative schema."

Additional DocBook References

Prepared by Robin Cover for The XML Cover Pages archive.

SEARCH Advanced Search ABOUT Site Map CP RSS Channel Contact Us Sponsoring CP About Our Sponsors NEWS Cover Stories Articles & Papers Press Releases CORE STANDARDS XML SGML Schemas XSL/XSLT/XPath XLink XML Query CSS SVG TECHNOLOGY REPORTS XML Applications General Apps Government Apps Academic Apps EVENTS LIBRARY Introductions FAQs Bibliography Technology and Society Semantics Tech Topics Software Related Standards Historic	SourceForge DocBook Project: DocBook 5 XSL Stylesheets SourceForge DocBook Project Announces First Release of the DocBook 5 XSL Stylesheets Date: Wed, 24 Jan 2007 00:51:45 -0800 From: Bob Stayton <bobs@sagehill.net> To: DocBook Apps <docbook-apps@lists.oasis-open.org> Subject: DocBook 5 XSL 1.72.0 released 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: You can write customization layers using the DocBook namespace. 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 DocBook V5.x — "The version 5.0 release is a complete rewrite of DocBook in RELAX NG. The intent of this rewrite is to produce a schema that is true to the spirit of DocBook while simultaneously removing inconsistencies that have arisen as a natural consequence of DocBook's long, slow evolution. The Technical Committee has taken this opportunity to simplify a number of content models and tighten constraints where RELAX NG makes that possible. The Technical Committee provides the DocBook 5.0 schema in other schema languages, including W3C XML Schema and an XML DTD, but the RELAX NG Schema is the normative schema." Additional DocBook References DocBook.org DocBook Technical Committee Document Repository OASIS DocBook TC DocBook FAQ DocBook Wiki SourceForge DocBook Project DocBook 5.0: The Definitive Guide DocBook - Wikipedia article Prepared by Robin Cover for The XML Cover Pages archive.