4 Publishing DocBook Documents

$Revision: 7801 $

$Date: 2008-03-03 12:34:51 -0500 (Mon, 03 Mar 2008) $

Creating and editing 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.

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 front-runners:

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

XSL 1.0 is well-established and is probably the most common styling technology for DocBook. XSL 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 Formatting Objects are an XML vocabulary for describing constraints on page layout.

XQuery

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

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:

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

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

@namespace "http://docbook.org/ns/docbook"

para              { display: block }
emphasis          { display: inline;
                    font-style: italic; }
emphasis emphasis { display: inline;
                    font-style: upright; }

Namespace selection in CSS is widely supported, but not yet a standard.

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

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/XSL/Transform/1.0"
                xmlns:fo="http://www.w3.org/XSL/Format/1.0"
                version="1.0">

<xsl:template match="para">   
  <fo:block>
    <xsl:apply-templates/>  
  </fo:block>
</xsl:template>  

<xsl:template match="emphasis">
  <fo:sequence font-style="italic">
    <xsl:apply-templates/>  
  </fo:sequence>
</xsl:template>  

<xsl:template match="emphasis/emphasis">
  <fo:sequence font-style="upright">
    <xsl:apply-templates/>  
  </fo:sequence>
</xsl:template>  

</xsl:stylesheet>

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

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

FIXME: WRITE THIS

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

Using XSL to Publish DocBook Documents

For a detailed discussion of using XSL to publish DocBook documents, see DocBook XSL: The Complete Guide by Bob Stayton.