2.3. Writing Customization Layers
Prev Chapter 2. Common Customizations Next

2.3. Writing Customization Layers

Difficulty: ★★☆ (medium)
Keyword: customization layer

Problem

You want to write a customization layer for the DocBook XSL stylesheets, but you do not know how to do it.

Solution

A DocBook XSL customization layer comprises the following components:

  • An XSLT stylesheet skeleton with the start tag <xsl:stylesheet> and the end tag </xsl:stylesheet>

  • At least the namespaces for XSLT, DocBook 5, and your output format (for example, FO or XHTML).

  • An <xsl:import/> element to incoporate the base DocBook XSLT stylesheet.

  • Your customizations (parameters, variables, templates, or other imports).

How this can look is shown in the following listing.

Example 2.1. General Customization Layer
Download File 'dbcustomize/docbook-customization.xsl'
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:d="http://docbook.org/ns/docbook">

  <xsl:import href="https://cdn.docbook.org/release/xsl/current/FORMAT/docbook.xsl"/>

  <!-- Your customizations go here -->

</xsl:stylesheet>

Discussion

Why not modify the original stylesheets? There are some profound reasons which speak against such modifications:

  • Whenever you update your stylesheet, all your modifications are lost.

  • You cannot separate between different customizations, for example, in one book you need an index but in the other it is unwanted.

  • If you modify the original stylesheets directly you cannot go back to the former output.

  • It is hard to distinguish between your customizations and the original one.

Refrain from editing the original stylesheets! Always write a customization layer.

Apart from the obvious reasons above, the following list gives you some recommendations:

  • Insert common parameters or templates into a stylesheet which is included in your customizations.

  • Structure your output formats into separate directories as shown in Section 2.1, “Introduction”.

  • Name your main stylesheet docbook.xsl or chunk.xsl (HTML only).

  • If your customization grows, outsource your customization into several stylesheets and include them into your “main” stylesheet.

  • Name your files like the DocBook XSL stylesheets. For example, if you customize filename (an inline element) put it into the file inline.xsl.

An example how this can look like, is shown in Example 2.2, “Structure ”:

Example 2.2. Structure 
mycustomizations/
  +-- common/
      +-- common.xsl 1
  +-- fo/
      +-- docbook.xsl 2
      +-- inline.xsl  3
  +-- html/
      +-- docbook.xsl 4
      +-- chunk.xsl   5
      +-- inline.xsl  6

1

Common customizations across different formats

2

Main stylesheet for FO output; includes inline.xsl

3

Contains all modifications for inline elements regarding the FO output.

4

Main stylesheet for single HTML output; includes inline.xsl

5

Main stylesheet for chunked HTML output; imports docbook.xsl

6

Contains all modifications for inline elements regarding the HTML output.

To use one of the customization layer with, for example, xsltproc, use:

xsltproc mycustomizations/html/docbook.xsl mydocbook.xml

See Also

http://www.sagehill.net/docbookxsl/CustomMethods.html#CustomizationLayer

Prev Up Next
2.2. Finding Professional Fonts Home 2.4. Inserting Date and Time
Project@GitHubIssue#7