FOSIs are SGML documents. The element in the FOSI that controls the presentation of specific elements is the e-i-c (element in context) element. A sample FOSI fragment is shown in Example 4.1, “A Fragment of a FOSI Stylesheet”.

<e-i-c gi="para">
  <charlist>
    <textbrk startln="1" endln="1">
  </charlist>
</e-i-c>

<e-i-c gi="emphasis">
  <charlist inherit="1">
    <font posture="italic">
  </charlist>
</e-i-c>

<e-i-c gi="emphasis" context="emphasis">
  <charlist inherit="1">
    <font posture="upright">
  </charlist>
</e-i-c>

DSSSL stylesheets are written in a Scheme-like language (see the section called “Scheme” later in this chapter). It is the element function that controls the presentation of individual elements. See the example in Example 4.2, “A Fragment of a DSSSL Stylesheet”.

(element para
  (make paragraph
    (process-children)))

(element emphasis
  (make sequence
    font-posture: 'italic
    (process-children)))

(element (emphasis emphasis)
  (make sequence
    font-posture: 'upright
    (process-children)))

CSS stylesheets consist of selectors and formatting properties, as shown in Example 4.3, “A Fragment of a CSS Stylesheet”.

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

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

<?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">

<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>

Element expressions, which define the rules for formatting particular elements, make up the bulk of most DSSSL stylesheets. A simple element rule can be seen in Example 4.7, “A Simple DSSSL Rule”. This rule says that a para element should be formatted by making a paragraph (see the section called “Make expressions”).

(element para
  (make paragraph
    space-before: 8pt
    (process-children)))

An element expression can be made more specific by specifying an element and its ancestors instead of just specifying an element. The rule (element title ...) applies to all Title elements, but a rule that begins (element (figure title) ...) applies only to Title elements that are immediate children of Figure elements.

If several rules apply, the most specific rule is used.

When a rule is used, the node in the source tree that was matched becomes the “current node” while that element expression is being processed.

A make expression specifies the characteristics of a “flow object.” Flow objects are abstract representations of content (paragraphs, rules, tables, and so on). The expression:

(make paragraph
  font-size: 12pt
  line-spacing: 14pt ...)

They're called flow objects because DSSSL, in its full generality, allows you to specify the characteristics of a sequence of flow objects and a set of areas on the physical page where you can place content. The content of the flow objects is then “poured on to” (or flows in to) the areas on the page(s).

In most cases, it's sufficient to think of the make expressions as constructing the flow objects, but they really only specify the characteristics of the flow objects. This detail is apparent in one of the most common and initially confusing pieces of DSSSL jargon: the sosofo. Sosofo stands for a “specification of a sequence of flow objects.” All this means is that processing a document may result in a nested set of make expressions (in other words, the paragraph may contain a table that contains rows that contain cells that contain paragraphs, and so on).

The general form of a make expression is:

(make flow-object-name
  keyword1: value1
  keyword2: value2
  ...
  keywordn: valuen
  (content-expression))

Keyword arguments specify the characteristics of the flow object. The specific characteristics you use depends on the flow object. The content-expression can vary; it is usually another make expression or one of the processing expressions.

Some common flow objects in the print stylesheet are:

The HTML stylesheet uses the SGML backend, which has a different selection of flow objects.

In both stylesheets, a completely empty flow object is constructed with (empty-sosofo).

Extracting parts of the source document can be accomplished with these functions:

A common requirement of formatting is the ability to reorder content. In order to do this, you must be able to select other elements in the tree for processing. DSSSL provides a number of functions that select other elements. These functions all return a list of nodes.

Other functions allow you to manipulate node lists.

There are many other expressions for manipulating nodes and node lists.

Processing expressions control which elements in the document will be processed and in what order. Processing an element is performed by finding a matching element rule and using that rule.

You can declare your own functions and constants in DSSSL. The general form of a function declaration is:

(define (function args)
  function-body)

(define constant
  constant-function-body)

The distinction between constants and functions is that the body of a constant is evaluated when the definition occurs, while functions are evaluated when they are used.

In DSSSL, the constant #t represents true and #f false. There are several ways to test conditions and take action in DSSSL.

Any expression that returns #f is false; all other expressions are true. This can be somewhat counterintuitive. In many programming languages, it's common to assume that “empty” things are false (0 is false, a null pointer is false, an empty set is false, for example.) In DSSSL, this isn't the case; note, for example, that an empty node list is not #f and is therefore true. To avoid these difficulties, always use functions that return true or false in conditionals. To test for an empty node list, use (node-list-empty?).

The way to create local variables in DSSSL is with (let). The general form of a let expression is:

(let ((var1 expression1)
      (var2 expression2)
      ...
      (varn expressionn))
  let-body)

In a let; expression, all of the variables are defined “simultaneously.” The expression that defines var2 cannot contain any references to any other variables defined in the same let expression. A let* expression allows variables to refer to each other, but runs slightly slower.

Variables are available only within the let-body. A common use of let is within a define expression:

(define (cals-rule-default nd)
   (let* ((table (ancestor "table" nd))
          (frame (if (attribute-string "frame" table)
                     (attribute-string "frame" table)
                     "all")))
    (equal? frame "all")))

This function creates two local variables table and frame. let returns the value of the last expression in the body, so this function returns true if the frame attribute on the table is all or if no frame attribute is present.

DSSSL doesn't have any construct that resembles the “for loop” that occurs in most imperative languages like C and Java. Instead, DSSSL employs a common trick in functional languages for implementing a loop: tail recursion.

Loops in DSSSL use a special form of let. This loop counts from 1 to 10:

(let loopvar ((count 1))
  (if (> count 10)
    #t
    (loopvar (+ count 1))))

	This variable controls the loop. It is declared without an initial value, immediately after the let operand.
	Any number of additional local variables can be defined after the loop variable, just as they can in any other let expression.
	If you ever want the loop to end, you have to put some sort of a test in it.
	This is the value that will be returned.
	Note that you iterate the loop by using the loop variable as if it was a function name.
	The arguments to this “function” are the values that you want the local variables declared in to have in the next iteration.

Chapters are processed by the chapter construction rule. Each Chapter is formatted as a simple-page-sequence. Every print stylesheet should format a document as one or more simple page sequences. Characteristics on the simple page sequence can specify headers and footers as well as margins and other page parameters.

One important note about simple page sequences: they cannot nest. This means that you cannot blindly process divisions (Parts, Reference) and the elements they contain (Chapters, RefEntrys) as simple page sequences. This sometimes involves a little creativity.

The make expression in the title element rule ensures that Titles are formatted in large, bold print.

This construction rule applies equally to Chapter titles, Figure titles, and Book titles. It's unlikely that you'd want all of these titles to be presented in the same way, so a more robust stylesheet would have to arrange the processing of titles with more context. This might be achieved in the way that nested Emphasis elements are handled in the section called “Processing emphasis”.

Para elements are simply formatted as paragraphs.

Processing Emphasis elements is made a little more interesting because we want to consider an attribute value and the possibility that Emphasis elements can be nested.

In the simple case, in which we're processing an Emphasis element that is not nested, we begin by testing the value of the role attribute. If the content of that attribute is the string strong, it is formatted in bold; otherwise, it is formatted in italic.

The nested case is handled by the (emphasis emphasis) rule. This rule simply formats the content using an upright (nonitalic) font. This rule, like the rule for Titles, is not robust. Emphasis nested inside strong Emphasis won't be distinguished, for example, and nestings more than two elements deep will be handled just as nestings that are two deep.

Processing Subscript and Superscript elements is really handled by the super-sub-script function. There are several interesting things about this function:

A basic driver file looks like this:

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY dbstyle PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA DSSSL>
]>

<style-sheet>
<style-specification use="docbook">
<style-specification-body>

;; your changes go here...

</style-specification-body>
</style-specification>
<external-specification id="docbook" document="dbstyle">
</style-sheet>

There are two public identifiers associated with the Modular DocBook Stylesheets:

You can add your own definitions, or redefinitions, of stylesheet rules and parameters so that

;; your changes go here...

For a concrete example of a driver file, see plain.dsl in the docbook/print directory in the stylesheet distribution (or on the CD-ROM). This is a customization of the print stylesheet, which turns off title page and TOC generation.

As distributed, the stylesheets use English for all generated text, but other localization files are also provided. The languages supported at the time of this writing are summarized in Table 4.1, “DocBook Stylesheet Language Codes”. (If you can write a localization for another language, please contribute it.)

There are two ways to switch languages: by specifying a lang attribute, or by changing the default language in a customization.

<chapter lang="fr"><title>Bêtises</title>
<para>Pierre qui roule n'amasse pas de mousse.</para>
</chapter>

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY dbstyle PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA DSSSL>
]>

<style-sheet>
<style-specification use="docbook">
<style-specification-body>

(define %default-language% "dege")

</style-specification-body>
</style-specification>
<external-specification id="docbook" document="dbstyle">
</style-sheet>

A DSSSL stylesheet consists of one or more “style specifications.” Using more than one style specification allows you to build a single stylesheet file that can format with either the print or SGML backends. Example 4.8, “both.dsl: A Stylesheet with Two Style Specifications” shows a stylesheet with two style specifications.

<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY html-ss 
  PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA dsssl>
<!ENTITY print-ss
  PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA dsssl>
]>
<style-sheet>
<style-specification id="print" use="print-stylesheet">
<style-specification-body> 

;; customize the print stylesheet

</style-specification-body>
</style-specification>
<style-specification id="html" use="html-stylesheet">
<style-specification-body> 

;; customize the html stylesheet

</style-specification-body>
</style-specification>
<external-specification id="print-stylesheet" document="print-ss">
<external-specification id="html-stylesheet"  document="html-ss">
</style-sheet>

Once you have stylesheets with more than one style specification, you have to be able to indicate which style specification you want to use. In Jade, you indicate this by providing the ID of the style specification after the stylesheet filename, separated with a hash mark: #.

Using the code from Example 4.8, “both.dsl: A Stylesheet with Two Style Specifications”, you can format a document using the print stylesheet by running:

jade -t rtf -d both.dsl#print file.sgm

and using the HTML stylesheet by running:

jade -t sgml -d both.dsl#html file.sgm

If your stylesheets parse fine with the default declaration, but you want to use an alternate declaration with a particular document, just pass the declaration on the command line:

jade options the-declaration the-document

The other way to fix this is with a little catalog trickery.

First, note that Jade always looks in the file called catalog in the same directory as the document that it is loading, and uses settings in that file in preference to settings in other catalogs.

With this fact, we can employ the following trick:

There's no easy way to have both the stylesheet and the document in the same directory if they must be processed with different declarations. But this is usually not too inconvenient.

Since you aren't writing a linear procedure to process your document, the context of where and how to apply each modular template is important. The match attribute of <xsl:template> provides that context for most templates. There is an entire expression language, XPath, for identifying what parts of your document should be handled by each template. The simplest context is just an element name, as in the example above. But you can also specify elements as children of other elements, elements with certain attribute values, the first or last elements in a sequence, and so on. Here is how the DocBook <formalpara> element is handled:

<xsl:template match="formalpara">
  <p>
    <xsl:apply-templates/>
  </p>
</xsl:template>

<xsl:template match="formalpara/title">
  <b><xsl:apply-templates/></b>
  <xsl:text> </xsl:text>
</xsl:template>

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

There are three templates defined, one for the <formalpara> element itself, and one for each of its children elements. The match attribute value formalpara/title in the second template is an XPath expression indicating a <title> element that is an immediate child of a <formalpara> element. This distinguishes such titles from other <title> elements used in DocBook. XPath expressions are the key to controlling how your templates are applied.

In general, the XSL processor has internal rules that apply templates that are more specific before templates that are less specific. That lets you control the details, but also provides a fallback mechanism to a less specific template when you don't supply the full context for every combination of elements. This feature is illustrated by the third template, for formalpara/para. By including this template, the stylesheet processes a <para> within <formalpara> in a special way, in this case by not outputting the HTML <p> tags already output by its parent. If this template had not been included, then the processor would have fallen back to the template specified by match="para" described above, which would have output a second set of <p> tags.

You can also control template context with XSL modes, which are used extensively in the DocBook stylesheets. Modes let you process the same input more than once in different ways. A mode attribute in an <xsl:template> definition adds a specific mode name to that template. When the same mode name is used in <xsl:apply-templates/>, it acts as a filter to narrow the selection of templates to only those selected by the match expression and that have that mode name. This lets you define two different templates for the same element match that are applied under different contexts. For example, there are two templates defined for DocBook <listitem> elements:

<xsl:template match="listitem">
  <li><xsl:apply-templates/></li>
</xsl:template>

<xsl:template match="listitem" mode="xref">
  <xsl:number format="1"/>
</xsl:template>

The first template is for the normal list item context where you want to output the HTML <li> tags. The second template is called with <xsl:apply-templates select="$target" mode="xref"/> in the context of processing <xref> elements. In this case the select attribute locates the ID of the specific list item and the mode attribute selects the second template, whose effect is to output its item number when it is in an ordered list. Because there are many such special needs when processing <xref> elements, it is convenient to define a mode name xref to handle them all. Keep in mind that mode settings do not automatically get passed down to other templates through <xsl:apply-templates/>.

Although XSL is template-driven, it also has some features of traditional programming languages. Here are some examples from the DocBook stylesheets.

Assign a value to a variable:
<xsl:variable name="refelem" select="name($target)"/>

If statement:
<xsl:if test="$show.comments">
    <i><xsl:call-template name="inline.charseq"/></i>
</xsl:if>

Case statement:
<xsl:choose>
    <xsl:when test="@columns">
        <xsl:value-of select="@columns"/>
    </xsl:when>
    <xsl:otherwise>1</xsl:otherwise>
</xsl:choose>

Call a template by name like a subroutine, passing parameter values and accepting a return value:
<xsl:call-template name="xref.xreflabel">
   <xsl:with-param name="target" select="$target"/>
</xsl:call-template>

However, you can't always use these constructs as you do in other programming languages. Variables in particular have very different behavior.

<xsl:param name="cols">1</xsl:param>
<xsl:variable name="segnum" select="position()"/>

 1 <xsl:template name="dbhtml-attribute">
 2 ...
 3    <xsl:choose>
 4       <xsl:when test="$count>count($pis)">
 5          <!-- not found -->
 6       </xsl:when>
 7       <xsl:otherwise>
 8          <xsl:variable name="pi">
 9             <xsl:value-of select="$pis[$count]"/>
10          </xsl:variable>
11          <xsl:choose>
12             <xsl:when test="contains($pi,concat($attribute, '='))">
13                <xsl:variable name="rest" select="substring-after($pi,concat($attribute,'='))"/>
14                <xsl:variable name="quote" select="substring($rest,1,1)"/>
15                <xsl:value-of select="substring-before(substring($rest,2),$quote)"/>
16             </xsl:when>
17             <xsl:otherwise>
18             ...
19             </xsl:otherwise>
20          </xsl:choose>
21       </xsl:otherwise>
22    </xsl:choose>
23 </xsl:template>

<xsl:call-template name="head.content">
   <xsl:with-param name="node" select="$doc"/>
</xsl:call-template>

<xsl:template name="head.content">
   <xsl:param name="node" select="."/>

You generate HTML from your DocBook XML files by applying the HTML version of the stylesheets. This is done by using the HTML driver file docbook/html/docbook.xsl as your stylesheet. That is the master stylesheet file that uses <xsl:include> to pull in the component files it needs to assemble a complete stylesheet for producing HTML.

The way the DocBook stylesheet generates HTML is to apply templates that output a mix of text content and HTML elements. Starting at the top level in the main file docbook.xsl:

<xsl:template match="/">
  <xsl:variable name="doc" select="*[1]"/>
  <html>
  <head>
    <xsl:call-template name="head.content">
      <xsl:with-param name="node" select="$doc"/>
    </xsl:call-template>
  </head>
  <body>
    <xsl:apply-templates/>
  </body>
  </html>
</xsl:template>

This template matches the root element of your input document, and starts the process of recursively applying templates. It first defines a variable named doc and then outputs two literal HTML elements <html> and <head>. Then it calls a named template head.content to process the content of the HTML <head>, closes the <head> and starts the <body>. There it uses <<xsl:apply-templates/>/> to recursively process the entire input document. Then it just closes out the HTML file.

Simple HTML elements can generated as literal elements as shown here. But if the HTML being output depends on the context, you need something more powerful to select the element name and possibly add attributes and their values. Here is a fragment from sections.xsl that shows how a heading tag is generated using the <xsl:element> and <xsl:attribute> elements:

 1 <xsl:element name="h{$level}">
 2   <xsl:attribute name="class">title</xsl:attribute>
 3   <xsl:if test="$level<3">
 4     <xsl:attribute name="style">clear: all</xsl:attribute>
 5   </xsl:if>
 6   <a>
 7     <xsl:attribute name="name">
 8       <xsl:call-template name="object.id"/>
 9     </xsl:attribute>
10     <b><xsl:copy-of select="$title"/></b>
11   </a>
12 </xsl:element>

This whole example is generating a single HTML heading element. Line 1 begins the HTML element definition by identifying the name of the element. In this case, the name is an expression that includes the variable $level passed as a parameter to this template. Thus a single template can generate <h1>, <h2>, etc. depending on the context in which it is called. Line 2 defines a class="title" attribute that is added to this element. Lines 3 to 5 add a style="clear all" attribute, but only if the heading level is less than 3. Line 6 opens an <a> anchor element. Although this looks like a literal output string, it is actually modified by lines 7 to 9 that insert the name attribute into the <a> element. This illustrates that XSL is managing output elements as active element nodes, not just text strings. Line 10 outputs the text of the heading title, also passed as a parameter to the template, enclosed in HTML boldface tags. Line 11 closes the anchor tag with the literal <//a> syntax, while line 12 closes the heading tag by closing the element definition. Since the actual element name is a variable, it couldn't use the literal syntax.

As you follow the sequence of nested templates processing elements, you might be wondering how the ordinary text of your input document gets to the output. In the file docbook.xsl you will find this template that handles any text not processed by any other template:

<xsl:template match="text()">
  <xsl:value-of select="."/>
</xsl:template>

This template's body consists of the "value" of the text node, which is just its text. In general, all XSL processors have some built-in templates to handle any content for which your stylesheet doesn't supply a matching template. This template serves the same function but appears explicitly in the stylesheet.

You generate formatting objects from your DocBook XML files by applying the fo version of the stylesheets. This is done by using the fo driver file docbook/fo/docbook.xsl as your stylesheet. That is the master stylesheet file that uses <xsl:include> to pull in the component files it needs to assemble a complete stylesheet for producing formatting objects. Generating a formatting objects file is only half the process of producing typeset output. You also need a formatting object processor such as the Apache XML Project's FOP as described in an earlier section.

The DocBook fo stylesheet works in a similar manner to the HTML stylesheet. Instead of outputting HTML tags, it outputs text marked up with <fo:something> tags. For example, to indicate that some text should be kept in-line and typeset with a monospace font, it might look like this:

<fo:inline-sequence font-family="monospace">/usr/man</fo:inline-sequence>

The templates in docbook/fo/inline.xsl that produce this output for a DocBook <filename> element look like this:

<xsl:template match="filename">
  <xsl:call-template name="inline.monoseq"/>
</xsl:template>

<xsl:template name="inline.monoseq">
  <xsl:param name="content">
    <xsl:apply-templates/>
  </xsl:param>
  <fo:inline-sequence font-family="monospace">
    <xsl:copy-of select="$content"/>
  </fo:inline-sequence>
</xsl:template>

There are dozens of fo tags and attributes specified in the XSL standard. It is beyond the scope of this document to cover how all of them are used in the DocBook stylesheets. Fortunately, this is only an intermediate format that you probably won't have to deal with very much directly unless you are writing your own stylesheets.

XSL actually provides two inclusion mechanisms: <xsl:include> and <xsl:import>. Of the two, <xsl:include> is the simpler. It treats the included content as if it were actually typed into the file at that point, and doesn't give it any more or less precedence relative to the surrounding text. It is best used when assembling dissimilar templates that don't overlap what they match. The DocBook driver files use this instruction to assemble a set of modules into a stylesheet.

In contrast, <xsl:import> lets you manage the precedence of templates and variables. It is the preferred mode of customizing another stylesheet because it lets you override definitions in the distributed stylesheet with your own, without altering the distribution files at all. You simply import the whole stylesheet and add whatever changes you want.

The precedence rules for import are detailed and rigorously defined in the XSL standard. The basic rule is that any templates and variables in the importing stylesheet have precedence over equivalent templates and variables in the imported stylesheet. Think of the imported stylesheet elements as a fallback collection, to be used only if a match is not found in the current stylesheet. You can customize the templates you want to change in your stylesheet file, and let the imported stylesheet handle the rest.

You can carry modularization to deeper levels because module files can also include or import other modules. You'll need to be careful to maintain the precedence that you want as the modules get rolled up into a complete stylesheet.

There is currently one example of customizing with <xsl:import> in the HTML version of the DocBook stylesheets. The xtchunk.xsl stylesheet modifies the HTML processing to output many smaller HTML files rather than a single large file per input document. It uses XSL extensions defined only in the XSL processor XT. In the driver file xtchunk.xsl, the first instruction is <xsl:import href="docbook.xsl"/>. That instruction imports the original driver file, which in turn uses many <xsl:include> instructions to include all the modules. That single import instruction gives the new stylesheet the complete set of DocBook templates to start with.

After the import, xtchunk.xsl redefines some of the templates and adds some new ones. Here is one example of a redefined template:

Original template in autotoc.xsl
<xsl:template name="href.target">
  <xsl:param name="object" select="."/>
  <xsl:text>#</xsl:text>
  <xsl:call-template name="object.id">
    <xsl:with-param name="object" select="$object"/>
  </xsl:call-template>
</xsl:template>

New template in xtchunk.xsl
<xsl:template name="href.target">
  <xsl:param name="object" select="."/>
  <xsl:variable name="ischunk">
    <xsl:call-template name="chunk">
      <xsl:with-param name="node" select="$object"/>
    </xsl:call-template>
  </xsl:variable>

  <xsl:apply-templates mode="chunk-filename" select="$object"/>

  <xsl:if test="$ischunk='0'">
    <xsl:text>#</xsl:text>
    <xsl:call-template name="object.id">
      <xsl:with-param name="object" select="$object"/>
    </xsl:call-template>
  </xsl:if>
</xsl:template>

The new template handles the more complex processing of HREFs when the output is split into many HTML files. Where the old template could simply output #object.id, the new one outputs filename#object.id.

You may not have to define any new templates, however. The DocBook stylesheets are parameterized using XSL variables rather than hard-coded values for many of the formatting features. Since the <xsl:import> mechanism also lets you redefine global variables, this gives you an easy way to customize many features of the DocBook stylesheets. Over time, more features will be parameterized to permit customization. If you find hardcoded values in the stylesheets that would be useful to customize, please let the maintainer know.

Near the end of the list of includes in the main DocBook driver file is the instruction <xsl:include href="param.xsl"/>. The param.xsl file is the most important module for customizing a DocBook XSL stylesheet. This module contains no templates, only definitions of stylesheet variables. Since these variables are defined outside of any template, they are global variables and apply to the entire stylesheet. By redefining these variables in an importing stylesheet, you can change the behavior of the stylesheet.

To create a customized DocBook stylesheet, you simply create a new stylesheet file such as mystyle.xsl that imports the standard stylesheet and adds your own new variable definitions. Here is an example of a complete custom stylesheet that changes the depth of sections listed in the table of contents from two to three:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                version='1.0'
                xmlns="http://www.w3.org/TR/xhtml1/transitional"
                exclude-result-prefixes="#default">

<xsl:import href="docbook.xsl"/>

<xsl:variable name="toc.section.depth">3</xsl:variable>
<!-- Add other variable definitions here -->

</xsl:stylesheet>

Following the opening stylesheet element are the import instruction and one variable definition. The variable toc.section.depth was defined in param.xsl with value "2", and here it is defined as "3". Since the importing stylesheet takes precedence, this new value is used. Thus documents processed with mystyle.xsl instead of docbook.xsl will have three levels of sections in the tables of contents, and all other processing will be the same.

Use the list of variables in param.xsl as your guide for creating a custom stylesheet. If the changes you want are controlled by a variable there, then customizing is easy.

If the changes you want are more extensive than what is supported by variables, you can write new templates. You can put your new templates directly in your importing stylesheet, or you can modularize your importing stylesheet as well. You can write your own stylesheet module containing a collection of templates for processing lists, for example, and put them in a file named mylists.xsl. Then your importing stylesheet can pull in your list templates with a <xsl:include href="mylists.xsl"/> instruction. Since your included template definitions appear after the main import instruction, your templates will take precedence.

You'll need to make sure your new templates are compatible with the remaining modules, which means:

Another approach to customizing the stylesheets is to write your own driver file. Instead of using <xsl:import href="docbook.xsl"/>, you copy that file to a new name and rewrite any of the <xsl:include/> instructions to assemble a custom collection of stylesheet modules. One reason to do this is to speed up processing by reducing the size of the stylesheet. If you are using a customized DocBook DTD that omits many elements you never use, you might be able to omit those modules of the stylesheet.

The DocBook stylesheets include features for localizing generated text, that is, printing any generated text in a language other than the default English. In general, the stylesheets will switch to the language identified by a lang attribute when processing elements in your documents. If your documents use the lang attribute, then you don't need to customize the stylesheets at all for localization.

As far as the stylesheets go, a lang attribute is inherited by the descendents of a document element. The stylesheet searches for a lang attribute using this XPath expression:

<xsl:variable name="lang-attr"
         select="($target/ancestor-or-self::*/@lang
                  |$target/ancestor-or-self::*/@xml:lang)[last()]"/>

This locates the attribute on the current element or its most recent ancestor. Thus a lang attribute is in effect for an element and all of its descendents, unless it is reset in one of those descendents. If you define it in only your document root element, then it applies to the whole document:

<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN" "docbook.dtd">
<book lang="fr">
...
</book>

When text is being generated, the stylesheet checks the most recent lang attribute and looks up the generated text strings for that language in a localization XML file. These are located in the common directory of the stylesheets, one file per language. Here is the top of the file fr.xml:

<localization language="fr">

<gentext key="abstract"                 text="R&#x00E9;sum&#x00E9;"/>
<gentext key="answer"                   text="R:"/>
<gentext key="appendix"                 text="Annexe"/>
<gentext key="article"                  text="Article"/>
<gentext key="bibliography"             text="Bibliographie"/>
...

The stylesheet templates use the gentext key names, and then the stylesheet looks up the associated text value when the document is processed with that lang setting. The file l10n.xml (note the .xml suffix) lists the filenames of all the supported languages.

You can also create a custom stylesheet that sets the language. That might be useful if your documents don't make appropriate use of the lang attribute. The module l10n.xsl defines two global variables that can be overridden with an importing stylesheet as described above. Here are their default definitions:

<xsl:variable name="l10n.gentext.language"></xsl:variable>
<xsl:variable name="l10n.gentext.default.language">en</xsl:variable>

The first one sets the language for all elements, regardless of an element's lang attribute value. The second just sets a default language for any elements that haven't got a lang setting of their own (or their ancestors).