You want to know what root elements are possible and what else is needed to create a DocBook V5 document.

A document type definition (DTD) allows every definied element to become a root element. A DTD cannot express any constraints to limit this set. On the other hand, RELAX NG—the official schema language for DocBook 5 and up—can impose such constraints.

To create a valid DocBook V5 document you need:

To assemble all the above hints, a valid DocBook 5 document could look like this:

<book version="5.0" xmlns="http://docbook.org/ns/docbook">
  <title>The Example Book</title>
  <chapter>
     <title>An Example Chapter</title>
     <para>This is a paragraph.</para>
  </chapter>
</book>

There a many more possible root elements, not only book. Using the list from the last section, a valid DocBook V5 element to start with can be:

For the next DocBook release, V5.1, the technical committee plans to include all elements that can contain an info wrapper.

Regarding namespaces, DocBook 5 uses only one namespace (which is http://docbook.org/ns/docbook). However, sometimes it is needed to include other in order to adhere to the XML specification.

A namespace declaration consists of an (optional) namespace prefix and a namespace URI. The prefix may be selected arbitrarily, however, it is recommended to use the prefixes from Table 1.1, “Common Prefixes and Their Namespaces”. Although they are not a “standard” in its strict sense, over time they have been extensively used.

Usually it is a good idea to insert all the namespaces used in the document into the root element. Example 1.2, “Start Tag with Several Namespace Declarations”, shows three namespace declarations: the DocBook namespace, using no prefix; the XInclude namespace using the xi prefix, and the XLink namespace using the xlink prefix.

<book version="5.0"
   xmlns="http://docbook.org/ns/docbook"
   xmlns:xi="http://www.w3.org/2001/XInclude"
   xmlns:xlink="http://www.w3.org/1999/xlink">

You need a method to split your document into several “modules” and put it together afterwards.

Use XInclude. It is a W3C specification and defines the elements xi:include and xi:fallback. They are not DocBook elements (as they are defined by the W3C and not OASIS ), however they have been integrated in version 5.x^[3]. Note, XIncludes work in DocBook regardless which version (4.x or 5.x) you use.

If you want to use XIncludes, you need these things:

The following example shows a book that points to a substructure assuming chapters:

<book version="5.0"
  xmlns="http://docbook.org/ns/docbook"
  xmlns:xi="http://www.w3.org/2001/XInclude">
  <title>...</title>
  <xi:include href="intro.xml"/>
  <xi:include href="conceptual-overview.xml"/>
</book>

The above book contains an introduction (file intro.xml) and a conceptual overview (file conceptual-overview.xml). Both are referenced by the XInclude´s href attribute.

Before you transform your document, you need to resolve your XIncludes first, either by your XML parser or “manually” by an XSLT transformation. The following procedure shows a typical workflow:

The previous procedure showed a book with xincluded chapters. It is possible to even go deeper and also include a section into a chapter. Actually, there is no limit. You should only be aware that you do not create circular references (file A includes file B and B includes A).

As XIncludes are very common nowadays, resolving xi:include and transforming into the output format can be done in one step. This is the case for most tools:

The last section showed a general method to work with XIncludes. In most cases this is enough. However, XIncludes offers more benefits that are discovered in the following subsections.

<xi:include href="revhistory.xml">
  <xi:fallback>
    <para>The revision history could not be retrieved.</para>
  </xi:fallback>
</xi:include>

<programlisting language="c"><xi:include
   parse="text"
   href="parser.c"/></programlisting>

You need two separate indices in your document, a general one and another one for persons.

Use the type attribute both on indexterm and index. The content of the type attribute can be any value. Usually it is a descriptive name (in our case, “persons” would be fine).

For example, the following paragraph contains two index terms. However, Guido is marked up as a “persons index”:

<para> The Python<indexterm>
   <primary>Python</primary></indexterm> programming
   language was designed by
   Guido van Rossum.<indexterm type="persons">
   <primary>van Rossum, Guido</primary></indexterm>
</para>

Use two index elements at the end of your document to distinguish between the two:

<index/> 

<index type="persons"> 
  <title>Persons</title>
</index>

Some documents contain two indices, one general and one for persons. This is quite common these days as it simplifies where to find your search term. You can add as many indices as you need, but more than two are normally uncommon.

By default, multiple indices are turned on by the DocBook stylesheets. So no special customization is needed. However, if you want to collect all index terms into one index, set the parameter index.on.type to 0 (zero). In that case, the type attribute has no effect.

You need to know the differences and advantages of using a section vs. a sectn element.

The differences between section vs. sectn are shown in Table 1.2, “Comparison Between section and sectn Elements”:

Apart from technical issues, using section or sect1 is in most cases a matter of taste. However, knowing some of the differences in Table 1.2 can be helpful to decide which better suits your document.

http://www.docbook.org/tdg51/en/html/ch05.html#ex.limitsdepth

You want to know what list types are available in DocBook.

DocBook provides three basic lists that are used most often:

Additionally, for specific purposes, DocBook provides special lists (not explained in this topic):

The previous lists are used to maintain semantic distinction.

The list types orderedlist and itemizedlist are structurally identical (except for their enclosing element) as you will see in the following subsections.

The variablelist is slightly different and contains the term element for its term.

<itemizedlist>
  <listitem>
    <para>The first entry</para>
  </listitem>
  <listitem>
    <para>The second entry</para>
  </listitem>
  <listitem>
    <para>The third entry</para>
  </listitem>
</itemizedlist>

<itemizedlist mark="circle">

<itemizedlist>
  <listitem>
    <para>The first entry</para>
  </listitem>
  <listitem overwrite="square">
    <para>The second entry</para>
  </listitem>
  <listitem>
    <para>The third entry</para>
  </listitem>
</itemizedlist>

<orderedlist>
  <listitem>
    <para>The first entry</para>
  </listitem>
  <listitem>
    <para>The second entry</para>
  </listitem>
  <listitem>
    <para>The third entry</para>
  </listitem>
</orderedlist>

<variablelist>
  <varlistentry>
    <term>Hamburg</term>
    <listitem>
       <para>Town in the northern part of Germany</para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>Nueremberg</term>
    <listitem>
       <para>Town in the south-eastern part of Germany</para>
    </listitem>
  </varlistentry>
</variablelist>

You need to add an element that is used for code listings.

Use the programlisting element. For example, the following markup shows some Python code:

<programlisting>#!/usr/bin/python

def sayhello(name):
  """Say hello to someone"""
  return "Hello %s" % name

sayhello("Tux")</programlisting>

If you want to benefit from syntax highlighting later, add the language attribute:

<programlisting language="python">...</programlisting>

In most cases, programlisting is probably enough for all your needs. However, the DocBook stylesheets and the DocBook extension support some convenient features you should know:

The above features are explained in the following subsections.

<programlisting>#!/usr/bin/python <lineannotation>She-bang line</lineannotation>

def sayhello(name):
  """Say hello to someone""" <lineannotation>Python's doc comment</lineannotation>
  return "Hello %s" % name

sayhello("Tux")
</programlisting>

#!/usr/bin/python Shebang line

def sayhello(name):
  """Say hello to someone""" Python's doc comment
  return "Hello %s" % name

sayhello("Tux")

<programlisting> ...
# <lineannotation>Function to output a warm welcome message</lineannotation>
def sayhello(name):
  ...
</programlisting>

<programlisting language="python"
>#!/usr/bin/python <co xml:id="co.shebang"/>

def sayhello(name):
  """Say hello to someone""" <co xml:id="co.doccomment"/>
  return "Hello %s" % name

sayhello("Tux")</programlisting>
<calloutlist>
   <callout arearefs="co.shebang">
     <para>A Shebang line. Unix-like operating systems can parse
           this line, execute the corresponding interpreter and pass
           the script as first argument.</para>
   </callout>
   <callout arearefs="co.doccomment">
     <para>A Python doc comment. Usually, written as triple quotes
           or as triple apostrophes marking the doc comment for a function
           or class.</para>
   </callout>
</calloutlist>

#!/usr/bin/python 

def sayhello(name):
  """Say hello to someone""" 
  return "Hello %s" % name

sayhello("Tux")

<programlisting linenumbering="numbered">...

 1 | #!/usr/bin/python
 2 |
 3 | def sayhello(name):
 4 | """Say hello to someone"""
 5 | return "Hello %s" % name
 6 |
 7 | sayhello("Tux")

<programlisting><?dbhtml
   linenumbering.everyNth="2"
   linenumbering.width="2" ?>#!/usr/bin/python
...
</programlisting>

  | #!/usr/bin/python
 2|
  | def sayhello(name):
 4| """Say hello to someone"""
  | return "Hello %s" % name
 6|
  | sayhello("Tux")

You have external files (codes, example files, and others) that you want to incorporate into a programlisting element, but you want to keep your files separate from your documentation files.

Use one of the following methods to incorporate external files into your programlisting element:

You can mix both, but for consistency reasons, it is better to stick to one method.

<programlisting><textobject>
   <textdata fileref="foo.py"/>
</textobject></programlisting>

<programlisting><xi:include
  href="foo.py" parse="text"
/><programlisting>

Keeping your external files separate from your documentation can have several reasons. Probably you need to change the files very often or you do not have control over these files. In such cases, it is better to leave them as separate files and don't include them directly into your XML code. Otherwise it would be tedious to include them manually whenever your code changes.

To avoid such tedious tasks, the textdata and xi:include elements were invented. The element textdata was introduced in DocBook 4.2, released in 2002. At that time the XInclude specification was not written yet, the first public release was published in 2006. Too late for DocBook to incorporate it into its schema.

Nowadays, in the light of XInclude, the element textdata can be considered obsolete—especially for DocBook 5 documents. Therefore, for new documents, prefer the XInclude element(s) as this has more advantages (see Table 1.3, “Comparision Between textdata and xi:include ”).

If you still want (or have) to use textdata you need to transform your DocBook documents with Saxon or Xalan. Currently, the extension functions are only available for these XSLT processors, not xsltproc. Make sure the DocBook extension JAR file(s) are included in your CLASSPATH variable. Furthermore, set the parameters use.extensions and textinsert.extension to 1 to enable this functionality.

You want to insert comments or remarks in your document to enable or disable them in the output format.

For this purpose, DocBook provides a remark element. The following example shows how to use it:

<para>
This is a small text.<remark>Add more content</remark>
</para>

To add comments in your document, there are two methods:

XML comments can be placed almost everywhere in your XML document. It is a very common method to give yourself or others some hints. This can be done with XML comments like in this example:

<para>
This is a text <!-- Ohh, we should add more -->
</para>

However, XML comments have one drawback: They are suppressed during transformation. As such, they are unavailable in your output format and cannot be displayed anymore. Usually, you do not want them to appear in your output.

On the contrary, by using the remark element, comments can be shown or suppressed whenever you want. For example, if you write your document and put in some remarks, you can show them to your contributors for review. After the document is ready to be published, leave the remarks as they are but suppress the remark transformation.

To display or suppress your remarks, use the parameter show.comments. This parameter can appear either on the command line of your XSLT processor or in a customization layer. Any non-zero value shows your remarks whereas a value of zero suppresses them.

When should you use XML comments and when remarks? The following table gives you a quick overview.

You want to set a “link” but you do not know which DocBook element to use.

DocBook distinguishes between two link types:

There are several differences between xref and link. An xref is used for cross referencing another part of the document. In its simplest form, you only need an ID value of the object that you want to refer:

<chapter xml:id="tea">
  <title>All About Tea</title>
  <section xml:id="about-tea">
    <title>About Tea</title>
    <para>This section gives you an introduction about tea.</para>
  </section>
  <section xml:id="prepar">
    <title>Preparing Tea</title>
    <para>Read an introduction in <xref linkend="about-tea"/>.</para>
  </section>
</chapter>

The DocBook XSL stylesheets take care of resolving the xref. By default, it replaces the xref element with a number and the title of the reference. It could look like this:

Read an introduction in Section 1.1, “About Tea”.

The text Section 1.1, “About Tea” is a “hot link” and points to the respective section. Using xref for cross-references has several advantages:

In contrast, a link is used in most cases for external links.

<section xml:id="about-tea">
  <title>About Tea</title>
  <para>See <link xlink:href="http://www.example.org/tea"/> for further information.</para>
</section>

Using link has the following advantages:

The differences between xref and link are collected in Table 1.5, “Differences Between xref and link ”.

You want to create a cross-reference from one part of your document into another.

Use the xref element for this purpose. A cross reference is a one-to-one relationship from your xref to your target. To create such a relationship you need two things:

For example, you want to reference to the introduction chapter in your book. The chapter looks like this:

<chapter xml:id="intro">
  <title>Introduction</title>
  ...
</chapter>

As you can see, the chapter contains a title but most importantly, it also has a xml:id attribute. This is our “anchor” or ID.

If you want to create a cross-reference to your introduction chapter, use the xref element as follows:

<para>Get basic information in <xref linkend="intro"/>.</para>

The previous xref is rendered as follows:

Get basic information in Chapter 1. “Introduction”.

Cross referencing is important in your documents as it makes your text accessible for your reader. The previous section showed the simplest form of a cross-reference. However, there is more to find out about xref. The following subsections give you some useful tips and tricks:

Section <xref linkend="dbc.markup.xref" xrefstyle="template:%t"/> helps you with the xref element.

Section Inserting Cross-References helps you with the xref element.

Section <xref linkend="dbc.markup.xref" xrefstyle="select:title"/> helps you with the xref element.

<l:context name="title-numbered">
  <l:template name="article/appendix" text="%n. %t"/>
</l:context>

<xref linkend="_para1"/>: the section called “Using xreflabel Only in Rare Cases”
               

<para xml:id="_para2" xreflabel="A better test"> ... <para
...
<xref linkend="_para2"/>: A better test
               

The following chapter <xref linkend="dbc.markup"/> explains...

The following chapter Chapter 1, Knowing DocBook’s Structure explains...

<xref linkend="dbc.markup"/> explains ...

The topic ABC is explained in <xref linkend="dbc.markup"/>.

The following <xref linkend="dbc.markup" xrefstyle="chapter %t"/>, explains...

You need some ideas about link markup.

Use the link^[4] element. Usually, external links are used in two ways:

Don't forget to add the XLink namespace declaration into the root element of your document, for example:

<book xmlns:xlink="http://www.w3.org/1999/xlink" ...>

The link element has several features for creating internal or external links. It optionally has content. Regardless of content, you have to choose between the attributes xlink:href or linkend.

<link xlink:href="https://github.com/tomschr/dbcookbook">https://github.com/tomschr/dbcookbook</link>

<link xlink:href="https://github.com/tomschr/dbcookbook"/>

<citetitle><ulink url="https://github.com/tomschr/dbcookbook">The DoCookBook</ulink></citetitle>

<ulink url="https://github.com/tomschr/dbcookbook"><citetitle>The DoCookBook</citetitle></ulink>

<citetitle xlink:href="https://github.com/tomschr/dbcookbook">The DoCookBook</citetitle>

<link xlink:show="new" xlink:href="https://github.com/tomschr/dbcookbook"/>

You want to use inline quotes in a consistent and language-independent way.

Use the quote tag:

<para>This is an <quote>English quote</quote>.</para>

When people need quotes, they usually write "this". However, from a typographical point of view, this is wrong. There are special start and end quotation characters. The more elegant way is to use “this”.

However, the opening and closing characters are language-dependent. Many languages have different quotation rules. German readers prefer „this“, French « this », and the Italians use «this».

Using quote markers directly has one disadvantage: if your text contains different languages you need to know how quotes are displayed in the respective language. Moreover, it is easier and more consistent to leave this typographic detail to the DocBook stylesheets.

One nice thing with inserting quote is that it can be adapted to a different language by using the xml:lang attribute:

<para>This is a <quote xml:lang="de">German quote</quote>.</para>

You search for an easy way to markup inline references to man pages.

Use citerefentry.

<citerefentry>
  <refentrytitle>xmllint</refentrytitle>
  <manvolnum>1</manvolnum>
</citerefentry>

It is rendered like this:

Some discussion about the problem and solution.

Include URL or bibliographic references.

You need to find professional fonts, preferably released under an open source license which can be used for print or web formats.

There are some very good fonts which can be used freely. Most fonts are even released under the Open Font License or other free or open licenses. The following list is a small overview which is by no means complete (also use your favorite search engine):

Before you use a font, answer the following questions:

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

A DocBook XSL customization layer comprises the following components:

How this can look is shown in the following listing.

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

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

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

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

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

mycustomizations/
  +-- common/
      +-- common.xsl 
  +-- fo/
      +-- docbook.xsl 
      +-- inline.xsl  
  +-- html/
      +-- docbook.xsl 
      +-- chunk.xsl   
      +-- inline.xsl  
               

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

xsltproc mycustomizations/html/docbook.xsl mydocbook.xml

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

You want to insert the current date, time, or both into your output format (for example, to show the date of creation).

Use the <?dbtimestamp?> processing instruction (PI). For example, integrate it into the pubdate to show the current publication date on the titlepage:

<info>
  <!-- ... -->
  <pubdate><?dbtimestamp?></pubdate>
</info>

The above PI includes the date in its localized form, or in other words: the output depends on the current language. If you do not have set any language, the default is English (en_US) which is month/day/year. If you want to change the default format, use one of the two options:

<l:context name="datetime">
  <l:template name="format" text="m/d/Y"/>
</l:context>

<?dbtimestamp format="Y"?>

You need to retrieve a title (or subtitle), but your current node is not a title.

The DocBook XSL stylesheets offer the title.markup mode for this purpose. Usually, insert the following code into the appropriate place:

<xsl:apply-templates select="." mode="title.markup"/>

The xsl:apply-templates recursively finds the correct title node, regardless where you are. It also looks into an info element, if necessary.

DocBook contains three elements which are used for title markup:

All of the above title elements contain a special mode to get the content of this node:

To further elaborate why you should use one of the previous modes, let's assume you have this chapter title:

<chapter>
   <title>Programming in Python</title>
   <!-- further substructure pruned -->
</chapter>

Let's further assume, you have a template where you need the title from the above chapter. One simple, yet unfavorable, solution could be coded like this:

<xsl:template name="...">
   <xsl:value-of select="ancestor::d:title"/>
</xsl:template>

This has several disadvantages:

Replacing xsl:value-of with xsl:apply-templates as shown in the solution section, ensures correct processing of child elements inside title.

The same is true for subtitle and titleabbrev. Using the subtitle.markup or titleabbrev.markup mode ensures that you always get the correct content.

To see what combination results in what string, find an overview in Table 2.2, “Different Combinations and Their Results on *.markup Modes”.

<title>Programming in Python</title>

<title>Programming in Python</title>
<subtitle>With an IDE</subtitle>

<title>Programming in Python</title>
<titleabbrev>Python</titleabbrev>

<title>Programming in Python</title>
<subtitle>With an IDE</subtitle>
<titleabbrev>Python</titleabbrev>

You need to get the documentation title as a string.

Use the named template get.doc.title (from common/utilities.xsl):

<xsl:template match="...">
   <xsl:variable name="doctitle">
     <xsl:call-template name="get.doc.title"/>
   </xsl:variable>
   <!-- ... use the varialbe $doctitle ...-->
</xsl:template>

The documentation title is the outmost title of your text. This can be a title from a book, glossary, set, article, or other, depending on the root element.

The get.doc.title template returns a string. In most cases this is probably enough, for example, if you want to use it as an attribute value where markup is not allowed.

If you need the full markup, use the methods described in Section 2.5, “Accessing Title Contents”.

You need an own processing instruction (not one from the DocBook XSL stylesheets) to fine-tune your transformation.

The DocBook XSL stylesheet offers the pi-attribute template for this purpose. It expects a processing instruction node and a “pseudo-attribute” name. For example, the following processing instruction is given:

<?toms-html background-color="blue"?>

Call pi-attribute to extract the content of the pseudo-attribute name:

<xsl:call-template name="pi-attribute">
  <xsl:with-param name="pis" select="processing-instruction('toms-html')"/>
  <xsl:with-param name="attribute" select="'background-color'"/>
</xsl:call-template>

This gives you the result blue.

Processing instructions (PIs) are usually needed to fine-tune your output formats, e.g., to add page break information, background color, or other stylistic hints. PIs should not be used to insert data that should normally reside inside a DocBook element! As a general rule of thumb: Use PIs if you want to provide layout specific information for your output format unless there is another method.

The following example uses the PI <?toms-html?> which is included inside a para element to insert background color in HTML:^[6]

The previous example recognizes a PI inside a para only. If you also want to recognize PIs before, use the following XPath expression in the select attribute of pi-attribute:

( processing-instruction('toms-html') |
  preceding-sibling::processing-instruction('toms-html')[1]
)[last()]

If two PIs are available (one inside, another outside), the inside one takes precedence.

You need the path to your current node—the XPath—to output it as debugging information.

The DocBook XSL stylesheet offers the xpath.location template for this purpose. To output the current XPath, use the following procedure:

If you need the XPath for a different node, extend the previous code:

<xsl:message>
  <xsl:text>Current XPath: </xsl:text>
  <xsl:call-template name="xpath.location">
    <xsl:with-param name="node" select="YOUR_XPath_Expression"/>
  </xsl:call-template>
</xsl:message>

Currently, the template in lib/lib.xsl is limited: it walks from the current node up to the root node and outputs just the element name. No namespace prefixes, no predicates. If you have a DocBook document with different namespaces, the original version does not help.

In Example 2.3, “Namespace-aware Output of an XPath”, the revised template recognizes namespaces and counts elements on the sibling axis.

<xsl:stylesheet version="1.0"
  xmlns:n="urn:x-toms:ns:namespaces"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  exclude-result-prefixes="n">
  <namespaces xmlns="urn:x-toms:ns:namespaces">  
    <ns prefix="d">http://docbook.org/ns/docbook</ns>
    <ns prefix="xi">http://www.w3.org/2001/XInclude</ns>
    <ns prefix="rdf">http://www.w3.org/1999/02/22-rdf-syntax-ns#</ns>
    <ns prefix="cc">http://creativecommons.org/ns#</ns>
    <ns prefix="svg">http://www.w3.org/2000/svg</ns>
  </namespaces>
  
  <xsl:variable name="nsnodes" select="document('')//n:namespaces/n:ns"/> 
  
  <xsl:template name="xpath.location">
    <xsl:param name="node" select="."/>
    <xsl:param name="path" select="''"/>
    <xsl:param name="method">prefix</xsl:param>            
  
    <xsl:variable name="next.path">
      <xsl:choose>                                         
        <xsl:when test="$method = 'prefix' and $nsnodes[namespace-uri($node)]">
          <xsl:value-of select="concat($nsnodes[namespace-uri($node) = .]/@prefix, ':')"/>
        </xsl:when>
        <xsl:when test="$method = 'clark' and namespace-uri($node) != ''">
          <xsl:value-of select="concat('{', namespace-uri($node), '}')"/>
        </xsl:when>
      </xsl:choose>  
      <xsl:value-of select="local-name($node)"/>      
      <xsl:if test="generate-id($node) != generate-id(/*) and
                    count(../*[local-name()=local-name(current()) and
                             namespace-uri()=namespace-uri(current())]) > 1">  
        <xsl:text>[</xsl:text>
        <xsl:value-of select="count(preceding-sibling::*
                          [local-name()=local-name(current()) and
                           namespace-uri()=namespace-uri(current())]) + 1"/>
      <xsl:text>]</xsl:text>
    </xsl:if>
      <xsl:if test="$path != ''">
        <xsl:text>/</xsl:text>
      </xsl:if>
      <xsl:value-of select="$path"/>
    </xsl:variable>
    
    <xsl:choose>
      <xsl:when test="$node/parent::*">
        <xsl:call-template name="xpath.location">
          <xsl:with-param name="node" select="$node/parent::*"/>
          <xsl:with-param name="path" select="$next.path"/>
        </xsl:call-template>
      </xsl:when>
      <xsl:otherwise>
        <xsl:value-of select="concat('/', $next.path)"/>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>
  
</xsl:stylesheet>

The template can output the XPath in two different notations:

Be aware, the previous template is slower than the original version (it has to count a little bit more). For debugging purpose it is probably fine.

You need a general solution to add localized text without hard-coding it into your stylesheet. Depending on the language, it should display the correct, translated text.

Use language files to add your text. Language files are the DocBook way to support several languages, all located under the common directory. Each file is in XML format and contains all your translated text as a key/value pair. For more complex settings and to group things, there are contexts. The key is never translated, it is a constant and is only needed to find and retrieve the translated text.

To use a language file, proceed as follows:

The “gentext” method to insert language specific text is quite powerful, but not almighty. It helps you to keep translatable text in one place and avoids hard-coded locations in your stylesheets. If you need the translated text not for the default language (usually marked in the root element), but for a different language, use the xsl:with-param as shown:

<xsl:call-template name="gentext">
  <xsl:with-param name="key" select="'Authors'"/>
  <xsl:with-param name="lang">de</xsl:with-param>
</xsl:call-template>

http://www.sagehill.net/docbookxsl/Localizations.html

You need the language of the current element or of your DocBook document.

Use the l10n.language template from common/l10n.xsl. It extracts the language attribute from the current context node or its ancestors:

<xsl:variable name="language">
   <xsl:call-template name="l10n.language"/>
</xsl:variable>

It returns a “normalized” string which is RFC1766 compliant.

If you need to change the current node, use the target parameter. For example, the following code extracts the language from the root element:

<xsl:variable name="lang">
   <xsl:call-template name="l10n.language">
      <xsl:with-param name="target" select="/*"/>
   </xsl:call-template>
</xsl:variable>

Language information is stored in DocBook either in the lang (4.x) or xml:lang (>5.x) attributes. These attributes can be set on every DocBook element.

For example, if you have a chapter inside a book and want to extract the contents of the language attribute from this chapter, the following XPath expression gives you this information:

/book/chapter/@lang             DocBook 4.x
/db:book/db:chapter/@xml:lang   DocBook 5.x
            

Although the XPath expressions are simple, they have some drawbacks:

All the previous problems are considered by the l10n.language template. It searches for the nearest ancestor that contains a language attribute and returns its content. For example, consider the following structure:

book xml:lang="en"
  chapter
    section
      para
        foreignphrase xml:lang="de"

If your current context is on the foreignphrase element, l10n.language will return de as language. However, if your context is on the para element, you will get en. The para, section, and chapter elements are children of book and therefore in the scope of the language attribute which gives you en. In the case no language is given, the template returns a default language from the l10n.gentext.default.language parameter (usually English).

Sometimes, returning only the language is not enough. The following table gives you some additional functions from common/l10n.xsl which can be useful for your code (Question marks(?) denote an optional parameter):

attrnode = language.attribute(node="."?)

attrnode = xml.language.attribute(node="."?)

string = l10n.language.name(lang?)

You need to format an author, a group of authors, or any other name of persons.

The DocBook stylesheets provide the template person.name for a single name or person.name.list for a group of names. For example, consider the following info element:

<info>
  <author>
    <personname>
      <firstname>Tux</firstname>
      <surname>Penguin</surname>
    </personname>
  </author>
</info>

To retrieve the author name, use the following code in your template:

<xsl:call-template name="person.name">
  <xsl:with-param name="node" select="$theauthor"/>
</xsl:call-template>

where the variable theauthor points to the author node. The previous template returns the expected string:

Tux Penguin

For a group of names it is similar, just replace person.name with person.name.list.

At first glance, names seem pretty easy to format. However, it is a little bit more complicated. For example, the title of a person, its lineage, or middle names can make it sometimes harder to extract all the information. The following author contains a title and a lineage:

<author>
  <personname>
    <honorific>Dr.</honorific>
    <firstname>Tux</firstname>
    <othername>Tuxy</othername>
    <surname>Penguin</surname>
    <lineage>Jr.</lineage>
  </personname>
</author>

Depending on what you need, the DocBook stylesheets can format the name in different ways

Dr. Tux Tuxy Penguin, Jr

Penguin, Tux

Penguin Tux [FAMILY Given]

Keep in mind, the current implementation only takes into account the first occurrence of honorific or lineage.

Your header contains a consecutive number and a title. As you want to style it differently, you need to split it into two pieces.

The DocBook stylesheets have two modes which are “responsible” for generating the labels and titles: the modes label.markup and title.markup.

To “split” the header, you need to introduce an inline element for styling. For HTML this is span with a class attribute, for XSL-FO it is fo:inline. The principle is the same, but this topic shows only HTML for better readability.

Customize the label.markup and title.markup templates for the specific DocBook element. To simplify the maintenance and customization, use the XSLT <xsl:apply-imports/> tag. This allows you to call the original template without repeating it and to introduce your changes. Save the result from <xsl:apply-imports/> in a variable and only output it, if its value is not empty. The following template shows this approach for a chapter label:

<xsl:template match="d:chapter" mode="label.markup">
  <xsl:variable name="number">
    <xsl:apply-imports/>
  </xsl:variable>

  <xsl:if test="string($number) != ''">
    <span class="number"><xsl:value-of select="$number"/></span>
  </xsl:if>
</xsl:template>

For a chapter title the template is even simpler:

<xsl:template match="d:chapter" mode="title.markup">
  <span class="title">
    <xsl:apply-imports/>
  </span>
</xsl:template>

Apply these changes for all elements that you need to restyle. After you have included these changes in your customization layer, a chapter title in HTML is shown as follows:

<h2 class="title"><a id="id275730"></a>Chapter
  <span class="number">1</span>. <span class="title">...</span>
</h2>

To style the number in bold and the title in a normal weight, use the following CSS rule:

h2.title > .number {
  font-weight: bold;
}
h2.title > .title {
  font-weight: normal;
}

Of course, you can apply all CSS rules you want.

Although the customization has some benefits (simple, easy to maintain, support the language files), you should be aware of some issues.

The label.markup and title.markup modes are very basic modes; as such, they are used in other templates as well, not only for titles. This can lead to side effects, which you may or may not want. For example, the modes are used also for the table of contents and for resolving cross-references.

<xsl:template match="*" mode="insert.label.markup">
  <xsl:param name="purpose"/>
  <xsl:param name="xrefstyle"/>
  <xsl:param name="label"/>

  <xsl:value-of select="$label"/>
</xsl:template>

<xsl:template match="d:chapter" mode="insert.title.markup">
  <xsl:param name="purpose"/>
  <xsl:param name="xrefstyle"/>
  <xsl:param name="title"/>

  <xsl:choose>
    <xsl:when test="$purpose = 'xref'">
      <em><xsl:copy-of select="$title"/></em>
    </xsl:when>
    <xsl:otherwise>
      <xsl:value-of select="$title"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>

<xsl:template name="toc.line">
  <xsl:param name="toc-context" select="."/>
  <xsl:param name="depth" select="1"/>
  <xsl:param name="depth.from.context" select="8"/>
  <xsl:variable name="title">  
    <xsl:apply-templates select="." mode="titleabbrev.markup"/>
  </xsl:variable>

  <span class="{local-name(.)}">
    <xsl:if test="$autotoc.label.in.hyperlink = 0">
      <xsl:variable name="label">
        <xsl:apply-templates select="." mode="label.markup"/>
      </xsl:variable>
      <xsl:value-of select="$label"/>  
      <xsl:if test="$label != ''">
        <xsl:value-of select="$autotoc.label.separator"/>
      </xsl:if>
    </xsl:if>

    <a>
      <xsl:attribute name="href">
        <xsl:call-template name="href.target">
          <xsl:with-param name="context" select="$toc-context"/>
          <xsl:with-param name="toc-context" select="$toc-context"/>
        </xsl:call-template>
      </xsl:attribute>
      <!-- * if $autotoc.label.in.hyperlink is non-zero, then output the label -->
      <!-- * as part of the hyperlinked title -->
      <xsl:if test="not($autotoc.label.in.hyperlink = 0)">
        <xsl:variable name="label">
          <xsl:apply-templates select="." mode="label.markup"/>
        </xsl:variable>
        <xsl:value-of select="$label"/>                    
        <xsl:if test="$label != ''">
          <xsl:value-of select="$autotoc.label.separator"/>
        </xsl:if>
      </xsl:if>
      <xsl:value-of select="$title"/>                      
    </a>
  </span>
</xsl:template>

.

You want to enumerate your figures, tables, program listings, or examples consistently throughout your document.

Use a customization layer and insert the following template into your customization layer:

<xsl:template match="d:figure" mode="label.markup"> 
    <xsl:choose>
      <xsl:when test="@label"> 
        <xsl:value-of select="@label"/>
      </xsl:when>
      <xsl:otherwise>
        <xsl:number format="1" from="d:book|d:article" level="any"/> 
      </xsl:otherwise>
    </xsl:choose>
</xsl:template>

The template shown in Example 2.4 matches only figures. It can be extended to match also procedures, tables, examples etc. If you do not need the support for the label attribute, remove the xsl:choose and its children, but leave the xsl:number element.

If you need a different numbering schema, modify the format attribute in the xsl:number start-tag. For example, if you write [a] you will get consecutive lowercase letters in brackets like [a], [b], [c] etc.

You need to convert a text string from lowercase or uppercase, respectively, taking care of the current locale.

Use the utility template string.lower or string.upper from the DocBook stylesheets:

<xsl:call-template name="string.upper">
   <xsl:with-param name="string">This is your string</xsl:with-param>
</xsl:call-template>

Or:

<xsl:call-template name="string.lower">
   <xsl:with-param name="string">This is your string</xsl:with-param>
</xsl:call-template>

To transform a string into uppercase letters, XPath offers the translate function. The translate function expects three parameters: the string you want to change, a string of lowercase letters, and a string of uppercase letters. Your code looks like this:

<xsl:value-of select="translate($string, 'abcdefghijklmnopqrstuvwxyz', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ')"/>

When called by the XSLT processor, the content of the string variable is transformed into uppercase. This works pretty well if your language is English or your string does not contain any accented characters. However, if your string contains, for example, the German lowercase letter “ö”, translate does not transform it into the uppercase letter “Ö”.

This is handled by the above templates string.lower and string.upper. They use the language files of the DocBook stylesheets and get the lowercase and uppercase letters from so-called “gentext templates”. The uppercase.alpha and lowercase.alpha entries are used in the current locale.

However, this transformation is not always perfect. For example, it is recommended to transform the German “ß” (lowercase) into “SS” (uppercase).^[7] This makes the translate function unusable for such corner cases. Only XPath 2.0 supports locale-sensitive mappings with fn:upper-case.

You have a cross-reference (usually tagged with xref) and you want to append text or graphics after the reference is resolved.

Use the xref-to-prefix or xref-to-suffix mode. These modes are called before or after the xref is being resolved. As such it makes it pretty easy to add text or graphics.

For example, the following example appends the text “[x]” to each xref, regardless where it points to:

<xsl:template match="*" mode="xref-to-suffix">
   <xsl:text>[X]</xsl:text>
</xsl:template>

If you need the text only for specific elements (for example, only for chapters) use the match attribute:

<xsl:template match="d:chapter" mode="xref-to-suffix">
   <xsl:text>[X]</xsl:text>
</xsl:template>

If you have to insert text before or after your reference only, you can use one of the templates described above. However, if you need to display a graphic, you need to insert FO- or HTML-specific code. For HTML, this could look like this:

<xsl:template match="d:chapter" mode="xref-to-suffix">
   <img src="chapter.png" alt="Chapter"/>
</xsl:template>

If you need to add a graphic for FO, use the following template:

<xsl:template match="d:chapter" mode="xref-to-suffix">
   <xsl:variable name="srcfile">
     <xsl:call-template name="fo-external-image">
       <xsl:with-param name="filename" select="'chapter.png'"/>
     </xsl:call-template>
   </xsl:variable>

   <fo:external-graphic src="{$srcfile}" height="1em"/>
</xsl:template>

The same principle applies if you want to add something before your cross-reference. In this case, replace the xref-to-suffix mode with xref-to-prefix.

Your file, be it autogenerated or somehow “mangled” is poorly indented and you want to get rid of this.

There are different solutions to this problem:

xmllint --format XMLFILE
               

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns="http://docbook.org/ns/docbook">
  
  <xsl:import href="copy.xsl"/>
  <xsl:output indent="yes"/>

  <xsl:strip-space elements="*"/>
  <xsl:preserve-space elements="d:screen d:literallayout
    d:programlisting d:address"/>
</xsl:stylesheet>

The xmllint command with its --format option is the easiest candidate but lacks customization. This is useful if you do not have any other tools at hand and you prefer a quick and rough reformatting.

The pretty.xsl stylesheet is a pure XSLT solution. As such, it works on every platform which supports an XSLT processor. It is adaptable to your needs, but mixed content (like in para) is problematic.

The most adaptable method is xmlformat.

You have a DocBook document in version 4.x, but you need 5.x.

Generally, the difference between version 4 and version 5 is minimal. Refer to the The Definitive Guide for detailed information what has been added, removed, or renamed.

One major change is that all DocBook 5.x elements are in the namespace http://docbook.org/ns/docbook. All these changes are taken into account by the db4-upgrade.xsl, see the URL https://github.com/docbook/docbook/blob/master/relaxng/tools/db4-upgrade.xsl. You just need to apply this stylesheet to your source DocBook document, for example:

$ xsltproc --output doc5.xml db4-upgrade.xsl doc.xml

After the migration, the file doc5.xml contains your DocBook5 source.

One disadvantage is that entities are not preserved. This is not a stylesheet issue but an XML issue. The entities are already resolved when the XSLT processor gets its hand on the source tree. The stylesheet never sees the entities.

In cases you need to leave your entities untouched, refer to Section 3.18, “Preserving Entities”.

You have a DocBook document in version 5.x, but you need 4.x.

Generally, the difference between version 4 and version 5 are minimal. Refer to the The Definitive Guide for detailed information what has been added, removed, or renamed.

In case you have or get DocBook 5 and need the former version, the following stylesheet which supports the core transformation might help:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:d="http://docbook.org/ns/docbook"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  xmlns:html="http://www.w3.org/1999/xhtml"
  xmlns:exsl="http://exslt.org/common"
  exclude-result-prefixes="d xi xlink exsl html">

  <xsl:import href="copy.xsl"/>
  
  <xsl:output method="xml" indent="yes" 
    doctype-public="-//OASIS//DTD DocBook XML V4.5//EN"
    doctype-system="http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"/>
  <xsl:strip-space elements="*"/>
  <xsl:preserve-space 
    elements="d:screen d:programlisting d:literallayout xi:*"/>
  <xsl:variable name="inlines">abbrev accel acronym alt anchor
    annotation application author biblioref citation citebiblioid
    citerefentry citetitle classname code command computeroutput
    constant coref database date editor email emphasis envar errorcode
    errorname errortext errortype exceptionname filename firstterm
    footnote footnoteref foreignphrase function glossterm guibutton
    guiicon guilabel guimenu guimenuitem guisubmenu hardware indexterm
    initializer inlineequation inlinemediaobject interfacename jobtitle
    keycap keycode keycombo keysym link literal markup menuchoice
    methodname modifier mousebutton nonterminal olink ooclass
    ooexception oointerface option optional org orgname package
    parameter person personname phrase productname productnumber prompt
    property quote remark replaceable returnvalue shortcut subscript
    superscript symbol systemitem tag termdef token trademark type uri
    userinput varname wordasword xref</xsl:variable>
  
  <!-- Overwrite standard template and create elements without 
       a namespace node
  -->
  <xsl:template match="d:*">
    <xsl:element name="{local-name()}">
      <xsl:apply-templates select="@*|node()"/>
    </xsl:element>
  </xsl:template>
    
  <xsl:template match="@xml:id|@xml:lang">
    <xsl:attribute name="{local-name()}">
      <xsl:apply-templates/>
    </xsl:attribute>
  </xsl:template>
  
  <!-- Suppress the following attributes: -->
  <xsl:template match="@annotations|@version"/>
  <xsl:template match="@xlink:*"/>
  
  <xsl:template match="@xlink:href">
    <xsl:choose>
      <xsl:when test="contains($inlines, local-name(..))">
        <ulink url="{.}" remap="{local-name(..)}">
          <xsl:value-of select=".."/>
        </ulink>
      </xsl:when>
      <xsl:otherwise>
        <xsl:message>@xlink:href could not be processed!
  parent element: <xsl:value-of select="local-name(..)"/>
        </xsl:message>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>
  
  <xsl:template match="d:*[@xlink:href]">
    <xsl:choose>
      <xsl:when test="contains($inlines, local-name())">
        <ulink url="{@xlink:href}" remap="{local-name(.)}">
          <xsl:element name="{local-name()}">
            <xsl:apply-templates 
              select="@*[local-name() != 'href' and
                         namespace-uri() != 'http://www.w3.org/1999/xlink']
                      |node()"/>
          </xsl:element>
        </ulink>
      </xsl:when>
      <xsl:otherwise>
        <xsl:element name="{local-name()}">
          <xsl:apply-templates 
            select="@*[local-name() != 'href' and
                       namespace-uri() != 'http://www.w3.org/1999/xlink']
                    |node()"/>
        </xsl:element>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>
  
  <xsl:template match="d:link/@xlink:href">
    <xsl:attribute name="url">
      <xsl:value-of select="."/>
    </xsl:attribute>
  </xsl:template>
  
  <xsl:template match="d:link[@xlink:href]">
    <ulink>
      <xsl:apply-templates select="@*|node()"/>
    </ulink>
  </xsl:template>
  
  <xsl:template match="d:link[@linkend]">
    <link>
      <xsl:apply-templates select="@*|node()"/>
    </link>
  </xsl:template>
  
  <!-- Renamed DocBook elements -->
  <xsl:template match="d:personblurb">
    <authorblurb>
      <xsl:apply-templates select="@*|node()"/>
    </authorblurb>
  </xsl:template>
  <xsl:template match="d:tag">
    <sgmltag>
      <xsl:apply-templates select="@*|node()"/>
    </sgmltag>
  </xsl:template>
  
  <!-- New DocBook v5.1 and HTML elements, no mapping available -->
  <xsl:template match="d:acknowledgements|d:annotation|d:arc
                       |d:cover
                       |d:definitions
                       |d:extendedlink
                       |d:givenname
                       |d:locator
                       |d:org|d:tocdiv
                       |html:*">
    <xsl:message>Don't know how to transfer "<xsl:value-of
      select="local-name()"/>" element into DocBook 4</xsl:message>
  </xsl:template>
  
  <xsl:template match="d:orgname">
     <othername>
       <xsl:apply-templates select="@*|node()"/>
     </othername>
   </xsl:template>

</xsl:stylesheet>

Use your favorite XSLT processor to transform your documents.

The stylesheet from Example 3.3, “ db5to4-core.xsl ” imports the templates from copy.xsl using an identity transformation. That means, whatever is not specified gets copied. In most cases that is what you want—a DocBook 5 section element will be transformed into an equally named DocBook 4 section element without the namespace.

Where it gets difficult are the new elements which are introduced in DocBook 5. Whenever the stylesheet encounters those it will print a warning. These elements are not copied to the output stream. If you have one of those elements you need to customize the stylesheet yourself.

Another issue is the almost ubiquitary info element which can appear in structual and block elements. The above stylesheet does it wrong and copies any info element straight into the output stream. However, DocBook 4 has different element names for meta information in DocBook 5. If you have info elements in your document they have to be renamed, depending on the parent element:

Apart from the renaming, the order of the renamed info element is crucial. Consider the following DocBook 5 structure:

section
  title
  info

This structure has to be renamed and reorganized as follows:

section
  sectioninfo
  title

As you can see, the title element appears now after the renamed info. All these issues are solved with the following additional stylesheet:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:d="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  xmlns:exsl="http://exslt.org/common"
  exclude-result-prefixes="d xlink exsl">
  
  <!-- Structural elements using info -->
  <xsl:template match="d:appendix[d:info]
                      |d:article[d:info]
                      |d:bibliography[d:info]
                      |d:book[d:info]
                      |d:chapter[d:info]
                      |d:colophon[d:info]
                      |d:equation[d:info]
                      |d:glossary[d:info]
                      |d:index[d:info]
                      |d:legalnotice[d:info]
                      |d:part[d:info]
                      |d:partintro[d:info]
                      |d:preface[d:info]
                      |d:reference[d:info]
                      |d:refsect1[d:info]
                      |d:refsect2[d:info]
                      |d:refsect3[d:info]
                      |d:refsection[d:info]
                      |d:refsynopsisdiv[d:info]
                      |d:sect1[d:info]
                      |d:sect2[d:info]
                      |d:sect3[d:info]
                      |d:sect4[d:info]
                      |d:sect5[d:info]
                      |d:section[d:info]
                      |d:set[d:info]
                      |d:setindex[d:info]">
    <!-- Change order of info and title  -->
    <xsl:element name="{local-name()}">
      <xsl:apply-templates select="@*"/>
      <xsl:apply-templates select="d:title/preceding-sibling::processing-instruction()
                                   |d:title/preceding-sibling::comment()"/>
      <xsl:apply-templates select="d:info"/>
      <xsl:apply-templates select="d:title"/>
      <!-- Process the rest -->
      <xsl:apply-templates select="d:info/following-sibling::node()"/>
    </xsl:element>
  </xsl:template>
  
  <!-- Block elements using info -->
  <xsl:template match="d:bibliolist[d:info]
                      |d:blockquote[d:info]
                      |d:equation[d:info]
                      |d:example[d:info]
                      |d:figure[d:info]
                      |d:glosslist[d:info]
                      |d:informalequation[d:info]
                      |d:informalexample[d:info]
                      |d:informalfigure[d:info]
                      |d:informaltable[d:info]
                      |d:itemizedlist[d:info]
                      |d:legalnotice[d:info]
                      |d:msgset[d:info]
                      |d:orderedlist[d:info]
                      |d:procedure[d:info]
                      |d:qandadiv[d:info]
                      |d:qandaentry[d:info]
                      |d:qandaset[d:info]
                      |d:table[d:info]
                      |d:task[d:info]
                      |d:taskprerequisites[d:info]
                      |d:taskrelated[d:info]
                      |d:tasksummary[d:info]
                      |d:variablelist[d:info]">
    <xsl:element name="{local-name()}">
      <xsl:apply-templates select="@*"/>
      <xsl:apply-templates select="d:title/preceding-sibling::processing-instruction()
                                   |d:title/preceding-sibling::comment()"/>
      <xsl:apply-templates select="d:info">
        <xsl:with-param name="infoname">block</xsl:with-param>
      </xsl:apply-templates>
      <xsl:apply-templates select="d:title|
                                   d:title/following-sibling::processing-instruction()[1]
                                   |d:title/following-sibling::comment()[1]"/>
      
      <!-- Process the rest -->
      <xsl:apply-templates select="d:info/following-sibling::node()"/>
    </xsl:element>
  </xsl:template>

  <!-- Suppress other info elements who has no direct mapping -->
  <xsl:template match="d:*[d:info]"/>
  
  <xsl:template match="d:info">
    <xsl:param name="infoname" select="local-name(..)"/>
    <xsl:variable name="rtf-node">
      <xsl:element name="{$infoname}info">
      <xsl:apply-templates select="@*|node()"/>
    </xsl:element>
    </xsl:variable>
    <xsl:choose>
      <xsl:when test="count(exsl:node-set($rtf-node)/*/*) > 0">
        <xsl:copy-of select="$rtf-node"/>
      </xsl:when>
      <xsl:otherwise><!-- Don't copy, it's empty --></xsl:otherwise>
    </xsl:choose>
  </xsl:template>
</xsl:stylesheet>

To combine both, use the following stylesheet:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:d="http://docbook.org/ns/docbook">

  <xsl:import href="db5to4-core.xsl"/>
  <xsl:import href="db5to4-info.xsl"/>
  
  <xsl:output method="xml" indent="yes" 
    doctype-public="-//OASIS//DTD DocBook XML V4.5//EN"
    doctype-system="http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"/>
</xsl:stylesheet>

The above stylesheets were separated between a core functionality (db5to4-core.xsl) with additional info element handling (db5to4-info.xsl). In most cases you will use the stylesheet db5to4-withinfo.xsl, but if you want to implement a different info handling you can. In Example 3.5, “ db5to4-withinfo.xsl ” just replace the line with importing db5to4-info.xsl with your own implementation.

You have a big DocBook document, like a book, and you want to split each chapter, appendix etc. into a separate file.

There are three solutions to this problems:

The following subsections describe each method.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE xsl:stylesheet 
[
 <!ENTITY db "https://cdn.docbook.org/release/xsl/current"> 
]>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:d="http://docbook.org/ns/docbook"
  xmlns:exsl="http://exslt.org/common"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  extension-element-prefixes="exsl">

  <xsl:import href="chunker.xsl"/>
  <xsl:import href="copy.xsl"/>
  <xsl:output indent="yes"/>


  <xsl:param name="base.dir" select="'out/'"/>
  <xsl:param name="use.id.as.filename" select="0"/>
  <xsl:param name="rootid"/>

  <xsl:param name="dbsplit.root.filename">Index</xsl:param>
  <xsl:param name="dbsplit.ext">.xml</xsl:param>
  <xsl:param name="dbsplit.chunk.depth" select="2"/>

  <xsl:template name="object.id">
    <xsl:param name="object" select="."/>
    <xsl:choose>
      <xsl:when test="$object/@id">
        <xsl:value-of select="$object/@id"/>
      </xsl:when>
      <xsl:when test="$object/@xml:id">
        <xsl:value-of select="$object/@xml:id"/>
      </xsl:when>
      <xsl:otherwise>
        <xsl:value-of select="generate-id($object)"/>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>

  <xsl:template match="*" mode="recursive-chunk-filename">
    <xsl:param name="recursive" select="false()"/>
    <xsl:variable name="filename">
      <xsl:choose>
        <!-- if this is the root element, use the dbsplit.root.filename -->
        <xsl:when test="not(parent::*) and $dbsplit.root.filename != ''">
          <xsl:value-of select="$dbsplit.root.filename"/>
          <xsl:value-of select="$dbsplit.ext"/>
        </xsl:when>
        <!-- Special case -->
        <xsl:when
          test="self::d:legalnotice and not($generate.legalnotice.link = 0)">
          <xsl:choose>
            <xsl:when
              test="(@id or @xml:id) and not($use.id.as.filename = 0)">
              <!-- * if this legalnotice has an ID, then go ahead and use -->
              <!-- * just the value of that ID as the basename for the file -->
              <!-- * (that is, without prepending an "ln-" too it) -->
              <xsl:value-of select="(@id|@xml:id)[1]"/>
              <xsl:value-of select="$dbsplit.ext"/>
            </xsl:when>
            <xsl:otherwise>
              <!-- * otherwise, if this legalnotice does not have an ID, -->
              <!-- * then we generate an ID... -->
              <xsl:variable name="id">
                <xsl:call-template name="object.id"/>
              </xsl:variable>
              <!-- * ...and then we take that generated ID, prepend an -->
              <!-- * "ln-" to it, and use that as the basename for the file -->
              <xsl:value-of select="concat('ln-',$id,$dbsplit.ext)"/>
            </xsl:otherwise>
          </xsl:choose>
        </xsl:when>
        <!-- if there's no dbhtml filename, and if we're to use IDs as -->
        <!-- filenames, then use the ID to generate the filename. -->
        <xsl:when test="(@id or @xml:id) and $use.id.as.filename != 0">
          <xsl:value-of select="(@id|@xml:id)[1]"/>
          <xsl:value-of select="$dbsplit.ext"/>
        </xsl:when>
        <xsl:otherwise/>
      </xsl:choose>
    </xsl:variable>

    <xsl:choose>
      <xsl:when test="not($recursive) and $filename != ''">
        <!-- if this chunk has an explicit name, use it -->
        <xsl:value-of select="$filename"/>
      </xsl:when>

      <xsl:when test="self::d:set">
        <xsl:value-of select="$dbsplit.root.filename"/>
        <xsl:if test="not($recursive)">
          <xsl:value-of select="$dbsplit.ext"/>
        </xsl:if>
      </xsl:when>

      <xsl:when test="self::d:book">
        <xsl:text>bk</xsl:text>
        <xsl:number level="any" format="01"/>
        <xsl:if test="not($recursive)">
          <xsl:value-of select="$dbsplit.ext"/>
        </xsl:if>
      </xsl:when>

      <xsl:when test="self::d:article">
        <xsl:if test="/d:set">
          <!-- in a set, make sure we inherit the right book info... -->
          <xsl:apply-templates mode="recursive-chunk-filename"
            select="parent::*">
            <xsl:with-param name="recursive" select="true()"/>
          </xsl:apply-templates>
        </xsl:if>

        <xsl:text>ar</xsl:text>
        <xsl:number level="any" format="01" from="d:book"/>
        <xsl:if test="not($recursive)">
          <xsl:value-of select="$dbsplit.ext"/>
        </xsl:if>
      </xsl:when>

      <xsl:when test="self::d:preface">
        <xsl:if test="/d:set">
          <!-- in a set, make sure we inherit the right book info... -->
          <xsl:apply-templates mode="recursive-chunk-filename"
            select="parent::*">
            <xsl:with-param name="recursive" select="true()"/>
          </xsl:apply-templates>
        </xsl:if>

        <xsl:text>pr</xsl:text>
        <xsl:number level="any" format="01" from="d:book"/>
        <xsl:if test="not($recursive)">
          <xsl:value-of select="$dbsplit.ext"/>
        </xsl:if>
      </xsl:when>

      <xsl:when test="self::d:chapter">
        <xsl:if test="/d:set">
          <!-- in a set, make sure we inherit the right book info... -->
          <xsl:apply-templates mode="recursive-chunk-filename"
            select="parent::*">
            <xsl:with-param name="recursive" select="true()"/>
          </xsl:apply-templates>
        </xsl:if>

        <xsl:text>ch</xsl:text>
        <xsl:number level="any" format="01" from="d:book"/>
        <xsl:if test="not($recursive)">
          <xsl:value-of select="$dbsplit.ext"/>
        </xsl:if>
      </xsl:when>

      <xsl:when test="self::d:appendix">
        <xsl:if test="/d:set">
          <!-- in a set, make sure we inherit the right book info... -->
          <xsl:apply-templates mode="recursive-chunk-filename"
            select="parent::*">
            <xsl:with-param name="recursive" select="true()"/>
          </xsl:apply-templates>
        </xsl:if>

        <xsl:text>ap</xsl:text>
        <xsl:number level="any" format="a" from="d:book"/>
        <xsl:if test="not($recursive)">
          <xsl:value-of select="$dbsplit.ext"/>
        </xsl:if>
      </xsl:when>

      <xsl:when test="self::d:part">
        <xsl:choose>
          <xsl:when test="/d:set">
            <!-- in a set, make sure we inherit the right book info... -->
            <xsl:apply-templates mode="recursive-chunk-filename"
              select="parent::*">
              <xsl:with-param name="recursive" select="true()"/>
            </xsl:apply-templates>
          </xsl:when>
          <xsl:otherwise> </xsl:otherwise>
        </xsl:choose>

        <xsl:text>pt</xsl:text>
        <xsl:number level="any" format="01" from="d:book"/>
        <xsl:if test="not($recursive)">
          <xsl:value-of select="$dbsplit.ext"/>
        </xsl:if>
      </xsl:when>

      <xsl:when test="self::d:reference">
        <xsl:choose>
          <xsl:when test="/d:set">
            <!-- in a set, make sure we inherit the right book info... -->
            <xsl:apply-templates mode="recursive-chunk-filename"
              select="parent::*">
              <xsl:with-param name="recursive" select="true()"/>
            </xsl:apply-templates>
          </xsl:when>
          <xsl:otherwise> </xsl:otherwise>
        </xsl:choose>

        <xsl:text>rn</xsl:text>
        <xsl:number level="any" format="01" from="d:book"/>
        <xsl:if test="not($recursive)">
          <xsl:value-of select="$dbsplit.ext"/>
        </xsl:if>
      </xsl:when>

      <xsl:when test="self::d:refentry">
        <xsl:choose>
          <xsl:when test="parent::d:reference">
            <xsl:apply-templates mode="recursive-chunk-filename"
              select="parent::*">
              <xsl:with-param name="recursive" select="true()"/>
            </xsl:apply-templates>
          </xsl:when>
          <xsl:otherwise>
            <xsl:if test="/d:set">
              <!-- in a set, make sure we inherit the right book info... -->
              <xsl:apply-templates mode="recursive-chunk-filename"
                select="parent::*">
                <xsl:with-param name="recursive" select="true()"/>
              </xsl:apply-templates>
            </xsl:if>
          </xsl:otherwise>
        </xsl:choose>

        <xsl:text>re</xsl:text>
        <xsl:number level="any" format="01" from="d:book"/>
        <xsl:if test="not($recursive)">
          <xsl:value-of select="$dbsplit.ext"/>
        </xsl:if>
      </xsl:when>

      <xsl:when test="self::d:colophon">
        <xsl:choose>
          <xsl:when test="/d:set">
            <!-- in a set, make sure we inherit the right book info... -->
            <xsl:apply-templates mode="recursive-chunk-filename"
              select="parent::*">
              <xsl:with-param name="recursive" select="true()"/>
            </xsl:apply-templates>
          </xsl:when>
          <xsl:otherwise> </xsl:otherwise>
        </xsl:choose>

        <xsl:text>co</xsl:text>
        <xsl:number level="any" format="01" from="d:book"/>
        <xsl:if test="not($recursive)">
          <xsl:value-of select="$dbsplit.ext"/>
        </xsl:if>
      </xsl:when>

      <xsl:when test="self::d:sect1 or self::d:sect2 or self::d:sect3 or 
                      self::d:sect4 or self::d:sect5 or self::d:section">
        <xsl:apply-templates mode="recursive-chunk-filename"
          select="parent::*">
          <xsl:with-param name="recursive" select="true()"/>
        </xsl:apply-templates>
        <xsl:text>s</xsl:text>
        <xsl:number format="01"/>
        <xsl:if test="not($recursive)">
          <xsl:value-of select="$dbsplit.ext"/>
        </xsl:if>
      </xsl:when>

      <xsl:when test="self::d:bibliography">
        <xsl:choose>
          <xsl:when test="/d:set">
            <!-- in a set, make sure we inherit the right book info... -->
            <xsl:apply-templates mode="recursive-chunk-filename"
              select="parent::*">
              <xsl:with-param name="recursive" select="true()"/>
            </xsl:apply-templates>
          </xsl:when>
          <xsl:otherwise> </xsl:otherwise>
        </xsl:choose>

        <xsl:text>bi</xsl:text>
        <xsl:number level="any" format="01" from="d:book"/>
        <xsl:if test="not($recursive)">
          <xsl:value-of select="$dbsplit.ext"/>
        </xsl:if>
      </xsl:when>

      <xsl:when test="self::d:glossary">
        <xsl:choose>
          <xsl:when test="/d:set">
            <!-- in a set, make sure we inherit the right book info... -->
            <xsl:apply-templates mode="recursive-chunk-filename"
              select="parent::*">
              <xsl:with-param name="recursive" select="true()"/>
            </xsl:apply-templates>
          </xsl:when>
          <xsl:otherwise> </xsl:otherwise>
        </xsl:choose>

        <xsl:text>go</xsl:text>
        <xsl:number level="any" format="01" from="d:book"/>
        <xsl:if test="not($recursive)">
          <xsl:value-of select="$dbsplit.ext"/>
        </xsl:if>
      </xsl:when>

      <xsl:when test="self::d:index">
        <xsl:choose>
          <xsl:when test="/d:set">
            <!-- in a set, make sure we inherit the right book info... -->
            <xsl:apply-templates mode="recursive-chunk-filename"
              select="parent::*">
              <xsl:with-param name="recursive" select="true()"/>
            </xsl:apply-templates>
          </xsl:when>
          <xsl:otherwise> </xsl:otherwise>
        </xsl:choose>

        <xsl:text>ix</xsl:text>
        <xsl:number level="any" format="01" from="d:book"/>
        <xsl:if test="not($recursive)">
          <xsl:value-of select="$dbsplit.ext"/>
        </xsl:if>
      </xsl:when>

      <xsl:when test="self::d:setindex">
        <xsl:text>si</xsl:text>
        <xsl:number level="any" format="01" from="d:set"/>
        <xsl:if test="not($recursive)">
          <xsl:value-of select="$dbsplit.ext"/>
        </xsl:if>
      </xsl:when>

      <xsl:otherwise>
        <xsl:text>chunk-filename-error-</xsl:text>
        <xsl:value-of select="name(.)"/>
        <xsl:number level="any" format="01" from="d:set"/>
        <xsl:if test="not($recursive)">
          <xsl:value-of select="$dbsplit.ext"/>
        </xsl:if>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>

  <xsl:template name="generate-filename">
    <xsl:apply-templates select="." mode="recursive-chunk-filename"/>
  </xsl:template>

  <xsl:template name="generate-content">
    <xsl:variable name="filename">
      <xsl:call-template name="make-relative-filename">
        <xsl:with-param name="base.dir" select="$base.dir"/>
        <xsl:with-param name="base.name">
           <xsl:call-template name="generate-filename"/>
        </xsl:with-param>
      </xsl:call-template>
    </xsl:variable>
    <xsl:variable name="depth" select="count(ancestor::*)"/>
    
    <!--<xsl:message>generate-content:
      name: <xsl:value-of select="name()"/>
      filename: <xsl:value-of select="$filename"/>
      depth: <xsl:value-of select="$depth"/>
      test: <xsl:value-of select="$depth >= $dbsplit.chunk.depth"/>
    </xsl:message>-->
    
    <xsl:choose>
      <xsl:when test="$depth &lt;= $dbsplit.chunk.depth">
        <xi:include href="{$filename}"/>
        <xsl:call-template name="write.xml.chunk">
          <xsl:with-param name="filename" select="$filename"/>
          <xsl:with-param name="content">
            <xsl:copy-of select="preceding-sibling::processing-instruction()|
                                 preceding-sibling::comment()"/>
            <xsl:copy>
              <xsl:apply-templates/>
            </xsl:copy>
          </xsl:with-param>
        </xsl:call-template>
      </xsl:when>
      <xsl:otherwise>
        <xsl:copy>
          <xsl:apply-templates/>
        </xsl:copy>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>

  <xsl:template
    match="d:acknowledgements|d:appendix|d:article|
           d:bibliography|
           d:chapter|d:colophon|d:dedication|d:glossary|
           d:part|d:preface|d:reference|d:topic|
           d:sect1|d:section[not(parent::d:section)]">
    <xsl:call-template name="generate-content"/>
  </xsl:template>

</xsl:stylesheet>

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:saxon="http://icl.com/saxon"
  xmlns:lxslt="http://xml.apache.org/xslt"
  xmlns:redirect="http://xml.apache.org/xalan/redirect"
  xmlns:exsl="http://exslt.org/common"
  xmlns="http://www.w3.org/1999/xhtml" version="1.0"
  exclude-result-prefixes="saxon lxslt redirect exsl"
  extension-element-prefixes="saxon redirect lxslt exsl">

  <xsl:param name="chunker.output.method" select="'xml'"/>
  <xsl:param name="chunker.output.encoding" select="'UTF-8'"/>
  <xsl:param name="chunker.output.indent" select="'no'"/>
  <xsl:param name="chunker.output.omit-xml-declaration" select="'no'"/>
  <xsl:param name="chunker.output.standalone" select="'no'"/>
  <xsl:param name="chunker.output.doctype-public" select="''"/>
  <xsl:param name="chunker.output.doctype-system" select="''"/>
  <xsl:param name="chunker.output.media-type" select="''"/>
  <xsl:param name="chunker.output.cdata-section-elements" select="''"/>
  <xsl:param name="chunker.output.quiet" select="0"/>

  <xsl:param name="saxon.character.representation"
    select="'entity;decimal'"/>

  <xsl:template name="make-relative-filename">
    <xsl:param name="base.dir" select="'./'"/>
    <xsl:param name="base.name" select="''"/>

    <xsl:choose>
      <!-- put Saxon first to work around a bug in libxslt -->
      <xsl:when test="element-available('saxon:output')">
        <!-- Saxon doesn't make the chunks relative -->
        <xsl:value-of select="concat($base.dir,$base.name)"/>
      </xsl:when>
      <xsl:when test="element-available('exsl:document')">
        <!-- EXSL document does make the chunks relative, I think -->
        <xsl:choose>
          <xsl:when test="count(parent::*) = 0">
            <xsl:value-of select="concat($base.dir,$base.name)"/>
          </xsl:when>
          <xsl:otherwise>
            <xsl:value-of select="$base.name"/>
          </xsl:otherwise>
        </xsl:choose>
      </xsl:when>
      <xsl:when test="element-available('redirect:write')">
        <!-- Xalan doesn't make the chunks relative -->
        <xsl:value-of select="concat($base.dir,$base.name)"/>
      </xsl:when>
      <xsl:otherwise>
        <xsl:message terminate="yes">
          <xsl:text>Don't know how to chunk with </xsl:text>
          <xsl:value-of select="system-property('xsl:vendor')"/>
        </xsl:message>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>

  <xsl:template name="write.chunk">
    <xsl:param name="filename" select="''"/>
    <xsl:param name="quiet" select="$chunker.output.quiet"/>
    <xsl:param name="suppress-context-node-name" select="0"/>
    <xsl:param name="message-prolog"/>
    <xsl:param name="message-epilog"/>

    <xsl:param name="method" select="$chunker.output.method"/>
    <xsl:param name="encoding" select="$chunker.output.encoding"/>
    <xsl:param name="indent" select="$chunker.output.indent"/>
    <xsl:param name="omit-xml-declaration"
      select="$chunker.output.omit-xml-declaration"/>
    <xsl:param name="standalone" select="$chunker.output.standalone"/>
    <xsl:param name="doctype-public"
      select="$chunker.output.doctype-public"/>
    <xsl:param name="doctype-system"
      select="$chunker.output.doctype-system"/>
    <xsl:param name="media-type" select="$chunker.output.media-type"/>
    <xsl:param name="cdata-section-elements"
      select="$chunker.output.cdata-section-elements"/>

    <xsl:param name="content"/>

    <xsl:if test="$quiet = 0">
      <xsl:message>
        <xsl:if test="not($message-prolog = '')">
          <xsl:value-of select="$message-prolog"/>
        </xsl:if>
        <xsl:text>Writing </xsl:text>
        <xsl:value-of select="$filename"/>
        <xsl:if test="name(.) != '' and $suppress-context-node-name = 0">
          <xsl:text> for </xsl:text>
          <xsl:value-of select="name(.)"/>
          <xsl:if test="@id or @xml:id">
            <xsl:text>(</xsl:text>
            <xsl:value-of select="(@id|@xml:id)[1]"/>
            <xsl:text>)</xsl:text>
          </xsl:if>
        </xsl:if>
        <xsl:if test="not($message-epilog = '')">
          <xsl:value-of select="$message-epilog"/>
        </xsl:if>
      </xsl:message>
    </xsl:if>

    <xsl:choose>
      <xsl:when test="element-available('exsl:document')">
        <xsl:choose>
          <!-- Handle the permutations ... -->
          <xsl:when test="$media-type != ''">
            <xsl:choose>
              <xsl:when
                test="$doctype-public != '' and $doctype-system != ''">
                <exsl:document href="{$filename}" method="{$method}"
                  encoding="{$encoding}" indent="{$indent}"
                  omit-xml-declaration="{$omit-xml-declaration}"
                  cdata-section-elements="{$cdata-section-elements}"
                  media-type="{$media-type}"
                  doctype-public="{$doctype-public}"
                  doctype-system="{$doctype-system}"
                  standalone="{$standalone}">
                  <xsl:copy-of select="$content"/>
                </exsl:document>
              </xsl:when>
              <xsl:when
                test="$doctype-public != '' and $doctype-system = ''">
                <exsl:document href="{$filename}" method="{$method}"
                  encoding="{$encoding}" indent="{$indent}"
                  omit-xml-declaration="{$omit-xml-declaration}"
                  cdata-section-elements="{$cdata-section-elements}"
                  media-type="{$media-type}"
                  doctype-public="{$doctype-public}"
                  standalone="{$standalone}">
                  <xsl:copy-of select="$content"/>
                </exsl:document>
              </xsl:when>
              <xsl:when
                test="$doctype-public = '' and $doctype-system != ''">
                <exsl:document href="{$filename}" method="{$method}"
                  encoding="{$encoding}" indent="{$indent}"
                  omit-xml-declaration="{$omit-xml-declaration}"
                  cdata-section-elements="{$cdata-section-elements}"
                  media-type="{$media-type}"
                  doctype-system="{$doctype-system}"
                  standalone="{$standalone}">
                  <xsl:copy-of select="$content"/>
                </exsl:document>
              </xsl:when>
              <xsl:otherwise>
                <!-- $doctype-public = '' and $doctype-system = ''"> -->
                <exsl:document href="{$filename}" method="{$method}"
                  encoding="{$encoding}" indent="{$indent}"
                  omit-xml-declaration="{$omit-xml-declaration}"
                  cdata-section-elements="{$cdata-section-elements}"
                  media-type="{$media-type}" standalone="{$standalone}">
                  <xsl:copy-of select="$content"/>
                </exsl:document>
              </xsl:otherwise>
            </xsl:choose>
          </xsl:when>
          <xsl:otherwise>
            <xsl:choose>
              <xsl:when
                test="$doctype-public != '' and $doctype-system != ''">
                <exsl:document href="{$filename}" method="{$method}"
                  encoding="{$encoding}" indent="{$indent}"
                  omit-xml-declaration="{$omit-xml-declaration}"
                  cdata-section-elements="{$cdata-section-elements}"
                  doctype-public="{$doctype-public}"
                  doctype-system="{$doctype-system}"
                  standalone="{$standalone}">
                  <xsl:copy-of select="$content"/>
                </exsl:document>
              </xsl:when>
              <xsl:when
                test="$doctype-public != '' and $doctype-system = ''">
                <exsl:document href="{$filename}" method="{$method}"
                  encoding="{$encoding}" indent="{$indent}"
                  omit-xml-declaration="{$omit-xml-declaration}"
                  cdata-section-elements="{$cdata-section-elements}"
                  doctype-public="{$doctype-public}"
                  standalone="{$standalone}">
                  <xsl:copy-of select="$content"/>
                </exsl:document>
              </xsl:when>
              <xsl:when
                test="$doctype-public = '' and $doctype-system != ''">
                <exsl:document href="{$filename}" method="{$method}"
                  encoding="{$encoding}" indent="{$indent}"
                  omit-xml-declaration="{$omit-xml-declaration}"
                  cdata-section-elements="{$cdata-section-elements}"
                  doctype-system="{$doctype-system}"
                  standalone="{$standalone}">
                  <xsl:copy-of select="$content"/>
                </exsl:document>
              </xsl:when>
              <xsl:otherwise>
                <!-- $doctype-public = '' and $doctype-system = ''"> -->
                <exsl:document href="{$filename}" method="{$method}"
                  encoding="{$encoding}" indent="{$indent}"
                  omit-xml-declaration="{$omit-xml-declaration}"
                  cdata-section-elements="{$cdata-section-elements}"
                  standalone="{$standalone}">
                  <xsl:copy-of select="$content"/>
                </exsl:document>
              </xsl:otherwise>
            </xsl:choose>
          </xsl:otherwise>
        </xsl:choose>
      </xsl:when>

      <xsl:when test="element-available('saxon:output')">
        <xsl:choose>
          <!-- Handle the permutations ... -->
          <xsl:when test="$media-type != ''">
            <xsl:choose>
              <xsl:when
                test="$doctype-public != '' and $doctype-system != ''">
                <saxon:output
                  saxon:character-representation="{$saxon.character.representation}"
                  href="{$filename}" method="{$method}"
                  encoding="{$encoding}" indent="{$indent}"
                  omit-xml-declaration="{$omit-xml-declaration}"
                  cdata-section-elements="{$cdata-section-elements}"
                  media-type="{$media-type}"
                  doctype-public="{$doctype-public}"
                  doctype-system="{$doctype-system}"
                  standalone="{$standalone}">
                  <xsl:copy-of select="$content"/>
                </saxon:output>
              </xsl:when>
              <xsl:when
                test="$doctype-public != '' and $doctype-system = ''">
                <saxon:output
                  saxon:character-representation="{$saxon.character.representation}"
                  href="{$filename}" method="{$method}"
                  encoding="{$encoding}" indent="{$indent}"
                  omit-xml-declaration="{$omit-xml-declaration}"
                  cdata-section-elements="{$cdata-section-elements}"
                  media-type="{$media-type}"
                  doctype-public="{$doctype-public}"
                  standalone="{$standalone}">
                  <xsl:copy-of select="$content"/>
                </saxon:output>
              </xsl:when>
              <xsl:when
                test="$doctype-public = '' and $doctype-system != ''">
                <saxon:output
                  saxon:character-representation="{$saxon.character.representation}"
                  href="{$filename}" method="{$method}"
                  encoding="{$encoding}" indent="{$indent}"
                  omit-xml-declaration="{$omit-xml-declaration}"
                  cdata-section-elements="{$cdata-section-elements}"
                  media-type="{$media-type}"
                  doctype-system="{$doctype-system}"
                  standalone="{$standalone}">
                  <xsl:copy-of select="$content"/>
                </saxon:output>
              </xsl:when>
              <xsl:otherwise>
                <!-- $doctype-public = '' and $doctype-system = ''"> -->
                <saxon:output
                  saxon:character-representation="{$saxon.character.representation}"
                  href="{$filename}" method="{$method}"
                  encoding="{$encoding}" indent="{$indent}"
                  omit-xml-declaration="{$omit-xml-declaration}"
                  cdata-section-elements="{$cdata-section-elements}"
                  media-type="{$media-type}" standalone="{$standalone}">
                  <xsl:copy-of select="$content"/>
                </saxon:output>
              </xsl:otherwise>
            </xsl:choose>
          </xsl:when>
          <xsl:otherwise>
            <xsl:choose>
              <xsl:when
                test="$doctype-public != '' and $doctype-system != ''">
                <saxon:output
                  saxon:character-representation="{$saxon.character.representation}"
                  href="{$filename}" method="{$method}"
                  encoding="{$encoding}" indent="{$indent}"
                  omit-xml-declaration="{$omit-xml-declaration}"
                  cdata-section-elements="{$cdata-section-elements}"
                  doctype-public="{$doctype-public}"
                  doctype-system="{$doctype-system}"
                  standalone="{$standalone}">
                  <xsl:copy-of select="$content"/>
                </saxon:output>
              </xsl:when>
              <xsl:when
                test="$doctype-public != '' and $doctype-system = ''">
                <saxon:output
                  saxon:character-representation="{$saxon.character.representation}"
                  href="{$filename}" method="{$method}"
                  encoding="{$encoding}" indent="{$indent}"
                  omit-xml-declaration="{$omit-xml-declaration}"
                  cdata-section-elements="{$cdata-section-elements}"
                  doctype-public="{$doctype-public}"
                  standalone="{$standalone}">
                  <xsl:copy-of select="$content"/>
                </saxon:output>
              </xsl:when>
              <xsl:when
                test="$doctype-public = '' and $doctype-system != ''">
                <saxon:output
                  saxon:character-representation="{$saxon.character.representation}"
                  href="{$filename}" method="{$method}"
                  encoding="{$encoding}" indent="{$indent}"
                  omit-xml-declaration="{$omit-xml-declaration}"
                  cdata-section-elements="{$cdata-section-elements}"
                  doctype-system="{$doctype-system}"
                  standalone="{$standalone}">
                  <xsl:copy-of select="$content"/>
                </saxon:output>
              </xsl:when>
              <xsl:otherwise>
                <!-- $doctype-public = '' and $doctype-system = ''"> -->
                <saxon:output
                  saxon:character-representation="{$saxon.character.representation}"
                  href="{$filename}" method="{$method}"
                  encoding="{$encoding}" indent="{$indent}"
                  omit-xml-declaration="{$omit-xml-declaration}"
                  cdata-section-elements="{$cdata-section-elements}"
                  standalone="{$standalone}">
                  <xsl:copy-of select="$content"/>
                </saxon:output>
              </xsl:otherwise>
            </xsl:choose>
          </xsl:otherwise>
        </xsl:choose>
      </xsl:when>

      <xsl:when test="element-available('redirect:write')">
        <!-- Xalan uses redirect -->
        <redirect:write file="{$filename}">
          <xsl:copy-of select="$content"/>
        </redirect:write>
      </xsl:when>

      <xsl:otherwise>
        <!-- it doesn't matter since we won't be making chunks... -->
        <xsl:message terminate="yes">
          <xsl:text>Can't make chunks with </xsl:text>
          <xsl:value-of select="system-property('xsl:vendor')"/>
          <xsl:text>'s processor.</xsl:text>
        </xsl:message>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>

  <xsl:template name="write.xml.chunk">
    <xsl:param name="filename" select="''"/>
    <xsl:param name="quiet" select="$chunker.output.quiet"/>
    <xsl:param name="suppress-context-node-name" select="0"/>
    <xsl:param name="message-prolog"/>
    <xsl:param name="message-epilog"/>
    <xsl:param name="method" select="'xml'"/>
    <xsl:param name="encoding" select="$chunker.output.encoding"/>
    <xsl:param name="media-type" select="$chunker.output.media-type"/>
    <xsl:param name="content"/>
    <xsl:call-template name="write.chunk">
      <xsl:with-param name="filename" select="$filename"/>
      <xsl:with-param name="quiet" select="$quiet"/>
      <xsl:with-param name="suppress-context-node-name"
        select="$suppress-context-node-name"/>
      <xsl:with-param name="message-prolog" select="$message-prolog"/>
      <xsl:with-param name="message-epilog" select="$message-epilog"/>
      <xsl:with-param name="method" select="$method"/>
      <xsl:with-param name="encoding" select="$encoding"/>
      <xsl:with-param name="indent" select="'yes'"/>
      <xsl:with-param name="omit-xml-declaration" select="'no'"/>
      <xsl:with-param name="standalone" select="'no'"/>
      <xsl:with-param name="doctype-public"/>
      <xsl:with-param name="doctype-system"/>
      <xsl:with-param name="media-type" select="$media-type"/>
      <xsl:with-param name="cdata-section-elements"/>
      <xsl:with-param name="content" select="$content"/>
    </xsl:call-template>
  </xsl:template>
</xsl:stylesheet>

dbautosplit --level 1 MyBook.xml

Creating file : out/preface-01/index.xml
Creating file : out/chapter-01/index.xml
Creating file : out/chapter-02/index.xml
Creating file : out/chapter-03/index.xml
Creating file : out/chapter-04/index.xml
Creating file : out/chapter-05/index.xml
Creating file : out/index.xml

dbautosplit -l 1 -o "%attr(xml:id)%txt(.xml)" MyBook.xml

Creating file : out/preface.xml
Creating file : out/markup.xml
Creating file : out/common.xml
Creating file : out/structure.xml
Creating file : out/fo.xml
Creating file : out/html.xml
Creating file : out/index.xml

The shown methods have both advantages and drawbacks.

You have a big DocBook document and you need to extract one structural element like a chapter, appendix etc. to edit or process it separately from the main document.

To make the solution work, the structural element needs an ID attribute. If this is available, use the following stylesheet:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <xsl:key name="id" match="*" use="@id|@xml:id"/>
  <!-- Contains the ID attribute of the extracted element: -->
  <xsl:param name="rootid"/>
  <!-- Controls some log messages: 0=off, 1=on -->
  <xsl:param name="rootid.debug" select="0"/>

  <xsl:template match="/">
    <xsl:choose>
      <xsl:when test="$rootid !=''">
        <xsl:if test="count(key('id',$rootid)) = 0">
          <xsl:message terminate="yes">
            <xsl:text>ID '</xsl:text>
            <xsl:value-of select="$rootid"/>
            <xsl:text>' not found in document.</xsl:text>
          </xsl:message>
        </xsl:if>
        <xsl:call-template name="rootid.debug.message"/>
        <xsl:call-template name="rootid.process"/>
      </xsl:when>
      <xsl:otherwise>
        <xsl:call-template name="normal.process"/>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>

  <xsl:template name="rootid.debug.message">
    <xsl:if test="$rootid.debug != 0">
      <xsl:message>
        <xsl:text>Using ID </xsl:text>
        <xsl:value-of select="concat('&quot;', $rootid, '&quot;')"/>
      </xsl:message>
    </xsl:if>
  </xsl:template>
  
  <xsl:template name="rootid.process">
    <xsl:apply-templates select="key('id',$rootid)" mode="process.root"/>
  </xsl:template>

  <xsl:template name="normal.process">
    <xsl:apply-templates/>
  </xsl:template>
  
  <xsl:template match="node() | @*" mode="process.root">
    <xsl:copy>
      <xsl:apply-templates select="@* | node()" mode="process.root"/>
    </xsl:copy>
  </xsl:template>
</xsl:stylesheet>

Pass the rootid parameter to your XSLT processor with the corresponding ID, for example:

xsltproc --stringparam rootid intro rootid.xsl XML_FILE
            

The result contains only the element with the corresponding ID value and everything inside it.

This solution cuts off the element with the corresponding ID and copies the element itself and its children to the output stream. The copying is done in the process.root mode. The stylesheet does not apply any further processing. This can be a disadvantage, for example, a xref pointing outside of the respective element. If the resulting file contains such a cross-reference, it will not be valid anymore.

It is possible to convert such cross-references into a “resolved form” by using the following code:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  xmlns:d="http://docbook.org/ns/docbook">
  
  <xsl:import href="rootid.xsl"/>
  
  <xsl:template match="d:xref" mode="process.root">
    <xsl:variable name="xhref" select="@xlink:href"/>
    <!-- is the @xlink:href a local idref link? -->
    <xsl:variable name="xlink.idref">
      <xsl:choose>
        <xsl:when test="starts-with($xhref,'#')">
          <xsl:value-of select="substring($xhref, 2)"/>
        </xsl:when>
        <xsl:when test="contains($xhref, '://')">
         <xsl:message>
            <xsl:text>ERROR: Don't know what do do with @xlink:href: </xsl:text>
            <xsl:value-of select="$xhref"/></xsl:message> 
        </xsl:when>
        <xsl:otherwise/>
      </xsl:choose>
    </xsl:variable>
    <xsl:variable name="xlink.targets" select="key('id',$xlink.idref)"/>
    <xsl:variable name="linkend.targets" select="key('id',@linkend)"/>
    <xsl:variable name="target" select="($xlink.targets | $linkend.targets)[1]"/>
    <xsl:variable name="refelem" select="local-name($target)"/>
    
    <xsl:variable name="this.div" 
      select="ancestor-or-self::d:*[@xml:id = $rootid][1]"/>
    <xsl:variable name="target.div"
      select="$target/ancestor-or-self::d:*[@xml:id = $rootid][1]"/>

    <xsl:choose>
      <xsl:when test="generate-id($this.div) = generate-id($target.div)">
        <xsl:copy-of select="."/>
      </xsl:when>
      <xsl:otherwise>
        <phrase xmlns="http://docbook.org/ns/docbook" remap="xref">
          <xsl:choose>
            <xsl:when test="@linkend">
              <xsl:attribute name="role">
                <xsl:value-of select="@linkend"/>
              </xsl:attribute>
            </xsl:when>
            <xsl:when test="$xlink.idref != ''">
              <xsl:attribute name="role">
                <xsl:value-of select="$xlink.idref"/>
              </xsl:attribute>
            </xsl:when>
            <xsl:otherwise>
              <xsl:attribute name="role">
                <xsl:value-of select="$xhref"/>
              </xsl:attribute>
            </xsl:otherwise>
          </xsl:choose>
          <xsl:apply-templates
            select="@*[local-name() != 'linkend' and
                       local-name() != 'href']"
            mode="process.root"/>
          <xsl:apply-templates
            select="($target/ancestor-or-self::d:*[d:title])[last()]/d:title/node()"
            mode="process.root"/>
        </phrase>
      </xsl:otherwise>
    </xsl:choose>
  </xsl:template>
</xsl:stylesheet>

The stylesheet in Example 3.9, “ rootid-resolve-xrefs.xsl ” imports the rootid.xsl and inherits all templates. To implement a different behaviour we need to add a new template matching for the xref element in mode process.root.

The template contains mostly code from the DocBook XSL stylesheets with some minor changes. The general behaviour is described in the following sequence:

TODO: Add graphic to illustrate the method

Section 3.5, “Splitting DocBook Documents” uses a different approach without needing an ID attribute.

You need to transform every sectX element into a section element.

This problem is solved through the following XSLT stylesheet:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:d="http://docbook.org/ns/docbook"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <xsl:import href="copy.xsl"/>
  
  <xsl:template match="d:sect1|d:sect2|d:sect3|d:sect4|d:sect5">
    <xsl:element name="section" namespace="http://docbook.org/ns/docbook">
      <xsl:apply-templates select="node()"/>
    </xsl:element>
  </xsl:template>
</xsl:stylesheet>

The stylesheet from Example 3.10, “Transforms every sectX Element into a section Element” is very easy: it imports the standard rules to copy every node from copy.xsl and create special rules for all sectX elements. As every sectX element creates the same structure, we can collect it in one template rule.

You need to transform every sectX element into a section element.

This problem is solved through the following XSLT stylesheet:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet
  xmlns:d="http://docbook.org/ns/docbook"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  version="1.0">
  
  <xsl:import href="copy.xsl"/>
  
  <xsl:template match="d:section">
    <xsl:variable name="level" select="count(ancestor::*)"/>
    <xsl:element name="sect{$level}" namespace="http://docbook.org/ns/docbook">
      <xsl:copy-of select="@*"/>
      <xsl:apply-templates/>
    </xsl:element>
  </xsl:template>
  
</xsl:stylesheet>

The above stylesheet calculates the section level with the ancestor axis, because the amount of elements is directly correlated with the level of the corresponding section. With an attribute value template it is inserted in the name attribute.

There is one caveat: The stylesheet does not check if the limit is reached. Currently (with version 5.1), DocBook supports levels up to 5. If you nest your section elements too deep, you can end up with, let's say, sect8 which is not allowed in DocBook. To avoid making mistakes, it is better to check the level:

<xsl:template match="d:section">
  <xsl:variable name="level" select="count(ancestor::*)"/>
  <xsl:choose>
    <xsl:when test="$level &lt;= 5">
      <xsl:element name="sect{$level}"
          namespace="http://docbook.org/ns/docbook">
        <xsl:copy-of select="@*"/>
        <xsl:apply-templates/>
      </xsl:element>
    </xsl:when>
    <xsl:otherwise>
      <xsl:message>ERROR: section <xsl:value-of
          select="normalize-space(d:title)"/> to deep</xsl:message>
      <!-- What to do if the section is too deeply nested? -->
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>

Amend the stylesheet when the section is too deeply nested (see above comment). You could avoid the section level (which is a bad idea) but it's better to rework the source document.

If you want, you can stop the transformation if the section level is too high. Change the xsl:message as follows:

<xsl:message terminate="yes">...

You have a DocBook document which contains several bridgehead elements. The bridgehead has to be transformed into the correct section structure.

A bridgehead element is a “free-floating heading”. In most cases it is a bad idea as it is difficult to handle in XSLT. To create the correct section hierarchy, a stylesheet need to collect all nodes between a bridgehead element and the next one. The following stylesheet uses a set difference method:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"  
  xmlns:d="http://docbook.org/ns/docbook"
  xmlns="http://docbook.org/ns/docbook"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  
  <xsl:import href="copy.xsl"/>
  
  <xsl:output indent="yes"/>
  <xsl:strip-space elements="*"/>
  <xsl:preserve-space elements="d:screen d:programlisting d:literallayout"/>
  
  <xsl:template match="d:section[d:bridgehead]">
    <!-- All nodes inside our section: -->
    <xsl:variable name="node1" select="node()"/>
    <!-- All nodes -->
    <xsl:variable name="node2" 
      select="d:bridgehead[1]|
              d:bridgehead[1]/following-sibling::node()"/>
    
    <!-- Copy our section with all attributes, apply the set difference
      and investigate the first bridgehead 
    -->
    <xsl:copy>
      <xsl:copy-of select="@*"/>
      <xsl:apply-templates select="$node1[count(.|$node2) != count($node2)]"/>
      <xsl:apply-templates select="d:bridgehead[1]"/>
    </xsl:copy>
    <xsl:text>&#10;</xsl:text>
  </xsl:template>
  
  <xsl:template match="d:bridgehead">
    <!-- All nodes who follow bridgeheads: -->
    <xsl:variable name="node1" 
      select="following-sibling::node()"/>
    <!-- All nodes who follow the next bridgehead including the next
         bridgehead.
         The next bridgehead element is included as we don't want it
         in the set difference:
    -->
    <xsl:variable name="node2"
      select="following-sibling::d:bridgehead[1]|
              following-sibling::d:bridgehead[1]/following-sibling::node()"/>   

    <!-- Create the section element with all attributes and apply
      standard rules for the diff set -->
    <xsl:element name="section">
      <xsl:copy-of select="@*"/>
      <xsl:text>&#10;  </xsl:text>
      <xsl:element name="title">
        <xsl:apply-templates select="node()"/>
      </xsl:element>
      <xsl:apply-templates select="$node1[count(.|$node2) != count($node2)]"/>
    </xsl:element>
    
    <!-- Process the next bridgehead -->
    <xsl:apply-templates select="following-sibling::d:bridgehead[1]"/>
  </xsl:template>
  
</xsl:stylesheet>

The solution is unfortunately not very trivial in XSLT 1.0. The template rule d:section[d:bridgehead] matches only sections which contain one or more bridgehead elements. The template rule performs the following steps:

The bridgehead template rule is responsible for transforming the current bridgehead element into a section. It is also responsible for the next bridgeheads. The rule performs the following steps:

DocBook allows to insert block elements like example, figure, etc. to be inserted in paras. This is sometimes hard to process with XSLT and you want to move those block elements outside of your paragraph. After this modification, the paragraph contains only text and inline elements (like simpara).

The solution explained

<!DOCTYPE xsl:stylesheet
[
 <!ENTITY dbblocks "d:address|d:bibliolist|d:blockquote|d:bridgehead|d:calloutlist|d:caution|d:classsynopsis|d:cmdsynopsis|d:constraintdef|d:constructorsynopsis|d:destructorsynopsis|d:epigraph|d:equation|d:example|d:fieldsynopsis|d:figure|d:funcsynopsis|d:glosslist|d:important|d:informalexample|d:informalfigure|d:informaltable|d:itemizedlist|d:literallayout|d:mediaobject|d:methodsynopsis|d:msgset|d:note|d:orderedlist|d:procedure|d:procedure|d:productionset|d:programlisting|d:programlistingco|d:qandaset|d:revhistory|d:screen|d:screenco|d:screenshot|d:segmentedlist|d:sidebar|d:simplelist|d:synopsis|d:table|d:task|d:tip|d:variablelist|d:warning">
 <!ENTITY dbselfblocks "self::d:address|self::d:bibliolist|self::d:blockquote|self::d:bridgehead|self::d:calloutlist|self::d:caution|self::d:classsynopsis|self::d:cmdsynopsis|self::d:constraintdef|self::d:constructorsynopsis|self::d:destructorsynopsis|self::d:epigraph|self::d:equation|self::d:example|self::d:fieldsynopsis|self::d:figure|self::d:funcsynopsis|self::d:glosslist|self::d:important|self::d:informalexample|self::d:informalfigure|self::d:informaltable|self::d:itemizedlist|self::d:literallayout|self::d:mediaobject|self::d:methodsynopsis|self::d:msgset|self::d:note|self::d:orderedlist|self::d:procedure|self::d:procedure|self::d:productionset|self::d:programlisting|self::d:programlistingco|self::d:qandaset|self::d:revhistory|self::d:screen|self::d:screenco|self::d:screenshot|self::d:segmentedlist|self::d:sidebar|self::d:simplelist|self::d:synopsis|self::d:table|self::d:task|self::d:tip|self::d:variablelist|self::d:warning">
 <!ENTITY dbblocksinpara "d:para/d:address|d:para/d:bibliolist|d:para/d:blockquote|d:para/d:bridgehead|d:para/d:calloutlist|d:para/d:caution|d:para/d:classsynopsis|d:para/d:cmdsynopsis|d:para/d:constraintdef|d:para/d:constructorsynopsis|d:para/d:destructorsynopsis|d:para/d:epigraph|d:para/d:equation|d:para/d:example|d:para/d:fieldsynopsis|d:para/d:figure|d:para/d:funcsynopsis|d:para/d:glosslist|d:para/d:important|d:para/d:informalexample|d:para/d:informalfigure|d:para/d:informaltable|d:para/d:itemizedlist|d:para/d:literallayout|d:para/d:mediaobject|d:para/d:methodsynopsis|d:para/d:msgset|d:para/d:note|d:para/d:orderedlist|d:para/d:procedure|d:para/d:procedure|d:para/d:productionset|d:para/d:programlisting|d:para/d:programlistingco|d:para/d:qandaset|d:para/d:revhistory|d:para/d:screen|d:para/d:screenco|d:para/d:screenshot|d:para/d:segmentedlist|d:para/d:sidebar|d:para/d:simplelist|d:para/d:synopsis|d:para/d:table|d:para/d:task|d:para/d:tip|d:para/d:variablelist|d:para/d:warning">
]>
<xsl:stylesheet xmlns:d="http://docbook.org/ns/docbook"
  xmlns="http://docbook.org/ns/docbook"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">

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

  <xsl:strip-space elements="d:para"/>
  <xsl:preserve-space elements="d:screen d:programlisting d:literallayout"/>
  <xsl:output indent="yes"/>

  <xsl:template match="d:para">
    <xsl:apply-templates select="node()[1]"/>
  </xsl:template>

  <xsl:template match="&dbblocksinpara;">
    <xsl:copy-of select="."/>
    <xsl:text>&#10;</xsl:text>
    <xsl:apply-templates select="following-sibling::node()[1]"/>
  </xsl:template>

  <xsl:template match="d:para/*|d:para/text()">
    <xsl:element name="{local-name(..)}">
      <xsl:apply-templates select="." mode="copy"/>
    </xsl:element>
    <xsl:text>&#10;</xsl:text>
    <xsl:apply-templates
      select="following-sibling::*[&dbselfblocks;][1]"/>
  </xsl:template>

  <xsl:template match="d:para/node()" mode="copy">
    <xsl:copy-of select="."/>
    <xsl:if test="not(following-sibling::node()[1][&dbselfblocks;])">
      <xsl:apply-templates select="following-sibling::node()[1]"
        mode="copy"/>
    </xsl:if>
  </xsl:template>

</xsl:stylesheet>

TBD

You want to add index entries (using the indexterm element) automatically and consistently into your document.

To see how the automatic addition works, the following procedure demonstrate this for the element envar.

After applying the stylesheet add-indexterms.xsl you will get the following output:

<article xmlns="http://docbook.org/ns/docbook" version="5.0">
  <title>Profiling Test</title>
  <para>Environment variable <envar>XML_CATALOG_FILES</envar><indexterm>
    <primary>XML_CATALOG_FILES</primary>
  </indexterm><indexterm>
    <primary>environment variables</primary>
    <secondary>XML_CATALOG_FILES</secondary>
    </indexterm></para>
  <para>Environment variable <envar condition="noindex">FOO</envar></para>
  <para>Environment variable <envar os="windows"
        >Path</envar><indexterm><primary>Path</primary></indexterm><indexterm><primary>environment
        variables</primary><secondary>Path</secondary></indexterm><envar
      os="linux"
      >PATH</envar><indexterm>
        <primary>PATH</primary>
      </indexterm><indexterm>
        <primary>environment variables</primary>
        <secondary>PATH</secondary>
      </indexterm></para>
</article>

Let´s go back at the beginning first. Assume you want to show an environment variable in the index. Usually you would mark up the text with the envar element and add an indexterm right after the first one. As is is useful to find the index term also under the primary term “environment variables”, you add an additional indexterm. This could look like this:

<para>Use the <envar>PATH</envar><indexterm>
        <primary>PATH</primary>
      </indexterm><indexterm>
        <primary>environment variables</primary>
        <secondary>PATH</secondary>
      </indexterm>
      to do ...
</para>

Although this is the usual method, it has some drawbacks:

All of the above problems can be solved with the stylesheet from Example 3.16, “ profile-tag.xsl ”. It exploits the DocBook XSL stylesheet´s profiling mechanism. Normally, profiling is a method to remove certain structures from a document rather than add something. In our case we use the special profile mode to customize the automatic index term addition.

With the above stylesheet, it is possible to influence how your index terms appear. This is done with the condition^[8] attribute, demonstrated on our envar example:

This method can not solve all index problems. You should know some of its limits:

Although this method does not replace hand-written index entries, it can ease the pain. Especially for those entries which can be be inserted automatically it improves consistency. The method described above can also be implemented for other inline elements, like persons, functions, etc.

You want to include revision information into your DocBook document from your version control systems, like Bazaar, Subversion, Mercurial, Git, and others.

Usually, the solution for each version control system is to output its log into its specific XML output and transform it with XSLT into a revhistory element.

bzr log --xml REPO > bzr-log.xml

TBD

git log --date=iso --pretty=format:"<logentry revision='%h'>%n <author email='%ae'>%an</author>%n <date>%ad</date>%n <msg xml:space='preserve'>%s</msg>%n</logentry>" \
  | sed -e '1i<logs>' -e '$a</logs>' > git-log.xml

hg log --style xml > hg-log.xml

<log>
  <logentry revision="69"
    node="dfadd024594c4083362fe6919264362803dcd285">
    <tag>tip</tag>
    <author email="tux@example.de">Tux Penguin</author>
    <date>2011-05-22T01:56:21+02:00</date>
    <msg xml:space="preserve">Corrected xml:id attribute</msg>
    <paths>
      <path action="M">xml/structure/topic.extract-element.xml</path>
    </paths>
  </logentry>
  <logentry revision="68"
    node="833287df8943d0bab5ec65ec8aafe5bc42002289">
    <author email="wilber@example.de">Wilber Gimp</author>
    <date>2011-05-22T01:56:03+02:00</date>
    <msg xml:space="preserve">Changed chapter title</msg>
    <paths>
      <path action="M">xml/structure/topic.revision-list.xml</path>
    </paths>
  </logentry>
  <!-- Many more entries ... -->
</log

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE xsl:stylesheet
[
  <!ENTITY dbns "http://docbook.org/ns/docbook">
]>
<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  
  <xsl:output method="xml" indent="yes"/>
  
  <xsl:param name="include.paths" select="1"/>
  <xsl:param name="include.copies" select="1"/>
  
  <xsl:template match="log">
    <revhistory xmlns="&dbns;">
      <xsl:apply-templates/>
    </revhistory>
  </xsl:template>
  
  <xsl:template match="logentry">
    <revhistory xmlns="&dbns;">
      <xsl:apply-templates select="@revision|*"/>
    </revhistory>
  </xsl:template>
  
  <xsl:template match="logentry/@revision">
    <revnumber xmlns="&dbns;">
      <xsl:apply-templates/>
    </revnumber>
  </xsl:template>
  
  <xsl:template match="tag">
    <revremark xmlns="&dbns;">
      <xsl:apply-templates/>
    </revremark>
  </xsl:template>
  
  <xsl:template match="date">
    <date xmlns="&dbns;">
      <xsl:apply-templates/>
    </date>
  </xsl:template>
  
  <xsl:template match="author">
    <xsl:variable name="firstname" select="substring-before(., ' ')"/>
    <xsl:variable name="surname" select="substring-after(., ' ')"/>
    <author xmlns="&dbns;">
      <personname>
        <firstname><xsl:value-of select="$firstname"/></firstname>
        <!--<othername></othername>-->
        <surname><xsl:value-of select="$surname"/></surname>
      </personname>
      <email><xsl:value-of select="@email"/></email>
    </author>
  </xsl:template>
  
  <xsl:template match="msg">
    <revdescription xmlns="&dbns;">
      <para>
        <xsl:apply-templates/>
      </para>
    </revdescription>
  </xsl:template>
  
  <xsl:template match="paths">
    <xsl:if test="$include.paths != 0">
      <itemizedlist xmlns="&dbns;">
        <title>Paths</title>
        <xsl:apply-templates/>
      </itemizedlist>
    </xsl:if>
  </xsl:template>
  
  <xsl:template match="path">
    <listitem xmlns="&dbns;">
      <para>
        <xsl:apply-templates select="@action|text()"/>
      </para>
    </listitem>    
  </xsl:template>
  
  <xsl:template match="path/@action">
    <xsl:text>[</xsl:text>
    <xsl:value-of select="."/>
    <xsl:text>] </xsl:text>
  </xsl:template>
  <xsl:template match="path/text()">
    <filename xmlns="&dbns;">
      <xsl:value-of select="."/>
    </filename>
  </xsl:template>

  <xsl:template match="copyies">
    <xsl:if test="$include.paths != 0">
      <listitem xmlns="&dbns;">
        <title>Copies</title>
        <para>
          <xsl:apply-templates select="@*|text()"/>
        </para>
      </listitem>
    </xsl:if>
  </xsl:template>
  <xsl:template match="copy">
    <listitem xmlns="&dbns;">
      <para>
        <xsl:apply-templates select="@*|text()"/>
      </para>
    </listitem>    
  </xsl:template>
  
  <xsl:template match="copy/@source">
    <filename xmlns="&dbns;">
      <xsl:value-of select="."/>
    </filename>
  </xsl:template>
  <xsl:template match="copy/text()">
    <xsl:text> -> </xsl:text>
    <filename xmlns="&dbns;">
      <xsl:value-of select="."/>
    </filename>
  </xsl:template>
  
</xsl:stylesheet>

svn log --xml > svn-log.xml

TBD

You have a glossary with acronyms and you want to generate a sorted list of these acronyms automatically.

The following prerequisites are needed:

The result will look like this:

<!--
 This file is dynamically generated at build time from a glossary file.
 To change this file, make changes to the appropriate glossary.xml file.
 In order to generate the acronyms file, any glossary entries with an
 acronym tag must have an xml:id.
-->
<appendix xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="acronyms">
  <title>Acronyms</title>
  <para> This appendix displays acronyms sorted alphabetically and
        linked to their definition in the glossary. </para>
  <itemizedlist remap="glossary">
    <listitem>
      <para>
        <acronym linkend="dtd-acronym" remap="acronym">DTD</acronym>
      </para>
    </listitem>
    <listitem>
      <para>
        <acronym linkend="oasis" remap="acronym">OASIS</acronym>
      </para>
    </listitem>
    <listitem>
      <para>
        <acronym linkend="pdf" remap="acronym">PDF</acronym>
      </para>
    </listitem>
    <listitem>
      <para>
        <acronym linkend="xml" remap="acronym">XML</acronym>
      </para>
    </listitem>
  </itemizedlist>
</appendix>

TBD

You need to create topics of your existing DocBook 5 document to use it with the new assembly and topic elements in DocBook 5.1.

Use the assembly/topic-maker-chunk.xsl stylesheet to create topics from your current DocBook 5 document. This breaks apart your existing document into modular files and creates an assembly file.

To disassemble an existing book.xml document, use the xsltproc command like this (the variable DB contains the path of your DocBook XSL directory):

xsltproc --xinclude \
    --stringparam assembly.filename  assembly.xml \
    --stringparam base.dir topics/ \
    $DB/assembly/topic-maker-chunk.xsl  \
    book.xml

The xsltproc command outputs the master assembly file assembly.xml. The document's content is break up into modular chunks, saved in the topics/ directory. The master file contains a single structure element.

The topic-maker-chunk.xsl contains several parameters to influence the chunking process:

The topic-maker-chunk.xsl stylesheet reuses the same chunking algorithm than the XHTML stylesheets. That means, it breaks the document at the same boundaries and you can alter the chunking process with the same parameters than the XHTML stylesheets.

The following subsections shows some specific examples to influence the chunking process.

You want to convert an assembly structure and its associated modular files into a single DocBook 5 file.

You need the following prerequisites:

Use xsltproc to create a single DocBook 5 (the variable DB contains the path of your DocBook XSL directory):

xsltproc \
    $DB/assembly/assemble.xsl \
    assembly.xml

The assemble.xsl stylesheet contains several parameters to influence the assembling process:

The following subsections shows some specific examples to influence the assembling process.

<assembly version="5.1" xmlns="http://docbook.org/ns/docbook">
  <resources> ... </resources>
  <structure xml:id="quickstart"> ... </structure>
  <structure xml:id="reference"> ... </structure>
</assembly>

xsltproc \
    --stringparam structure.id reference \
    $DB/assembly/assemble.xsl \
    assembly.xml

<assembly version="5.1" xmlns="http://docbook.org/ns/docbook">
  <resources> ... </resources>
  <structure type="help.system"> ... </structure>
  <structure type="startup"> ... </structure>
</assembly>

xsltproc \
    --stringparam output.type startup \
    $DB/assembly/assemble.xsl \
    assembly.xml

You want create topic oriented documents with the assembly element manually.

In its simplest form, an assembly file contains the following elements:

The following example assumes, the files are composed of topic root elements, except for the glossary.xml file (which is comprised by a glossary element).

<assembly version="5.1" xmlns="http://docbook.org/ns/docbook">
  <resources>
    <resource fileref="intro.xml" xml:id="intro"/>
    <resource fileref="kde.xml" xml:id="kde"/>
    <resource fileref="gnome.xml" xml:id="gnome"/>
    <resource fileref="glossary.xml" xml:id=""/>
  </resources>
  <structure xml:id="user-guide">
    <output renderas="book"/>
    <module resourceref="intro"/>
    <module resourceref="kde"/>
    <module resourceref="gnome"/>
    <module resourceref="glossary"/>
  </structure>
</assembly>

TDB

You need text or a small XML structure that you want to use throughout your document.

Use custom entities. An entity is a placeholder for text or XML. You can define them inside a DOCTYPE declaration or in external files. The following procedure shows you how to create and use a entity:

Entities improve the consistency of your texts. If your product name, your version, or any other definition changes, it is very easy to change its definition too, without going through all of your texts.

Entities can contain text and XML. For example, if you have text where you need to add the same file name repeatedly, it would be a good idea to create a entity:

<!ENTITY configfile "<filename xmlns='http://docbook.org/ns/docbook'>foo.conf</filename>">

The only problem with XML structures in entities is, you need to add the DocBook namespace in each definition. By default, each XML element belongs to no namespace.

You want to process your XML file, but you do not want to expand any of the defined entities.

Replace all your entities with a string that is easy to search for. For example, you can replace the entity &product; with the string [[[product]]] (assuming that the string [[[product]]] doesn't occur anywhere else in our document).

Before you can proceed, you need to prepare your system as described in Procedure 3.3, “Preparing the Workflow”.

Once you have done all the preparations, proceed with Procedure 3.4, “Workflow for Protecting Custom Entities”.

Not expanding entities looks like an abnormal use case as XML parsers are supposed to expand entities by default. However, expanding entities has one disadvantage: after the XML parser has resolved entities, the content is indistinguishable from other content. In other words, you cannot distinguish content that comes from an entity definition from existing content. You cannot “go back” and revert this process once all entities are expanded.

For this reason, preserving entities can be useful when you want to process XML, but keep the definied entities untouched. Procedure 3.4 showed one solution. However, be aware of certain issues that might cause problems with XML files:

If you prefer a solution that can handle XML, use the Python script ents2pi.py. This script can parse XML and replaces each entity with a processing instruction. For example, the entity &product; is converted to the PI <?entity product>. That makes it easier to process it with XSLT or any other XML-agnostic tool.

You want to design a title page of your book or article.

To design your title page there are two ways to do it, regardless if it is a book or an article:

Both methods are shown below. Although the following descriptions focus on a book title page, the same procedure applies for an article title page as well.

Before we customize the stylesheets, we need to define, what we want to display on our title page(s). Depending on if it is a left or a right page, different elements needs to be shown. For this example, we use the following requisites:

There are several reasons to customize a title page:

All these requirements can be done, either with the direct or indirect method. Apart from your own preferences, use the direct method if you have more complicated conditions which can not be expressed by simple title page definitions. Sometimes it is faster to just add the respective named template instead of going through the indirect method.

Regardless which method you prefer, it ends up with the same named templates. For a book title page, the named templates are called in the following order, starting with book.titlepage:

book.titlepage
  book.titlepage.before.recto
  book.titlepage.recto
  book.titlepage.before.verso
  book.titlepage.verso
  book.titlepage.separator

Usually, the book.titlepage template is only customized in rare cases. For example, if you want to revamp the previous schema completely and add additional pages like half titles. Each of the templates in book.titlepage are responsible for a different setup of a title page. We discussed the book.titlepage.recto and book.titlepage.verso templates already. The templates book.titlepage.separator and book.titlepage.before.verso contain page breaks, whereas book.titlepage.before.recto is empty.

Note, all of the above templates process title page elements in a special mode. As you have seen in the section called “Customizing Title Pages Directly”, elements for a recto page are processed in the book.titlepage.recto.auto.mode mode. The same principle applies for a verso page and its mode book.titlepage.verso.auto.mode. However, not all elements have a template with such modes as not all elements can (and should) appear on a title page. Look into the file fo/titlepage.templates.xsl to see which are definied. Assume title and subtitle have already templates for recto and verso pages as well as all the elements which are listed in the original book.titlepage.verso and book.titlepage.recto.

For example, the edition element has certainly no templates for a recto and verso book title page. If you do not have definied one, a fallback mechanism takes place. For this reason, if you call a element in book.titlepage.verso and book.titlepage.recto, you need also to define the respective templates:

<xsl:template match="d:edition" mode="book.titlepage.recto.auto.mode">
   <!-- Add your code for a recto page -->
</xsl:template>

<xsl:template match="d:edition" mode="book.titlepage.verso.auto.mode">
   <!-- Add your code for a verso page -->
</xsl:template>

Usually, you want to display the edition on a recto page different than on a verso page.

You do not want to overhaul the default title pages, but you want to change small things, like the font size, margins, or other stylistic parameters.

The difficulty is to find the correct template to customize. Here is a general procedure how to do this:

To make the general explanations a bit more useful, here is a small example: you want to change the font size for the title of a book's recto title page. Applying Procedure 4.1, “Finding the Correct Template to Customize for a Title Page” leads to the following template:

<xsl:template match="d:title" mode="book.titlepage.recto.auto.mode">

After you have copied it to your customization layer, you can change the font-size (marked bold):

<xsl:template match="d:title" mode="book.titlepage.recto.auto.mode">
  <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"
     xsl:use-attribute-sets="book.titlepage.recto.style"
     text-align="center"
     font-size="40pt"
     space-before="18.6624pt"
     font-weight="bold"
     font-family="{$title.fontset}">
    <xsl:call-template name="division.title">
      <xsl:with-param name="node" select="ancestor-or-self::d:book[1]"/>
    </xsl:call-template>
  </fo:block>
</xsl:template>

In the previous example, the font size was changed from the original value of 24.8832pt to 40pt. The other objects are unchanged. Other attributes can be changed as needed.

Section 4.2, “Designing a Title Page”

You want to change the leading between consecutive lines of text.

Leading is the distance from one baseline to the next, or in other words, the “interlinear space.” It is not the same as the line height. Unfortunately, the FO specification named the property for influencing the leading line-height which makes it confusing.

The DocBook stylesheets introduce the parameter line-height with the same name and functionality. It acts as a placeholder for the above line-height property. The following examples do all the same (except for the value normal). It is assumed, you have a base font size of 10pt; negative values in line-height are not allowed:

Unfortunately, the situation with line height in FO is a bit more complicated as it first seems. Usually, this is what most people expects:

First line
 [Gap]
Second Line
 [Gap]
Third Line
 [Gap]

However, the line-height property is a “half-leading” value which are added before and after a line. This leads to the more realistic picture:

 [1/2 Gap]
First line
 [1/2 Gap]
 [1/2 Gap]
Second Line
 [1/2 Gap]
 [1/2 Gap]
Third Line
 [1/2 Gap]

If the line height is constant in each line, the effect is the same (except at the top or bottom of a reference area). According to the FO specification of line-height the FO property is a compound datatype which has minimum, optimum, maximum, conditionally, and precedence. The minimum, optimum, and maximum constraints are length

That said, leading has a direct influence on how easy a text is read. If the value is too small, consecutive lines gets overlapped. If the value is too big, the cohersion of text gets lost. Most text requires positive leading. Usually 9pt/11pt, 10pt/12pt, 11pt/13pt, and 12pt/15pt are the most common (the two values depicting the font size and line height).

According to RobertBringhurst in his book The Elements of Typographic Style he recommends more lead in the following situations (cited from his book from page 37):

You have URLs or paths which you want to hyphenate correctly. The URLs have to break on slashes or other characters only, but not between words.

The hyphenation of URLs in the DocBook stylesheets are controlled by two parameters: ulink.hyphenate and ulink.hyphenate.chars. The first parameter, if not empty, turns on hyphenation. Specify a hyphenation character, usually either a Unicode soft hyphen (U+00AD) or a Unicode zero-width space (U+200B).

The second parameter, ulink.hyphenate.chars, let you define your allowable hyphenation points. The default value is a slash (/), but URLs can contain more characters where it is desirable to hyphenate. For this reason, the DocBook parameter reference recommends the following value:

<xsl:param name="ulink.hyphenate.chars">:/@&?.#</xsl:param

The easiest way is to set the parameters ulink.hyphenate.chars and ulink.hyphenate to the values showed in the last section and be happy. However, for professional needs, this is not enough. The parameters and embedded algorithm do not take into account protocols, for example http. Protocols begin with the schema followed by :// as in http://. In some situations (although rare), a hyphenation can occur between the double slashes or before the colon. Furthermore, according to the Chicago Manual of Style, it is desirable to distinguish characters before and after the hyphenation takes place.

All these requirements are implemented in the stylesheet showed in Example 4.1, “ hyphenate-url.xsl ”. It cuts off the protocol with its :// and iterates through each characters and checks, if a hyphenation point needs to be inserted before or after it.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:fo="http://www.w3.org/1999/XSL/Format">

<xsl:template name="hyphenate-url">
  <xsl:param name="url" select="''"/>

  <!-- Remove the "schema://" prefix, so it disturbs not the
       algorithm in "hyphenate-url-string" -->
  <xsl:choose>
   <xsl:when test="$ulink.hyphenate = ''">
      <xsl:value-of select="$url"/>
   </xsl:when>
   <xsl:when test="contains($url, '://')">
      <xsl:value-of select="substring-before($url, '://')"/>
      <xsl:text>://</xsl:text>
      <xsl:copy-of select="$ulink.hyphenate"/>
      <xsl:call-template name="hyphenate-url-string">
        <xsl:with-param name="url" select="substring-after($url, '://')"/>
      </xsl:call-template>
   </xsl:when>
   <xsl:otherwise>
      <xsl:call-template name="hyphenate-url-string">
        <xsl:with-param name="url" select="normalize-space($url)"/>
      </xsl:call-template>
   </xsl:otherwise>
  </xsl:choose>
</xsl:template>


<xsl:template name="hyphenate-url-string">
  <xsl:param name="url" select="''"/>
  <xsl:variable name="char" select="substring($url, 1,1)"/>

  <xsl:choose>
   <xsl:when test="$url=''"/>
   <!-- Insert breakpoint _before_ the character -->
   <xsl:when test="contains($ulink.hyphenate.before.chars, $char)">
     <xsl:value-of select="concat($ulink.hyphenate, $char)"/>
     <xsl:call-template name="hyphenate-url-string">
       <xsl:with-param name="url" select="substring($url, 2)"/>
     </xsl:call-template>
   </xsl:when>
   <!-- Insert breakpoint _after_ the character -->
   <xsl:when test="contains($ulink.hyphenate.after.chars, $char)">
     <xsl:value-of select="concat($char, $ulink.hyphenate)"/>
     <xsl:call-template name="hyphenate-url-string">
       <xsl:with-param name="url" select="substring($url, 2)"/>
     </xsl:call-template>
   </xsl:when>
   <xsl:otherwise>
     <xsl:value-of select="$char"/>
     <xsl:call-template name="hyphenate-url-string">
       <xsl:with-param name="url" select="substring($url, 2)"/>
     </xsl:call-template>
   </xsl:otherwise>
  </xsl:choose>
</xsl:template>
</xsl:stylesheet>

Include the above stylesheet into your customization layer with additionally the following parameters:

<!-- Insert breakpoint /before/ the following characters: -->
<xsl:param name="ulink.hyphenate.before.chars"
  >.,%?&amp;#\-+{_</xsl:param>
<!-- Insert breakpoint /after/ the following characters: -->
<xsl:param name="ulink.hyphenate.after.chars"
  >/:@=};</xsl:param>

You need a “drop cap”, or Initial, which is a “a letter at the beginning of a work, a chapter, or a paragraph that is larger than the rest of the text.”

Typographically, you have different options to place initials:

Additionally you can design your initials as graphics, but we will come to this later.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
  xmlns:fo="http://www.w3.org/1999/XSL/Format"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  
  <xsl:param name="drop.caps.size">20pt</xsl:param>
  <xsl:param name="drop.caps.font-family" select="$body.font.family"/>
  <xsl:param name="drop.caps.font-weight">bold</xsl:param>
  
  <xsl:template name="create.initial">
    <xsl:param name="initial" select="substring(normalize-space(.),1,1)"/>
    <fo:inline>
      <fo:inline font-size="{$drop.caps.size}"
        font-weight="{$drop.caps.font-weight}"
        font-family="{$drop.caps.font-family}">
        <xsl:copy-of select="$initial"/>
      </fo:inline>
      <xsl:value-of select="substring(normalize-space(.), 2)"/>
    </fo:inline>
  </xsl:template>
</xsl:stylesheet>

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE xsl:stylesheet 
[
 <!ENTITY db "https://cdn.docbook.org/release/xsl/current"> 
]>
<xsl:stylesheet version="1.0"
  xmlns:d="http://docbook.org/ns/docbook"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  
  <xsl:import href="&db;/fo/docbook.xsl"/>
  <xsl:include href="initials-baseline.xsl"/>
  
  <xsl:template match="d:article/d:section/d:para[1]/text()">
    <xsl:call-template name="create.initial"/>
  </xsl:template>
</xsl:stylesheet>

<xsl:template match="d:chapter/d:section/d:para[1]/text()">

The solution described in the section called “Place Initials on the Same Baseline” is in most cases sufficient. However, if the first character is not a letter, any character is incorrectly made an initial.

Find information about the property line-height in Section 4.4, “Influencing the Leading”.

You want a number in front of your structural elements like appendix, chapter, section, etc.

The DocBook XSL stylesheets provide already a decent numbering scheme for high level divisions like parts, appendices, chapters, and references. The most common use is numbering section. If you want to automatically number section titles, set the section.autolabel parameter either manually or through a customization layer, for example:

<xsl:param name="section.autolabel" select="1"/>

The DocBook XSL stylesheets contain autolabel parameters for the common elements appendix, chapter, part, preface, qandadiv, reference, and section. These can be set individually to change the numbering of for the same elements. The default values are shown in Table 4.1, “Autolabel Parameters and their Default Values”.

The autolabel parameters can contain the following values:

Mostly you will probably want sections to be numbered including its parent numbering. If you do not touch chapter.autolabel, use the parameter section.label.includes.component.label and set it to 1:

<xsl:param name="section.autolabel" select="1"/>
<xsl:param name="section.label.includes.component.label" select="1"/>

With the following parameters you can further customize your numbering:

Let us assume the following structure in a book:

Part: The Python Language
  Chapter: A Tutorial Introduction
     Section: Running Python
     Section: Variables

  Chapter: Lexical Conventions and Syntax
     Section: Line Structure and Indentation
     Section: Identifiers and Reserved Words

Part: The Python Library
  Chapter: Build-In Functions
     Section: Build-In Functions and Types
     Section: Build-In Exceptions
  Chapter: Python Runtime Services
     Section: atext
     Section: copy

I. The Python Language
  1. A Tutorial Introduction
      Running Python
      Variables
  2. Lexical Conventions and Syntax
      Line Structure and Indentation
      Identifiers and Reserved Words
II. The Python Library
  3. Build-In Functions
      Build-In Functions and Types
      Build-In Exceptions
  4. Python Runtime Services
      atext
      copy

I. The Python Language
  1. A Tutorial Introduction
      1. Running Python
      2. Variables
  2. Lexical Conventions and Syntax
      1. Line Structure and Indentation
      2. Identifiers and Reserved Words
II. The Python Library
  3. Build-In Functions
      1. Build-In Functions and Types
      2. Build-In Exceptions
  4. Python Runtime Services
      1. atexit
      2. copy

I. The Python Language
  1. A Tutorial Introduction
      1.1. Running Python
      1.2. Variables
  2. Lexical Conventions and Syntax
      2.1. Line Structure and Indentation
      2.2. Identifiers and Reserved Words
II. The Python Library
  3. Build-In Functions
      3.1. Build-In Functions and Types
      3.2. Build-In Exceptions
  4. Python Runtime Services
      4.1. atexit
      4.2. copy

I. The Python Language
  I.1. A Tutorial Introduction
      I.1.1. Running Python
      I.1.2. Variables
  I.2. Lexical Conventions and Syntax
      I.2.1. Line Structure and Indentation
      I.2.2. Identifiers and Reserved Words
II. The Python Library
  II.3. Build-In Functions
      II.3.1. Build-In Functions and Types
      II.3.2. Build-In Exceptions
  II.4. Python Runtime Services
      II.4.1. atexit
      II.4.2. copy

I. The Python Language
  I.1. A Tutorial Introduction
      I.1.1. Running Python
      I.1.2. Variables
  I.2. Lexical Conventions and Syntax
      I.2.1. Line Structure and Indentation
      I.2.2. Identifiers and Reserved Words
II. The Python Library
  II.1. Build-In Functions
      II.1.1. Build-In Functions and Types
      II.1.2. Build-In Exceptions
  II.2. Python Runtime Services
      II.2.1. atexit
      II.2.2. copy

However, when dealing with other numbering systems, the above parameters are not enough. To support, for example, Japanese numbering, you need to customize the named template autolabel.format from common/labels.xsl.

<xsl:template name="autolabel.format">
  <xsl:param name="context" select="."/>
  <xsl:param name="format"/>

  <xsl:choose>
    <xsl:when test="string($format) != 0">
      <xsl:choose>
        <xsl:when test="string($format)='001'">
          <xsl:value-of select="$format"/>
        </xsl:when>
        <xsl:when test="$format='loweralpha' or $format='a'">
          <xsl:value-of select="'a'"/>
        </xsl:when>
        <xsl:when test="$format='lowerroman' or $format='i'">
          <xsl:value-of select="'i'"/>
        </xsl:when>
        <xsl:when test="$format='upperalpha' or $format='A'">
          <xsl:value-of select="'A'"/>
        </xsl:when>
        <xsl:when test="$format='upperroman' or $format='I'">
          <xsl:value-of select="'I'"/>
        </xsl:when>
        <xsl:when test="$format='arabicindic' or $format='١'">
          <xsl:value-of select="'١'"/>
        </xsl:when>
        <xsl:when test="$format='japanese' or $format='&#x4e00;'">
          <xsl:value-of select="'&#x4e00;'"/>
        </xsl:when>
        <xsl:otherwise>
          <xsl:message>
            <xsl:text>Unexpected </xsl:text>
            <xsl:value-of select="local-name(.)"/>
            <xsl:text>.autolabel value: </xsl:text>
            <xsl:value-of select="$format"/>
            <xsl:text>; using default.</xsl:text>
          </xsl:message>
          <xsl:call-template name="default.autolabel.format"/>
        </xsl:otherwise>
      </xsl:choose>
    </xsl:when>
  </xsl:choose>
</xsl:template>

Unfortunately, the xsltproc processor does not support this currently (as in version 1.1.24). Only Saxon does it correct.

You need to know how to insert a graphic to your titlepage.

To insert a graphic to one of your title pages, you need to create a template for titlepages as described in Section 4.2, “Designing a Title Page”.

To add your graphic, the XSL-FO specification has defined an fo:block-container to encapsulate an fo:external-graphics element. Additionally, there are many, many options to modify your graphic on the title pages like scaling or positioning. The following listing show how to use both elements.

<fo:block space-before="1em" space-after="1em">
    <fo:external-graphic src="{$img.src.path}/your-graphic.svg"/>
</fo:block>

Depending on the position within the customized title element, where you want to place your graphic, you must place the fo:block-container before or after the title block-container.

The following example places the graphic after the document title. The graphic is scaled by 50% and the aspect ratio is preserved.

<xsl:template match="d:title" mode="book.titlepage.recto.auto.mode">
    <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"
        xsl:use-attribute-sets="book.titlepage.recto.style" text-align="center"
        font-size="32pt" space-before="18.6624pt" font-weight="bold">
        <xsl:call-template name="division.title">
            <xsl:with-param name="node" select="ancestor-or-self::d:book[1]"/>
        </xsl:call-template>
        <fo:block space-before="1em" space-after="1em">
            <fo:external-graphic src="{$img.src.path}/your-graphic.svg" content-height="50%"
                scaling="uniform"/>
         </fo:block>
    </fo:block>
</xsl:template>

It's a good idea to use only supported high resolution bitmap graphics (300x300 dpi) or supported vector graphics for your title page. Otherwise you may notice that your graphic looks like small blocks.

You have a document which is written by different authors (like in proceedings) and want to include the author names in the table of contents.

You need to customize the toc.line template. Proceed as follows:

When you process the above section with the customization layer, you will receive the following line:

Tux Penguin: How to Become a Linux Mascott

Or in HTML notation:

<span class="author">Tux Penguin: </span>
<span class="section">
  <a href="...">How to Become a Linux Mascott</a>
</span>

Depending on the parameter section.autolabel the title can be prefixed with a number.

The previous stylesheet works also for one or more authors. It does not matter if the author elements appear as a direct child of info or authorgroup. The following code produces the same string:

<info>
  <author>
    <personname>
      <firstname>Tux</firstname>
      <surname>Penguin</surname>
    </personname>
  </author>
  <author>
    <personname>
      <firstname>Wilber</firstname>
      <surname>Gimp</surname>
    </personname>
  </author>
</info>

<info>
  <authorgroup>
    <author>
      <personname>
        <firstname>Tux</firstname>
        <surname>Penguin</surname>
      </personname>
    </author>
    <author>
      <personname>
        <firstname>Wilber</firstname>
        <surname>Gimp</surname>
      </personname>
    </author>
  </authorgroup>
</info>

Even if you mix author and authorgroup you will get the correct string output.

You can also use elements other than author. To detect editor, extend the variable author as follows:

<xsl:variable name="author"
      select="*/author|*/editor|*/authorgroup/author|*/authorgroup/editor"/>

You need for every appendix, chapter, section, etc. a small hint (often depicted as “¶”) which points to the division itself. This “permalink” simplies the retrieval and indentification of such a division.

You need an ID attribute on your division (chapter, section, examples, etc.) to make it work. The permalinks.xsl stylesheet is a named template which expects an id parameter.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" 
  xmlns="http://www.w3.org/1999/xhtml"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

  <xsl:param name="generate.permalink" select="1"/>        
  <xsl:param name="permalink.text">¶</xsl:param>           

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

    <xsl:if test="$generate.permalink != '0'">
      <span class="permalink">                             
        <a alt="Permalink" title="Permalink">              
          <xsl:attribute name="href">                      
            <xsl:call-template name="href.target">
              <xsl:with-param name="object"  select="$node"/>
            </xsl:call-template>
          </xsl:attribute>
          <xsl:copy-of select="$permalink.text"/>
        </a>
      </span>
    </xsl:if>
  </xsl:template>
</xsl:stylesheet>

This is of course not enough. Use the following steps to include it into your customization layers:

Permalinks are useful as it allows it easily to copy its URL. The DocBook XSL stylesheets allows the addition of permalinks in different locations, but the above customizations make the permalink more “attached” to its title.

All the above customization files create almost the same structure in regards to its permalink. For example, a chapter title looks like this in HTML:

<h2 class="title">The Chapter Title<span
      class="permalink"><a href="..." title="Permalink"
      alt="Permalink">¶</a></span>
</h1>

With CSS rules, you can style your permalink whatever you like.

You need a simple navigation for your single HTML file. The navigation should contain for each chapter a link to the next and previous chapters including an up link pointing to the enclosing part or book. This is depicted in the following graphic:

The following file defines the named template generate.simple.navigation:

<xsl:stylesheet version="1.0"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:d="http://docbook.org/ns/docbook"
  xmlns="http://www.w3.org/1999/xhtml"
  exclude-result-prefixes="d">
    
  <xsl:template name="generate.simple.navigation">
    <xsl:param name="node" select="."/>
    <xsl:variable name="prev" select="$node/preceding-sibling::d:chapter"/>
    <xsl:variable name="next" select="$node/following-sibling::d:chapter"/>
    <xsl:variable name="up"   select="$node/parent::d:*"/>
   
    <div class="chapter-navigation">
      <ul>
        <xsl:if test="count($next) >0">
          <li class="next">
            <xsl:call-template name="gentext.nav.next"/>
            <xsl:text>: </xsl:text>
            <a>
              <xsl:attribute name="href">
                <xsl:call-template name="href.target">
                  <xsl:with-param name="object" select="$next"/>
                </xsl:call-template>
              </xsl:attribute>
              <xsl:value-of select="$next/d:title"/>
            </a>
          </li>
        </xsl:if>
        <xsl:if test="count($prev) >0">
          <li class="prev">
            <xsl:call-template name="gentext.nav.prev"/>
            <xsl:text>: </xsl:text>
            <a>
              <xsl:attribute name="href">
                <xsl:call-template name="href.target">
                  <xsl:with-param name="object" select="$prev"/>
                </xsl:call-template>
              </xsl:attribute>
              <xsl:value-of select="$prev/d:title"/>
            </a>
          </li>
        </xsl:if>
        <xsl:if test="count($up) >0">
          <li class="up">
            <xsl:call-template name="gentext.nav.up"/>
            <xsl:text>: </xsl:text>
            <a>
              <xsl:attribute name="href">
                <xsl:call-template name="href.target">
                  <xsl:with-param name="object" select="$up"/>
                </xsl:call-template>
              </xsl:attribute>
              <xsl:value-of select="$up/d:title"/>
            </a>
          </li>
        </xsl:if>
      </ul>
    </div>
  </xsl:template>
</xsl:stylesheet>

This is not enough, of course. Use the following steps to include it into your customization layers:

If you want to switch on or off the above behaviour, use the parameter generate.simple.navigation^[9] and set it to 0.

The named template generate.simple.navigation works as follows:

The generate.simple.navigation template matches only chapters along the sibling axis. As such it can not find a glossary or appendix after a chapter. If you want to create links for any component elements, not only chapters, you need to change the variables prev and next. A first attempt would lead to this:

<xsl:variable name="prev" select="$node/preceding-sibling::d:*[1]"/>
<xsl:variable name="next" select="$node/following-sibling::d:*[1]"/>

This works for the next variables. However, our expression for the prev variable contains a bug. Consider the following structure:

book
  title
  info
  chapter
  ...

The preceding-sibling axis returns the info and title elements. This is not what you want as these are no component elements for our prev link. In that case we need an expression to filter out the unwanted elements. This is done with an predicate:

<xsl:variable name="prev" select="$node/preceding-sibling::d:*[not(self::d:title|self::d:info)][1]"/>

That expression first creates a node set with all preceding elements. In a second step they are check against the term not(self::d:title|self::d:info); only those elements remain in the node set which are not title or info elements. In our above example, this leads to a node set with zero nodes and is exactly what we wanted to achieve.

With the previous change, we allow any structural element to be included in a next or previous link. However, we show our navigation links only in chapter titlepages at the moment (the named template chapter.titlepage.before.recto.) We need to extend the stylesheet db-simple-navigation.xsl to allow elements like appendix, glossary, etc. Refer to the content modell of DocBook´s book element for details. For an appendix this looks like this:

<xsl:template name="appendix.titlepage.before.recto">
  <xsl:if test="$generate.simple.navigation != 0">
    <xsl:call-template name="generate.simple.navigation"/>
  </xsl:if>
</xsl:template>

For the other elements this is exactly the same except the name. Just use the element name and append .titlepage.before.recto.

You want to display a “path” to your current chapter, section etc. to improve fast jumping to parent structures.

Use breadcrumbs^[10] to improve navigation. Use the following procedure to create breadcrumbs for your documents:

For example, consider the current topic. It is embedded into this nested structure:

book: The DoCookBook
  chapter: (X)HTML Customizations
     sect1: Implementing “Breadcrumbs”

The above breadcrumbs.xsl stylesheets creates this HTML code when the current node is this topic:

<div class="breadcrumbs">
  <span><a href="...X...">The DoCookBook</a></span>
  >
  <span><a href="...Y...">(X)HTML Customizations</a></span>
  >
  <span class="breadcrumb-node">Implementing “Breadcrumbs”</span>
</div>

Leading to the following appearance:

The DoCookBook > (X)HTML Customizations > Implementing “Breadcrumbs”

Whereas all spans contains links to their respective components except the last one.

TBD

You have a book and want the table of contents appear after the main content.

The processing of a book is handled in the xhtml/division.xsl file. The template needs to be copied and inserted in your customization layer. To move your table of contents, do the following:

The same principle applies to other structural elements, although the handling is a bit different.

You want to highlight your source codes in programlisting elements with Google Code Prettifiy.

Syntax highlighting makes source code easier to read as keywords, strings, etc. appear in different colors. Use the following procedure to implement syntax highlighting with Google Code Prettifiy:

The current implementation uses a JavaScript solution to render the result in your browser. This has the advantage that you do not need any extensions in your customization layer during transformation. You only need to add the above additions to your customization layer and your source code to enable syntax highlighting.

However, if JavaScript is disabled it won't work anymore. If you rely on minimal HTML without any JavaScript code, this solution is not for you. Use the highlighting mechanism which uses an XSLT extension. Add link to highlighting extension topic with JAR

<xsl:template match="d:programlisting[@language]" mode="class.value">
  <xsl:param name="class" select="local-name(.)"/>
  <xsl:variable name="lang" select="concat('lang-', @language, ' ')"/>
  <xsl:choose>
    <xsl:when test="@linenumbering = 'numbered'">
      <xsl:value-of select="concat('prettyprint ', $lang, 'linenums ', $class)"/>
    </xsl:when>
    <xsl:otherwise>
      <xsl:value-of select="concat('prettyprint ', $lang, $class)"/>
    </xsl:otherwise>
  </xsl:choose>
</xsl:template>