Code-reuse Modularity

Added 26 Jul 2008

Modularity for code-reuse is standard software engineering practice. Code that can be shared between several stylesheets can be stored in a single module. Naturally, the extent to which this is applicable to a given project is going to vary.

The DocBook XSL Stylesheets were designed from the beginning with the goal of writing both HTML and Formatting Object Stylesheets from the beginning. It was clear to me that some of the functionality that was necessary to format DocBook documents would not depend on the result tree type.

Some likely candidates for this sort of modularity are:

The XSL strip-space and preserve-space elements.
Named templates that calculate a position in the source tree hierarchy (section level, for example).
Named templates that calculate simple text values (figure numbers, generated cross-reference text, etc.).

Consider the formatting of divisions in a QandASet:


Some Technical FAQs...
...

Some Procedural FAQs...
...

...

Most authors expect the titles of these divisions to appear in a font size that's relative to the section that contains them. That is, they expect the title to be a size smaller than the nearest surrounding section title.

In order to achieve this, the stylesheet must calculate the relative position of this QandADiv within the nested hierarchy of sections and divisions:

This section-level information applies equally well to HTML or Formatting Object stylesheets (though it would naturally be used in different ways by the two stylesheets) so it is a good candidate for a “common” module.

Like all software engineering practices, code-reuse often involves some tradeoffs. One of the tradeoffs here is between maximum code-reuse and stylesheet readability.

There are some of the questions to consider when deciding whether or not to reuse a template. The DocBook XSL Stylesheets contain examples of each of these tradeoffs.