DocBook Title Pages with XSLT 2.0

XSLT 2.0 is around the corner (it’s probably a little too early to describe it as “just around the corner”) and I’ve started to think about how the DocBook XSL Stylesheets might be improved in an XSLT 2.0 version. (No, the XSLT 1.0 version isn’t going away any time soon, have no fear.)

One of the things that I’d like to address is the clumsy way that title pages are currently handled. One goal of the stylesheets is to allow end users to customize them without becoming XSLT template-writing wizards. There’s no question that if you’re an XSLT hack, you can do almost anything: the trick is arranging things so that the average mortal can do stuff too.

Lots of customizations: double sided printing, admonition graphics, section numbering, etc., can be achieved with simple parameters, but title pages don’t fall into that category. There’s a lot of variation possible in title pages and no easy way to describe it in terms of scalar parameters.

The current solution is to write an XML document that contains a template that describes the title page you’d like, then process that template with a stylesheet to produce a stylesheet that you actually incorporate into your customization (yet another stylesheet) which you use to produce your output. That’s way too many steps, way to much complexity. The stylesheet produced from the template, by the way, is a horrifying thing.

I think we can do better now. Let’s begin by making three simplifying assumptions:

Let’s start with a parameter to describe the title page. How does this look?

<xsl:param name="preface.titlepage.recto">
  <div class="titlepage">
    <db:title/>
    <db:subtitle/>
    <db:pubdate/>
    <db:author/>
    <db:releaseinfo role="cvs"/>
    <db:copyright/>
    <db:abstract/>
  </div>
  <hr/>
</xsl:param>

That says that the title page for a Preface should be wrapped in a <div class="titlepage"> tag, should include title, subtitle, publication date, author, release info identified as “cvs” with the role attribute, copyright, and abstract elements, and should be separated from the rest of the document with an <hr/>.

The idea is that the structure of the title page (the div and <hr/> in this case) is written just the way the customizer wants it. When the stylesheet processes this parameter, it will replace each of the DocBook elements with the result of processing the matching element from the source document.

Unfortunately, it isn’t quite that simple. Some elements, like bibliography, have an optional title. If it isn’t specified in the source document, we need to provide a default. Unfortunately, if it isn’t in the source document, there isn’t going to be any element to match, so we’re going to have to be able call named templates. A couple of attributes from another namespace will provide that functionality:

<xsl:param name="bibliography.titlepage.recto">
  <div class="titlepage">
    <db:title t:named-template="component.title"
              t:force="1"/>
    <db:subtitle/>
  </div>
  <hr/>
</xsl:param>

That’s not too bad.

Ideally, the only thing a customizer should have to do is redefine the appropriate title page template.

Now, before we get started, you might be wondering why we don’t just put all the markup in this template. Like this, perhaps:

<xsl:param name="preface.titlepage.recto">
  <div class="titlepage">
    <h1><db:title/></h1>
    <h2><db:subtitle/></h2>
    <h3>Published on: <db:pubdate/></h3>
    <h3>By <db:author/></h3>
    <h4><db:releaseinfo role="cvs"/></h4>
    <h4><db:copyright/></h4>
    <div class="abstract">
      <db:abstract/>
    </div>
  </div>
  <hr/>
</xsl:param>

The problem is that some elements can be repeated, and sometimes at different levels (e.g. authorgroup vs. author). Consider a document with multiple authors, you probably wouldn’t want to repeat the generated text “By ” in front of each of them. Any system rich enough to handle that much complexity would, I fear, become as complex as writing the XSLT by hand. So instead, we rely on XSLT templates for each of the individual elements to generate the markup for that element, and we hope that the supplied defaults work most of the time.

Ok, back to work. How are we going to process our template parameter?

First, we have to make sure something gets called to do the processing, so at the beginning of each XSLT template for an element that can have a title page (book, preface, …, bibliography, etc.) we call a titlepage template. Here’s what a template for preface might look like:

<xsl:template match="db:preface">
  <div class="preface">
    <xsl:call-template name="titlepage">
      <xsl:with-param name="info"
                      select="db:title|db:subtitle|db:titleabbrev|db:info/*"/>
      <xsl:with-param name="content" select="$preface.titlepage.recto"/>
    </xsl:call-template>

    <xsl:call-template name="titlepage">
      <xsl:with-param name="side" select="'verso'"/>
      <xsl:with-param name="info"
                      select="db:title|db:subtitle|db:titleabbrev|db:info/*"/>
      <xsl:with-param name="content" select="$preface.titlepage.verso"/>
    </xsl:call-template>

    <xsl:apply-templates/>
  </div>
</xsl:template>

The titlepage named-template looks like this:

<xsl:template name="titlepage">
  <xsl:param name="side" select="'recto'" as="xs:string"/>
  <xsl:param name="info" as="element()*"/>
  <xsl:param name="content"/>

  <xsl:if test="$content instance of document-node()">
    <xsl:apply-templates select="$content" mode="titlepage-templates">
      <xsl:with-param name="side" select="$side" tunnel="yes"/>
      <xsl:with-param name="node" select="." tunnel="yes"/>
      <xsl:with-param name="info" select="$info" tunnel="yes"/>
    </xsl:apply-templates>
  </xsl:if>
</xsl:template>

XSLT 2.0 features aside, the practical upshot of titlepage is that it processes each of the elements of the title page parameter in “titlepage-templates” mode.

In titlepage-templates mode, anything not in the DocBook namespace is just passed straight through. But we need to do some extra work for DocBook elements:

<xsl:template match="db:*" mode="titlepage-templates" priority="1000">
  <xsl:param name="side" tunnel="yes"/>
  <xsl:param name="node" tunnel="yes"/>
  <xsl:param name="info" tunnel="yes"/>

  <xsl:variable name="this" select="."/>
  <xsl:variable name="content" select="$info[dbf:node-matches($this,.)]"/>

  <xsl:choose>
    <xsl:when test="@t:named-template">
      <xsl:if test="$content or (@t:force and @t:force != 0)">
        <xsl:call-template name="titlepage-templates">
          <xsl:with-param name="template" select="@t:named-template" tunnel="yes"/>
          <xsl:with-param name="content" select="$content" tunnel="yes"/>
          <xsl:with-param name="this" select="$this" tunnel="yes"/>
        </xsl:call-template>
      </xsl:if>
    </xsl:when>
    <xsl:otherwise>
      <!-- $content may be empty -->
      <xsl:apply-templates select="$content" mode="titlepage.mode"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>

The node-matches function looks like this:

<xsl:function name="dbf:node-matches" as="xs:boolean">
  <xsl:param name="template-node" as="element()"/>
  <xsl:param name="document-node" as="element()"/>

  <xsl:choose>
    <xsl:when test="node-name($template-node) = node-name($document-node)">
      <xsl:variable name="attrMatch">
        <xsl:for-each select="$template-node/@*[namespace-uri(.) = '']">
          <xsl:variable name="aname" select="local-name(.)"/>
          <xsl:variable name="attr" select="$document-node/@*[local-name(.) = $aname]"/>
          <xsl:choose>
            <xsl:when test="$attr = .">1</xsl:when>
            <xsl:otherwise>0</xsl:otherwise>
          </xsl:choose>
        </xsl:for-each>
      </xsl:variable>

      <xsl:choose>
        <xsl:when test="not(contains($attrMatch, '0'))">
          <xsl:value-of select="dbf:user-node-matches($template-node, $document-node)"/>
        </xsl:when>
        <xsl:otherwise>
          <xsl:value-of select="false()"/>
        </xsl:otherwise>
      </xsl:choose>
    </xsl:when>
    <xsl:otherwise>
      <xsl:value-of select="false()"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:function>

If the node matches, we call user-node-matches, which gives the customizer an opportunity to add additional selection criteria. The default implementation of user-node-matches always returns true().

The titlepage-templates template looks like this:

<xsl:template name="titlepage-templates">
  <xsl:param name="side" tunnel="yes"/>
  <xsl:param name="node" tunnel="yes"/>
  <xsl:param name="info" tunnel="yes"/>
  <xsl:param name="template" tunnel="yes"/>
  <xsl:param name="content" tunnel="yes"/>
  <xsl:param name="this" tunnel="yes"/>

  <xsl:choose>
    <xsl:when test="$template = 'component.title'">
      <xsl:call-template name="component.title"/>
    </xsl:when>
    <xsl:otherwise>
      <xsl:call-template name="user-titlepage-templates"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>

XSLT doesn’t allow template names to be dynamically constructed, so our mechanism for calling the named template identified in t:named-template devolves into a big xsl:choose statement. The user-titlepage-templates is an extension point for customizers that add a new name. The default implementation of user-titlepage-templates terminates the stylesheet.

That’s the bulk of the work. Each template for a DocBook element in “titlepage.mode” is passed three parameters: the side, the node, and the set of info elements.

To see all these bits in action, run this example through your favorite XSLT 2.0 processor. The input document is irrelevant, it always uses an internal document as its test data.

Disclaimer: the stylesheets, like DocBook itself, are very much a group effort and these scribblings are just my initial thoughts; they are subject to change. Though if they do change, I’ll try to write about that too.

In terms of XSLT 2.0, I don’t know which is more interesting, the fact that I used so few type-related features, or the fact that I used any at all. The few that I did use could easily be removed.

Could it be done in XSLT 1.0? Yes, probably, with the node-set extension function and a fair bit of cleverness to replace the node-matches stylesheet function.