Publishing DocBook Documents

$Revision$

Creating and validating XML documents is usually only half the battle. After you’ve composed your document, you’ll want to publish it. Publishing, for our purposes, means either print or web publishing. For XML documents, this is usually accomplished with some kind of stylesheet. In some environments, it is now possible to publish an XML document on the Web simply by putting it online with a stylesheet.

1. A Survey of Stylesheet Languages

Over the years, a number of attempts have been made to produce a standard stylesheet language and, failing that, a large number of proprietary languages have been developed. Since this book was first written, three standards have emerged as the clear frontrunners:

CSS

The W3C CSS Working Group created CSS as a style attachment language for HTML. It has also been advanced as a stylesheet language for XML. Some browsers will style arbitrary XML with CSS and some commercial products exist that will render XML+CSS either online or in print.

XSL

XSLT 1.0 is well established and is probably the most common styling technology for DocBook. XSLT 2.0 offers a number of important new features (at the expense of some complexity, naturally) and is growing in popularity.

It’s worth observing that there are two, related technologies in play here. XSLT 1.0 and 2.0, the transformation languages, and XSL Formatting Objects (XSL-FO). XSL-FO is an XML vocabulary for describing constraints on page layout.

XQuery

XQuery 1.0, developed in parallel with XPath 2.0, provides a different set of features than XSL, but can be used to transform DocBook into other formats.

1.1. Stylesheet Examples

By way of comparison, here’s an example of each of the standard style languages. In each case, the stylesheet fragment shown contains the rules that reasonably formatted the following paragraph:

  1 <para>This is an example paragraph. It should be presented in a
  2 reasonable body font. <emphasis>Emphasized</emphasis> words
    should be printed in italics. A single level of 
  4 <emphasis>Nested <emphasis>emphasis</emphasis> should also
    be supported.</emphasis>
  6 </para>

1.1.1. CSS stylesheet

CSS stylesheets consist of selectors and formatting properties, as shown in Example 4.1, “A fragment of a CSS stylesheet”.

Example 4.1. A fragment of a CSS stylesheet

  1 @namespace "http://docbook.org/ns/docbook"
  2 
    para              { display: block }
  4 emphasis          { display: inline;
                        font-style: italic; }
  6 emphasis emphasis { display: inline;
                        font-style: normal; }

As this edition is being written, namespace selection in CSS, while widely supported, is still a Candidate Recommendation at W3C.

1.1.2. XSL stylesheet

XSL stylesheets are XML documents, as shown in Example 4.2, “A fragment of an XSL stylesheet”. The element in the XSL stylesheet that controls the presentation of specific elements is the xsl:template element.

Example 4.2. A fragment of an XSL stylesheet

  1 <?xml version='1.0'?>
  2 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                    xmlns:fo="http://www.w3.org/1999/XSL/Format"
  4                 xmlns:db="http://docbook.org/ns/docbook"
                    version="1.0">
  6 
    <xsl:template match="db:para">   
  8   <fo:block>
        <xsl:apply-templates/>  
 10   </fo:block>
    </xsl:template>  
 12 
    <xsl:template match="db:emphasis">
 14   <fo:inline font-style="italic">
        <xsl:apply-templates/>  
 16   </fo:inline>
    </xsl:template>  
 18 
    <xsl:template match="db:emphasis/db:emphasis">
 20   <fo:inline font-style="normal">
        <xsl:apply-templates/>  
 22   </fo:inline>
    </xsl:template>  
 24 
    </xsl:stylesheet>

A complete stylesheet for generating an entire XSL-FO document would require additional boilerplate text not shown.

1.1.3. XQuery

XQuery is expressed in a mixture of text and XML fragments, as shown in Example 4.3, “A fragment of XQuery”.

Example 4.3. A fragment of XQuery

  1 xquery version "1.0";
  2 
    declare default function namespace "http://www.w3.org/2005/xpath-functions";
  4 
    declare namespace db="http://docbook.org/ns/docbook";
  6 declare namespace fo="http://www.w3.org/1999/XSL/Format";
    
  8 declare function local:convert($node as node()) as node()* {
      if (empty($node))
 10   then
        ()
 12   else
        typeswitch ($node)
 14       case text() return $node
          case document-node() return local:convert($node/node())
 16       case element(db:para) return local:para($node)
          case element(db:emphasis) return local:emphasis($node)
 18       default return ("ERROR: UNEXPECTED NODE", local:convert($node/node()))
    };
 20 
    declare function local:para($node as element()) as element() {
 22   <fo:block>
        { local:convert($node/node()) }
 24   </fo:block>
    };
 26 
    declare function local:emphasis($node as element()) as element() {
 28   if ($node/parent::db:emphasis)
      then
 30     <fo:inline font-style="normal">
          { local:convert($node/node()) }
 32     </fo:inline>
      else
 34     <fo:inline font-style="italic">
          { local:convert($node/node()) }
 36     </fo:inline>
    };

A complete query for generating an XSL-FO document would require additional boilerplate text not shown.

2. Using XSL to Publish DocBook Documents

The community of people using DocBook has created a set of open source XSL stylesheets that are maintained at Sourceforge.net. These stylesheets can be used to transform DocBook XML into a wide variety of formats, including HTML, Javahelp, XSL-FO (for processing into print), ePub, and HTML help.

For a detailed discussion of using XSL to publish DocBook documents, see DocBook XSL: The Complete Guide [Stayton07].