DocBook xslTNG Reference

Author: Norman Walsh

Version 2.8.0

Updated: 26 Apr 2026

Copyright © 2020–2026 Norman Walsh.

Part I. Introduction

Table of Contents

Preface

1. Overview

1.1. What do the stylesheets do?

1.2. Getting the stylesheets

2. Using the stylesheets

2.1. Using the Jar

2.2. Using the Python script

2.3. Run with Java

2.4. Run with Docker

2.5. Run in Oxygen

2.6. Extension functions

2.7. “Chunked” output

2.8. Presentation mode

2.9. Effectivity attributes and profiling

2.10. Customize individual cross references

2.11. Verbatim environments

2.12. “Lists of titles” (tables of contents)

2.13. Paged-media (print output)

2.14. EPUB output

2.15. Ad hoc CSS styling

2.16. Responsive images

2.17. CALS tables

3. Customizing the stylesheets

3.1. Changing stylesheet parameters

3.2. Creating a customization layer

3.3. Managing CSS stylesheets

3.4. Customizing title pages

3.5. Managing media

3.6. Controlling numeration

3.7. Using glossaries

3.8. Using bibliographies

3.9. Something completely different

4. Localization

4.1. Overview

4.2. Localization files

4.3. Customizing a localization

4.4. Caveats

4.5. Background

5. Implementation details

5.1. Customizing chunking

5.2. Lengths and units

5.3. Line numbers

5.4. Processing mediaobjects

5.5. Templates

5.6. Annotations

5.7. The pre- and post-processing pipeline

6. Building the stylesheets

6.1. Prerequisites

6.2. Repository structure

6.3. Build configuration

6.4. Build tasks

6.5. Testing tasks

6.6. Running XSpec

A. Changes in version 2.x

A.1. Change Log

A.2. Introduction to xslTNG 2.x

Glossary

References

Acknowledgements

Index

Index by module

Preface

These stylesheets are the third iteration of stylesheets for DocBook that I’ve written. I started working on the XSLT 1.0 Stylesheets for DocBook in the 90’s, before XSLT 1.0 was even a W3C Recommendation. I started working on the XSLT 2.0 Stylesheets for DocBook just around the time when XSLT 2.0 became a W3C Recommendation. I wrote most of DocBook xslTNG just a month or so before the third anniversary of the XSLT 3.0 Recommendation.

Why did it take so long?

To answer that question, we need to reflect for a moment on XSLT and its place in the XML ecosystem. When XSLT arrived on the scene, we were near the peak of XML enthusiasm. Not only was XML supported everywhere, it was possible to imagine XSLT everywhere as well. Certainly, the presence of XSLT in the browser felt significant at the time.

The ubiquity of XML and the fact that XSLT was “just an XML vocabulary” may have contributed to another significant phenomenon: lots of users who did not self identify as programmers were learning to use XSLT and doing significant things with it.

There were other tools available for transforming markup at the time, and arguably some of them were better than XSLT, but they were programming languages and you had to be a programmer to use them. They were also mostly commercial applications not widely available to casual users.

XSLT was free, it was everywhere, and it was used by everyone, not “just” programmers. It was the clear winner than and remains the clear winner today in terms of markup transformation.

You could do a lot of things with XSLT 1.0. You could do a lot more things than you might at first even have thought possible. (In fact, you could do all things, but the Turing complete nature of XSLT isn’t relevant here.) Some very common tasks, like grouping, were possible but difficult. Lots of very useful things were either not possible or required extensions: regular expressions, functions, date and time formatting, creating special characters in the output, to name just a few.

XSLT 2.0 solved all of these problems (and more). Significantly, I think, all of these new features appealed directly to almost all users of XSLT 1.0. Everyone had encountered a grouping problem (building an index, for example). Everyone had wanted regular expression matching or date formatting. Lots of users wanted to write more sophisticated predicates (and many were willing to learn how to use functions to achieve that result).

XSLT 3.0 arguably introduces larger and more dramatic features than XSLT 2.0 did. There are a bunch of new features designed to enable streaming processing; there are significant software engineering improvements: packaging, exception handling, and assertions; there are common programming language constructs like maps and arrays. There is also a selection of features inherited from updates to XPath (new functions, a subset of let syntax, and support for higher order functions, for example).

What’s curious, I think, is that many of these features are probably less immediately appealing to many (most?) current users. XSLT 2.0 doesn’t feel constraining in the same way that XSLT 1.0 did, and the features in XSLT 3.0 don’t immediately and obviously solve problems that most users have.

Streaming, for example, is incredibly powerful and it’s an important and significant milestone in markup processing. It makes it possible to solve whole classes of problems that were previously impossible to solve or required enormously expensive hardware. But my laptop will quite easily process a book full of complex markup that runs to hundreds of pages. I don’t have any problems that require a streaming processor.

Likewise, packaging is useful and important. The DocBook xslTNG stylesheets should absolutely be a package. But that’s not true of a lot of stylesheets. There might be software engineering benefit in making a package even for stylesheets that you don’t intend to distribute, but that’s more likely to appeal to people who think of what they’re doing as programming.

Nevertheless, there are lots of good reasons to use XSLT 3.0 even if you are “only” transforming documents and even if you don’t think of writing transformations as programming.

Chapter 1. Overview

Before we get started, let’s look at what the stylesheets do and where you can get them!

1.1. What do the stylesheets do?

The DocBook xslTNG stylesheets transform DocBook V5.x into HTML. The intent is that they support all of DocBook V5.2, including the DocBook Publishers elements. (The test suite report gives a precise summary of the current state of coverage.) They will also process DocBook V4.x documents by first converting them (tranforming source elements that have changed, adding the namespace, etc.) into 5.x documents.

Some parts of DocBook, especially the modeling parts, are very open-ended. One could, in principle, write a function synopsis for any programming language. The stylesheets are naturally going to support only a subset of languages out of the box. Every attempt has been made to make customizations easy where it’s anticipated that they may be necessary.

The stylesheets can also be used to produce paged media such as PDF files. This works by having a slightly different HTML transformation initially, and then by further transforming the HTML so that it can be formatted with an appropriate CSS formatter to produce paged output. This is similar, but not the same as producing XSL Formatting Objects and then transforming those.

Producing other output formats, EPUB files, for example, is planned for the future but no specific schedule is promised. There are no plans at the moment to produce XSL FO stylesheets.

1.2. Getting the stylesheets

There are three ways to get the stylesheets: you can download the latest release from GitHub, you can get them from Maven, or you can clone the repository and build them yourself. We’ll cover the first two options in this chapter; Chapter 6, Building the stylesheets covers the last option in detail.

1.2.1. Download the latest release

The latest release is always available from the GitHub releases page. At the time of publication, the latest release was version 2.8.0.

Distributed this way, you’ll get a ZIP file that contains the stylesheets plus a number of ancillary files and tools. These are mostly covered in the next chapter Chapter 2, Using the stylesheets.

You can unzip the file anywhere that’s convenient: in your home directory or in a system-wide location.

1.2.2. Getting the release from Maven

The latest release is always available from Maven*.

The group, artifact, and version ID for the latest release at the time of publication is:

org.docbook:docbook-xslTNG:2.8.0

If you’re comfortable using Maven, I’m going to assume that’s all you need to know.

The Maven distribution differs from the zip file in a couple of ways:

It doesn’t bundle any of the dependencies. The ZIP file is more akin to an “uber” or “fat” jar; it includes (some of) the core dependencies so that it works out-of-the-box. Maven is designed to resolve dependencies, so that shouldn’t be necessary here.

The Maven jar doesn’t include the Python script or the extra resources (CSS and JavaScript files) because it doesn’t seem like it would be convenient to extract them from the Maven jar (which will probably be installed deep in some repository hierarchy well out of sight). Consequently, you may want to download the distribution periodically as well.

*

With the caveat that it sometimes takes a few hours for the releases to make their way from the registry onto the website. If you’re chasing the very latest release and it’s just been published, it may be available before it appears on the website.

Chapter 2. Using the stylesheets

In principle, the stylesheets will run with any conformant XSLT 3.0 processor. For many users, that means Saxon. Although earlier versions may work, Saxon 10.1 or later is recommended.

In principle, the instructions for using the stylesheets are straightforward: using your XSLT 3.0 processor of choice, transform your DocBook source documents with the docbook.xsl stylesheet in the xslt directory of the distribution.

In practice, for most users, running the stylesheets will require getting a Java environment configured appropriately. For many, one of the most significant challenges is getting all of the dependencies sorted out. Modern software development, for better or worse, often consists of one library relying on another which relies on another, etc.

The DocBook xslTNG stylesheets attempt to simplify this process, especially for the “out of the box” experience by providing two convenience methods for running the stylesheets: a jar file with a Main class, and a Python script that attempts, among other things, to make sure all of the dependencies are available.

If you’re an experience Java user, you may prefer to simply run the stylesheets directly with Java.

Irrespective of which method you choose, running the stylesheets is simply a matter of processing your input document myfile.xml with xslt/docbook.xsl. For example:

$ saxon myfile.xml -xsl:xslt/docbook.xsl -o:myfile.html

The exact path to docbook.xsl will vary, of course, but it’s in the xslt directory of the distribution.

ⓘ

Note

The resulting HTML document contains references to CSS stylesheets and possibly JavaScript libraries. The output won’t look as nice in your browser if those resources aren’t available. They’re in the resources directory of the distribution. A quick and easy way to see the results is simply to send the output to the samples directory from the distribution. The resources have already been copied into that directory. In the longer run, you’ll want to make sure that they get copied into the output directory for each of your projects.

Alternatively, you can copy them to a web location of your choosing and point to them there. You can even point to them in the DocBook CDN, but beware that those are not immutable. The “current” version will change with every release and versioned releases will not persist indefinitely.

Change the $resource-base-uri to adjust the paths used in the output document.

Many aspects of the transformation can be controlled simply by setting parameters (see I. Parameter reference). It’s also possible to change the transformation by writing your own customization layer (see Chapter 3, Customizing the stylesheets).

2.1. Using the Jar

The ZIP distribution includes a JAR file that you can run directly. That JAR file is $ROOT/libs/docbook-xslTNG-version.jar where “$ROOT” is whatever directory you chose to unzip the distribution into and version is the stylesheet version.

Assuming you unzipped the version 2.8.0 distribution into /home/ndw/xsltng, you can run the JAR like this:

java -jar /home/ndw/xsltng/libs/docbook-xslTNG-2.8.0.jar

Let’s try it out. Open a shell window and change to the samples directory, /home/ndw/xsltng/samples assuming you unzipped it as described above. Now run the java command:

$ java -jar ../libs/docbook-xslTNG-2.8.0.jar article.xml
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml">
…more HTML here...
<nav class="bottom"></nav></body></html>

That big splash of HTML was your first DocBook document formatted by the stylesheets! Slightly more usefully, you can save that HTML in a file:

$ java -jar ../libs/docbook-xslTNG-2.8.0.jar article.xml \
        -o:article.html

If you now open article.html in your favorite web browser, you’ll see the transformed sample document which should look like Figure 2.1, “The sample document: article.xml”.

Figure 2.1. The sample document: article.xml

The JAR file, run this way, accepts the same command line options as Saxon, with a few caveats:

No -x, -y, or -r options

The executable in the JAR file automatically configures Saxon to use a catalog-based resolver and points the resolver at a catalog that includes the files in the distribution.

No -init option

The DocBook xslTNG extension functions will be registered automatically.

Multiple -catalog options

You can repeat the -catalog option. All of the catalogs you specify will be searched before the default catalog.

Default stylesheet

If you do not specify a stylesheet with the -xsl option, the xslt/docbook.xsl stylesheet will be used automatically.

2.2. Using the Python script

The ZIP distribution includes a Python script in the bin directory. This helper script is a convenience wrapper around Saxon. It sets up the Java classpath and automatically configures a catalog resolver and the DocBook extension functions.

☝

Important

The script requires the click and pygments packages, which you must install with pip before running the script. For example:

python3 -m pip install pygments=2.6.1 click

This script behaves much like the JAR file described in Section 2.1, “Using the Jar”. In particular, it accepts the same command line options as Saxon, with the same caveats.

The significant feature of the Python script is that it will attempt to sort out the dependencies for you. It assumes that you’ve used Maven to install the package and its dependencies, so you’ll have to have installed Maven. How you do that varies by platform, but your package manager probably has it.

The following command will assure that you’ve downloaded all of the necessary dependencies. You only have to do this once.

$ mvn org.apache.maven.plugins:maven-dependency-plugin:2.4:get \
      -Dartifact=org.docbook:docbook-xslTNG:2.8.0

That might take a while.

The script will work through the dependencies that you have installed, and the things that they depend on, and construct a Java class path that includes them all.

The script stores its configuration in .docbook-xsltng.json in your home directory.

Options passed to the script are processed as follows: the initial options, all introduced by two hyphens, are interpreted by this script; all the remaining options are passed directly to Saxon.

The script options are:

--help

Prints a usage message.

--config:filename

Use filename as the configuration file. The default configuration file is .docbook-xsltng.json in your home directory.

--resources:dir

This option will copy the resources directory (the CSS and JavaScript files) from the distribution into the directory where your output files are going, dir. If dir is not specified, the script attempts to work out the directory from the -o option provided to Saxon. If no directory is specified and it can’t work out what the directory is, it does nothing.

--java:javaexec

Use javaexec as the Java executable. The default java executable is the first one on your PATH.

--home:dir

Use dir as the DocBook xslTNG home directory. This should be the location where you unzipped the distribution. (You probably shouldn’t change this.)

--verbose

Enables verbose mode; it prints more messages about what it finds.

--debug

Enables debug mode. Instead of running the transformation, it will print out the command that would have been run.

--

Immediately stop interpreting options. Everything that follows this option will be passed to Saxon, even if it begins with two hyphens.

2.3. Run with Java

Assuming you’ve organized your class path so that all of the dependencies are available (you may find that using a tool like Gradle or Maven simplifies this process), simply run the Saxon class.

For Saxon HE, the class is net.sf.saxon.Transform. For Saxon PE and EE, the class is com.saxonica.Transform.

2.4. Run with Docker

This is experimental.

The docker directory contains an experimental Dockerfile. Using docker allows you to isolate the environment necessary to run the DocBook xslTNG Stylesheets from your local environment. (If you’re using Linux, see Section 2.4.1, “Docker on Linux”.)

Using Docker is a three step process. Step 0, you have to have installed Docker!

Build the docker image. In the docker directory, run the docker build command:

$ docker build -t docbook-xsltng .

The “-t” option provides a tag for the image; you can make this anything you want. There’s a VERSION build argument if you want to build a particular release. For example,

$ docker build --build-arg VERSION=2.8.0 -t docbook-xsltng .

will build a Docker image for the 2.8.0 release of the stylesheets irrespective of the version in the Dockerfile.

Run the image, for example:

$ docker run docbook-xsltng samples/article.xml

If you chose a different tag when you built the image, use that tag in place of docbook-xsltng in the run command. Everything after the container tag becomes options to the docbook Python script.

ⓘ

Note

The context the script runs in is inside the container. It can’t for example, see your local filesystem. The example above works because the distribution is unpacked inside the container. So the article.xml document isn’t the one on your local filesystem.

You can use the Docker facilities for mounting directories to change what documents the script can access. For example:

$ docker run -v /tmp:/output -v /path/to/samples:/input \
       docbook-xsltng /input/article.xml chunk=index.html \
       chunk-output-base-uri=/output/

Assuming that the “samples” directory in the distribution is located at /path/to/samples, this will chunk the article.xml sample document that the script sees in /input (which is where you mounted samples) and it will write the output to /output (which is where you mounted /tmp).

When the script finishes, the chunked output will be in /tmp.

☞

Tip

If you choose to use Docker, you don’t have to rebuild the container everytime a new stylesheet release occurs. You can simply mount the new xslt directory into the container like any other directory.

2.4.1. Docker on Linux

When a Docker container running on Linux writes to the local filesystem, for example because you mounted it in a container, any files written by the container will be owned by “root”. This can be quite inconvenient.

If there’s an elegant solution to this problem, I haven’t found it. Some users have reported success using podman, a Docker-compatible, open source alternative that apparently doesn’t exhibit this behavior.

The following approach will work with Docker, but it’s a bit more complicated.

Create a volume, say docbook-output, with the docker volume command.

docker volume create docbook-output

Instead of mounting a directory on the local filesystem in the container, mount the volume.

Run the transformation.

In order to copy the files off the volume, the volume has to be mounted on a running container. You can start one with docker run, for example:

docker run —mount source=docbook-output,target=/out \
       --name copy-helper -d busyboxy sleep 3600

Copy the files out of the container. For a single file, docker cp will do the trick:

docker cp copy-helper:/out/filename.html .

If there are multiple output files, you can copy them individually, or you can use docker exec:

docker exec copy-helper \
       /bin/sh -c 'cd /out && tar cf - .' > out.tar

That’ll copy all the files into the out.tar archive which you can expand wherever you like.

When you have the files, you can stop and remove the container with:

docker stop copy-helper
docker rm copy-helper

You may want to remove the volume you created as well:

docker volume rm docbook-output

and recreate it for the next transformation. If you don’t, be aware that the content of the volume will persist. If you resuse the volume for other transformations, the output from the various transformations will be mingled together on the volume.

And, perhaps obviously, if you remove the volume before you copy the files off of it, the files will be lost.

In short: using a Docker container on Linux is somewhat less convenient.

2.5. Run in Oxygen

“Oxygen” is a family of tools for XML authoring and development. The DocBook xslTNG Stylesheets are not currently shipped with Oxygen. To take advantage of the xslTNG stylesheets, you must setup the transformation scenarios yourself.

Download the nosaxon xslTNG release that you want to use in Oxygen (docbook-xslTNG-nosaxon-version.zip) and unzip it somewhere in your filesystem. (Oxygen includes Saxon EE; the integration will be cleaner if the release you use does not include a different version of Saxon.)

Define a transformation scenario with path/xslt/docbook.xsl as the XSLT file (where path is where you unzipped the release in the previous step.

In order to use the extension functions defined in Section 2.6, you have to add the docbook-xslTNG-version.jar library as an Extension and set org.docbook.xslt.extensions as the Initializer class in the Advanced Saxon HE/PE/EE XQuery Transformation Options for the transformation scenario.

Without this step the basic transformation will work, but extensions like image metadate extraction with ext:image-metadata will not be available.

Set the stylesheet parameters accordingly in the transformation scenario.

Run the transformation to generate HTML output. You will have to copy the resources/css and resources/js directories to the output location in order to get the styling and interactive features.

2.6. Extension functions

The stylesheets are distributed with several extension functions:

ext:cwd()

Returns the “current working directory” where the processor is running.

ext:image-properties()

Returns basic properties of an image, width and height.

ext:image-metadata()

Returns much more comprehensive image properties and understands far more image types than ext:image-properties(). Requires the metadata-extractor libraries.

ext:pygmentize()

Runs the external Pygments processor on a verbatim listing to add syntax highlighting.

ext:pygmentize-available()

Returns true if the external Pygments processor is available on the current system.

ext:xinclude()

Performs XInclude processing. This extension supports the basic XPointer schemes, RFC 5147 fragment identifiers, and search, a scheme that supports searching in text documents.

ext:validate-with-relax-ng()

Performs RELAX NG validation.

At the time of this writing, all of these extension functions require Saxon 10.1 or later. Make sure that the docbook-xsltng-version.jar file is on your class path and use the Saxon -init option to load them:

-init:org.docbook.xsltng.extensions.Register

2.6.1. Extension function debugging

When an extension function fails, or produces result other than what you expect, it can be difficult sometimes to work out what happened. You can enable debugging messages by setting the the system property org.docbook.xsltng.verbose.

Setting the property to the value “true” enables all of the debugging messages. For a more selective approach, set it to a comma separated list of keyword values.

The following keywords are recognized:

registration

Enables messages related to function registration.

image-properties

Enables messages related to image properties.

image-errors

Enables messages related to image properties, but only when the function was unable to find the properties or encountered some sort of error condition.

pygmentize-show-command

Enables a message that will show the pygmentize command as it was run.

pygmentize-show-results

Enables a message that will show the output of the pygmentize command, before it is processed by the function.

pygmentize-errors

Enables messages related to errors encountered attempting to highlight listings with pygmentize.

2.7. “Chunked” output

Transforming myfile.xml with docbook.xsl usually produces a single HTML document. For large documents, books like this one for example, it’s sometimes desirable to break the input document into a collection of web pages. You can achieve this with the DocBook xslTNG Stylesheets by setting two parameters:

$chunk

This parameter should be set to the name that you want to use for the first, or top, page of the result. The name index.html is a common choice.

$chunk-output-base-uri

This parameter should be set to the absolute path where you want to use as the base URI for the result documents, for example /home/ndw/output/guide/.

ⓘ

Note

The trailing slash is important, this is a URI. If you specify only /home/ndw/output/guide, the base URI will be taken to be /home/ndw/output/, and the documents won’t have the URIs you expect.

This output URI has nothing to do with where your documents are ultimately published and the documents themselves won’t contain any references to it. It simply establishes the root of output. If you’re running your XSLT processor from the command line, it’s likely that the documents will be written to that location. If you’re running an XProc pipeline, it simply controls the URIs that appear on the secondary result port.

Many aspects of chunking can be easily customized. A few of the most relevant parameters and templates are:

$chunk-include and $chunk-exclude

Taken together, these two parameters determine what elements in your source document will be considered “chunks” in the output.

$persistent-toc

If this parameter is true, then a JavaScript “fly-out” table of contents will be available on every page.

$chunk-nav

This parameter, discussed more thoroughly in Section 2.7.1, “Keyboard navigation” enables keyboard navigation between chunks.

t:top-nav and t:bottom-nav

These templates control how the top-of-page and bottom-of-page navigation aids are constructed.

$use-id-as-filename

If this parameter is true, the xml:id on a chunk will be used to construct the filename for that chunk. You can also control the chunk filename on a per-chunk basis with the db processing instruction using the filename pseudo-attribute.

2.7.1. Keyboard navigation

If the $chunk-nav parameter is true, a reference to an additional JavaScript library will be included in the resulting pages. This library supports keyboard navigation between the pages. The navigation keys are described in the parameter reference page.

2.8. Presentation mode

Presentation mode implements paged navigation through a document. For presentation mode, a single document is used (rather than chunking) with some JavaScript code providing the user interface.

As the name implies, it’s designed for use in presentations:

It uses generally larger fonts by default and works best for many small pages

Each unit of a document (part, chapter, article, section, etc.) becomes a page.

Presentation mode replaces earlier “slides” and “speaker notes” implementations.

Beyond the paginated navigation, presentation mode has three key features:

Synchronization

When served with https (or from localhost with http), presentation mode can use local storage to synchronize display in different browser windows.

Add

<meta xmlns="http://www.w3.org/1999/xhtml"
      name="localStorage.key" content="keyName"/>

to the info of your document.

The key name is irrelevant, but is used to coordinate between windows. All documents with the same key name will be synchronized together. *

Synchronized displays are useful for reading speaker notes in one view while presenting the “normal” view to your audience.

Speaker notes

Speaker notes can be placed on any page. They are not displayed as part of the normal presentation. They can be revealed by selecting notes view (pressing S).

Use the speaker-notes role to add speaker notes.

Progressive reveal

Any elements marked with the role reveal will be hidden initially. Navigating forward or pressing Space will reveal them.

When applied to lists, the behavior applies to all of the items except the first.

If an item is marked both reveal and transitory, it will be revealed in turn and then concealed again when the next item is revealed. This allows one to create the illusion, for example, of bullet items being replaced.

In sort, you get:

Quick and easy presentations from DocBook documents.

No special markup required.

Easy navigation.

Clean look and feel.

Advanced features:

Synchronized display

Speaker notes

Progressive and transitory reveals

Pressing F1 in a presentation mode document will display a summary of the keyboard navigation shortcuts.

There’s a small customization layer in the distribution, presentation.xsl that enables presentation mode and changes some of the generated text so that the labels “Part”, “Chapter”, and so forth aren’t in the output.

2.9. Effectivity attributes and profiling

When documenting computer hardware and software systems, it’s very common to have different documentation sets that overlap signficantly. Documentation for two different models of network router, for example, might differ only in a few specific details. Or a user guide aimed at experts might have a lot in common with the new user guide.

2.9.1. Effectivity

There are many ways to address this problem, but one of the simplest is to identify the “effectivity” of different parts of a document. Effectivity in this context means identifying the parts of a document that are effective for different audiences.

When a document is formatted, the stylesheets can selectively include or omit elements based on their configured effectivity. This “profiled” version of the document is the one that’s explicitly targeted to the audience specified.

DocBook supports a wide variety of common attributes for this purpose:

Table 2.1. Common DocBook effectivity attributes

Attribute | Nominal effectivity axis
arch | The architecture, Intel or AMD
audience | The audience, operations or development
condition | Any condition (semantically neutral)
conformance | The conformance level
os | The operating system, Windows or Linux
outputformat | The output format, print or online
revision | The revision, 3.4 or 4.0.
security | The security, secret or top-secret
userlevel | The user level, novice or expert
vendor | The vendor, Acme or Yoyodyne
wordsize | The word size, 32 or 64 bit

ⓘ

Note

DocBook places no constraints on the values used for effectivity and the stylesheets don’t either. You’re free to use “cat” and “dog” as effectivity values in the wordsize attribute, if you wish. The further you deviate from the nominal meaning, the more important it is to document your system!

Consider Example 2.1, “A contrived effectivity example”.

<para>This is an utterly contrived example of
some common text. Options are introduced with the
<phrase os="windows">/</phrase>
<phrase os="mac;linux">-</phrase> character.</para>

Example 2.1. A contrived effectivity example

If this document is formatted with the $profile-os parameter set to “windows”, it will produce:

This is an utterly contrived example of some common text. Options are introduced with the / character.

If “mac” or “linux” is specified, it will produce:

This is an utterly contrived example of some common text. Options are introduced with the - character.

☝

Important

If the document is formatted without any profiling, all of the versions will be included:

This is an utterly contrived example of some common text. Options are introduced with the / - character.

That is unlikely to work well.

2.9.2. Other common Attributes

In addition, the stylesheets support profiling on several common attributes that are not explicitly for effectivity: xml:lang, revisionflag, and role.

ⓘ

The role attribute is multi-valued

The stylesheets treat the role attribute as multi-valued, similar to the class attribute in HTML. It may contain a sequence of tokens, seperated by whitespace. This allows you, for example, to classify a section as informal which should be printed in landscape orientation with the role value “informal landscape”.

2.9.3. Profiling

The profiling parameters are applied to every document: $profile-arch, $profile-audience, $profile-condition, $profile-conformance, $profile-lang, $profile-os, $profile-outputformat, $profile-revision, $profile-revisionflag, $profile-role, $profile-security, $profile-userlevel, $profile-vendor, and $profile-wordsize. Each of these values is treated as a string and broken into tokens at the $profile-separator.

For every element in the source document:

If it specifies a value for an effectivity attribute, the value is split into tokens at the $profile-separator.

If the corresponding profile parameter is not empty, then the element is discarded unless at least one of the tokens in the profile parameter list is also in the effectivity list.

In practice, elements that don’t specify effectivity are always included and profile parameters that are empty don’t exclude any elements.

2.9.4. Dynamic profiling

Dynamic profiling is a feature that allows you to profile the output of the stylesheets according to the runtime values of stylesheet parameters. You can, for example, produce different output depending on whether or not chunking is enabled or JavaScript is being used for annotations.

To enable dynamic profiling, set the $dynamic-profiles parameter to “true”.

In the interest of performance, security, and legibility, dynamic profiles don’t support arbitrary expressions. You can use a variable name by itself, $flag, which tests if that variable is true, or you can use a simple comparison, $var=value which tests if (the string value of) $var has the value value. (If $var is a list, it’s an existential test.) You also can’t use boolean operators or any other fancy expressions.

If you really need to have a dynamic profile based on some arbitrary condition, you can do it by making a customization layer that stores that computation in a variable and then testing that variable in your dynamic profile.

Backwards incompatibility

This is slightly backwards incompatible in that profile values that begin with a dollar sign are now interpreted differently. This is only true if dynamic profiling is enabled.

An element with dynamic profiling will be published if none of it’s profile expressions evaluate to false. This is slightly different from the ordinary profiling semantic which publishes the element if any of it’s values match.

2.10. Customize individual cross references

Most kinds of generated text apply across an entire document: do you want chapters to be numbered? Should generated text be in English or French? What form should numbered and unnumbered sections have? The mechanisms for changing this generated text are described in Chapter 4, Localization. These mechanisms control the formatting of cross references.

But it’s sometimes useful to change the format of a cross reference on an individual basis (that is, on the basis of the context in which the reference occurs, not the nature of what is referenced). You might, for example, want to shorten a cross reference to just a label if it is referenced several times.

Consider a cross reference to a section: see <xref linkend="syntax-highlighting"/>. In the localization style of this guide, that is rendered like this: see Section 2.11.2, “Syntax highlighter”.

The text that is generated by a cross reference can be customized for individual references with the xrefstyle attribute. For example, see <xref linkend="syntax-highlighting" xrefstyle="%l"/>, will produce a result like this: see 2.11.2.

You can use the %c, %l and %p values from Table 4.1, “Template %-letter substitutions” in xrefstyle. There is also an additional %label for the full Label, which is the component`s name and number. The use of these percent-values is explained in the following table. The result column shows how a cross reference to the section below entitled Syntax highlighter would appear in each xrefstyle.

Value of xrefstyle attribute on xref | Result | Remark
(@xrefstyle is absent) | Section 2.11.2, “Syntax highlighter” | Default
%c | Syntax highlighter | Content, e. g. title of target
%l | 2.11.2 | Label, usually the target’s number.
%label | Section 2.11.2 | The full Label, usually the target’s number and name.
%p |  | Page number in print output (PDF). Displays as “#” in HTML.
%label (%c) | Section 2.11.2 (Syntax highlighter) | You can combine %-letters with text

Legacy values for xrefstyle

In order to support migration from XSLT 1.0 Stylesheets, xslTNG supports the template: Syntax which is explained in “Customizing with an xrefstyle attribute / Using template:” in the book “DocBook XSL: The Complete Guide”. This is summarized in the following table.

Value of xrefstyle attribute on xref | Result | Remark
template:the chapter numbered %n | the chapter numbered 2.11.2 | XSLT 1.0 Legacy Syntax
template:the chapter called %t | the chapter called Syntax highlighter | XSLT 1.0 Legacy Syntax

Using pagenumber in cross-references

The %p value in xrefstyle makes little sense in HTML output, since there are no page numbers. If you use it anyway, it will be displayed as “”. This may be confusing for readers. A possible solution for this problem is the use of the outputformat attribute. For example:

The outputformat attribute was intoduced in Section 2.9, “Effectivity attributes and profiling” and Table 2.1.

The paragraph markup in that example is:

1 |<para>The <code>outputformat</code> attribute was intoduced in
  |<xref linkend="profiling"/> and
  |<xref linkend="table.effectivity-attributes" xrefstyle="%label"
  |/><phrase outputformat="print"> on page
5 |<xref linkend="table.effectivity-attributes" xrefstyle="%p"
  |/></phrase>.
  |</para>

Example 2.2. Use outputformat to deal with page numbers in cross references

Where the page number appears in the print version, but not in the HTML version. Note that some care has been taken with line breaks and spaces around markup to avoid extraneous whitespace in either version.

2.11. Verbatim environments

Verbatim environments are ones in which spaces and line-breaks are preserved. There are several flavors of verbatim environment in DocBook: programlisting, screen, literallayout, address, and several flavors of synopsis. Most verbatim environments are presented in a monospace font, but literallayout and address usually are not. In addition, programlistingco and screenco provide mechanisms for out-of-band annotations (“callouts”) in the environments the contain.

To further complicate matters, line numbering may be added to verbatim environments, they may be syntax highlighted, and these embellishments can be performed by the stylesheets or with JavaScript in the browser (or more generally, "the rending engine"; it’s not impossible to imagine a paged media formatter that renders JavaScript, I just don’t know of any).

Handling of verbatim environments was largely rewritten in version 2.5.0 of the stylesheets to clarify what can be controlled and how. There are still a collection of not-quite-orthogonal issues at play.

Broadly, there are four possible presentation styles for verbatim environments and three sets of features: syntax highlighting, line numbering, and support for out-of-band callouts. Syntax highlighting can be performed by the stylesheets using Pygments or by the browser using JavaScript.

Table 2.2. Verbatim processing matrix

| Verbatim presentation style
| lines | table | plain | raw
Pygments highlighting | ✔ | ✔ | ✔ |
JavaScript highlighting |  |  | ✔ | ✔
Line numbering | ✔ | ✔ | * | *
Out-of-band callouts | ✔ | ✔ |  |
* Maybe, if supported by JavaScript highlighter

At the highest level, if $verbatim-embellishments is false, no special formatting is provided. If $verbatim-embellish-linenumbers is false, no line numbering will be provided, irrespective of other settings. The DocBook xslTNG Stylesheets have always numbered verbatim environments by default; this is a simple, global parameter to disable that behavior. Assuming that embellishments are enabled, the $verbatim-numbered-elements parameter determines which elements are numbered by default.

How a verbatim environment is processed depends a number of options described in the sections that follow.

2.11.1. Verbatim style

There are four verbatim styles: lines, table, plain, and raw.

lines

In the lines style, each line of the verbatim environment is marked up individually. In this style, lines can be numbered and callouts can be inserted.

table

In the table style, each line of the verbatim environment is marked up individually, very much like the lines style. In this style, lines can be numbered and callouts can be inserted. It differs from the lines style in that the whole thing is wrapped in a table.

The table has one row and two columns. The line numbers appear in the first column, the lines in the second. This format was added in order to improve the display in user agents that don’t support CSS. Ironically, in the course of adding this style, a number of changes were made to the way line numbers are formatted in the lines style making it largely, perhaps entirely, unnecessary.

plain

In the plain style, callouts can be inserted, but additional markup is not added (except for the callouts). Consequently, it isn’t possible to do line numbering or syntax highlighting. (It may be possible to provide these features with JavaScript libraries in the browser, however.)

raw

In the raw style, no changes are made to the verbatim content. It’s output as it appears. Inline markup that it contains, emphasis or other elements, will be processed, but you cannot add line numbers, callouts, or syntax highlighting.

The lines style assures that inline markup doesn’t cross line boundaries, wraps each line in a span, may add an additional spans for line numbers, and may be augmented with out-of-band callouts.

The table style is essentially the same as the lines style except that the final presentation uses an HTML table to separate the line numbers from the listing.

The plain style assures that inline markup doesn’t cross line boundaries, but otherwise adds no markup.

The raw style does nothing but format the listing.

For a given verbatim element, if its (local) name appears in the $verbatim-table-style parameter, it will use the table style, if it appears in the $verbatim-line-style parameter, it will use the line style, if it appears in the $verbatim-plain-style parameter, it will use the plain style. Otherwise, it will use the raw style.

The style of an individual element can be changed by adding a db processing instruction with a verbatim-style pseudo attribute that specifies the style.

In addition, the default style for all the listings in a given document can be specified by setting the verbatim-style on a db processing instruction in the root element.

2.11.2. Syntax highlighter

Program listings and other verbatim environments can be “syntax highlighted”, that is, the significant tokens in the listing can be colored differently (keywords in red, quoted strings in blue, that sort of thing).

The default syntax highlighter is Pygments, an external Python program. This has the advantage that the highlighted listing is available to the stylesheets. The stylesheets can then render line numbers, call outs, and other features.

But running an external program for every verbatim environment requires having the external program and also, if there are many verbatim environments, may slow down the formatting process

An alternative is to use a JavaScript highlighter in the browser such as highlight.js or Prism. This approach has no impact on formatting and doesn’t require an external process. However, it means the xslTNG Stylesheets have no control over the process. Most of the verbatim options only apply when Pygments is used.

There are four highlighter choices: pygments, highlight.js, prism, or none.

If the pygments highlighter is selected, an attempt is made to run an external Python program to apply syntax highlighting to the listing. This ignores all inline markup and, obviously, will only succeed if the Pygments highlighter is configured on your system.

The highlight.js and prism highlighters are two different JavaScript-based highlighters.

If none is selected, no highlighting will be attempted.

The highlighter for an individual element can be changed by adding a db processing instruction with a syntax-highlighter pseudo attribute that specifies the highlighter.

In addition, the default style for all the listings in a given document can be specified by setting the syntax-highlighter on a db processing instruction in the root element.

ⓘ

Note

Although none and pygments can always be selected, the JavaScript highlighters can only be selected at the document level.

2.11.3. Verbatim numbering

If enabled, line numbers are added to verbatim listings.

The $verbatim-numbered-elements parameter determines which elements are numbered by default. Numbering for an individual element can be changed by adding a db processing instruction with a verbatim-numbered pseudo attribute.

2.11.4. Verbatim (out-of-band) callouts

This option determines how out-of-band callouts should be rendered.

The $verbatim-callouts parameter determines the default renderings. The rendering for an individual element can be changed by adding a db processing instruction with a verbatim-highlight pseudo attribute.

2.11.5. Starting line number

When numbering, what is the number of the first line?

This is determined by the startinglinenumber and continuation attributes.

2.11.6. Shortest numbered listing

What is the shortest listing that should be numbered? Even if line numbering is enabled, it may not be desirable to number the lines of very short listings. Listings shorter than the minimimum number will not be numbered.

The $verbatim-number-minlines parameter determines the default value. The valu for an individual element can be changed by adding a db processing instruction with a linenumbering-minlines pseudo attribute.

2.11.7. Trimming blank lines

Controls if leading and/or trailing blank lines will be removed from the listing. This can improve the appearance of listings where the author has added a blank line after the start tag or before the end tag.

The $verbatim-trim-leading-blank-lines ($verbatim-trim-trailing-blank-lines parameter determines if leading (trailing) blank lines will be removed by default. The value for an individual element can be changed by adding a db processing instruction with a verbatim-trim-leading or verbatim-trim-trailing pseudo attribute.

This only applies for the lines and table presentation styles.

2.12. “Lists of titles” (tables of contents)

There are several features related to “lists of titles”: tables of contents and lists of figures, tables, examples, etc. taken as a group.

2.12.1. Placement of the table of lists

If the $auto-toc parameter is true, lists of titles generated automatically. By default, these are generated for the set, book, part, and reference elements, and the article element when it is the document element. Each element is processed in the m:toc mode to generate the automatic list of titles. The lists are placed near the beginning of the element, just after the title and other metadata.

More control over the placement of the list of titles can be achieved with the toc element. A list of titles will be placed wherever an empty toc element occurs. By default this will be a list of titles for the element that is the parent of the toc. If the linkend attribute appears on the toc, then the list will be generated for the element identified by the linkend attribute.

The parameters $lists-of-figures, $lists-of-tables, $lists-of-examples, $lists-of-equations, and $lists-of-procedures determine whether or not a list of titles is created for figures, tables, examples, equations, and procedures. By default, these are only ever generated for set and book.

The role attribute on the toc element affords more control here too. If present, the role must contain one or more of the strings contents, figures, tables examples equations and procedures. Only the nominated lists will be created. They will be created in the order they appear in the role attribute.

The $auto-toc parameter and the toc element can interact. If the toc element is a direct child of an element that would have an automatically generated of list of titles, the automatically generated list is suppressed in favor of the location where the toc occurs. If the toc element is nested in a descendant or if it identifies some other element with a linkend attribute, you may get missing, duplicated, or incorrect lists of titles.

The title and metadata for most elements is controlled by a header template. This is not true of lists of titles. They all have the same structure. Use CSS to adjust the style of the title, if necessary.

2.12.2. Persistent table of contents

The persistent Table of Contents (ToC) provides a full ToC for an entire document accessible from each chunked page.

The ToC is accessed by clicking on the “book” icon in the upper right corner of the page as shown in Figure 2.2, “Opening the ToC”.

Figure 2.2. Opening the ToC

The icon and other aspects of the style can be changed by providing $persistent-toc-css.

Once open, the ToC is displayed. A long ToC will be scrolled to the location of the current page in the document as shown in Figure 2.3, “The Persistent ToC”.

Figure 2.3. The Persistent ToC

The persistent ToC popup is transient by default, meaning that it will disappear if you use it to navigate to a different page. If you open the popup by “shift-clicking” on it, the ToC will persist until you dismiss it. This can also be accomplished by selecting the check box in the ToC. The presense of the search bar is controlled by the $persistent-toc-search parameter.

2.12.2.1. Persistent ToC data

The data used by the persistent ToC can be stored in a separate file or stored in each chunk. This is controlled by the $persistent-toc-filename.

If chunking is enabled and the $persistent-toc-filename parameter is non-empty, it’s used as a filename and a single copy of the ToC will be saved in that file.

The benefit of this approach is that the HTML chunks are smaller. If the persistent ToC is written into every chunk, the size of each HTML chunk increases in proportion to the size of the ToC. For a large document with lots of small pages, this can be a significant percentage of the overall size.

There are two disadvantages:

This will not work if the documents are accessed with file: URIs: you must use http (and in some environments, perhaps https) to load the documents. The browser will (quite reasonably) not allow JavaScript to load documents from the filesystem.

Also, with this approach, opening the ToC requires another document to be loaded into the browser. For a large ToC, this can introduce visible latency, although browser caching tends to reduce that after the document has been loaded once.

If the $persistent-toc-filename parameter is the empty sequence, a copy of the ToC is stored in each chunk.

ⓘ

Note

When stored in each chunk, the Table of Contents is secreted away in a script element so that it will be ignored by screen readers and other user agents that don’t support JavaScript or CSS.

The benefit of this approach is that it requires no additional document to be loaded and will work even if the documents are loaded with file URIs.

The disadvantage of this approach is that it increases the size of each chunk. Whether that matters depends on the size of the ToC, the relative size of the chunks, bandwidth and other constraints.

If chunking is not being used, there will only be one HTML result and the ToC will always be stored in that chunk.

2.12.3. On-page table of contents

Documents come in many shapes and sizes. Consequently, there are a variety of navigation mechanisms available. For long documents, such as books, a Table of Contents (ToC) is traditional (as are indexes). For web presentation, long documents may be broken into chunks, for example at the chapter level. In this case, header and footer navigation between chunks is almost always available. For large documents a “persistent ToC” can enable quick navigation from any chunk.

You can also enable an on-page ToC. The on-page ToC provides a navigation mechanism for sections within a page. By default, it appears on the right of the page if the window is wide enough to comfortably display it next to the main body.

The current implementation requires JavaScript. In fact it is not constructed from the DocBook markup, but instead from the HTML markup when the page is rendered. To be precise, the ToC is constructed from HTML section elements that begin with a header that contains an h1…h6 element. It is therefore either a bug or a feature, depending on your perspective, that a customization layer that changes how sections are marked up will change what appears in the ToC. If you simply wish to suppress a particular section from appearing in the ToC, add nopagetoc to its class attribute.

Several parameters control presentation and formatting of the on-page ToC.

$pagetoc-elements

A list of the names of the elements (technically, the classes of the sections) that should get an on-page ToC. It’s empty by default (meaning no such ToC is rendered). For the standard presentation of this guide, the list is set to preface chapter appendix refentry. (The sneaky among you may wonder if you could simply set it to “component” because that class is used for all those elements; “Yes. Yes, you could.”)

$pagetoc-dynamic

Determines whether or not the ToC is “dynamic”. Inspired by Kevin Drum’s table of contents progress animation, the ToC keeps track of the reader’s location in the main view and highlights the corresponding sections in the ToC (albeit without the clever SVG animation of the original).

Set this parameter to false if you find the animation distracting. (If the animation is enabled, a control is provided to let the reader turn it off, in case they find it distracting.)

$pagetoc-js

This is the JavaScript that implements the on-page ToC. Changing this parameter allows you to replace it with JavaScript of your own invention.

CSS

There is no pagetoc-css parameter; the CSS is integrated into the standard CSS. You can find it in the pagetoc.scss file in the repository if you want to change the presentation. (Don’t change that file, simply add overriding rules later in the cascade.)

There is also a JavaScript API that you can use to control some features of the presentation. This is done by adding a DocBook property to the browser’s window object. The value of the DocBook property should be a map. To control the on-page ToC, add a pagetoc property to the DocBook map. The value of this property must also be a map.

The properties of the pagetoc map can be used to change the display:

decorated

This is the markup used for the user-control on the on-page ToC when the ToC is decorated. The default value is “☀”.

plain

This is the markup used for the user-control on the on-page ToC when the ToC is plain (not decorated). The default value is “￮”.

hidden

This is the markup used for the user-control on the on-page ToC when the ToC is hidden. The default value is “◄”.

nothing_to_reveal

This property controls how the on-page ToC is rendered if there are no additional sections to be revealed. It can have the value “hide”, to hide the ToC, “plain” to make its presentation plain in this case, or “decorated” to use the decorated style. The ToC will not appear if there are no sections.

To use the JavaScript API, make sure your assignments to the DocBook object are performed before the on-page ToC JavaScript is executed.

2.13. Paged-media (print output)

Formatters, the tools that turn markup of any sort into aesthetically pleasing (or even passably acceptable) printed pages are fiendishly difficult to write.

In the XML space, there have been a number of standards and vendor-specific solutions to this problem. The current standards are XSL FO and CSS.

At present, the DocBook xslTNG Stylesheets are focused on CSS for print output. There’s a customization layer that produces “paged-media-ready” HTML that can be processed with a CSS formatter such as Antenna House or Prince.

To get print output, format your documents with the print.xsl stylesheet instead of the docbook.xsl stylesheet. The additional cleanup provided by print.xsl assures that footnotes, annotations, and other elements will appear in the right place, and with reasonable presentation, in the printed version.

The resulting HTML document can be formatted directly with a CSS paged-media formatter.

2.13.1. Landscape orientation

The default orientation for pages in print output is portrait. The stylesheets support a simple mechanism for selecting landscape pages. This works in many common cases, but you may need additional CSS if you have complex requirements.

ⓘ

Note

This feature enables whole pages with a landscape orientation. It doesn’t support rotating a single block element (paragraph, table, figure, etc.) to lanscape orientation within an otherwise portrait page. If you rotate a single block element, it will introduce a page break before and after the element.

Rotations within an otherwise portrait page might be possible with custom CSS, depending on your formatting engine.

The stylesheets slightly abuse the role attribute (which is multi-valued) for this purpose. Placing the token landscape in the role attribute will select lanscape orientation for the element on which the role attribute appears. (Placing the token portrait in the role attribute will select portrait orientation in an otherwise landscape document.)

This may apply to the whole book or article, or to individual chapter, section or appendix elements.

You can also print individual tables or figures in landscape, if they are too wide for portrait pages. For wide tables, you should use the orient attribute with the value land, because it is provided precisely for this purpose. However, in the interests of a uniform solution, the role attribute with the value landscape can also be used for tables.

For legacy reasons, the landscapeFigure processing instruction from the XSLT 1.0 stylesheets is also supported for figure and informalfigure elements, as described in Chapter 18 of Bob Staytons Complete Guide.

2.13.1.1. AntennaHouse extensions

The rotation mechanism supported by standard CSS rotates the entire page, including any running headers and footers. For documents that are read online, this has some real advantages as the PDF viewer is likely to show the landscape pages “the right way up”.

But for documents that are going to be printed, or where a more traditional presentation is desirable, the goal is usually to rotate the content of the page, but not the page itself.

This can be accomplished with the AntennaHouse formatter using the $vendor-css extension. In an otherwise portrait document, including the vendor-ahf-portrait.css file using $vendor-css will present landscape rotations in the portrait page. If the document is being printed on landscape pages, including the vendor-ahf-landscape.css file using $vendor-css will present portrait rotations in the landscape page.

2.14. EPUB output

The DocBook xslTNG Stylesheets will produce output designed for EPUB(3) if you use the epub.xsl stylesheet instead of docbook.xsl. This is new in version 1.11.0 and may be incomplete. The output conforms to EPUBCheck version 3.2.

Producing an EPUB file is a slightly complicated process. You must produce (X)HTML that conforms to strict requirements, you must produce a media type document containing a specific text string, you must produce a manifest that identifies all of the content including all the images, stylesheets, fonts, etc, and you must finally create a ZIP archive (with some special consideration as well).

The stylesheets can only do part of this process. In some future release where we use, for example, an XProc 3.0 pipeline, it may be practical to do more.

When you run the EPUB stylesheet, the principle result document is the media type document. This has two useful side effects: first, it establishes the output base URI from which all the relative documents can be created, and second, if you fail to process some element in the input, you’re likely to get extra text characters in the principle result document. That will cause tools to reject the EPUB and draw your attention to the error.

The stylesheets also produce the META-INF files and the OPS directory containing the document parts and the manifest.

There are two parameters specific to EPUB:

pub-id

This is the unique identifier for your EPUB. If you don’t specify one, a random one will be generated for you.

manifest-extra

This is a URI. If it’s specified, then it must be an XML document and that will be added to the EPUB manifest. This is how you can add links to media and other resources that the stylesheets don’t know about.

2.14.1. Adding metadata

You can add elements to the info element of the root element of your document to add metadata to your EPUB files. Elements in the Dublin Core namespace will be copied through. You can also add the elements meta and link in the special namespace http://docbook.org/ns/docbook/epub.

2.14.2. EPUB in action

The Getting Started project has been updated to show how to create EPUB from a book. The project has support for dealing with external media, fonts, and constructing the final ZIP file.

2.15. Ad hoc CSS styling

Generally speaking, it’s considered good practice to separate content from presentation. On the web, this is most often accomplished with clean, structural HTML as the content and CSS styling providing the presentation. Indeed, that’s how the output from the DocBook xslTNG Stylesheets is structured.

And yet, sometimes you need to tweak individual elements in small ways. For example, you may want to change the style of a single programlisting to avoid a page break inside it. Or perhaps you need to make some adjustment to a single image.

In principle, this can be done in a completely “hands off” manner: add an ID to the element and add an ID selector to the external CSS file. In practice, that’s a bit tedious and there’s nothing in the source to suggest that the styling is required or even exists.

HTML allows for inline styles with the style attribute and starting in version 2.1.5, the xslTNG stylesheets provide a way to access this feature.

DocBook allows namespace qualified attributes on any element. Adding attributes in the https://xsltng.docbook.org/ns/css namespace to an element will add those properties to the HTML style attribute. For example:

  |<para xmlns:css="https://xsltng.docbook.org/ns/css"
  |      css:border="1px solid blue" css:border-radius="0.5em"
  |      css:padding="0.5em">This
  |is a paragraph with a border.</para>

Will be rendered as you expect:

This is a paragraph with a border.

The generated HTML wraps up the CSS properties in a style attribute:

  |<p style="padding:0.5em;border:1px solid blue;border-radius:0.5em;"
  |>This is a pargraph with a border.</p>

To facilitate different properties based on the output medium, the stylesheets will also look for attributes in the “https://xsltng.docbook.org/ns/css#$output-media” namespace. For example, this paragraph:

1 |<para xmlns:p-css="https://xsltng.docbook.org/ns/css#print"
  |      xmlns:css="https://xsltng.docbook.org/ns/css"
  |      css:background-color="#ffaaaa"
  |      p-css:background-color="#bbbbbb">This paragraph
5 |has a background color.
  |</para>

Will be rendered with a pinkish background online and with a grey background in print:

This paragraph has a background color.

By default, the stylesheets set $output-media to screen for “ordinary output”, epub for EPUB, and print for paged media.

2.16. Responsive images

Starting in version 2.7.6, you can encode information about responsive images in DocBook. HTML “responsive images” are a technique where several images are grouped together with additional metadata about the circumstances when they are intended to be used (media queries on the environment and resolution, for example). Here’s what they look like in HTML:

1 |<picture class="imageobject">
  |   <source media="(min-width: 40em)"
  |           srcset="media/duck.png 1x, media/duck2x.png 2x"
  |           type="image/png"/>
5 |   <source srcset="media/duck-lr.png 1x, media/duck-lr2x.png 2x" type="image/png"/>
  |   <img src="media/duck-small.png"/>
  |</picture>

Broadly, that defines two sets of images, one for wide displays and one for narrow displays. Within each set of images there are “low res” (1x) and “high res” (2x) versions. Finally, there’s a fallback img to use if the responsive images markup isn’t recognized or there are no available choices.

In DocBook, rather than attempt to impose more complicated markup on media objects, we use multimediaparam elements to provide additional metadata. The HTML above was created from this DocBook markup:

 1 |<mediaobject>
   |  <imageobject>
   |    <imagedata fileref="../media/duck.png">
   |      <multimediaparam name="media" value="(min-width: 40em)"/>
 5 |      <multimediaparam name="pixeldensity" value="1"/>
   |    </imagedata>
   |    <imagedata fileref="../media/duck2x.png">
   |      <multimediaparam name="media" value="(min-width: 40em)"/>
   |      <multimediaparam name="pixeldensity" value="2"/>
10 |    </imagedata>
   |    <imagedata fileref="../media/duck-lr.png">
   |      <multimediaparam name="pixeldensity" value="1"/>
   |    </imagedata>
   |    <imagedata fileref="../media/duck-lr2x.png">
15 |      <multimediaparam name="pixeldensity" value="2"/>
   |    </imagedata>
   |    <imagedata fileref="../media/duck-small.png"/>
   |  </imageobject>
   |</mediaobject>

The stylesheets attempt to group alternatives based on the media and pixeldensity parameters.

It’s possible that there are more sophisticated uses of responsive images that can’t be entirely supported this way. Please open an issue if you find yourself in that situation.

2.17. CALS tables

CALS tables are handled in two stages†: first, the structure of the table is analyzed and made explicit in the markup, then the HTML is generated from that explicit markup. This greatly simplifies the HTML generation and, equally, simplifies generation of any other kind of markup from the table structure.

In order to keep the resulting table markup valid, several attributes are added in the “ghost” namespace (http://docbook.org/ns/docbook/ghost"). The following example illustrates how this works. The input is a small, if slightly complicated, CALS table:

 1 |<informaltable xmlns="http://docbook.org/ns/docbook"
   |               version="5.0" frame="all">
   |  <tgroup cols="4" colsep="1" rowsep="1">
   |    <colspec colnum="2" colname="cb"/>
 5 |    <colspec colname="cc"/>
   |    <colspec colname="cd" align="char"/>
   |    <?db align-char-width="2"?>
   |    <spanspec spanname="btoc" namest="cb" nameend="cc"/>
   |    <thead>
10 |      <colspec colnum="2" colname="hcb" colsep="0"/>
   |      <row>
   |        <entry>A</entry>
   |        <entry>B</entry>
   |        <entry>C</entry>
15 |        <entry>D</entry>
   |      </row>
   |    </thead>
   |    <tbody>
   |      <row>
20 |        <entry>a1</entry>
   |        <entry namest="cd">1</entry>
   |      </row>
   |      <row>
   |        <entry>a2</entry>
25 |        <entry spanname="btoc" morerows="1">b2/c2 b3/c3</entry>
   |      </row>
   |      <row>
   |        <entry morerows="1">a3/a4</entry>
   |        <entry namest="cd">3.14</entry>
30 |      </row>
   |      <row>
   |        <entry>b4</entry>
   |        <entry>c4</entry>
   |        <entry>102.7</entry>
35 |      </row>
   |    </tbody>
   |  </tgroup>
   |</informaltable>

This table has horizontal and vertical spans and a couple of missing cells. There are also a couple of simple examples of inheritance of row and column separators and “char” alignment. In the interest of simplicity, this example doesn’t attempt to illustrate all, or even very many, of the ways that values are inherited.

The intent is a table that looks like this:

A | B | C | D   
a1 |  |  | 1   
a2 | b2/c2 b3/c3 |
a3/a4 | 3.14
b4 | c4 | 102.7 

The result of the first stage of processing is a table that’s similar to the original, but with inherited and computed values made explicit.

ⓘ

Note

Although the structure is explicit, there is still some work to be done in the second stage to identify which cells should have borders and where. That depends on the placement of the cell with respect to the edge of the table itself and the table section (head, foot, body), as well as the value of the table frame attribute and perhaps the table style.

All of the entries have an explicit column number and all of the attributes that can be inherited are explicitly present on each entry. A few additional attributes, as well as attributes that aren’t allowed on an entry, are in the “ghost” namespace. Using the ghost namespace assures that the table model is still valid after the first stage of processing.

After the first stage, the table above looks like this:

 1 |<tgroup xmlns="http://docbook.org/ns/docbook"
   |        xmlns:g="http://docbook.org/ns/docbook/ghost"
   |        cols="4"
   |        colsep="1"
 5 |        rowsep="1"
   |        g:preprocessed="true">
   |   <colspec colnum="1" colsep="1" rowsep="1" g:inserted="true"/>
   |   <colspec colnum="2" colname="cb" colsep="1" rowsep="1"/>
   |   <colspec colnum="3" colname="cc" colsep="1" rowsep="1"/>
10 |   <colspec colnum="4"
   |            colname="cd"
   |            align="char"
   |            colsep="1"
   |            rowsep="1"
15 |            g:align-char-width="2"/>
   |   <spanspec spanname="btoc"
   |             namest="cb"
   |             nameend="cc"
   |             colsep="1"
20 |             rowsep="1"
   |             g:col="2"
   |             g:colend="3"/>
   |   <thead>
   |      <colspec colnum="1" colsep="1" rowsep="1" g:inserted="true"/>
25 |      <colspec colnum="2" colname="hcb" colsep="0" rowsep="1"/>
   |      <colspec colnum="3" colname="cc" colsep="1" rowsep="1"/>
   |      <colspec colnum="4"
   |               colname="cd"
   |               align="char"
30 |               colsep="1"
   |               rowsep="1"
   |               g:align-char-width="2"/>
   |      <row>
   |         <entry colsep="1" rowsep="1" g:col="1">A</entry>
35 |         <entry colsep="0" rowsep="1" g:col="2">B</entry>
   |         <entry colsep="1" rowsep="1" g:col="3">C</entry>
   |         <entry align="right" colsep="1" rowsep="1" g:col="4" g:char=".">D   </entry>
   |      </row>
   |   </thead>
40 |   <tbody>
   |      <row>
   |         <entry colsep="1" rowsep="1" g:col="1">a1</entry>
   |         <entry g:col="2" g:inserted="true" colsep="1" rowsep="1"/>
   |         <entry g:col="3" g:inserted="true" colsep="1" rowsep="1"/>
45 |         <entry namest="cd"
   |                align="right"
   |                colsep="1"
   |                rowsep="1"
   |                g:col="4"
50 |                g:char=".">1   </entry>
   |      </row>
   |      <row>
   |         <entry colsep="1" rowsep="1" g:col="1">a2</entry>
   |         <entry spanname="btoc"
55 |                morerows="1"
   |                colsep="1"
   |                rowsep="1"
   |                g:col="2"
   |                g:colend="3"
60 |                g:colspan="2"
   |                g:rowspan="2"
   |                g:following-covered-cells="1">b2/c2 b3/c3</entry>
   |         <entry g:col="4"
   |                g:inserted="true"
65 |                align="char"
   |                colsep="1"
   |                rowsep="1"
   |                g:align-char-width="2"/>
   |      </row>
70 |      <row>
   |         <entry morerows="1"
   |                colsep="1"
   |                rowsep="1"
   |                g:col="1"
75 |                g:rowspan="2"
   |                g:following-covered-cells="2">a3/a4</entry>
   |         <entry namest="cd"
   |                align="right"
   |                colsep="1"
80 |                rowsep="1"
   |                g:align-char-width="2"
   |                g:col="4"
   |                g:char=".">3.14</entry>
   |      </row>
85 |      <row>
   |         <entry colsep="1" rowsep="1" g:col="2" g:preceding-covered-cells="1">b4</entry>
   |         <entry colsep="1" rowsep="1" g:col="3">c4</entry>
   |         <entry align="right" colsep="1" rowsep="1" g:col="4" g:char=".">102.7 </entry>
   |      </row>
90 |   </tbody>
   |</tgroup>

The colspec and spanspec elements are preserved, although second stage processing does not need them. Every element’s column is identified with a g:col attribute. In spanning entries, the last colum is identified with a g:colend attribute. Spanning elements also have either (or both) of g:colspan and g:rowspan describing how many columns and rows are spanned, respectively.

On a row where some cells are covered by horizontal or vertical spans, the number of preceding or following covered cells is indicated with the g:preceding-covered-cells and g:following-covered-cells attributes, respectively. Identifying following cells is preferred, so preceding cells are only identified when they precede the first uncovered cell. (No table row may be completely empty, so there will always be at least one entry on which the attributes can be specified.)

2.17.1. Char alignment

Alignment on a character is now handled by the preprocessing step. The alignment value will be changed from char to right and the cell will be padded such that the alignment is correct.

The attribute g:char containing the alignment character is added to the entry so that subsequent processing can identify which cells were char aligned.

The $align-char-processing parameter controls whether or not this processing is performed.

*

In other words, if you have two different documents that use the same key name and you attempt to view them simultanously on synchronized windows, you’ll get a tangled mess.

†

Starting with DocBook xslTNG Stylesheets version 2.8.0.

Chapter 3. Customizing the stylesheets

In many circumstances, the stylesheets can be used “out of the box” without any customization. But sometimes you may need to change the formatting of certain elements. One common reason is to change the formatting of title pages or navigational features. In other cases, it may be to support local extensions to DocBook or simply to change the markup to support a particular use case.

Three approaches are possible, with increasing degrees of effort: changing stylesheet parameters, creating your own customization layer, or making broader changes to the stylesheet’s implementation.

The subject of broader implementation changes is the subject of Chapter 5, Implementation details. In this chapter, we’ll look at the easier options.

3.1. Changing stylesheet parameters

The DocBook xslTNG Stylesheets define a lot of parameters. They are all described in I. Parameter reference. If the change you want to make has already been parameterized, you may be able to achieve your goal simply by setting a parameter at runtime.

For example, if you want to change the formatting of dates and times in date elements, you can simply change the date and time formatting parameters. Similarly, if you want to change the numeration style of ordered lists, you can simply change the ordered list item numeration parameter.

These changes can be accomplished by simply passing the new values to the processor, on the command line or in a configuration file, for example. You do not have to write any XSLT to make these changes.

Parameter values apply to the entire document processed by the stylesheets. In some cases, you may wish to change the presentation of just one or small number of elements. This can often be accomplished with a db processing instruction in the source document itself. These customizations can also be accomplished without writing any XSLT.

If you want to make a change that isn’t supported by a parameter, or an ad hoc exception that doesn’t have a supporting processing instruction, you will have to write a customization layer. (You are invited to submit an issue with your use case if you think it would be of general interest.)

You may also find it convenient to write a customization layer if you want to change several parameters and you find it inconvenient to pass them all to the processor on every invocation.

3.2. Creating a customization layer

A customization layer is simply an XSLT stylesheet that you write which extends the DocBook stylesheets. The simplest* customization layer is:

 1 |<?xml version="1.0" encoding="utf-8"?>
   |<xsl:stylesheet
   |    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   |    xmlns:db="http://docbook.org/ns/docbook"
 5 |    xmlns:xs="http://www.w3.org/2001/XMLSchema"
   |    xmlns="http://www.w3.org/1999/xhtml"
   |    exclude-result-prefixes="db xs"
   |    version="3.0">
   |
10 |<!-- This href has to point to your local copy
   |     of the stylesheets. -->
   |<xsl:import href="docbook/xslt/docbook.xsl"/>
   |
   |</xsl:stylesheet>

This customization doesn’t do anything. But you can, for example, redefine parameters if you wish:

 1 |<?xml version="1.0" encoding="utf-8"?>
   |<xsl:stylesheet
   |    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   |    xmlns:db="http://docbook.org/ns/docbook"
 5 |    xmlns:xs="http://www.w3.org/2001/XMLSchema"
   |    xmlns="http://www.w3.org/1999/xhtml"
   |    exclude-result-prefixes="db xs"
   |    version="3.0">
   |
10 |<xsl:import href="docbook/xslt/docbook.xsl"/>
   |
   |<xsl:param name="orderedlist-item-numeration"
   |           select="'1'"/>
   |
15 |<xsl:param name="date-dateTime-format"
   |           select="'[D01] [MNn,*-3] [Y0001]
   |                   at [H01]:[m01]'"/>
   |
   |</xsl:stylesheet>

This will have the effect of running the DocBook stylesheets with those two parameters set as specified.

If you want to change the HTML output for an element, you can write a template for that element in your customization layer. Consider this DocBook document:

 1 |<?xml version="1.0" encoding="utf-8"?>
   |<article xmlns="http://docbook.org/ns/docbook"
   |         version="5.1">
   |<info>
 5 |<title>Sample Document</title>
   |<date>2020-07-05</date>
   |</info>
   |
   |<para>This is a sample <productname>DocBook</productname>
10 |document.</para>
   |
   |</article>

Suppose that you decided you wanted to have the productname element link automatically to the vendor webpage.

☝

Important

The DocBook xslTNG Stylesheets process all DocBook elements in the m:docbook mode. This is different from previous XSLT stylesheets for DocBook which simply used the default mode.

You must either specify a default mode in your customization layer or remember to specify the mode on match templates and template applications. If you forget the mode, you’ll get unexpected results!

One way to do that would be to redefine the template that processes the productname element:

 1 |<?xml version="1.0" encoding="utf-8"?>
   |<xsl:stylesheet
   |    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   |    xmlns:db="http://docbook.org/ns/docbook"
 5 |    xmlns:m="http://docbook.org/ns/docbook/modes"  ①
   |    xmlns:xs="http://www.w3.org/2001/XMLSchema"
   |    xmlns="http://www.w3.org/1999/xhtml"
   |    exclude-result-prefixes="db m xs"  ②
   |    version="3.0">
10 |
   |<xsl:import href="docbook/xslt/docbook.xsl"/>
   |
   |<xsl:param name="orderedlist-item-numeration"
   |           select="'1'"/>
15 |
   |<xsl:param name="date-dateTime-format"
   |           select="'[D01] [MNn,*-3] [Y0001]
   |                   at [H01]:[m01]'"/>
   |
20 |<xsl:template match="db:productname"
   |              mode="m:docbook">  ③
   |  <xsl:variable name="name"
   |                select="normalize-space(.)"/>
   |④
25 |  <xsl:variable name="url" as="xs:string?">
   |    <xsl:choose>
   |      <xsl:when test="$name='DocBook'">
   |        <xsl:sequence select="'https://docbook.org/'"/>
   |      </xsl:when>
30 |      <xsl:when test="$name='DocBook xslTNG Stylesheets'">
   |        <xsl:sequence select="'https://xsltng.docbook.org/'"/>
   |      </xsl:when>
   |      <xsl:when test="$name='Wikipedia'">
   |        <xsl:sequence select="'https://wikipedia.org/'"/>
35 |      </xsl:when>
   |      <xsl:otherwise>
   |        <!-- Unrecognized -->
   |      </xsl:otherwise>
   |    </xsl:choose>
40 |  </xsl:variable>
   |
   |  <xsl:choose>
   |    <xsl:when test="empty($url)">
   |      <xsl:next-match/>  ⑤
45 |    </xsl:when>
   |    <xsl:otherwise>
   |      <a href="{$url}" title="Home page">
   |        <xsl:next-match/>  ⑤
   |      </a>
50 |    </xsl:otherwise>
   |  </xsl:choose>
   |</xsl:template>
   |
   |</xsl:stylesheet>

①

All of the DocBook elements are processed in the “m:docbook” mode.

②

Remember to exclude all the namespaces you declare so that they don’t wind up scattered about in your HTML.

③

I repeat, all of the DocBook elements are processed in the “m:docbook” mode. I expect that failure to declare this mode is going to be a common error.

④

Yes, this whole listing is rather cramped. I’m trying to make it all narrow enough to fit in the display without making horizontal scrolling necessary.

⑤

Calling xsl:next-match invokes the underlying processing. The effect of this template is to wrap an HTML “a” around the default processing for productname.

It’s worth pointing out that if the tag has an xlink:href attribute, that will generate an HTML a as well. A more robust stylesheet would check for that, but I’m trying to keep the example simple.

3.3. Managing CSS stylesheets

The HTML that the DocBook xslTNG stylesheets produce is intended to be clean, robust markup for styling with CSS. Exactly how you control which stylesheet links are produced has changed several times. The current scheme is this:

If syntax highlighting is enabled, a link to the $verbatim-syntax-highlight-css stylesheet is included.

If $persistent-toc is true a link to the $persistent-toc-css stylesheet is included.

If $use-docbook-css is true, links to the standard DocBook stylesheets are included. Those stylesheets are docbook.css (for all media), docbook-screen.css (for screen media), and docbook-page-setup.css and docbook-paged.css (for print media).

The DocBook element that is the context element when the HTML head is being generated is processed in the m:html-head-links mode. By default, that template does nothing, but you can change that in a customization layer.

If any CSS stylesheets are defined in $user-css-links, they are included.

The DocBook element that is the context element when the HTML head is being generated is processed in the m:html-head-last mode. By default, that template does nothing, but you can change that in a customization layer.

3.4. Customizing title pages

All of the titled elements (books, chapters, sections, etc.) have “title pages”. That is, they have a header element that contains the elements from the info that should be presented in the title header. In practice, info is a wrapper for general metadata about the element and often contains many elements that shouldn’t be presented.

There’s so much variation both in what goes in the info elements and in what users need to have in the title header, that there’s no practical way to control it simply with stylesheet parameters.

Instead the stylesheets offer two customization mechanisms: first, each header is formed from a header template. You can change the titlepage template in your customization layer.

For example, the default titlepage template for chapter headers is:

1 |<header>
  |  <tmp:apply-templates select="db:title">
  |    <h2><tmp:content/></h2>
  |  </tmp:apply-templates>
5 |  <tmp:apply-templates select="db:subtitle">
  |    <h3><tmp:content/></h3>
  |  </tmp:apply-templates>
  |</header>

The tmp:apply-templates elements aren’t as sophisticated as XSLT templates, but they let you select parts of the document. If nothing is selected, the content is ignored. When the title page template is evaluated, the context item is the info element.

Inside the tmp:apply-templates, you can decide what HTML markup should appear. The tmp:content element will be replaced by the result of processing the element or elements you selected.

As a consequence of that template, a chapter title page contains the chapter title in an h2 and the subtitle in an h3. No other elements in the info are presented.

Suppose you are writing a book where each chapter has a different author. You can add the authors to the chapter title page by updating the template in your customization layer. The stylesheets contain a $v:templates variable for this purpose. Any templates that you put inside it will be used before the default templates.

 1 |<xsl:variable name="v:templates" as="document-node()"
   |              xmlns:v="http://docbook.org/ns/docbook/variables">
   |  <xsl:document xmlns:tmp="http://docbook.org/ns/docbook/templates"
   |                xmlns:db="http://docbook.org/ns/docbook"
 5 |                xmlns="http://www.w3.org/1999/xhtml">
   |    <db:chapter context="parent::db:book">
   |      <header>
   |        <tmp:apply-templates select="db:title">
   |          <h2><tmp:content/></h2>
10 |        </tmp:apply-templates>
   |        <tmp:apply-templates select="db:subtitle">
   |          <h3><tmp:content/></h3>
   |        </tmp:apply-templates>
   |        <tmp:apply-templates select="db:author">
15 |          <h3 class="author">
   |            <tmp:content/>
   |          </h3>
   |        </tmp:apply-templates>
   |      </header>
20 |    </db:chapter>
   |  </xsl:document>
   |</xsl:variable>

With that customization, a chapter title page contains the chapter title in an h2 and the subtitle and authors in h3 elements, in that order. If you change the order of the tmp:apply-template elements, the order of the elements in the header will change.

Another common requirement is to put a graphic on the title page of a book. Here’s how you might do that. (This example appears in the test suite as test book.014.xml.) Add the cover to your info element:

 1 |<book xmlns="http://docbook.org/ns/docbook" version="5.2">
   |<info>
   |  <title>Unit Test: book.014</title>
   |  <cover>
 5 |    <mediaobject>
   |      <imageobject>
   |        <imagedata fileref="../media/yoyodyne.png"/>
   |      </imageobject>
   |    </mediaobject>
10 |  </cover>
   |  <editor>
   |    <personname>
   |      <firstname>Norman</firstname>
   |      <surname>Walsh</surname>
15 |    </personname>
   |    <email>ndw@nwalsh.com</email>
   |  </editor>
   |</info>
   |…
20 |</book>

Then decide how you want that graphic in the header with a new book template:

 1 |<xsl:variable name="v:templates" as="document-node()"
   |              xmlns:v="http://docbook.org/ns/docbook/variables">
   |  <xsl:document xmlns:tmp="http://docbook.org/ns/docbook/templates"
   |                xmlns:db="http://docbook.org/ns/docbook"
 5 |                xmlns="http://www.w3.org/1999/xhtml">
   |    <db:book>
   |      <header>
   |        <tmp:apply-templates select="db:cover/db:mediaobject">
   |          <div class="cover">
10 |            <tmp:content/>
   |          </div>
   |        </tmp:apply-templates>
   |        <tmp:apply-templates select="db:title">
   |          <h1><tmp:content/></h1>
15 |        </tmp:apply-templates>
   |        <tmp:apply-templates select="db:editor">
   |          <div class="editor">
   |            <h3><tmp:content/></h3>
   |          </div>
20 |        </tmp:apply-templates>
   |      </header>
   |    </db:book>
   |  </xsl:document>
   |</xsl:variable>

This template will output the cover image, then the title, then the editor. If you want to update multiple templates, put them all in the same $v:templates element as siblings.

Once you’ve output the elements in the header, you can use CSS to customize their appearance further.

You can get a long way just by updating the title page templates, but not always far enough. If you can’t achieve what you need by changing a template, you can take full control.

Each element generates its title page with the m:generate-titlepage mode. If you add a template in that mode to your customization layer, it has complete freedom to generate a custom title page.

Here, for example, is a book title page template:

1 |<xsl:template match="db:book" mode="m:generate-titlepage">
  |  <header>
  |    <h1>
  |      <xsl:apply-templates select="db:info/db:title" mode="m:titlepage"/>
5 |    </h1>
  |    <p>Hello, world</p>
  |  </header>
  |</xsl:template>

With this XSLT template in your customization layer, the book title page will consist of the title in an h1 and the phrase “Hello, world” in a paragraph. In this case, the context item for the XSLT template is the main element, not its info child. But it will always have an info child, even if your original document didn’t have a wrapper around the titlepage metadata.

3.5. Managing media

References to external media through imagedata, videodata, audiodata, and even textdata can be tricky to manage. On the one hand, it’s most convenient if the URIs in the source documents point to the actual media files. This allows extensions, like the image properties extension function, to access the files. At the same time, the references generated in the HTML have to point to the locations where they will be published. It is often, but not always, the case that the authoring structures and the publishing structures are the same.

The stylesheets are regularly tested against five possible arrangements: three where the media are stored in locations relative to the XML files and two where the media are stored in a separate hierarchy. These are unimaginative named “mo-1”, “mo-2”, “mo-3”, “mo-4”, and “mo-5”. You can find them in the src/test/resources/xml hierarchy in the repository.

mo-1

All of the XML files are in a single directory, the media are in the same hierarchy. Media references in the source use relative URIs to refer to the underlying media: preface.xml refers to the “this is a test” audio clip as media/this-is-a-test.mp3.

mo-2

The XML files are in different directories (this changes the base URI of the media elements). The media are in the same hierarchy. Media references in the source use relative URIs to refer to the underlying media: front/preface.xml refers to the “this is a test” audio clip as ../media/spinning-top.mp4.

mo-3

The XML files are in different directories, but the structure is deeper. This scenario represents the case where there might be multiple books, each with their own media, but also a shared media folder “above” the book hierarchies. The media are in the same hierarchy, but some are “above” the book. Media references in the source use relative URIs to refer to the underlying media: book/front/preface.xml refers to the “this is a test” audio clip as ../../media/spinning-top.mp4.

mo-4

The XML files are still in different directories, but the significant change here is that the media are in their own hierarchy. Media references in the source use URIs relative to the root of that hierarchy: book/front/preface.xml refers to the “this is a test” audio clip as spinning-top.mp4.

mo-5

The XML files are in different directories and the media are in their own hierarchy. What’s different here is that the media hierarchy is further subdivided by media type. Media references in the source use URIs relative to the root of media hierarchy without the media type: book/front/preface.xml still refers to the “this is a test” audio clip as spinning-top.mp4, but this time it is found in media/mp4/spinning-top.mp4 rather than directly in media.

For each arrangement, we look at five possible output structures:

A single HTML document with the media in the same relative locations as the sources.

A single HTML document with the media in a single media subdirectory.

“Chunked” HTML output with the media in the same relative locations as the sources.

“Chunked” HTML output with the media in custom locations. (This is especially tricky for the “mo-5” case because there are two kinds of customization involved.)

“Chunked” HTML output with the media in a single media subdirectory.

The list below gives a brief summary of the parameters used to achieve the desired results for each combination of input and output arrangements.

ⓘ

Note

Remember that in each case, the questions are: can the stylesheets find the media files to query them and are the correct HTML references produced? Actually copying the media files from where they are in the source system to where they need to be in the HTML is “not our problem.”

mo-1, mo-2, and mo-3 / scenario 1

No parameters are needed, this combination works correctly with the defaults.

mo-1, mo-2, and mo-3 / scenario 2

mediaobject-output-base-uri = "media/"
mediaobject-output-paths = "false"

The output base URI is relative to the “root” of the HTML result. Setting the output paths to “false” removes intermediate hierarchy from the image references.

mo-1, mo-2, and mo-3 / scenario 3

chunk = "index.html"
chunk-output-base-uri = "/path/to/output/location/"

These parameters aren’t related to media objects, they just tell the stylesheets how and where to “chunk” the output.

mo-1, mo-2, and mo-3 / scenario 4

chunk = "index.html"
chunk-output-base-uri = "/path/to/output/location/"

This combination is really the same as the previous except that it uses a custom stylesheet with a template in the m:mediaobject-output-adjust mode to add an extra level of hierarchy to the output URIs. This is just an example of arbitrary, custom processing.

mo-1, mo-2, and mo-3 / scenario 5

chunk = "index.html"
chunk-output-base-uri = "/path/to/output/location/"
mediaobject-output-base-uri = "media/"
mediaobject-output-paths = "false"

The output base URI is relative to the “root” of the HTML result. Setting the output paths to “false” removes intermediate hierarchy from the image references.

mo-4 / scenario 1

mediaobject-input-base-uri = "../media/"

The input base URI will be made absolute relative to the base URI of the input document, so it’s often convenient to specify it as a relative URI. It’s equally possible to specify it as an absolute URI.

mo-4 / scenario 2

mediaobject-input-base-uri = "../media/"
mediaobject-output-base-uri = "media/"
mediaobject-output-paths = "true"

This example has two images with the same name in different directories, so it’s necessary to preserve the output paths.

mo-4 / scenario 3

chunk = "index.html"
chunk-output-base-uri = "/path/to/output/location/"
mediaobject-input-base-uri = "../media/"

This is the combination of chunking and a single media directory.

mo-4 / scenario 4

chunk = "index.html"
chunk-output-base-uri = "/path/to/output/location/"
mediaobject-input-base-uri = "../media/"

This combination is really the same as the previous except that it uses a custom stylesheet with a template in the m:mediaobject-output-adjust mode to add an extra level of hierarchy to the output URIs. This is just an example of arbitrary, custom processing.

mo-4 / scenario 5

chunk = "index.html"
chunk-output-base-uri = "/path/to/output/location/"
mediaobject-input-base-uri = "../media/"
mediaobject-output-base-uri = "media/"
mediaobject-output-paths = "true"

This is effectively scenario 2 with chunking.

mo-5 / scenarios 1-5

The “mo-5” scenarios are all the same as the “mo-4” scenarios with the addition of one more parameter:

mediaobject-grouped-by-type = "true"

In each case, this adds the extra “media object type” level to the URI path.

If you download the source repository, you can see these combinations in action with the build targets “mo_number_test_scenario”, for example, run:

./gradlew mo_3_test_2

to see the results of processing “mo-3” in scenario 2. The output will be in the build/actual directory. The build target all_mo_tests will run them all.

3.6. Controlling numeration

Numeration refers to the process(es) by which sets, books, divisions, components, sections, and formal objects are numbered. There are three separate aspects to numeration: what’s numbered, where does numbering begin, and does the number inherit from its ancestors.

Consider this book:

 1 |<book>
   |  <title>Book title</title>
   |  <part>
   |    <title>Part title</title>
 5 |    <chapter>
   |      <title>Chapter title</title>
   |      <para>…</para>
   |    </chapter>
   |  </part>
10 |  <part>
   |    <title>Another part title</title>
   |    <chapter>
   |      <title>Another chapter title</title>
   |      <para>…</para>
15 |    </chapter>
   |    <chapter>
   |      <title>Yet another chapter title</title>
   |      <para>…</para>
   |    </chapter>
20 |  </part>
   |</book>

Let’s suppose that parts are numbered “I” and “II”. (The number format is controlled by the localization, see Chapter 4, Localization.) If chapter numbering begins at the book level, those chapters will be numbered “1”, “2”, and “3”. If chapter numbering begins at the division level (the part), those chapters will be numbered “1”, “1”, and “2”. If division numbers are inherited, those numbers will be “I.1”, “II.1”, “II.2”.

In the 1.x versions of these stylesheets, all of the aspects of numeration were controlled by three now obsolete parameters: $component-numbers-inherit, $division-numbers-inherit, and $section-numbers-inherit. In the 2.x stylesheets, the various aspects can be controlled independently and the result is much more consistent, if a bit more complicated.

The default numeration parameters are designed to cover the most common use cases and are specified with strings so that they’re easy to control with parameters. Any numeration scheme can be implemented with a customization layer, but hopefully that will be necessary only rarely and in uncommon cases.

To simplify the problem, we divide the DocBook elements into six categories:

sets

The set is the only member of this category.

books

The book is the only member of this category.

divisions

The divisions elements are part and reference.

components

The component elements are acknowledgements, appendix, article, bibliography, chapter, colophon, dedication, glossary, index, partintro, preface, refentry, and setindex.

sections

The section elements are section, sect1, sect2, sect3, sect4, sect5, simplesect. The refentry section elements are not included because they are not typically numbered.

formal objects

The formal objects are figure, table, example, equation, formalgroup, procedure.

There’s a bit of complexity here. A formalgroup that contains figures counts as a figure, a formalgroup that contains tables counts as a table, etc. An equation or procedure only counts as a formal object if it has a title.

Six parameters control where numbering starts (or restarts): $sets-number-from, $books-number-from, $divisions-number-from, $components-number-from, $sections-number-from, and $formal-objects-number-from. In each case, the value of the parameter must be the name of one of the categories. Sets and books can only number from sets, divisions can number from sets or books, components can number from sets, books, or divisions, etc. It is also possible to specify the value root to indicate that elements in the relevant category are numbered sequentially through the whole document.

To assure consistency, “numbering from” resets when the specified category or one of its ancestors is encountered. In other words, if you’re formatting a set of books and numbering components from divisions, the numbering resets when a new division, book, or set begins.

Six parameters control how numbers are inherited: $sets-inherit-from, $books-inherit-from, $divisions-inherit-from, $components-inherit-from, $sections-inherit-from, and $formal-objects-inherit-from. Like the “number from” parameters, each parameter takes the value of the categories above it. In this case, however, you can specify more than one category.

For example, the default value for formal objects is to inherit from “component section”. That means that the first figure in chapter 2 will be labeled “2.1” and the first figure in the first section in chapter 2 will be labeled “2.1.1”, etc. This most closely reproduces the numbering from the 1.x stylesheets.

3.6.1. Numeration overrides

Although the numeration parameters give you complete control over numeration, they aren’t simple to use. A few common cases can be handled with simpler settings: $division-numbers, $component-numbers, $section-numbers, and $formal-object-numbers. Each of these parameters is “true” by default and numeration of divisions, components, and sections is handled as described above. If these parameters are set to “false”, divisions, components, and sections, respectively, will not be numbered.

The additional parameter $use-label-numeration controls whether or not a label attribute overrides the numeration. Although the documentation has long stated that was the case, it wasn’t in fact true. The $use-label-numeration parameter is false by default for backwards compatibility.

Numbering can also be controlled on a per-element basis with the db processing instruction. If the numbered pseudo-attribute is “true”, the division, component, or section in which that processing instruction occurs, and all of its descendants, will be numbered. If it’s “false”, the element and its descendants will not be numbered.

In this way, it would be possible to have a single chapter or article with numbered sections even in a book where sections are not normally numbered.

3.7. Using glossaries

There are essentially two ways to manage glossaries: you can author them by hand, or you can compose them automatically from a collection of glossary entries.

In a glossary authored by hand, no special processing takes place. The entries appear as they are listed and every entry appears whether there is a corresponding glossary reference in the document or not. The author is free to use glossdiv elements to divide the glossary into sections and the document may have multiple glossary elements.

If you compose them from glossary collections, only the terms used in your document (in glossterm or firstterm elements) will appear in the glossary. The glossary collections can be managed internally or externally. If multiple definitions appear in the glossary collections, only the first definition is included.

The best way to explain automatic glossaries is to use an example. Let's assume that you have marked the two terms Apple and Pear as glossterms in your document. Your automatic glossary should ultimately contain exactly two entries, one for each of those terms.

Create a glossary in your document and add auto to the role attribute on the glossary element. (If you’re using automatic glossaries, there should only be one glossary element in your document.) This is the internal glossary.

Even if your internal glossary has three entries, one each for Apple, Jackfruit and Pear, you will end up with a glossary in the generated document that has only two entries. There will be no entry for Jackfruit, since there is no corresponding glossterm or firstterm in the main part of your text.

You can also use external glossaries for this task, which can be identified by the $glossary-collection parameter, or the db processing instructions with a glossary-collection pseudo-attribute in the root element.

If you use external glossaries, you can leave the internal, automatic glossary completely empty. As long as there are entries for Apple and Pear in one of your external glossaries, you will end up with those two entries in the generated glossary, even if the external glossaries contain many more terms.

You can use the internal, automatic glossary in conjunction with external glossaries. In this case, entries from the internal glossary take precedence over entries for the same term from external glossaries. Lets say you have entries for Apple and Pear among others in your external glossary, and also a glossentry for Apple in your internal glossary. In this case you will end up with a glossary which contains two entries, one for Apple, with the definition taken from the internal glossary, and one for Pear with a definition from the external glossary.

Entries will appear in the glossary in the same order as they appear in the internal and external glossaries unless they are sorted. Sorting is controlled by the $glossary-sort-entries parameter.

An automatic glossary may have glossary divisions. Those are controlled by the $glossary-automatic-divisions parameter.

3.7.1. Using Schematron to manage the glossary

Schematron rules can help manage the glossary. The f:glossentries() function (defined in standalone-functions.xsl in the xslTNG install directory) has been designed so that it can be integrated into Schematron independently of the xslTNG stylesheets. You can use it to check whether a corresponding glossentry exists for a glossterm or firstterm while you are still writing. Corresponding Schematron schemas are not yet part of the xslTNG framework. Example 3.1, however, shows how you could use schematron to check whether there is exactly one glossentry for the glossterm and firstterm elements in your document.

 1 |<schema xmlns="http://purl.oclc.org/dsdl/schematron" queryBinding="xslt2">
   |
   |①  <xsl:include xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   |    href="standalone-functions.xsl"/>
 5 |
   |   <ns uri="http://docbook.org/ns/docbook" prefix="db"/>
   |②  <ns uri="http://docbook.org/ns/docbook/functions" prefix="f"/>
   |
   |  <pattern>
10 |    <rule context="
   |        db:firstterm
   |        | db:glossterm[not(ancestor::db:glossary)]">
   |       <let name="term" value="((@baseform, .)[1])"/>
   |③      <let name="n" value="count(f:glossentries(.))"/>
15 |
   |      <report role="error" test="$n eq 0">No entry for
   |        <value-of select="$term"/> in glossary.</report>
   |
   |      <report role="warning" test="$n gt 1"><value-of select="$n"/>
20 |        entries for <value-of select="$term"/> in glossary.</report>
   |
   |    </rule>
   |  </pattern>
   |
25 |</schema>

①

Include the standalone-functions.xsl file. You have to adjust the path accordingly.

②

Provide declaration for the namespace of functions from xslTNG.

③

Use the f:glossentries() function to get the number of matching glossentry elements for the given glossterm or firstterm

Example 3.1. A Schematron schema to check glossary terms

If you want to use Schematron rules with external glossaries, it’s most convenient to use the db processing instruction to identify the external glossaries. The f:glossentries() function will load them automatically (see Example 3.2).

1 |<article xmlns="http://docbook.org/ns/docbook" version="5.0">
  |  <?db glossary-collection='resources/glosscollection.xml' ?>
  |  <title>My document</title>
  |  …
5 |</article>

Example 3.2. Pass the glossary-collection parameter to Schematron

3.8. Using bibliographies

Bibliographies are more complicated than glossaries. Bibliography entries can be “cooked” (bibliomixed) or “raw” (biblioentry) and there’s no obvious way to sort bibliography entries in the general case.

There are also two different cross-referencing mechanisms for bibliographic entries: by ID, using biblioref or xref, or with citation that matches on abbrev elements in the bibliography entry.

Consider this example bibliography:

1 |<bibliography>
  |<bibliomixed xml:id="bib.xml"><abbrev>XML</abbrev>Tim Bray,
  |Jean Paoli, …</bibliomixed>
  |
5 |<biblioentry><abbrev>MalerElAndaloussi96</abbrev>
  |  <title>Developing SGML DTDs</title> …</biblioentry>
  |</bibliography>

The first entry can be cited in two ways: <biblioref linkend="bib.xml"/> or <citation>XML</citation>. The second can only be cited with a <citation>MalerElAndaloussi96</citation> (it has no xml:id to link to).

Taking all of these variations into account, there are three ways to construct bibliographies:

Entirely by hand.

Managed by hand, with empty elements as placeholders.

Managed automatically.

There are tradeoffs to each approach.

When external bibliographies are used, they can be identified either with the $bibliography-collection parameter or with db processing instructions with a bibliography-collection pseudo-attribute in the root element.

3.8.1. Entirely by hand

In a bibliography constructed entirely by hand, no special processing takes place. The entries appear as they are listed and every entry appears whether it is cited or not. The author is free to use bibliodiv elements to divide the bibliography into sections and the document may have multiple bibliography elements.

3.8.2. Managed by hand

Bibliographic entries can be complex and may be shared across multiple documents. One approach to managing this complexity is to store the full entries in an external bibliography and use only placeholders in your actual document.

A placeholder is an empty entry with an xml:id, or an entry that contains only an abbrev (if it has both an xml:id and contains only an abbrev, the ID will be used to search for a matching entry in the external bibliography). It will be replaced by the full entry from the external bibliography when the document is formatted.

For example, if the full entries are available externally, the preceding bibliography example could be shortened to:

1 |<bibliography>
  |<bibliomixed xml:id="bib.xml"/>
  |<biblioentry><abbrev>MalerElAndaloussi96</abbrev>
  |</biblioentry>
5 |</bibliography>

The entries appear in the order listed and every entry appears whether it is cited or not. The author is free to use bibliodiv elements to divide the bibliography into sections and the document may have multiple bibliography elements.

3.8.3. Automatic

An automatic bibliography is selected by using the token auto in the role attribute on a bibliography. Placeholders can still be used, but they are unnecessary when using citation for citations.

Any citation that appear in the text will be matched to entries in the external bibliographies. Those entries will be included automatically. Automatically added entries appear at the end of the bibliography (after any internal ones, if the internal bibliography has entries), in the order that they appear in the external bibliographies. If multiple external entries match, only the first is added.

Any bibliography entries in the internal bibliography that aren’t cited will be removed.

When using the automatic style, there should be only one bibliography in the document and it cannot contain divisions.

3.9. Creating something completely different

Your input documents go through several pre-processing steps before they are rendered into HTML. If you want to produce completely different outputs, the place to start is with root template in the m:docbook mode.

Consider, for example, the task of creating a JSON version of the Table of Contents. In principle, you could write your own stylesheet to do this, but leveraging the DocBook xslTNG Stylesheets means you can make use of functions like f:generate-id() to create links.

To produce completely different results, override the root template in the m:docbook mode:

1 |<xsl:template match="/" mode="m:docbook">
  |  <xsl:document>
  |    <!-- your processing here -->
  |  </xsl:document>
5 |</xsl:template>

This template must return a document node.

Note that you can mix-and-match your processing with default processing by processing DocBook elements in the m:docbook mode.

Here is a simple example of a stylesheet that produces a JSON version of the Table of Contents for a DocBook document:

 1 |<?xml version="1.0" encoding="utf-8"?>
   |<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   |                xmlns:db="http://docbook.org/ns/docbook"
   |                xmlns:f="http://docbook.org/ns/docbook/functions"
 5 |                xmlns:m="http://docbook.org/ns/docbook/modes"
   |                xmlns:t="http://docbook.org/ns/docbook/templates"
   |                xmlns:xs="http://www.w3.org/2001/XMLSchema"
   |                xmlns="http://www.w3.org/1999/xhtml"
   |                exclude-result-prefixes="db f m t xs"
10 |                version="3.0">
   |
   |  <!-- This href has to point to your local copy
   |       of the stylesheets. -->
   |  <xsl:import href="docbook/xslt/docbook.xsl"/>
15 |
   |  <xsl:output method="text"/>
   |
   |  <!-- Suppress xslTNG's default HTML output; note that this template
   |       must return a document node.  -->
20 |  <xsl:template match="/" mode="m:docbook">
   |    <xsl:document>
   |      <xsl:apply-templates select="." mode="TOC"/>
   |    </xsl:document>
   |  </xsl:template>
25 |
   |  <!-- The templates below generate a simple JSON ToC. -->
   |
   |  <xsl:template match="/" mode="TOC">
   |    {"toc": [
30 |    <xsl:apply-templates mode="TOC"/>
   |    ]}
   |  </xsl:template>
   |
   |  <xsl:template match="db:part|db:article|db:section|db:chapter" mode="TOC"
35 |                expand-text="yes">
   |    <xsl:if test="preceding-sibling::db:part
   |                  | preceding-sibling::db:article
   |                  | preceding-sibling::db:section
   |                  | preceding-sibling::db:chapter">,&#10;</xsl:if>
40 |    {{
   |    "ref": "{f:generate-id(.)}",
   |    "title": "{normalize-space(db:info/db:title)}",
   |    "subtitle": "{normalize-space(db:info/db:subtitle)}",
   |    "items": [
45 |    <xsl:apply-templates select="db:part|db:article|db:section|db:chapter" mode="TOC"/>
   |    ]
   |    }}
   |  </xsl:template>
   |
50 |  <xsl:template match="*" mode="TOC">
   |    <xsl:apply-templates select="*" mode="TOC"/>
   |  </xsl:template>
   |</xsl:stylesheet>

ⓘ

Note

This example is meant as a starting point; it’s not robust as it only handles a few of the possible elements that might appear in a Table of Contents.

When processing documents this way, be aware that you are transforming the pre-processed, normalized versions of your input documents. For example, whether or not you put info wrappers around the titles of your sections, in the pre-processed input, titles always appear inside info wrappers. This normalization greatly simplifies processing in many places.

*

Ok, technically, this stylesheet has a couple of namespace references that aren’t strictly necessary so it could be a teeny bit simpler, but you’ll need those declarations (and more!) if you want to do anything useful.

Chapter 4. Localization

The DocBook xslTNG stylesheets support localization in more than 70 languages. At the time of this writing: Afrikaans, Albanian, Amharic, Arabic, Assamese, Asturian, Azerbaijani, Bangla, Basque, Bosnian, Bulgarian, Catalan, Chinese, Chinese (Taiwan), Chinese Simplified, Croatian, Czech, Danish, Dutch, English, Esperanto, Estonian, Finnish, French, Galician, Georgian, German, Greek, Gujarati, Hebrew, Hindi, Hungarian, Icelandic, Indian Bangla, Indonesian, Irish, Italian, Japanese, Kannada, Kirghiz, Korean, Latin, Latvian, Lithuanian, Low German, Malayalam, Marathi, Mongolian, Northern Sami, Norwegian Bokmål, Norwegian Nynorsk, Oriya, Polish, Portuguese, Portuguese (Brazil), Punjabi, Romanian, Russian, Serbian in Cyrillic script, Serbian in Latin script, Slovak, Slovenian, Spanish, Swedish, Tagalog, Tamil, Telugu, Thai, Turkish, Ukrainian, Urdu, Vietnamese, Welsh, and Xhosa.

4.1. Overview

In this context, localization mostly refers to “generated text”, words and symbols that appear in a published DocBook document that aren’t present in the original XML. Consider Figure 4.1, “Sample book source”.

 1 |<book xmlns="http://docbook.org/ns/docbook"
   |      version="5.0" xml:lang="en">
   |<info>
   |  <title>Localization Example</title>
 5 |</info>
   |<part>
   |<title>Part the first</title>
   |<chapter xml:id="chap">
   |<title>Chapter the first</title>
10 |<para>This is a tiny sample chapter.
   |See also <xref linkend="app"/>.</para>
   |</chapter>
   |</part>
   |<appendix xml:id="app">
15 |<title>An appendix</title>
   |<para>This is a tiny sample appendix.
   |See also <xref linkend="chap"/>.</para>
   |</appendix>
   |</book>

Figure 4.1. Sample book source

It might be published as shown in Figure 4.2, “Sample book (annotated)”. Here we can see examples of several different kinds of generated text.

Figure 4.2. Sample book (annotated)

The title “Table of Contents” is entirely generated; it appears nowhere in the XML. The chapter title appears in the text, but it’s labeled “1.” in the list of titles, “Chapter 1.” in the chapter itself, and “Chapter 1” (without the title) in the cross reference.

Now consider a French version of the document in Figure 4.3, “Sample book source (French)”.

 1 |<book xmlns="http://docbook.org/ns/docbook"
   |      version="5.0" xml:lang="fr">
   |<info>
   |  <title>Exemple de Localisation</title>
 5 |</info>
   |<part>
   |<title>Première partie</title>
   |<chapter xml:id="chap">
   |<title>Chapitre un</title>
10 |<para>Ceci est un petit exemple de chapitre.
   |Voir aussi <xref linkend="app"/>.</para>
   |</chapter>
   |</part>
   |<appendix xml:id="app">
15 |<title>Annexe</title>
   |<para>Ceci est un petit exemple d’annexe.
   |Voir aussi <xref linkend="chap"/>.</para>
   |</appendix>
   |</book>

Figure 4.3. Sample book source (French)

In this case, the published version will have different localization, as shown in Figure 4.4, “Sample book (French)”.

Figure 4.4. Sample book (French)

The question is, how is this accomplished? The answer, I’m afraid, is not simple.

It begins with a localization file.

4.2. Localization files

The localization files are in src/main/locale in the repository. The localization file is designed to be simple enough to edit by hand. The stylesheets use compiled versions created by processing the input locale with src/main/xslt/modules/xform-locale.xsl to produce the files in xslt/locale in the distribution.

A locale begins by defining the language it supports and providing an English language name for it. The language attribute identifies the language (in the same terms as xml:lang) to which this localization applies.

That’s followed by metadata about the file (authors, etc.), then mappings, groups, lists, and letters as shown in Figure 4.5, “Example locale file (excerpted)”. We’ll consider each section in detail below.

 1 |<locale xmlns="http://docbook.org/ns/docbook/l10n/source"
   |        xmlns:db="http://docbook.org/ns/docbook"
   |        language="en" english-language-name="English">
   |  <info>
 5 |    …
   |  </info>
   |  <mappings>
   |    <gentext key="above">above</gentext>
   |    …
10 |  </mappings>
   |  <group name="title">
   |    <template match="self::db:chapter">{chapter} %l%.%c</template>
   |    …
   |  </group>
15 |  <list name="_default">
   |    <items>%c</items>
   |    <items>%c {and} %c</items>
   |    <items>%c<repeat>, %c</repeat>, {and} %c</items>
   |  </list>
20 |  <letters>
   |    …
   |  </letters>
   |</locale>

Figure 4.5. Example locale file (excerpted)

4.2.1. Mappings

The mappings section is a simple list of key/value pairs. Each gentext element defines a key and its replacement.

1 |  <mappings>
  |    <gentext key="above">above</gentext>
  |    <gentext key="abstract">Abstract</gentext>
  |    …
5 |    <gentext key="xrefto">xref to</gentext>
  |   </mappings>

These mappings serve two purposes. For many languages, a lot of the work of defining a new localization is just updating these mappings. For a stylesheet customization layer, it provides a mechanism for remapping on an ad hoc basis.

In a localization template, any key entered in curly braces will be replaced by the mapping. In other words, for the example above, {abstract} will be replaced by the word “Abstract”. This mapping is done when the document is transformed, not when the localization file is compiled.

4.2.2. Group

Groups are the primary templating system. In a context where generated text is required, a group is selected and within that group, a template is selected. The template is selected by evaluating the expression in the match attribute with the current node as the context item. A template with the match express true() will always succeed; it is used as a fallback.

The title-numbered group determines how titles are formatted if they are numbered, (there’s also title-unnumbered when titles aren’t being numbered):

1 |<group name="title-numbered">
  |   <template match="self::db:section[ancestor::db:preface]">%c</template>
  |   …
  |   <template match="self::db:appendix">{Appendix} %l%.%c</template>
5 |   …
  |   <template match="self::db:warning">%c</template>
  |   <template match="true()">%l%.%c</template>
  |</group>

(Note that not all titles are numbered, this is just the group that’s used if they could be. See $division-numbers, $component-numbers, and $section-numbers.)

Within a template, two kinds of substitution are performed: names in curly braces are replaced by the corresponding mapping and %-letter values are substituted as follows:

Table 4.1. Template %-letter substitutions

%-letter | Substitution
%c | The content (for example, the text of the title)
%l | The label (for example, “Chapter 1” or “see also”)
%p | The page number (not yet implemented)
%o | The olink title (not yet implemented)
%. | The separator (often, “. ”)
%% | A literal % character

If the title group is being used to generate text for the chapter from our example document:

The chapter context is used to select the template ({chapter} %l%.%c).

The string {chapter} is replaced by the mapping for chapter, which is “Chapter” in English.

The label %l is “1” because this is the first chapter. (In fact, constructing the label uses templates from the localization file as well.)

The separator %. is “. ”. (Like the label, this is also constructed from a separate query to the localization file.)

And the content %c is “Chapter the first”. (There’s no markup in this title, but if there was, it would be retained. The content is a list of items, not a string.)

Literal text, such as the non-breakable space between “{chapter}” and “%l”, is retained verbatim.

4.2.3. List

List elements are used to format items that can be repeated (terms in a variable list, lists of authors, lists of “see also” terms, etc.). The list consists of a series of items. Within each item, one or more content replacements is specified with %c. The items must be arranged so that there’s a match for one, two, three, etc. items.

If an item contains a repeat, that repeat will be used for as many items as necessary to complete the list formatting. The default list format is:

1 |   <list name="_default">
  |      <items>%c</items>
  |      <items>%c {and} %c</items>
  |      <items>%c<repeat>, %c</repeat>, {and} %c</items>
5 |   </list>

Consider how a list of four authors in an authorgroup would be formatted. Call them A, B, C, D, for simplicity (and assume there’s no list for “authorgroup”, so the “_default” will be used).

The first two items match one and two items, respectively. They aren’t appropriate for a list of four items. The third item contains three items and a repeat, so that can be used for a list of four (or more) items.

The first %c is “A”. The second %c is in a repeat, followed by another %c. There are three elements left in the list at this point, so two will be used in the repeat and the last one will follow it.

The result will be A, B, C, and D where the word “and” was found by looking for the and key in the mappings.

4.2.4. Letters

The letters group is used to identify the lexical order and grouping of letters.

 1 |   <letters>
   |      <l i="-1"/>
   |      <l i="0">Symbols</l>
   |      <l i="10">A</l>
 5 |      <l i="10">a</l>
   |      …
   |      <l i="20">B</l>
   |      <l i="20">b</l>
   |      …
10 |   </letters>

All of the symbols with the same “i” value will be grouped together.

This mechanism dates from the days before XSLT supported language-specific collations. It is used in generated indexes, but perhaps it should simply be phased out.

4.3. Customizing a localization

For many users, the localizations provided are entirely sufficient. But if you want to change them, you have a few options.

4.3.1. Replacing entire localization files

If you want to replace an entire localization file (if, for example, you want to apply the same changes to a set of stylesheets), you can approach that as follows:

Copy the localization source files.

Update the ones you wish to change.

Compile them all with src/main/xslt/modules/xform-locale.xsl saving the output in a new location.

In your stylesheet, change the $v:localization-base-uri to point to the directory where the new locales reside. Those locale files will be used.

4.3.2. Overriding mappings, groups, etc.

If you only want to override a small number of localization features, it may be simpler to do so directly in your stylesheet. The variable $v:custom-localizations will be merged with the default localizations before transformation begins. But you can only override existing groups with the procedure described here. You cannot use $v:custom-localizations to define new groups.

Suppose, for example, that you wanted:

The table of contents title to simply be “Contents”,

To omit the word “Appendix” from the appendix title, and

To change the form of the cross reference to appendixes to read “App. A” instead of “Appendix A”.

The following customization would accomplish that:

 1 |<xsl:variable name="v:custom-localizations">
   |  <locale xmlns="http://docbook.org/ns/docbook/l10n/source"
   |          language="en"
   |          english-language-name="English">
 5 |    <mappings>
   |      <gentext key="TableofContents">Contents</gentext>
   |    </mappings>
   |    <group name="title-numbered">
   |      <template name="appendix">%l%.%c</template>
10 |    </group>
   |    <group name="xref-number">
   |      <template name="appendix">App. %l</template>
   |    </group>
   |  </locale>
15 |</xsl:variable>

Note that it defines (a portion of) a locale source file for the language en. These changes only apply to that locale.

This fragment replaces the mapping for TableofContents and the templates for numbered titles and numbered cross references.

To update multiple languages, put additional locale elements in the variable as siblings.

Formatting our example document above now produces:

Figure 4.6. Sample book (Alternate)

4.3.3. Changing the group

Sometimes, rather than change a template, you want to change which group of templates is used. This is controlled by two variables: $v:user-title-groups and $v:user-xref-groups.

4.3.3.1. Changing the title group

The $v:user-title-groups element consists of a list of title elements, each with an xpath attribute, a group attribute, and an optional template attribute.

Suppose the stylesheet is trying to generate a title for an element. It considers each title element in turn. The xpath expression is evaluated with the element as the context item. If the effective boolean value of the expression is true(), then that title is selected and templates from the corresponding group are used.

If a template attribute is present, a template with that name is used. Otherwise the local name of the element is used as the template name.

By default, sections in a preface are not numbered. That’s because the default title groups include:

  |<title xpath="self::db:section[ancestor::db:preface]"
  |       group="title-unnumbered"/>

If you add a title that matches sections in a preface to $v:user-title-groups, it will take precedence. For example:

  |<title xpath="self::db:section"
  |       group="title-numbered"/>

Because all of the user groups are consulted first, it isn’t necessary to include the predicate that limits this title to sections in a preface (although it wouldn’t change the result if you did).

4.3.3.2. Changing the cross reference group

Cross references are processed just like titles, except that the $v:user-xref-groups element consists of a list of crossref elements. (See also Section 2.10, “Customize individual cross references”, for a discussion of how individual cross references can be customized.)

The default for cross references to chapters and appendixes is “xref-number-and-title”, so you get things like “Chapter 1. The Chapter Title”. In order to get a different presentation in the localization example used in this chapter, the following localization is used:

  |<xsl:variable name="v:user-xref-groups" as="element()*">
  |  <crossref xpath="self::db:chapter|self::db:appendix"
  |            context="xref-number"/>
  |</xsl:variable>

That’s why the cross reference to the first chapter is just “Chapter 1”.

4.4. Caveats

There’s currently little documentation to tell you which group or template to change. The names are supposed to be somewhat self explanatory (for speakers of English), but sometimes you just have to look in the stylesheet.

The formalgroup element is unique in DocBook in that its label depends on what it contains. A formalgroup of figure elements is itself a “Figure” where a formalgroup of example elements is an “Example”. If you need to change it, you may have to create your own template for the formalgroup element in the m:headline mode. The default version is in modules/titles.xsl.

4.5. Background

If you’re interested in how things got this way, it’s useful to consider the history of stylesheet localization for DocBook. Near the end of the previous millennium, I was working on the DSSSL stylesheets for DocBook. They were popular enough that users of languages other than English wanted to use them.

I invented a mechanism for doing simple localization so that the word “Chapter” in “Chapter 5” would, for example, be spelled “Chapitre” if the book was in French, and “Розділ” if it was in Ukrainian. What started as a simple word substitution system grew a few macro facilities and became a little more sophisticated*.

Over time, with the aid of dozens of volunteers around the world who contributed files for their languages, the DocBook stylesheets developed localization capabilities that were for the most part good enough.

Fast forward a few years and those language-specific localization files, and some of those mechanisms, were ported to the XSLT 1.0 stylesheets for DocBook.

Fast forward another decade and those XSLT 1.0 localization files and some of the mechanisms were ported to the XSLT 2.0 stylesheets for DocBook.

Fast forward the better part of another decade and those XSLT 2.0 localization files and some of the mechanisms were ported to the DocBook xslTNG stylesheets.

Well. Sort of. Initially, I tried to replace the complex system of templates with a model that took the text that had to be generated and decomposed it into logical parts. It worked fine for English and many other languages, but didn’t account for the complexity of many others, such as Chinese.†

Starting in version 2.0.0, the xslTNG stylesheets have reverted back to a templating system. The localization files have been transformed a little bit to make some of the customization easier (I hope). They can’t stray too far from the original designs because I must reuse the localization data I have. I don’t want to devise a system that requires another army of volunteers to provide new localization data.

4.5.1. Consequences

One unfortunate consequence of this history is that there’s some cruft in the localization files. There are mappings and possibly templates that aren’t actually used. Or, at least, they’re not used in the standard DocBook stylesheet. They might be used in customization layers.

I made a few attempts to trim out cruft, but found all of the results unsatisfying. So, at least for the moment, I’ve left it in place. Like everything on earth, it’s mostly harmless.

*

I’m not sure you’d pick a twenty-something, monolingual Anglophone American to do this work if you were planning ahead, but that’s what happened.

†

Turns out a fifty-something, monolingual Anglophone American isn’t much of an improvement, really.

Chapter 5. Implementation details

This section sketches out some features of the implementation. It would probably be better to build an annotated Definitive Guide or something, but this will have to do for now.

5.1. Customizing chunking

Chunking is controlled by the $chunk-include and $chunk-exclude parameters. These parameters are both strings that must contain an XPath expression.

For each node in the document, the $chunk-include parameter is evaluated. If it does not return an empty sequence, the element is considered a chunking candidate. In this case, the $chunk-exclude parameter is evaluated. If the exclude expression does return an empty sequence, then the element identified becomes a chunk. (If the exclude expression returns a non-empty value, the element will not become a chunk.)

5.2. Lengths and units

Lengths appear in the context of images (width and height) and tables (column widths). Several different units of length are possible: absolute lengths (e.g., 3in), relative lengths (e.g., 3*), and percentages (e.g., 25%). In some contexts, these can be combined: a column width of “3*+0.5in” should have a width equal to 3 times the relative width plus ½ inch.

In practice, some of the more complicated forms in TR 9502:1995 have no direct mapping to the units available in HTML and CSS. The stylesheets attempt to specify a mapping that’s close. Broadly, they take the nominal width of the table ($nominal-page-width), subtract out the fixed widths, divide up the remaining widths proportionally among the relative widths, and compute final widths. The final widths can be expressed either in absolute terms or as percentages.

In handling the width and height of images, the intrinsic width and height of the image in pixels are converted into lengths by dividing by $pixels-per-inch. Nominal widths are taken into consideration if necessary.

ⓘ

Note

Determining the intrinsic size of an image depends on an extension function. See Section 2.6, “Extension functions”. Many bitmap image formats are supported. The bounding box of EPS images is used, if it’s present. The intrinsic size of SVG images is not available.

The list of recognized units (in, cm, etc.) are taken from $v:unit-scale.

5.3. Line numbers

In the lines and table styles, line numbers may be added to the beginning of some (or all) lines. Prior to version 1.10.0, the stylesheets inserted the numbers without any padding:

  |<span class="line">
  |  <span class="ln">5</span>
  |  <span class="ld">The line of text</span>
  |</span>

(The newlines and indentation in these examples are for clarity. In practice, these are inside a pre where every space counts and they’re all run together with line breaks only occurring between lines.)

In a graphical browser with CSS support, this looked fine. But without CSS, the line numbers and the text that followed them could flow together and the alignment of the numbers was unclear.

Starting in version 1.10.0, the stylesheets insert padding spaces before each number so that they will all be aligned. If the largest line number is three digits long, every number smaller than 100 will be padded to a width of three characters. A single space is added after the number to separate it from the text that follows. An additional separator may also be inserted, as shown here.

  |<span class="line">
  |  <span class="ln"> 5 <span class="nsep">|</span></span>
  |  <span class="ld">The line of text</span>
  |</span>

These changes have no visible effect when CSS is used to style the verbatim environment. But without CSS, the numbers are aligned and separated from the text that follows. The $verbatim-number-separator is generally suppressed by CSS, but is visible in text browsers.

5.4. Processing mediaobjects

Starting in version 1.11.0, the way media objects are processed has been refactored. This is designed to support fallback at both the object level (imageobject, audioaobject, videoobject, textobject, and imageobjectco) and at the data level (imagedata, audiodata, videodata, and textdata within the objects).

Each data element and object element is processed in the m:mediaobject-info mode. This returns a map for each object that contains an array of maps, one for each data element:

Table 5.1. The object map

Key | Value
content-types | An array of the distinct content types in the data elements
datas | An array of data maps
extensions | An array of the distinct extensions in the data elements
node | The media object node

Each data map has the following structure:

Table 5.2. The data map

Key | Value
align | The alignment of the data (if specified)
content-type | The computed content type for the data
contentheight | The content height of the data (if specifieda)
contentwidth | The content width of the data (if specified)
extension | The extension of the data file (if there is one)
fileref | The original fileref attribute value
height | The height of the data (if specifieda)
href | The computed href value for the HTML element; this takes account of the $mediaobject-input-base-uri and $mediaobject-output-base-uri).
node | The data element
params | Any multimediaparams associated with the data element
properties | The properties of the element (as returned by the extension funtions; this can include EXIF data and metadata)
scale | The scaling factor (if there is one) or 1.0
scalefit | True if the image should be scaled to fit (implicitly or explicitly)
uri | The computed absolute URI of the input data
valign | The vertical alignment of the data (if specified)
width | The width of the data (if specifieid)

a

DocBook uses “depth” instead of “height”, but we convert it to height for consistency with most other systems.

🛑

Warning

Prior to version 2.7.0, percentage values for the width or depth of a media object were incorrectly computed against the intrinsic size of the object. That error has been corrected, but will effect the size of those images. To retain the previous, incorrect behavior, see $mediaobject-percentage-of-intrinsic-size.

The uri and href properties are computed by processing the data elements in the m:mediaobject-uris mode.

Armed with information about the objects and the data associated with them, the stylesheets proceed to choose an object and then process it. Each object is considered in turn, if any of the data elements it contains were excluded, then it is rejected. The first object where all of the elements are acceptable is selected.

Consider this example:

 1 |<mediaobject>
   |<imageobject>
   |  <imagedata fileref="image.svg"/>
   |  <imagedata fileref="image.eps"/>
 5 |  <imagedata fileref="image.png" width="4in"/>
   |</imageobject>
   |<imageobject>
   |  <imagedata fileref="image.svg"/>
   |  <imagedata fileref="image.png" width="40em"/>
10 |</imageobject>
   |</mediaobject>

If this is being processed for online presentation, the default value of $mediaobject-exclude-extensions will exclude the EPS file. Because one of it’s data elements was excluded, the processor will choose the object containing only the SVG and PNG images for online presentation.

Once an object is selected, an appropriate wrapper is created and all of the alternatives are placed within it. So the example above will result in picture element containing a source for the SVG image and an img for the fallback PNG.

ⓘ

Note

Consistent with HTML, only the size, scaling, and alignment attributes of the last alternative data element are considered! These apply irrespective of which alternative is selected.

5.4.1. Mediaobject URIs

Media object URIs are tricky to handle. It’s most convenient if the URIs in the source documents point to the actual media files. This allows extensions, like the image properties extension function, to access the files. At the same time, the references generated in the HTML have to point to the locations where they will be published.

In previous versions, the stylesheets attempted (broadly) to use the relative difference between the input and output base URIs to work out the correct relative URIs for media. That imposed restrictions on the authoring environment that weren’t always easy to work with. Starting in version 2.0.6, the mechanisms for finding sources and producing references in the output has changed. Three parameters are used:

$mediaobject-input-base-uri

If the $mediaobject-input-base-uri is empty (the default), then URIs in the source document are assumed to be relative to the base URI on which they occur. This is the usual case if you mix XML and media into the same directory structure on the filesystem.

If the $mediaobject-input-base-uri is not empty, it is used to resolve all media URIs. If it’s initialized with a relative URI, that URI will be made absolute against the base URI if the input document.

$mediaobject-output-base-uri

If the $mediaobject-output-base-uri is empty (the default), then URIs in the output are treated as parallel to the URIs in the input. If the reference ../image.png works in the source document, it’s assumed that will also work in the output document.

If the $mediaobject-output-base-uri is not empty, it is the base URI used for media objects. If this is a relative URI, it is taken to be relative to the root of the output hierarchy.

Suppose the output base URI is https://images.example.com/, then a reference to image.png will appear as https://images.example.com/image.png in the output.

If the output base URI is media/, then a reference to image.png will appear as media/image.png in the output. If the document is chunked, the paths back to the output directory are relative. In otherwords, if the reference to image.png appears in a chunk that will be located at back/appendix.html, then the media URI will be ../media/image.png.

$mediaobject-output-paths

This parameter controls whether the relative paths in the input URIs apply to the output URIs as well. If the parameter is true, the output base URI is media/, and the input URI is path/to/image.png, then the output reference will be to media/path/to/image.png. If it’s false, then the output reference will be to media/image.png.

For a further discussion of the options, see Section 3.5, “Managing media”.

☝

Important

The stylesheets are not responsible for actually copying the media files into the correct locations in the output. The stylesheets only generate the HTML files and the references. You must copy the images and other media with some other process.

5.5. Templates

It’s difficult to make title pages for documents easy to customize. There is a lot of variation between documents and the styles can have very precise design constraints. At the end of the day, if you need complete control, you can define a template that matches the element in the m:generate-titlepage mode and generate all of the markup you wish. The parameter $default-templates-uri points to the file with default templates.

The default title page handling attempts to make some declarative customization possible by using templates. A typical header template looks like this:

 1 |<db:section>
   |  <header>
   |    <tmp:apply-templates select="db:title">
   |      <h2><tmp:content/></h2>
 5 |    </tmp:apply-templates>
   |    <tmp:apply-templates select="db:subtitle">
   |      <h3><tmp:content/></h3>
   |    </tmp:apply-templates>
   |  </header>
10 |</db:section>

Any HTML element in the template will be copied to the output. The semantics of a “template apply templates” element (tmp:apply-templates) is that it runs the ordinary xsl:apply-templates instruction on the elements that match its select expression. If they result is the empty sequence (e.g, if there is no subtitle), nothing is output. If there is a result, the content of the tmp:apply-templates element is processed. Anywhere that tmp:content appears, the result of applying templates will be output.

In this example, if the title is “H₂O” and there is no subtitle, the resulting HTML title page will be:

  |<header>
  |  <h2>H<sub>2</sub>O</h2>
  |</header>

5.6. Annotations

The stylesheets fully support annotations, including a number of presentation styles enabled by JavaScript in the browser. They also support an extension of the documented semantics of annotation.

Annotations are applied to elements with links. Either the element must point to its annotations (with an annotations attribute) or the annotations must point to the elements they annotate (with an annotates attribute). These are documented as ID/IDREF links but they are not IDREFS attributes because annotations may be stored separately.

Starting in version 1.5.1, the DocBook xslTNG Stylesheets⌖¹ support a non-standard extension: if you place the string xpath: in the annotates attribute of an annotation, then the rest of the attribute is assumed to contain an XPath expression that points to the element(s) to which the annotation applies. (If you want to put IDREF values before the xpath: token, that’s fine, but you can’t put them after; the expression continues to the end of the attribute value.)

Suppose, for example, that you wanted to annotate the stylesheet title in the previous paragraph. The standard mechanisms would require that you either put an xml:id attribute on the element or point to the annotation from the element. With the XPath extension, you can do this:

1 |<annotation
  |   annotates="xpath:preceding-sibling::db:para/db:citetitle"
  |   xmlns:db="http://docbook.org/ns/docbook">
  |<para>This annotation applies to the stylesheet title.
5 |For a discussion of this annotation, see the
  |following paragraphs.</para>
  |</annotation>

When the XPath expression is evaluated, the annotation element is the context item. Often, this means that you’ll want to start the expression with id() or /.

The namespace context for the expression is also the annotation element, that’s why I’ve added the DocBook namespace binding for the db prefix. In practice, if you’re doing this on several annotations, you can just put all the namespace bindings on a common ancestor. All of the bindings in scope on the annotation element are available in the expression.

Caveats:

There’s no way to have multiple XPath expressions. You can’t put “xpath:” in there twice. If you want an annotation to apply to multiple elements, you’ll have to construct a single expression that selects all the elements, or duplicate the annotation, or use ID/IDREF links.

If this turns out to be a serious limitation in practice, additional syntax could be added to support multiple expressions, but it doesn’t seem necessary.

You can only select elements. There’s no way to select the third word in a particular paragraph, for example, unless it already has some markup around it. There’s also no way to select a comment or a processing instruction.

The placement of the annotation marker (“⌖” by default) can also be controlled globally and on individual annotations. The $annotation-placement parameter provides global control. To specify the position for an individual annotation, put the token “before” or “after” in the role attribute on the annotation.

5.7. The pre- and post-processing pipeline

Processing a DocBook document is a multi-stage process. The original document is transformed several times before converting it to HTML. The standard transformations are:

Adjust the logical structure. Adds an XML base attribute to the root of the document and converts media object entityref attributes into fileref attributes.

Perform XInclude processing. Only occurs if the appropriate extension function is available and if the document contains XInclude element.

Convert DocBook 4.x to DocBook 5.x. Only occurs if the root element is not in a namespace.

Peform transclusion.

Perform profiling.

Normalize the content. This removes a lot of variation that’s allowed for authoring. For example, authors aren’t required to use an info element if a formal object has only a title. This process adds the info element if it’s missing.

Resolve annotations.

Process XLink link bases.

Validate. Only occurs if the appropriate extension function is available and the stylesheet specifies a $relax-ng-grammar.

Process Oxygen change markup. Only occurs if $oxy-markup is true and the document contains Oxygen change markup processing instructions.

A customization can introduce transformations to the original document using three parameters:

$transform-original

This transform runs before step 1 in the standard transformations. Note that this is before XInclude processing, before transclusion, before any other processing. If you need to make a change to the original input document, this is where you can do it, but for preprocessing “the XML document that will be transformed”, the $transform-before parameter is likely to be a better choice.

If this transformation is used, it must take special care to preserve the base URI of the original document by adding an xml:base attribute to the root element (if it doesn’t already have one).

Only the first transformation in the list has access to the original base URI. If it isn’t preserved, relative references to other documents will be resolved against the static base URI of the stylesheet and not the URI of the original document. That’s unlikely to be correct.

$transform-before

This transformation runs after step 10. Its input is the DocBook document that will be transformed into HTML.

$transform-after

This transformation runs after the DocBook document has been transformed into HTML. The resulting HTML document is not valid HTML, but contains islands of valid HTML that will be separated out into chunks by subsequent processing.

(If you need to insert a transformation in the middle of the standard transformations, you’ll have to update the $v:standard-transforms variable in your customization.)

Each of the transformation variables holds a list of transforms that will be applied in the order specified. Each member of the list can be a map or a string. If a string is provided, it’s the equivalent of providing this map:

  |map {
  |  'stylesheet-location': $the-string
  |}

The map can have several keys:

Table 5.3. The transformation map

Key | Value
stylesheet-location | The location of the XSLT stylesheet that performs this transformation. This key is required.
extra-params | A map of QName/value pairs. These parameters will be made available to the transformation in addition to all of the standard parameters available to a standard DocBook stylesheet.
functions | A list of functions (expressed as EQNames). The transformation will only be run if every extension function listed is available.
test | An arbitrary XPath expression. The expression will be evaluated with the document as the context item. If it returns an effective boolean value of true, the transformation will be run.

Annotations

⌖¹

This annotation applies to the stylesheet title. For a discussion of this annotation, see the following paragraphs.

Chapter 6. Building the stylesheets

If you wish, you can also clone the distribution and build them yourself. The distribution is designed to be self contained. In a Unix or Mac environment, running:

./gradlew dist

will build the stylesheets. Building will:

Compile the stylesheets and run the unit tests. The compiled stylesheets will be available in build/xslt.

Running all the tests requires building the reference guide and a few other things. You can build the stylesheets without running any of the tests with the makeXslt task.

Compile the extension functions. The compiled extension functions will be available in build/libs. The jar task will compile the extensions without running the tests.

“Compile” the Python script that helps run the stylesheets. (It’s not really compiled, but several stylesheet-version-specific strings are interpolated.) The copyBin task will setup the Python script without running the tests.

☝

Important

In principle, it should be possible to build the stylesheets on Windows. In practice, it isn’t entirely reliable. It has been much improved as of version 2.1.4, but still fails randomly on some Windows machines, but not others. It may be more expedient to build in the Linux subsystem on Windows 10 or in a Docker container.

6.1. Prerequisites

In order to build the stylesheets, you must configure your system with several prerequisites:

Gradle. The stylesheet builds use the Gradle wrapper to assure a consistent environment across systems, it’ll be downloaded automatically the first time you build.

A modern version of Java. (Java 1.8 or later, for example.)

Python 3 and the click module. The Pygmentize program is also required for syntax highlighting, though that’s not technically a build requirement.

If you discover other prerequisites that have been overlooked, or have questions or suggestions about how best to manage them, please let us know.

6.2. Repository structure

The most significant parts of the repository hierarchy are:

src/main/xslt
src/main/xslt/transforms
src/main/xslt/modules

These are the sources for the stylesheets themselves. The transform subdirectory contains the preprocessing stylesheets that are run as separate transforms. The modules directory doesn’t have any special significance, it just makes the main entry points easier to find.

You cannot run the XSLT stylesheets directly from the source location. You must build them first with the makeXslt build target.

src/main/web
src/main/web/resources/css
src/main/web/resources/js

These are the CSS and JavaScript files needed for accurate rendering in the browser or formatter process.

src/main/locales/locale-10
src/main/locales/locale

The local-10 directory holds copies of the localization files from the XSLT 1.0 stylesheets. They’re transformed into the locale versions by the build system. This whole area is one that needs work.

src/test/xspec
src/test/generators
src/test/resources/xml
src/test/resources/expected

These are the testing resources. You cannot run the XSpec tests directly from src/test/xspec. The build system copies them into build/xspec along with a few XSpec tests generated automatically by the stylesheets in generators.

The library of DocBook documents that are used for testing is stored in the xml directory. The HTML files in expected correspond to the expected results. The expected results aren’t usefully viewed in a browser. Only the body element and its decendants are stored in the expected results. This avoids a lot of noise in the head.

src/main/java

These are the sources for the extension functions.

src/guide
src/website

These are the sources, resources, and ancillary files for the reference guide and the website.

tools

The tools directory holds a number of stylesheets and other scripts used by the build process.

lib

The lib directory holds third party jar files. This is also where you can put your Saxon PE or EE files if you have them.

build
build/actual
build/xslt

The build system puts all of its temporary files under build. It’s always safe to delete the entire directory and start over, though it will require internet access and it may take a while.

Test files that you format are published to build/actual and the images, CSS, and JavaScript resources are copied under there so that everything will look right in the browser. For security reasons, some JavaScript features may not work if you are looking at the documents from the filesystem. You can work around this by pointing a local web server at the build directory.

The built stylesheets are in build/xslt. You can run them directly from there.

6.3. Build configuration

Several build properties are defined in gradle.properties.

verbose

If true, enables additional messages in the extension functions.

requireCompileSuccess

If true, the build will fail if there are any errors building the stylesheets.

requireTestSuccess

If true, the build will fail if any tests fail.

xspecVersion

The version of XSpec.

xsltExplorerVersion

The version of XSLT Explorer.

pdftool

Select a tool for formatting PDFs. Expected values are antennahouse or prince.

antennahouse

The path to the Antenna House Formatter.

prince

The path to the Prince formatter.

There are four additional properties that are used by the dbtransform target. This target allows you to process arbitrary documents with the stylesheets. It takes care of loading all of the extension functions.

dbsource

The URI of the source document.

dboutput

The path for outputting the principle result document.

dbstyle

The URI of the base stylesheet, defaults to the main DocBook xslTNG stylesheet.

dbparams

Stylesheet parameters.

You can change these variables in your local version of gradle.properties, or you can specify them on the command line. For example, to enable verbose processing, pass -Pverbose=true on the Gradle command line.

6.4. Build tasks

The build system is Gradle. Gradle’s processing model operates in several phases, this allows an initial configuration phase to construct build targets (called tasks) dynamically. The DocBook xslTNG Stylesheets build script uses this facility quite a bit.

In the discussion that follows, testdoc is the base name of a test document, that is, one of the example files from the src/test/resources/xml directory. For example, one of the test documents is src/test/resources/xml/article.001.xml. In the build targets that would be the “testdoc” article.001. In an analogous way, “testset” is the root name of an XSpec test file in src/test/xspec.

The most important tasks are:

makeXslt

This tasks “compiles” the stylesheets into build/xslt.

report

This task runs all of the tests and generates a unified report in build/report. This is the default task.

test

Runs the test suite against the stylesheets.

jar

Compiles the extension functions and creates the jar file in build/libs.

dist

Builds an archive in build/distributions suitable for distribution.

guide

Builds the reference guide.

website

Builds the website.

explorer

Generates the XSLT Explorer report for the stylesheets in build/explorer.

helloWorld

A smoke test target. It just prints a message, but doing so will exercise a bunch of the build machinery in Gradle.

6.5. Testing tasks

The way tests are managed was completely refactored in version 2.0.13. The new system is largely automatic.

Create a new test document in src/test/resources/xml. For this example, we’ll create para.003.xml, an example of a sidebar in a para.

Use the build target para.003.html to format the document. This build target (and several others) exist automatically because the source file has been created.

Inspect the results (in build/actual/para.003.html) and adjust the stylesheets until you are satisfied that the results are correct. Each time you make a stylesheet change, you can re-run the para.003.html target to rebuild the output.

When you are satisified, run param.003.expected to update the expected results.

Run the report target to make sure no other tests have broken as a result of your changes.

More generally, the following targets exist for any source document in src/test/resources/xml:

testdoc.html

Formats testdoc into HTML and stores the result in build/actual where it can be viewed in the browser with the appropriate CSS, JavaScript, images, etc.

testdoc.expected

Formats testdoc into HTML and stores the result in src/test/resources/expected. You should only run this task when you’ve made a change and determined that the new results are correct and should replace the previously expected results.

testdoc.pdf.html

Formats testdoc into HTML suitable for paged media and stores the result in build/actual.

testdoc.pdf

The .pdf target will generate the .pdf.html output and then attempt to transform it into PDF with either AntennaHouse or PrinceXML. Additional configuration may be necessary to get this to work.

testdoc.chunk

Formats testdoc into HTML with chunking turned on. The result is stored in index.html and other files in build/actual. No attempt is made to avoid having the output files from different documents overwrite each other. At the moment, none of the automated tests create chunked output.

testset.xspec

Runs the testset set of XSpec tests. The test sets that are available are the sets constructed from build environments and the sets created by hand (in src/test/xspec).

6.6. Running XSpec

In order to get consistent results across different runs and in different environments, the XSpec tests run a driver stylesheet, xspec-driver.xsl.

Note also that the XSpec shell script is modified by the stylesheets.

Appendix A. Changes in version 2.x

A.1. Change Log

This section documents the changes made in each release. This does not necessarily include every minor change, only those likely to be of interest to users of the stylesheets. See the commits and pull requests on the repository for finer detail.

A.1.1. Changes in version 2.8.0

The way CALS tables are processed has been completely rewritten for this release. It is very likely that customization layers that modify CALS table processing will need to be changed; this release is not backwards compatible with version 2.7.7.

The new approach is simpler, and faster, than previous approaches and should simplify customizations that produce other kinds of markup.

Fixed #40. Added a $prefer-xrefstyle parameter allowing xrefstyle on xref to override xreflabel on the linked element.

A.1.2. Changes in version 2.7.7

Fixed #56. Moved styling for the persistent ToC from explicit style changes in JavaScript back into CSS where it belongs. (It’s much easier to change that way.)

Fixed #46. When both the image properties extension function and the image metadata extension function are available, combine the results. This provides the width and height properties even in cases where the image metadata stores them in some other form.

Fixed #49. Added explicit ordered list numeration CSS for paged meda. (Fixes a problem with Weasyprint.)

Updates for the Docker container: moved to Ubuntu “Noble” and adopted some best practice improvements to the Dockerfile. h/t @tsteven4.

Bumped DocBook version to 5.2.1.

A.1.3. Changes in version 2.7.6

Fixed #35. Attempted to implement support for responsive images by generating srcset from media objects.

Fixed #34. Added footers to the guide pointing readers to the issues list.

Fixed #33. Corrected the normalized form of language tags in localizations. The stylesheets were normalizing language identifiers that have a language and a country to a string with an underscore: "en_us", but that doesn’t work. The correct separator is a hyphen.

A.1.4. Changes in version 2.7.5

Fixed #27. Update the Maven POM so that the xslTNG release no longer carries a runtime dependency on EPUBCheck.

Fixed #26. Avoid number format exceptions when parsing image metadata.

Fixed #25. Added a wrapper around arg (and group) elements that appear in a cmdsynopsis. This allows the whole argument, including any surrounding punctuation, to be styled.

Fixed #21. Avoid adding a persistent ToC to pages that have no sections.

A.1.5. Changes in version 2.7.4

Fixed #653 (GitHub). Added support for unnumbered formal objects. All of the locales have been corrected so that unnumbered formal objects have no labels. The parameter $formal-object-numbers has been added to control formal object numbering. Also, there’s a new $use-label-numeration parameter to control whether or not label values should be used in place of generated numeration.

Fixed #14. Publishing the guide updates the current release on the website.

A.1.6. Changes in version 2.7.3

Fixed #8. Adjusted the “on-error-color” to have higher contrast with the error background. (Changed it from yellow to black.)

Fixed #681 (GitHub). Avoid duplicate ID values in the ToC when inline anchors are used. Also changed the rendering of anchor elements from span to a.

Fixed #680 (GitHub). Added the pubwork value to the class attribute for biblioentry, bibliomixed, and citetitle.

Fixed #665 (GitHub). The release description automatically includes the relevant changelog entries.

Fixed a typo in the description of $mathml-js-role, improved CSS rendering of mathphrase in equations.

Cleaned up the jar manifest, removed unnecessary dependencies accidentally added when the build started using EPUBCheck.

Sorted out how to read the gradle.properties file from buildSrc. Removed the confusing properties.gradle file.

Corrected some out-of-date links to GitHub.

A.1.7. Changes in version 2.7.2

Fixed #683. Reworked support for Oxygen change markup processing instructions. The markup is improved, using real attributes in the http://docbook.org/ns/docbook/oxygen namespace. The order of processing has been changed so that annotations are handled correctly.

Fixed #675. Make emphasis and citation upright in media object captions. (To distinguish them from the already italicized caption.)

Fixed #674. Support finer granularity in placement and generation of ToCs. The toc element can now be used to place “lists of titles” more-or-less arbitrarily, both in terms of location and generated lists.

Fixed #623. Improve numbering of co elements; change the default numbering. It’s now possible to renumber callouts (co callouts) starting at each verbatim environment or at any of the other places used for numeration boundaries.

Added a $label-wrapper parameter for labels. This adds a wrapper around both the label and separator for labeled elements. This makes some kinds of CSS styling easier (for example, floating section numbers in the left margin). The default value is the empty sequence for backwards compatibility.

Migrated to Codeberg.org

A.1.8. Changes in version 2.7.1

Fixed #666. Avoid putting the subtitle in the title when $titleabbrev-passthrough is used.

Switched to SInclude version 5.6.0 for the fix to in-scope namespace handling.

A.1.9. Changes in version 2.7.0

☝

Important

This release contains backwards incompatible changes in the way relative media object widths are computed. If you specify media object widths or depths with percentages, take special care to assure you’re getting the results you expect. Use $mediaobject-percentage-of-intrinsic-size to select backwards compatible behavior.

Fixed #657. If a resource path appears to be absolute, don’t add the resource base URI to it.

Fixed #655. Avoid duplicate ID values in automatically generated glossaries when a document consists of multiple books.

Fixed #654. Corrected the context for abstracts in titlepage templates.

Fixed #651. Avoid a runtime error when using multiple admonition icons.

Fixed #648. When the width or depth of a media object is specified as a percentage, it is supposed to be a percentage of the available space. All versions of the stylesheets before 2.7.0 incorrectly calculate percentages against the intrinsic size of the media object. That has been fixed. Note that this is a backwards incompatible change if you specify widths or depths as percentages. Use $mediaobject-percentage-of-intrinsic-size to select backwards compatible behavior.

Fixed #647. Support language localization with Saxon PE.

Improved the fix for #581. It occurred to me that the templates processing CALS tables do know the width of each column. That allows the available space in a CALS table to be computed correctly for media objects that specify widths as a percentage. This is also a backwards incompatible change. Like the fix for #648, backwards compatible behavior can be retained with the $mediaobject-percentage-of-intrinsic-size parameter.

A.1.10. Changes in version 2.6.1

Fixed #637. Catch and ignore parse errors from pygmentize.

Fixed #634. Attempt to avoid false positive warnings about table widths.

Fixed #629. Don’t create duplicate ID values when styling coref elements. This fix also changes the element that wraps a co from “a” to “span”. That’s possibly backwards incompatible, but seems unlikely to be harmful and “a” is clearly wrong.

Fixed #625. Added a $user-document-class parameter.

Fixed #621. Assure that when indexterm elements appear in title elements, they don’t generate anchors in the list of titles.

Fixed #620. Fixed an error in how scope was computed for generated indexes.

Fixed #614. Corrected the way citation links are constructed so that they work even when the bibliography entry doesn’t have an xml:id. This change also introduces a warning message for citations that don’t have corresponding entries. I think that’s the right thing to do.

There’s a small markup change in this fix. Where previously a citation would produce something like this:

1 |<a href="#R_bi1_biblioentry1" class="xref xref-biblioentry">
  |  <span class="label">
  |    <span class="abbrev">AhoSethiUllman96</span>
  |  </span>
5 |</a>

it now produces:

  |<span class="citation">
  |  <a href="#R_bi1_biblioentry1" class="xref xref-biblioentry">AhoSethiUllman96</a>
  |</span>

Technically this is backwards incompatible; it’s possible that the label/abbrev classes were used for styling, but styling the citation class should be a lot easier.

Fixed #573. Make sure that section numbering works correctly when sections contain refentry elements.

Made a number of improvements to this guide with special thanks to Olivier Cailloux for careful review and feedback.

A.1.11. Changes in version 2.6.0

Fixed #616. The spacebar has a navigation purpose in the browser, so don’t interfere with that.

Fixed #615. Title and subtitle elements now get attributes, for example lang. This also has the benefit that headings for subtitles have a class attribute to identify them.

Fixed #612. Whitespace in the baseform attribute is normalized when processing glossary entries.

Fixed #593. Updated MathJax, added support for TeX equations with a role of tex on mathphrase.

Fixed #587. Improved support for titles on abstract and legalnotice elements.

Fixed #584. Support both para and simpara in compact lists.

Fixed #582. Allow gentext letters to be the empty sequence. This won’t give the correct result, but it will allow the stylesheets to run without crashing. Thank you, Johan, for the updated sequences for Japanese and Korean.

Fixed #579. Remove “.” and “..” segments from the chunk output base URI with the new function f:flatten-path().

Fixed #576. Make sure that bibliography entries have unique (and not possibly duplicate) IDs even when the bibliography entries are loaded from external files.

Fixed #581; handle width=100% and scalefit=1 on media objects.

Added support for different options when dealing with unhandled elements, see $on-unhandled-elements. Fixed #572. Bring the documentation and the code in sync with respect to $on-unhandled-elements.

Fixed #568. Resolved some ambiguity in $refentry-generate-name and $refentry-generate-title.

Fixed #563. Corrected a typo in the locale files.

Accepted a patch with a large number of Python style improvements. Thank you, Rafał!

Accepted a patch to fix a problem when copying namespace-qualified attributes. Thank you, Frank!

Accepted a patch to add a parameter to identify the file containing default templates. Thank you, Frank!

Accepted a patch to support collecting the secondary outputs of internal transforms. Thank you, Frank!

Upgraded Pygments in the test harness to version 2.19.1.

Upgraded a number of dependencies.

A.1.12. Changes in version 2.5.0

Rewrote verbatim handling; fixed #556.

There are a lot of changes to verbatim handling. The code has been refactored and cleaned up significantly. There are a number of backwards-incompatible changes as a result. (Though the goal is that most documents should look substantially the same.)

A bug where db-line in the output didn’t take the starting line number into consideration has been fixed.

Verbatim environments that aren’t numbered no longer have “invisible” line number markup.

The verbatim features are provided using highlight.js and prism as much as is practical.

There are new top-level parameters, $verbatim-embellishments and $verbatim-embellish-linenumbers. These can control embellishments overall and line numbering specifically at a global level. (Apparently, the XSLT 1.0 stylesheets didn’t number verbatim environments by default but when I wrote the xslTNG stylesheets, I did. I’m reluctant to make that backwards-incompatible change, so I’ve added a parameter to get that effect easily.)

The verbatim style and syntax highlighter can be set on per-document basis with a processing instruction.

The f:verbatim-highlight and f:highlight-verbatim functions have been removed. The highlighter, and highligting, are determined by the combination of options. See Section 2.11, “Verbatim environments”.

Added $use-id-as-filename parameter. If true, the xml:id value of a chunk will be used as the chunk filename.

Support xrefstyle on link; fixed #561.

A.1.13. Changes in version 2.4.1

A recent fix for bottom-of-page navigation links broke the persistent ToC navigation link. This release fixes both of those problems simultaneously; fixed #543.

A.1.14. Changes in version 2.4.0

Reworked the main.xsl module to resolve import precedence issues; fixed #536. This change has two visible consequences:

The formatting of command in cmdsynopsis uses span instead of code. This was always the intent; a cmdsynopsis is already monospaced.

The formatting of task elements no longer suppresses the title. I don’t imagine that was intentional, but if you use task elements with titles, make sure you’re getting the results you expect!

It’s also possible that this will have consequences in customization layers, but I don’t think that’s the case.

Added a wrapper around cmdsynopsis; fixed #538. This makes customization of command synopses more practical in CSS.

In the DocBook Python script, pass the Saxon return code back to the shell; fixed #535. Thanks, Frank!

Fixed the CI build issue that was preventing the link to the most recent version of the guide from updating correctly; fixed #534.

A.1.15. Changes in version 2.3.0

The principle new feature in version 2.3.0 is support for landscape (and portrait) rotation in paged media, fixing #476. This entails a lage number of changes to the paged media stylesheets and some markup changes in the HTML output.

The most significant markup change is that elements that appear before the first section of component (before the first section of a chapter, for example) are now wrapped in a div element with the class “db-bfs”. This true in both browser and paged media presentations, though it’s currently unused in the browser presentation.

Another change is that rotated elements will have “landscape” or “portrait” in their class attribute. At present, this has no effect in the browser presentation.

Added support for titleabbrev in bibliography entries; fixed #487. Thanks, Frank!

Added a vendor-weasyprint.css stylesheet for use with the $vendor-css parameter; fixed #497.

Reworked Java initialization; fixed #504. This change is a consequence of how Saxon initializes the XML Resolver.

Support linking on db:arg and db:group elements; fixed #528.

Provided additional class attributes on various flavors of synopsis to enable more precise CSS styling.

A.1.16. Changes in version 2.2.1

Add missing zh-cn localization for “Danger”; fixed #510.

Added Section 3.4, “Customizing title pages”, describing how to customize title pages; fixed #507.

Added support for a numbered DocBook processing instruction pseudo-attribute to control numbering of divisions, components, and sections on a per-element basis; fixed #506. See Section 3.6.1, “Numeration overrides”.

Added $variablelist-panelset to support a “panel set” presentation of variable lists.

Simplified and corrected the selection of bibliography entry abbreviations; fixed #479. Thanks, Frank!

Improved docbook.py script. Thanks, Rafal!

Added support for caption elements in CALS tables; fixed #472.

A.1.17. Changes in version 2.2.0

Support $titleabbrev-passthrough, fixed #469.

Integrated support for automatic glossaries contributed by Frank Steimke. Fixed #453 and #445. Extended to support automatic glossary divisions, fixed #460.

Added support for automatic bibliographies analogous to automatic glossaries.

Integrated documentation improvements contributed by Frank Steimke, fixed #452.

Attempted to work around a scrolling issue in the persistent ToC, fixed #451.

Corrected the image intrinsic functions so that non-integer dimensions are supported in SVG; added support for dimensions with units, fixed #413, #432, and #443.

Allow pre- and post-processing transforms to be specified as command line parameters, fixed #440 and #441

Merged a fix to the German localization contributed by Tom Schraitle, fixed #428.

Make sure $v:debug is declared in print.xsl, fixed #420.

Ensure that subtitle appears on a book titlepage, fixed #415.

Integrated improved support for improved cross reference styles contributed by Frank Steimke, fixed #414.

Merged a patch, contributed by Frank Steimke, to avoid a warning when a table width is exactly the same as the nominal page width, fixed #411.

Corrected an error where column widths computed from CALS tables did not correctly specify units, fixed #410.

A.1.18. Changes in version 2.1.9

Links added with m:head-additions were not being made relative to the chunk base URI. Reworked m:html-body-script slightly so that links there can also be made relative appropriately.

A.1.19. Changes in version 2.1.8

Added m:head-additions mode for customizers. This allows a customization layer to add information to the HTML head.

Added tunnel parameters to the list of titles templates. This allows a customization to determine the parent element of the list of titles. (For example, to format the table of contents for a set differently than for the contained books.)

When formatting a part with a partintro and a list of titles, move the partintro before the list of titles. (This is technically backwards incompatible, but it seems so obviously superior to the current behavior that I’m calling the current behavior a bug.)

Removed incorrect use of v: prefix in the documentation; fixed #406.

Added a $inline-xlink-href parameter to control whether or not XLink href attributes are printed after the link in the paged media stylesheets; fixed #404. Previously, this was handled in two different ways: for simple links, the links where always printed; for extended links, the text were actually added by CSS. Now they’re both controlled by the parameter and CSS is no longer involved.

Hacked PrismJS a bit; added support for ABNF and my own attempt at an Invisible XML highlighter.

Added CSS for lists of titles in sets.

A.1.20. Changes in version 2.1.7

Tweaks to presentation.js to make sure revealed elements are in view.

Tweaks to the bundled PrismJS to support (not especially well) syntax highlighting Invisible XML.

CSS improvements for footnote rendering in paged media.

First attempt to support Vivliostyle for rendering paged media.

A.1.21. Changes in version 2.1.6

Fixed the bug where disabling division, component, or section numbers didn’t change their presentation in Tables of Contents. It’s not especially elegant, the stylesheets simply check if “unnumbered” occurs in the localization group name for the title. If it does, then the unnumbered table of contents template is also selected.

Fixed the bug where chunk navigation wasn’t localized.

A.1.22. Changes in version 2.1.5

Introduced “presentation mode” as a replacement for earlier “slides” and “speaker notes” customizations. Simplified the normal “chunk navigation” processing.

Improved copyright handling on title pages. Removed most CSS page-break-inside: avoid rules. (They cause overflow if the space isn’t big enough.)

Added the ability to put arbitrary CSS properties on elements with attributes in the https://xsltng.docbook.org/ns/css namespace.

Added css to the set of verbatim environment languages that are syntax highlighted by default.

The $output-media is now set to “epub” when formatting EPUBs.

Paged media improvements: removed body margins (they’re provided by the page setup); enabled hyphenation.

Add documentation for the properties in gradle.properties.

Yet even more fussing with the building the distribution on Windows.

A.1.23. Changes in version 2.1.4

Fixed a bug where the Index by module index in the PDF guide ran off the bottom of the page.

Improved the left and right page headers in PDF output.

Fixed (another) bug in $unwrap-paragraphs support.

Fixed a bug where the link for the persistent ToC was not visible. (This started in 2.1.3 when a z-index was added to the page header.)

Added a m:back-cover mode for producing a back cover. By default, this mode produces no output, but it can be changed an a customization layer to produce a cover.

Fixed a few places where the $debug parameter was not being tested correctly. Documented the templates-matches debug flag.

Reworked how the change log is produced; it’s now an appendix rather than attempting to put it between the front cover and the table of contents.

Fixed some navigation issues associated with annotations when JavaScript is being used to display the annotations.

For convenience, the SASS SCSS stylesheets are now in the distribution ZIP archive. These aren’t used at runtime, but if you have plans to make extensive changes to the CSS, deriving those changes from the SASS sources may prove easier than updating the derived CSS directly.

Added CSS variables: default-font-size and default-line-height to simplify customization.

Reworked the title page for articles in books. Previously, they only rendered the title. An article in a book now renders the “full” titlepage that’s consistent with stand-alone articles.

A bunch of build fixes: matrix builds work again, attempting to get the release information uses an authenticated request if it can, an old Xerces implementation pulled in by a transitive dependency is explicitly excluded (it has problems with UTF-16 encoded files, for example on Windows).

A.1.24. Changes in version 2.1.3

Fixed a bug in the handling of the $unwrap-paragraphs parameter. The list of “block” elements understood to be “unwrapped” was incomplete.

Fixed the way title and citetitle are formatted in bibliographies.

Added support for the translate attribute in HTML via the $translate-suppress-elements parameter and the f:translate-attribute() function. Note that these attributes are in the HTML output, so they won’t directly help with translations of the source XML. Apparently, some production toolchains involve translating the published HTML.

Attempt to address problems caused by Oxygen change markup in CALS tables. Deleted cells are now identified in the output (to keep the dimensions of the table valid) rather than removing them.

Fixed the rendering of table footnotes in PDF.

Added support for PDF bookmarks for H1 and H2 headings.

Removed the page-break-inside: avoid property from program listings. The property was causing some program listings to be rendered beyond the bottom of the page in PDF.

CSS has been adjusted in an attempt to avoid extra space below a calloutlist.

Added z-index to avoid problems in fixed navigation headers.

Extended the documentation about Docker and Docker alternatives; improved the Dockerfile, especially with respect to Linux.

There are now two files in the GitHub distribution, the “normal” one and one labeled “nosaxon”. The “nosaxon” ZIP file is the same release, but without a copy of Saxon-HE. This release should be easier to integrate into environments, like <oXygen/>, where a version of Saxon is already provided. (Having two different versions of Saxon can cause problems.)

A fallback version of the “Pygments” CSS file is included in repository. This allows the correct formatting to be achieved even if Pygments (and especially pygmentize) isn’t available locally.

Lots (and lots) of build changes to support building the release on Windows. It’s now at the “works on my machine” stage, but not yet working generally. Specific suggestions welcome.

A few other build improvements. A wholly unsuccessful attempt to use the matrix build in CI.

A variety of typos have been fixed in the guide.

A.1.25. Changes in version 2.1.2

Added a $verbatim-trim-leading-blank-lines parameter. This is analagous to the $verbatim-trim-trailing-blank-lines parameter except for leading blank lines instead of trailing ones. It is false by default, for backwards compatibility, but note that some syntax highlighters may trim leading (and trailing) blank links anyway.

A.1.26. Changes in version 2.1.1

Added a $copy-verbatim-js parameter. This feature creates a dynamic “copy” button on verbatim listings that will copy the text of the listing (without callouts, line annotations, etc.) to the clipboard.

Fixed a minor issue where some spurious namespace declarations were being copied into the HTML output.

A.1.27. Changes in version 2.1.0

This is the first official release of the “2.x” versions of the stylesheets. Version 2.1.0 introduces a number of new features and corrects major issues with localization and media object rendering, but is not entirely backwards compatible with the 1.x versions. The incompatibilities should mostly effect customization layers, not formatted documents, though the HTML output will be a little different in most cases. For a summary of the changes, see Section A.2, “Introduction to xslTNG 2.x”.

A.2. Introduction to xslTNG 2.x

Version 2.x of the DocBook xslTNG Stylesheets include some substantial changes from version 1.x. If you use the stylesheets “out of the box” without any customization, you should have no trouble updating from version 1.x to version 2.1.0 (or later), but there will be differences in the HTML produced. If you have customization layers for 1.x, you may need to change them in order to get the results you expect from 2.x.

The most significant rewrite, and the change that actually motivated the decision to adopt some backwards incompatible changes, is in the area of localization. Version 1.x of the xslTNG stylesheets attempted to simplify (from the preceding XSLT 2.0 stylesheets) how generated text was constructed. The model adopted simply didn’t work for some languages. Trying to adapt the model to support these languages was going to result in something even more complicated than what had worked before, so the model has largely been reverted to what it was before.

The format of the localization data and the way that it’s used are the subject of Chapter 4, Localization. In broad terms, the new system should produce “the same results” as the old system for an equivalent localization, but there may be small changes in the way lists of titles and cross references are formatted.

The major changes are:

Completely reworked how localization is handled. See Chapter 4, Localization. The localization file format has changed. Localization files are no longer simply transformed from the XSLT 1.0 stylesheet format.

Completely reworked how numbering of elements is performed. See Section 3.6, “Controlling numeration”. It’s a bit more complicated now, but it’s also more flexible and better tested. The default numeration should be the same as before, although a few small changes may appear in places where (I think) the previous numeration was wrong.

Completely refactored the way that media objects are located during the transformation and how the URIs for them are generated in the output. It is now possible to store the media objects in a location independent of the source files. Four separate source arrangements are represented in the test suite and each can be processed to produce several different outputs; see the all_mo_tests build target and its dependencies.

Refactored the templates for processing media objects to improve support for accessibility metadata and formatting copyright statements, legal notices, etc. See m:mediaobject-start and m:mediaobject-end.

Fixed the bug where attributes on image, video, audio, and text objects in mediaobject and inlinemediaobject were not being preserved in the output. In particular, this meant that role attributes on those objects were not reflected in the HTML class attribute.

Reworked audio and video fallback. Placing an HTML prose description in the video tag is not the correct approach in modern browsers. That prose is only rendered by browsers that don’t understand the video tag at all. Apparently, it has to be handled by JavaScript. There’s now a $fallback-js parameter.

Support media objects that have no media (e.g., a media object that contains only inline text objects).

Implemented an on-page table of contents feature.

Switched to section elements (instead of div elements) for sections inside of refentry and a number of other places. This supports the new on-page table of contents feature and should have been done when the rest of the sectioning elements were converted.

Reworked ToC handling. Added $auto-toc parameter. The placement of generated lists-of-titles can now be controlled with an empty toc element (or db-toc processing instruction).

Added support for creating ToCs by hand. (Former handling for tocdiv and tocentry was just broken.)

Placement of table titles, before or after the table, is now set with $formal-object-title-placement. For backwards compatibility, it defaults to ‘before’ for tables. Within a formalgroup, title placement is controlled by $formalgroup-nested-object-title-placement. In a related way, the placement of media object details can be set with $mediaobject-details-placement.

Labels for formal objects may be different, but I think the previous formatting was actually in error.

Changed $mediaobject-accessibility and $table-accessibility parameters into space-separated lists of strings.

The parameters for the t:top-nav and t:bottom-nav templates have changed. They are now always called, even when chunking is not being performed. The new $chunk parameter indicates whether or not a chunk is being formatted.

Moved the footer element from just after main to just inside it. This simplifies and improves CSS rendering and is arguably more correct.

Added an $unwrap-paragraphs parameter. If this parameter is true, a single DocBook paragraph that contains block elements (for example, tables or figures) will be rendered as several HTML paragraphs with blocks between them. HTML doesn’t allow blocks inside paragraphs.

Made including the docbook-print.css file conditional on producing print output. Modern browsers attempt to parse the file, even when the link specifies that it’s for print media, and produce a large number of spurious error messages.

Deprecated the m:html-body-script mode. Changed the way the standard scripts are included; instead of putting them at the end of the body element, they’re placed in the head but explicitly marked deferred.

In some contexts, for example callouts, labels are now used for the links instead of titles.

Removed up-arrow from the keys that $chunk-nav responds to. The up-arrow key is used by browser to move up the page and chunk navigation was interfering with that behavior. The U key will still go “up” in chunk navigation.

Reworked the persistent ToC. It can now store the ToC in a separate file. Improved the error messages when the persistent ToC is unavailable.

Changed ext:cwd() so that it always returns an absolute URI. This fixes a bug in chunk output base URI handling. Tidied up some code.

Process unexected elements in titlepage templates in the normal way; removed the warning message associated with them. Add it back by putting templates in $debug.

Improved presentation of multiple keycap elements in a keycombo.

Added table-of-contents to the linear flow of EPUBs. This fixes an epubcheck 3.3 error. Fixed the CSS for the ToC.

Added support for ISO 690 bibliographies via a $bibliography-style parameter.

Added a $message-level parameter to support suppressing some informational messages.

Removed db-footnote attributes from the output. Technically, attribute names that contain a hyphen are HTML5 extension attributes, but sometimes they make validation more difficult. Some extension attributes remain, because they’re used by JavaScript in the presentation for example, but db-footnote isn’t used that way.

Fixed bug where authorgroup wasn’t being processed in biblioentry.

Fixed a bug where orderedlist numeration was not handled correctly in cross-references to list items.

Fixed incorrect URIs for SVG draft overlay in print CSS.

Fixed a bug where the catalog.xml file in the jar file was not at a location where the XML Resolver would find it.

Updated the build system to use Pygments version 2.14.0. This effects the markup produced in some syntax highlighted listings. (You’re free to use any version of Pygments that’s convenient; this is just about conformance with the expected test results.)

The way unit tests are managed has been completely rewritten. See Section 6.5, “Testing tasks”.

Glossary

Clark name

A Clark name is a way of unambiguously representing a qualified name (see XML) as a string. It consists of the namespace name in curly braces followed immediately by the local name. For example, the Clark name for the DocBook para element is: “{http://docbook.org/ns/docbook}para”.

hamburger menu

The “hamburger menu” or “hamburger button” is the name for the “☰” icon often used to indicate a menu of choices.

intrinsic size

The intrinsic size of an object is it’s actual size, measured in absolute units, usually pixels. The stylesheets rely on extension functions to obtain the intrinsic size of objects; if the extension functions aren’t available or the image format is not recognized, no intrinsic size will be known.

is true

XPath defines a boolean type, xs:boolean, that is either true or false. But for the purpose of passing parameters to the stylesheet at runtime, whether it’s from the command line, from a configuration file, or through some other means, it’s often more convenient to pass string values. This saves the user from having to use whatever extra syntactic mechanisms would be required to identify the type of the variable.

To this end, many “boolean” parameters are actually strings. A string value is true if it consists of one of the strings “true”, “yes”, or “1”.

object

In this guide, the term “object” is used to refer generally to any image, video, or audio media element. They have a width and a height but no useful internal structure from the perspective of the stylesheets.

pseudo-attribute

Processing instructions (see XML) have no internal structure. The stylesheets interrogate the db processing instruction to determine formatting properties for a number of different elements.

In order to make it easy to consistently specify different properties, the value of the processing instruction is parsed as if it contained attributes. These pseudo-attributes must consist of a name, followed by “=”, followed by a quoted string.

References

[Antenna House] Antenna House Formatter. Version 7.0.3.

[ISO 8601] ISO 8601-1:2019 Date and time — Representations for information interchange — Part 1: Basic rules. ISO (International Organization for Standardization). 2019-02.

[CSS] What Is CSS?. A family of standards developed by the W3C.

[TR 9901:1999] XML Exchange Table Model Document Type Definition. Organization for the Advancement of Structured Information Standards (OASIS) Technical Memorandum TR 9901:1999. Tables Technical Committee. Norman Walsh, editor.

[TR 9502:1995] CALS Table Model Document Type Definition. SGML Open Technical Memorandum TM 9502:1995. Table Interchange Subcommittee. Harvey Bingham, editor.

[Gradle] Gradle.

[RFC 5147] URI Fragment Identifiers for the text/plain Media Type. E. Wilde and M. Duerst, editors. Internet Engineering Task Force. 2008.

[MathJax] MathJax.

[OldMeasure] The Old Measure: An Inquiry Into the Origins of the U.S. Customary System of Weights and Measures. 2010. Jon Bosak.

[Prince] Prince. Version 13.5.

[Transclusion] DocBook Transclusion. 2015. Jirka Koskek.

[Names] Falsehoods Programmers Believe About Names. 2010. Patrick McKenzie.

[XML] Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, and Eve Maler, editors. Extensible Markup Language (XML) 1.0 Fifth Edition. World Wide Web Consortium, 2008.

[XInclude] Jonathan Marsh, David Orchard, and Daniel Veillard, editors. XML Inclusions (XInclude) Version 1.0 (Second Edition). World Wide Web Consortium, 2006.

[Pygments] Pygments: Python Syntax Highlighter. Version 2.6.1.

[highlight.js] highlight.js. Version 10.1.2.

[Prism] Prism. Version 1.20.0.

[metadata-extractor] metadata-extractor. Version 2.14.0.

[search] Searching text/plain documents with a fragid.

[XSLT 1.0] XSL Transformations (XSLT) Version 1.0. James Clark, editor. W3C Recommendation. 16 November 1999.

[XSLT 2.0] XSL Transformations (XSLT) Version 2.0. Michael Kay, editor. W3C Recommendation. 23 January 2007.

[XSLT 3.0] XSL Transformations (XSLT) Version 3.0. Michael Kay, editor. W3C Recommendation. 8 June 2017.

[XSL FO] Extensible Stylesheet Language (XSL) Version 1.1. Anders Berglund, Editor. W3C Recommendation. 5 December 2006.

Acknowledgements

I’d like to thank The Academy, the…no, wrong event.

DocBook has benefited immeasurably by the time and energy that innumerable people have poured into it. I thank them all.

This project has benefited from the generous support of Michael Kay and Saxonica for Saxon EE and Micheal Miller and Antenna House for Antenna House Formatter.

Bethan Tovey-Walsh designed the lovely xslTNG logo.

Index

D

db processing instruction, 1, 1, 2, 1, 2, 1, 1, 1, 1, 1, 1, 1, 1

filename pseudo-attribute, 1

verbatim-style pseudo-attribute, 1

syntax-highlighter pseudo-attribute, 1

verbatim-numbered pseudo-attribute, 1

verbatim-highlight pseudo-attribute, 1

linenumbering-minlines pseudo-attribute, 1

verbatim-trim-leading pseudo-attribute, 1

verbatim-trim-trailing pseudo-attribute, 1

numbered pseudo-attribute, 1

glossary-collection pseudo-attribute, 1

bibliography-collection pseudo-attribute, 1

P

param

resource-base-uri, 1

chunk, 1

chunk-output-base-uri, 1

chunk-include, 1, 1, 2

chunk-exclude, 1, 1, 2

persistent-toc, 1, 1

chunk-nav, 1, 1, 1

use-id-as-filename, 1, 1

profile-os, 1, 1

profile-arch, 1

profile-audience, 1

profile-condition, 1

profile-conformance, 1

profile-lang, 1

profile-outputformat, 1

profile-revision, 1

profile-revisionflag, 1

profile-role, 1

profile-security, 1

profile-userlevel, 1

profile-vendor, 1

profile-wordsize, 1

profile-separator, 1, 2

dynamic-profiles, 1

verbatim-embellishments, 1, 1

verbatim-embellish-linenumbers, 1, 1

verbatim-numbered-elements, 1, 1

verbatim-table-style, 1

verbatim-line-style, 1

verbatim-plain-style, 1

verbatim-callouts, 1

verbatim-number-minlines, 1

verbatim-trim-leading-blank-lines, 1, 1

verbatim-trim-trailing-blank-lines, 1, 1

auto-toc, 1, 2, 1

lists-of-figures, 1

lists-of-tables, 1

lists-of-examples, 1

lists-of-equations, 1

lists-of-procedures, 1

persistent-toc-css, 1, 1

persistent-toc-search, 1

persistent-toc-filename, 1, 2, 3

pagetoc-elements, 1

pagetoc-dynamic, 1

pagetoc-js, 1

vendor-css, 1, 2, 3, 1

output-media, 1, 2, 1

align-char-processing, 1

verbatim-syntax-highlight-css, 1

use-docbook-css, 1

user-css-links, 1

sets-number-from, 1

books-number-from, 1

divisions-number-from, 1

components-number-from, 1

sections-number-from, 1

formal-objects-number-from, 1

sets-inherit-from, 1

books-inherit-from, 1

divisions-inherit-from, 1

components-inherit-from, 1

sections-inherit-from, 1

formal-objects-inherit-from, 1

division-numbers, 1, 1

component-numbers, 1, 1

section-numbers, 1, 1

formal-object-numbers, 1, 1

use-label-numeration, 1, 2, 1

glossary-collection, 1

glossary-sort-entries, 1

glossary-automatic-divisions, 1

bibliography-collection, 1

nominal-page-width, 1

pixels-per-inch, 1

verbatim-number-separator, 1

mediaobject-input-base-uri, 1, 1, 2, 3

mediaobject-output-base-uri, 1, 1, 2, 3

mediaobject-percentage-of-intrinsic-size, 1, 1, 2, 3

mediaobject-exclude-extensions, 1

mediaobject-output-paths, 1

default-templates-uri, 1

annotation-placement, 1

relax-ng-grammar, 1

oxy-markup, 1

transform-original, 1

transform-before, 1, 2

transform-after, 1

prefer-xrefstyle, 1

mathml-js-role, 1

label-wrapper, 1

titleabbrev-passthrough, 1, 1

user-document-class, 1

on-unhandled-elements, 1, 2

refentry-generate-name, 1

refentry-generate-title, 1

variablelist-panelset, 1

inline-xlink-href, 1

unwrap-paragraphs, 1, 1, 1

debug, 1, 1

translate-suppress-elements, 1

copy-verbatim-js, 1

fallback-js, 1

formal-object-title-placement, 1

formalgroup-nested-object-title-placement, 1

mediaobject-details-placement, 1

mediaobject-accessibility, 1

table-accessibility, 1

bibliography-style, 1

message-level, 1

V

variable

v:templates, 1, 2

v:localization-base-uri, 1

v:custom-localizations, 1, 2

v:user-title-groups, 1, 1, 2

v:user-xref-groups, 1, 1

v:unit-scale, 1

v:standard-transforms, 1

v:debug, 1

Index by module

Many modules define related functions, templates, or variables.

../standalone-functions.xsl

f:available-bibliographies(), f:available-bibliographies(), f:available-glossaries(), f:available-glossaries(), f:biblioentries(), f:biblioentries(), f:citations(), f:citations(), f:flatten-path(), f:glossentries(), f:glossentries(), f:glossrefs(), f:glossrefs(), f:pi(), f:pi(), f:pi-attributes(), $v:pi-db-attributes-are-uris

VERSION.xsl

$v:VERSION, $v:VERSION-ID

highlight.xsl

f:syntax-highlight(), f:syntax-highlight(), f:syntax-highlight()

main.xsl

m:docbook, $output-media

modules/admonitions.xsl

m:docbook

modules/annotations.xsl

m:annotation-content, m:docbook

modules/attributes.xsl

m:attributes, m:docbook

modules/biblio690.xsl

m:biblio690

modules/bibliography.xsl

m:biblioentry, m:bibliomixed, m:docbook

modules/blocks.xsl

m:docbook, m:revhistory-list, m:revhistory-table, m:toc

modules/chunk-cleanup.xsl

t:bottom-nav, m:chunk-cleanup, t:chunk-footnotes, m:chunk-title, f:chunk-title(), m:footnote-number, m:mediaobject-output-adjust, t:top-nav

modules/chunk-output.xsl

m:chunk-output

modules/chunk.xsl

f:chunk(), m:chunk-filename, f:chunk-filename()

modules/components.xsl

m:docbook

modules/divisions.xsl

m:back-cover, m:docbook

modules/errors.xsl

$dbe:DYNAMIC-PROFILE-EVAL-ERROR, $dbe:DYNAMIC-PROFILE-SYNTAX-ERROR, $dbe:INTERNAL-HIGHLIGHT-ERROR, $dbe:INTERNAL-RENUMBER-ERROR, $dbe:INVALID-AREAREFS, $dbe:INVALID-CALS, $dbe:INVALID-CONSTRAINT, $dbe:INVALID-DYNAMIC-PROFILE-ERROR, $dbe:INVALID-INJECT, $dbe:INVALID-NAME-STYLE, $dbe:INVALID-PRODUCTIONRECAP, $dbe:INVALID-RESULTS-REQUESTED, $dbe:INVALID-TEMPLATE, $dbe:INVALID-TRANSFORM

modules/footnotes.xsl

m:docbook, m:footnote-number, m:footnotes, t:table-footnotes

modules/functions.xsl

f:attributes(), f:attributes(), f:conditional-orientation-class(), f:date-format(), f:generate-id(), f:generate-id(), f:gentext-letters(), f:gentext-letters-for-language(), f:global-syntax-highlighter(), f:href(), f:id(), f:is-true(), f:l10n-language(), f:label-separator(), f:orderedlist-item-number(), f:orderedlist-item-numeration(), f:orderedlist-startingnumber(), f:orientation-class(), f:refsection(), f:relative-path(), f:section(), f:section-depth(), f:spaces(), f:step-number(), f:step-numeration(), f:target(), f:tokenize-on-char(), f:translate-attribute(), f:unique-id(), f:uri-scheme()

modules/gentext.xsl

m:gentext, f:in-scope-language(), f:languages()

modules/glossary.xsl

m:docbook, t:glossary-divisions

modules/head.xsl

m:head-additions, m:html-body-script, m:html-head, m:html-head-last, m:html-head-links, m:html-head-script

modules/index.xsl

m:docbook, t:generate-index, m:index-div, m:index-primary, m:index-secondary, m:index-see, m:index-seealso, m:index-tertiary, t:index-zone-reference

modules/info.xsl

m:copyright-years, m:docbook, t:person-name, t:person-name-family-given, t:person-name-first-last, t:person-name-last-first, t:person-name-list, m:to-uppercase

modules/inlines.xsl

m:docbook, t:inline

modules/l10n.xsl

m:docbook, m:gentext-list, f:l10n-token(), f:l10n-token()

modules/links.xsl

m:docbook, m:link

modules/lists.xsl

m:callout-link, m:docbook, m:panelset, m:seglist-table, m:segtitle-in-seg

modules/msgset.xsl

m:docbook

modules/objects.xsl

f:css-length(), f:css-property(), m:details, m:docbook, m:imagemap, f:mediaobject-amend-uri(), m:mediaobject-end, t:mediaobject-img, m:mediaobject-info, f:mediaobject-input-base-uri(), m:mediaobject-start, f:mediaobject-type(), m:mediaobject-uris, t:mediaobject-viewport, f:object-align(), f:object-contentheight(), f:object-contentwidth(), f:object-height(), f:object-properties(), f:object-properties(), f:object-scale(), f:object-scalefit(), f:object-valign(), f:object-width()

modules/programming.xsl

m:ansi, m:ansi-table, m:docbook, m:kr, m:kr-args, m:kr-table, m:kr-table-args, m:production-number, m:synopfragment-bug, m:synopsis

modules/publishers.xsl

m:docbook

modules/refentry.xsl

m:docbook

modules/sections.xsl

$v:bridgehead-map, m:docbook

modules/tablecals.xsl

f:cals-colsep(), f:cals-rowsep(), m:docbook,

modules/tablehtml.xsl

m:docbook, m:htmltable

modules/templates.xsl

t:biblioentry, m:docbook, m:generate-titlepage, f:template(), $v:templates, $v:titlepage-default

modules/titlepage.xsl

m:titlepage

modules/titles.xsl

m:docbook, m:headline, m:headline-label, m:headline-number, m:headline-title, m:title, $v:title-groups, $v:user-title-groups

modules/toc.xsl

m:docbook, m:list-of-equations, m:list-of-examples, m:list-of-figures, m:list-of-procedures, m:list-of-tables, m:list-of-titles, m:persistent-toc, m:toc, m:toc-entry, m:toc-nested

modules/unhandled.xsl

m:docbook

modules/units.xsl

f:absolute-length(), f:empty-length(), f:equal-lengths(), f:is-empty-length(), f:length-string(), f:length-units(), f:make-length(), f:make-length(), f:make-length(), f:parse-length(), f:relative-length(), $v:unit-scale

modules/variable.xsl

$v:admonition-icons, $v:annotation-close, $v:arg-choice-def-close-str, $v:arg-choice-def-open-str, $v:arg-choice-opt-close-str, $v:arg-choice-opt-open-str, $v:arg-choice-plain-close-str, $v:arg-choice-plain-open-str, $v:arg-choice-req-close-str, $v:arg-choice-req-open-str, $v:arg-or-sep, $v:arg-rep-def-str, $v:arg-rep-norepeat-str, $v:arg-rep-repeat-str, $v:as-json, $v:as-xml, $v:chunk, $v:chunk-filter-namespaces, $v:chunk-renumber-footnotes, $v:custom-localizations, $v:debug, $v:formal-object-title-placement, $v:formalgroup-nested-object-title-placement, $v:highlight-js-head-elements, $v:image-nominal-height, $v:image-nominal-width, $v:localization-base-uri, $v:mathml-js-roles, $v:media-type-default, $v:media-type-map, $v:mediaobject-details-placement, $v:mediaobject-exclude-extensions, $v:mediaobject-output-base-uri, $v:nominal-page-width, $v:olink-databases, $v:personal-name-styles, $v:prism-js-head-elements, $v:theme-list, $v:toc-close, $v:toc-open, $v:verbatim-callouts, $v:verbatim-line-style, $v:verbatim-number-every-nth, $v:verbatim-number-first-line, $v:verbatim-number-minlines, $v:verbatim-numbered-elements, $v:verbatim-plain-style, $v:verbatim-space, $v:verbatim-syntax-highlight-languages, $v:verbatim-syntax-highlight-options, $v:verbatim-syntax-highlight-pygments-options, $v:verbatim-table-style

modules/verbatim.xsl

m:callout-bug, m:docbook, m:highlight-options, $v:invisible-characters, m:pygments-options, f:verbatim-callout(), f:verbatim-numbered(), $v:verbatim-properties, f:verbatim-style(), f:verbatim-syntax-highlighter(), f:verbatim-trim-leading(), f:verbatim-trim-trailing()

modules/xlink.xsl

m:docbook, t:xlink, f:xlink-style(), f:xpointer-idref()

modules/xref.xsl

m:crossref, m:crossref-label, m:crossref-number, m:crossref-number-separator, m:crossref-suffix, m:crossref-title, m:docbook, $v:user-xref-groups, $v:xref-groups

param.xsl

$additional-languages, $align-char-default, $align-char-pad, $align-char-processing, $align-char-width, $allow-eval, $annotate-toc, $annotation-collection, $annotation-mark, $annotation-placement, $annotation-style, $annotations-js, $auto-toc, $bibliography-collection, $bibliography-style, $books-inherit-from, $books-number-from, $callout-default-column, $callout-unicode-start, $cals-table-width-threshold, $chunk, $chunk-exclude, $chunk-include, $chunk-nav, $chunk-nav-js, $chunk-output-base-uri, $chunk-renumber-footnotes, $chunk-section-depth, $classsynopsis-indent, $component-numbers, $component-numbers-inherit, $components-inherit-from, $components-number-from, $control-js, $copy-verbatim-js, $copyright-collapse-years, $copyright-year-range-separator, $copyright-year-separator, $cos-number-from, $date-date-format, $date-dateTime-format, $dc-metadata, $debug, $default-float-style, $default-language, $default-length-magnitude, $default-length-unit, $default-templates-uri, $default-theme, $division-numbers, $division-numbers-inherit, $divisions-inherit-from, $divisions-number-from, $docbook-transclusion, $dynamic-profile-error, $dynamic-profile-variables, $dynamic-profiles, $experimental-pmuj, $fallback-js, $footnote-numeration, $formal-object-numbers, $formal-object-title-placement, $formal-objects-inherit-from, $formal-objects-number-from, $formalgroup-nested-object-title-placement, $funcsynopsis-default-style, $funcsynopsis-table-threshold, $funcsynopsis-trailing-punctuation, $generate-html-page, $generate-index, $generate-nested-toc, $generate-toc, $generate-trivial-toc, $generated-id-root, $generated-id-sep, $generator-metadata, $gentext-language, $glossary-automatic-divisions, $glossary-collection, $glossary-sort-entries, $html-extension, $image-ignore-scaling, $image-nominal-height, $image-nominal-width, $image-property-warning, $index-on-role, $index-on-type, $index-show-entries, $indexed-section-groups, $inline-xlink-href, $label-wrapper, $lists-of-equations, $lists-of-examples, $lists-of-figures, $lists-of-procedures, $lists-of-tables, $local-conventions, $mathml-js, $mathml-js-config, $mathml-js-role, $mediaobject-accessibility, $mediaobject-details-placement, $mediaobject-exclude-extensions, $mediaobject-grouped-by-type, $mediaobject-input-base-uri, $mediaobject-output-base-uri, $mediaobject-output-paths, $mediaobject-percentage-of-intrinsic-size, $mediaobject-video-element, $message-level, $nominal-page-width, $number-single-appendix, $olink-databases, $on-unhandled-elements, $orderedlist-item-numeration, $othername-in-middle, $output-media, $oxy-markup, $page-style, $pagetoc-dynamic, $pagetoc-elements, $pagetoc-js, $paper-size, $persistent-toc, $persistent-toc-css, $persistent-toc-filename, $persistent-toc-js, $persistent-toc-search, $personal-name-style, $pixels-per-inch, $prefer-xrefstyle, $presentation-css, $presentation-js, $presentation-mode, $procedure-step-numeration, $productionset-lhs-rhs-separator, $profile-arch, $profile-audience, $profile-condition, $profile-conformance, $profile-lang, $profile-os, $profile-outputformat, $profile-revision, $profile-revisionflag, $profile-role, $profile-security, $profile-separator, $profile-userlevel, $profile-vendor, $profile-wordsize, $qandadiv-default-toc, $qandaset-default-label, $qandaset-default-toc, $refentry-generate-name, $refentry-generate-title, $relax-ng-grammar, $resource-base-uri, $revhistory-style, $section-numbers, $section-numbers-inherit, $section-toc-depth, $sections-inherit-from, $sections-number-from, $segmentedlist-style, $sets-inherit-from, $sets-number-from, $show-remarks, $sidebar-as-aside, $sort-collation, $table-accessibility, $table-footnote-numeration, $theme-picker, $titleabbrev-passthrough, $transclusion-id-fixup, $transclusion-link-scope, $transclusion-prefix-separator, $transclusion-suffix, $transform-after, $transform-before, $transform-original, $transformed-docbook-input, $transformed-docbook-output, $translate-suppress-elements, $unwrap-paragraphs, $use-docbook-css, $use-id-as-filename, $use-label-numeration, $use-minified-css, $user-css-links, $user-document-class, $variablelist-panelset, $variablelist-termlength-threshold, $varlistentry-separate-terms, $vendor-css, $verbatim-callouts, $verbatim-default-language, $verbatim-embellish-linenumbers, $verbatim-embellishments, $verbatim-line-style, $verbatim-number-every-nth, $verbatim-number-first-line, $verbatim-number-minlines, $verbatim-number-separator, $verbatim-numbered-elements, $verbatim-plain-style, $verbatim-space, $verbatim-style-default, $verbatim-syntax-highlight-css, $verbatim-syntax-highlight-languages, $verbatim-syntax-highlighter, $verbatim-table-style, $verbatim-trim-leading-blank-lines, $verbatim-trim-trailing-blank-lines, $warn-about-missing-localizations, $xlink-arclist-after, $xlink-arclist-before, $xlink-arclist-sep, $xlink-arclist-titlesep, $xlink-icon-closed, $xlink-icon-open, $xlink-js, $xlink-style, $xlink-style-default, $xspec

Part II. Reference

Table of Contents

I. Parameter reference

$additional-languages

$align-char-*

$allow-eval

$annotate-toc

$annotation-collection

$annotation-mark

$annotation-placement

$annotation-style

$annotations-js

$auto-toc

$bibliography-collection

$bibliography-style

$books-inherit-from

$books-number-from

$callout-default-column

$callout-unicode-start

$cals-table-width-threshold

$chunk

$chunk-exclude

$chunk-include

$chunk-nav

$chunk-nav-js

$chunk-output-base-uri

$chunk-renumber-footnotes

$chunk-section-depth

$classsynopsis-indent

$component-numbers

$component-numbers-inherit

$components-inherit-from

$components-number-from

$control-js

$copy-verbatim-js

$copyright-collapse-years

$copyright-year-range-separator

$copyright-year-separator

$cos-number-from

$date-date-format, $date-dateTime-format

$dc-metadata

$debug

$default-float-style

$default-language

$default-length-magnitude, $default-length-unit

$default-templates-uri

$default-theme

$division-numbers

$division-numbers-inherit

$divisions-inherit-from

$divisions-number-from

$docbook-transclusion

$dynamic-profile-error

$dynamic-profile-variables

$dynamic-profiles

$experimental-pmuj

$fallback-js

$footnote-numeration

$formal-object-numbers

$formal-object-title-placement

$formal-objects-inherit-from

$formal-objects-number-from

$formalgroup-nested-object-title-placement

$funcsynopsis-default-style

$funcsynopsis-table-threshold

$funcsynopsis-trailing-punctuation

$generate-html-page

$generate-index

$generate-nested-toc

$generate-toc

$generate-trivial-toc

$generated-id-root

$generated-id-sep

$generator-metadata

$gentext-language

$glossary-automatic-divisions

$glossary-collection

$glossary-sort-entries

$html-extension

$image-ignore-scaling

$image-nominal-height

$image-nominal-width

$image-property-warning

$index-on-role, $index-on-type

$index-show-entries

$indexed-section-groups

$inline-xlink-href

$label-wrapper

$lists-of-equations

$lists-of-examples

$lists-of-figures

$lists-of-procedures

$lists-of-tables

$local-conventions

$mathml-js

$mathml-js-config

$mathml-js-role

$mediaobject-accessibility

$mediaobject-details-placement

$mediaobject-exclude-extensions

$mediaobject-grouped-by-type

$mediaobject-input-base-uri

$mediaobject-output-base-uri

$mediaobject-output-paths

$mediaobject-percentage-of-intrinsic-size

$mediaobject-video-element

$message-level

$nominal-page-width

$number-single-appendix

$olink-databases

$on-unhandled-elements

$orderedlist-item-numeration

$othername-in-middle

$output-media

$oxy-markup

$page-style

$pagetoc-dynamic

$pagetoc-elements

$pagetoc-js

$paper-size

$persistent-toc

$persistent-toc-css

$persistent-toc-filename

$persistent-toc-js

$persistent-toc-search

$personal-name-style

$pixels-per-inch

$prefer-xrefstyle

$presentation-css

$presentation-js

$presentation-mode

$procedure-step-numeration

$productionset-lhs-rhs-separator

$profile-arch

$profile-audience

$profile-condition

$profile-conformance

$profile-lang

$profile-os

$profile-outputformat

$profile-revision

$profile-revisionflag

$profile-role

$profile-security

$profile-separator

$profile-userlevel

$profile-vendor

$profile-wordsize

$qandadiv-default-toc

$qandaset-default-label

$qandaset-default-toc

$refentry-generate-name

$refentry-generate-title

$relax-ng-grammar

$resource-base-uri

$revhistory-style

$section-numbers

$section-numbers-inherit

$section-toc-depth

$sections-inherit-from

$sections-number-from

$segmentedlist-style

$sets-inherit-from

$sets-number-from

$show-remarks

$sidebar-as-aside

$sort-collation

$table-accessibility

$table-footnote-numeration

$theme-picker

$titleabbrev-passthrough

$transclusion-id-fixup

$transclusion-link-scope

$transclusion-prefix-separator

$transclusion-suffix

$transform-after

$transform-before

$transform-original

$transformed-docbook-input

$transformed-docbook-output

$translate-suppress-elements

$unwrap-paragraphs

$use-docbook-css

$use-id-as-filename

$use-label-numeration

$use-minified-css

$user-css-links

$user-document-class

$variablelist-panelset

$variablelist-termlength-threshold

$varlistentry-separate-terms

$vendor-css

$verbatim-callouts

$verbatim-default-language

$verbatim-embellish-linenumbers

$verbatim-embellishments

$verbatim-line-style

$verbatim-number-every-nth

$verbatim-number-first-line

$verbatim-number-minlines

$verbatim-number-separator

$verbatim-numbered-elements

$verbatim-plain-style

$verbatim-space

$verbatim-style-default

$verbatim-syntax-highlight-css

$verbatim-syntax-highlight-languages

$verbatim-syntax-highlighter

$verbatim-table-style

$verbatim-trim-leading-blank-lines

$verbatim-trim-trailing-blank-lines

$warn-about-missing-localizations

$xlink-arclist-after

$xlink-arclist-before

$xlink-arclist-sep

$xlink-arclist-titlesep

$xlink-icon-closed

$xlink-icon-open

$xlink-js

$xlink-style

$xlink-style-default

$xspec

II. Variables reference

$arg-choice-def-close-str, …

$err:DYNAMIC-PROFILE-EVAL-ERROR

$err:DYNAMIC-PROFILE-SYNTAX-ERROR

$err:INTERNAL-HIGHLIGHT-ERROR

$err:INTERNAL-RENUMBER-ERROR

$err:INVALID-AREAREFS

$err:INVALID-CALS

$err:INVALID-CONSTRAINT

$err:INVALID-DYNAMIC-PROFILE-ERROR

$err:INVALID-INJECT

$err:INVALID-NAME-STYLE

$err:INVALID-PRODUCTIONRECAP

$err:INVALID-RESULTS-REQUESTED

$err:INVALID-TEMPLATE

$err:INVALID-TRANSFORM

$v:personal-name-styles

$v:VERSION

$v:VERSION-ID

$v:admonition-icons

$v:annotation-close

$v:as-json

$v:as-xml

$v:bridgehead-map

$v:chunk

$v:chunk-filter-namespaces

$v:chunk-renumber-footnotes

$v:custom-localizations

$v:debug

$v:formal-object-title-placement

$v:formalgroup-nested-object-title-placement

$v:highlight-js-head-elements

$v:image-nominal-height

$v:image-nominal-width

$v:invisible-characters

$v:localization-base-uri

$v:mathml-js-roles

$v:media-type-default

$v:media-type-map

$v:mediaobject-details-placement

$v:mediaobject-exclude-extensions

$v:mediaobject-input-base-uri

$v:mediaobject-output-base-uri

$v:nominal-page-width

$v:olink-databases

$v:pi-db-attributes-are-uris

$v:prism-js-head-elements

$v:standard-transforms

$v:templates

$v:theme-list

$v:title-groups

$v:title-properties

$v:titlepage-default

$v:toc-close

$v:toc-open

$v:unit-scale

$v:user-title-groups

$v:user-title-properties

$v:user-xref-groups

$v:user-xref-properties

$v:verbatim-callouts

$v:verbatim-line-style

$v:verbatim-number-every-nth

$v:verbatim-number-first-line

$v:verbatim-number-minlines

$v:verbatim-numbered-elements

$v:verbatim-plain-style

$v:verbatim-properties

$v:verbatim-space

$v:verbatim-syntax-highlight-languages

$v:verbatim-syntax-highlight-options

$v:verbatim-syntax-highlight-pygments-options

$v:verbatim-table-style

$v:xref-groups

$v:xref-properties

III. Function reference

ext:cwd

ext:image-metadata

ext:image-properties

ext:pygmentize

ext:pygmentize-available

ext:validate-with-relax-ng

ext:xinclude

f:absolute-length

f:attributes

f:available-bibliographies

f:available-glossaries

f:biblioentries

f:cals-colsep

f:cals-rowsep

f:check-gentext

f:chunk

f:chunk-filename

f:chunk-title

f:citations

f:conditional-orientation-class

f:css-length

f:css-property

f:date-format

f:empty-length

f:equal-lengths

f:flatten-path

f:generate-id

f:gentext

f:gentext-letters

f:gentext-letters-for-language

f:global-syntax-highlighter

f:glossentries

f:glossrefs

f:href

f:id

f:in-scope-language

f:intra-number-separator

f:is-empty-length

f:is-true

f:l10n-language

f:l10n-token

f:label-separator

f:language

f:languages

f:length-string

f:length-units

f:locales

f:make-length

f:mediaobject-amend-uri

f:mediaobject-input-base-uri

f:mediaobject-type

f:number-separator

f:object-align

f:object-contentheight

f:object-contentwidth

f:object-height

f:object-properties

f:object-scale

f:object-scalefit

f:object-valign

f:object-width

f:orderedlist-item-number

f:orderedlist-item-numeration

f:orderedlist-startingnumber

f:orientation-class

f:parse-length

f:pi

f:pi-attributes

f:post-label-punctuation

f:refsection

f:relative-length

f:relative-path

f:section

f:section-depth

f:spaces

f:step-number

f:step-numeration

f:syntax-highlight

f:target

f:template

f:tokenize-on-char

f:translate-attribute

f:unique-id

f:uri-scheme

f:verbatim-callout

f:verbatim-numbered

f:verbatim-style

f:verbatim-syntax-highlighter

f:verbatim-trim-leading

f:verbatim-trim-trailing

f:xlink-style

f:xpointer-idref

IV. Template reference

t:audio-fallback

t:biblioentry

t:bottom-nav

t:chunk-cleanup

t:chunk-footnotes

t:chunk-output

t:docbook

t:generate-index

t:glossary-divisions

t:index-zone-reference

t:inline

t:mediaobject-img

t:mediaobject-viewport

t:person-name

t:person-name-family-given

t:person-name-first-last

t:person-name-last-first

t:person-name-list

t:table-footnotes

t:top-nav

t:video-fallback

t:xlink

V. Mode reference

m:annotation-content

m:ansi

m:ansi-table

m:attributes

m:back-cover

m:biblio690

m:biblioentry

m:bibliomixed

m:callout-bug

m:callout-link

m:chunk-cleanup

m:chunk-filename

m:chunk-output

m:chunk-title

m:chunk-write

m:copyright-years

m:crossref

m:crossref-inherit-separator

m:crossref-label

m:crossref-label-separator

m:crossref-number

m:crossref-number-separator

m:crossref-prefix

m:crossref-suffix

m:crossref-title

m:details

m:details-attribute

m:docbook

m:footnote-number

m:footnotes

m:generate-titlepage

m:gentext

m:gentext-list

m:head-additions

m:headline

m:headline-label

m:headline-label-separator

m:headline-number

m:headline-number-separator

m:headline-prefix

m:headline-suffix

m:headline-title

m:highlight-options

m:html-body-script

m:html-head

m:html-head-last

m:html-head-links

m:html-head-script

m:htmltable

m:imagemap

m:index-div

m:index-primary

m:index-secondary

m:index-see

m:index-seealso

m:index-tertiary

m:kr

m:kr-args

m:kr-table

m:kr-table-args

m:link

m:list-of-equations

m:list-of-examples

m:list-of-figures

m:list-of-procedures

m:list-of-tables

m:list-of-titles

m:mediaobject-end

m:mediaobject-info

m:mediaobject-output-adjust

m:mediaobject-start

m:mediaobject-uris

m:panelset

m:persistent-toc

m:production-number

m:pygments-options

m:revhistory-list

m:revhistory-table

m:seglist-table

m:segtitle-in-seg

m:synopfragment-bug

m:synopsis

m:title

m:titlepage

m:to-uppercase

m:toc

m:toc-entry

m:toc-nested

m:unhandled

VI. Processing instruction reference

DocBook-xslTNG-version

current-dateTime

db

system-property

I. Parameter reference

Table of Contents

$additional-languages

$align-char-*

$allow-eval

$annotate-toc

$annotation-collection

$annotation-mark

$annotation-placement

$annotation-style

$annotations-js

$auto-toc

$bibliography-collection

$bibliography-style

$books-inherit-from

$books-number-from

$callout-default-column

$callout-unicode-start

$cals-table-width-threshold

$chunk

$chunk-exclude

$chunk-include

$chunk-nav

$chunk-nav-js

$chunk-output-base-uri

$chunk-renumber-footnotes

$chunk-section-depth

$classsynopsis-indent

$component-numbers

$component-numbers-inherit

$components-inherit-from

$components-number-from

$control-js

$copy-verbatim-js

$copyright-collapse-years

$copyright-year-range-separator

$copyright-year-separator

$cos-number-from

$date-date-format, $date-dateTime-format

$dc-metadata

$debug

$default-float-style

$default-language

$default-length-magnitude, $default-length-unit

$default-templates-uri

$default-theme

$division-numbers

$division-numbers-inherit

$divisions-inherit-from

$divisions-number-from

$docbook-transclusion

$dynamic-profile-error

$dynamic-profile-variables

$dynamic-profiles

$experimental-pmuj

$fallback-js

$footnote-numeration

$formal-object-numbers

$formal-object-title-placement

$formal-objects-inherit-from

$formal-objects-number-from

$formalgroup-nested-object-title-placement

$funcsynopsis-default-style

$funcsynopsis-table-threshold

$funcsynopsis-trailing-punctuation

$generate-html-page

$generate-index

$generate-nested-toc

$generate-toc

$generate-trivial-toc

$generated-id-root

$generated-id-sep

$generator-metadata

$gentext-language

$glossary-automatic-divisions

$glossary-collection

$glossary-sort-entries

$html-extension

$image-ignore-scaling

$image-nominal-height

$image-nominal-width

$image-property-warning

$index-on-role, $index-on-type

$index-show-entries

$indexed-section-groups

$inline-xlink-href

$label-wrapper

$lists-of-equations

$lists-of-examples

$lists-of-figures

$lists-of-procedures

$lists-of-tables

$local-conventions

$mathml-js

$mathml-js-config

$mathml-js-role

$mediaobject-accessibility

$mediaobject-details-placement

$mediaobject-exclude-extensions

$mediaobject-grouped-by-type

$mediaobject-input-base-uri

$mediaobject-output-base-uri

$mediaobject-output-paths

$mediaobject-percentage-of-intrinsic-size

$mediaobject-video-element

$message-level

$nominal-page-width

$number-single-appendix

$olink-databases

$on-unhandled-elements

$orderedlist-item-numeration

$othername-in-middle

$output-media

$oxy-markup

$page-style

$pagetoc-dynamic

$pagetoc-elements

$pagetoc-js

$paper-size

$persistent-toc

$persistent-toc-css

$persistent-toc-filename

$persistent-toc-js

$persistent-toc-search

$personal-name-style

$pixels-per-inch

$prefer-xrefstyle

$presentation-css

$presentation-js

$presentation-mode

$procedure-step-numeration

$productionset-lhs-rhs-separator

$profile-arch

$profile-audience

$profile-condition

$profile-conformance

$profile-lang

$profile-os

$profile-outputformat

$profile-revision

$profile-revisionflag

$profile-role

$profile-security

$profile-separator

$profile-userlevel

$profile-vendor

$profile-wordsize

$qandadiv-default-toc

$qandaset-default-label

$qandaset-default-toc

$refentry-generate-name

$refentry-generate-title

$relax-ng-grammar

$resource-base-uri

$revhistory-style

$section-numbers

$section-numbers-inherit

$section-toc-depth

$sections-inherit-from

$sections-number-from

$segmentedlist-style

$sets-inherit-from

$sets-number-from

$show-remarks

$sidebar-as-aside

$sort-collation

$table-accessibility

$table-footnote-numeration

$theme-picker

$titleabbrev-passthrough

$transclusion-id-fixup

$transclusion-link-scope

$transclusion-prefix-separator

$transclusion-suffix

$transform-after

$transform-before

$transform-original

$transformed-docbook-input

$transformed-docbook-output

$translate-suppress-elements

$unwrap-paragraphs

$use-docbook-css

$use-id-as-filename

$use-label-numeration

$use-minified-css

$user-css-links

$user-document-class

$variablelist-panelset

$variablelist-termlength-threshold

$varlistentry-separate-terms

$vendor-css

$verbatim-callouts

$verbatim-default-language

$verbatim-embellish-linenumbers

$verbatim-embellishments

$verbatim-line-style

$verbatim-number-every-nth

$verbatim-number-first-line

$verbatim-number-minlines

$verbatim-number-separator

$verbatim-numbered-elements

$verbatim-plain-style

$verbatim-space

$verbatim-style-default

$verbatim-syntax-highlight-css

$verbatim-syntax-highlight-languages

$verbatim-syntax-highlighter

$verbatim-table-style

$verbatim-trim-leading-blank-lines

$verbatim-trim-trailing-blank-lines

$warn-about-missing-localizations

$xlink-arclist-after

$xlink-arclist-before

$xlink-arclist-sep

$xlink-arclist-titlesep

$xlink-icon-closed

$xlink-icon-open

$xlink-js

$xlink-style

$xlink-style-default

$xspec

$additional-languages — Additional localization languages (beyond the default language)

Parameter:

{}additional-languages

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$additional-languages := ()

Description

If the stylesheets need to generate text (the names of labels such as “Chapter”, for example), they attempt to do so in the same language as the document. This is determined by finding the nearast in-scope xml:lang attribute from the context where the generated text is required.

The stylesheets can generate text in more than 70 languages, but very few documents use more than a few. To avoid the overhead of loading a great many localizations that will never be used, the stylesheets don’t load them all.

The stylesheets always load the $default-language and will load any additional languages identified in $additional-languages, a space separated list of language identifiers.

If the $additional-languages is the empty sequence, the stylesheets attempt to determine which languages are used in the document and load the appropriate localizations.

$align-char-default, $align-char-pad, $align-char-processing, $align-char-width — Support “char” alignment on CALS table cells.

Parameter:

{}align-char-default

{}align-char-pad

{}align-char-processing

{}align-char-width

Defined in:

param.xsl (4)

Used in:

param.xsl

Synopsis

$align-char-default as xs:string := '.'

$align-char-pad := ' '

$align-char-processing := true()

$align-char-width := 2

Description

CALS tables support “char” alignment on columns. The most common use case for character alignment is to align a column of numbers on a decimal point even when the number of characters to right or left of the decimal point varies.

Three parameters apply to character alignment:

$align-char-default

Specifies the default alignment character.

$align-char-pad

Specifies the default padding character, usually an en space.

$align-char-processing

If this parameter is true, the CALS table preprocessor will resolve char alignment as described. If it is false, the character alignment attributes are left on the table cells and the alignment process is left to some other process.

$align-char-width

Specifies the number of characters that follow the alignment character.

ⓘ

Notes

The HTML table model doesn’t really support character alignment. This feature pads each entry on the right as necessary to put the alignment character in the same place. Naturally, this will only produce the desired result if a monospace font is used in the cell.

If the alignment character appears more than once in the cell, the cells are aligned around the last occurrence. The notion of “last” and padding on the right or the left should be sensitive to the writing direction, but it isn’t currently.

Character alignment is ignored if a cell contains markup.

Example 1, “An example of char alignment” shows an example of character alignment on the “,” character.

<informaltable frame="all">
   <tgroup cols="2" colsep="1" rowsep="1">
      <colspec colnum="2" align="char" char=","/>
      <tbody>
         <row>
            <entry>Row A</entry>
            <entry>10000,01</entry>
         </row>
         <row>
            <entry>Row B</entry>
            <entry>10</entry>
         </row>
         <row>
            <entry>Row C</entry>
            <entry>-3,14</entry>
         </row>
      </tbody>
   </tgroup>
</informaltable>

Example 1. An example of char alignment

Row A | 10000,01
Row B | 10   
Row C | -3,14

Example 2. Tabular rendering

The alignment character can be specified on a per-column, per-table basis with the char attribute on colspec.

The alignment width and padding character can be specified on a per-column, per-table basis with a db processing instruction.

If the settings apply to the whole table, the processing instruction can be a child of tgroup, preceding any other elements. If you want to specify different values for different columns, the processing instruction must immediately follow the colspec for the column.

The align-char-width pseudo-attribute controls the number of characters following the alignment character. The align-char-pad pseudo-attribute controls the character used for padding.

A value that does not contain the alignment character is assumed to be followed immediately by the alignment character. (In other words, if you’re aligning on “.”, “10” is considered to be “10.”.) If the pad character is a space*, then the pad character will be used to pad the value. If the pad character isn’t a space, the value will be padded with the alignment character followed by pad characters as necessary.

*

Technically, is in the class of Unicode characters considered to be spaces, one that matches \p{Zs}.

$allow-eval — Process the eval processing instruction?

Parameter:

{}allow-eval

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$allow-eval as xs:string := 'true'

Description

If this parameter is true, XPath expressions contained in the eval processing instruction will be evaluated, otherwise the processing instruction is silently ignored.

If the eval is performed, the result of the evaluation is inserted into the formatted document.

$annotate-toc — Annotate the table-of-contents?

Parameter:

{}annotate-toc

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$annotate-toc := 'true'

Description

If true, a table of contents containing refentry elements will also include the refpurpose for each entry.

$annotation-collection — An external collection of annotations.

Parameter:

{}annotation-collection

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$annotation-collection as xs:string := ''

Description

Because annotations can be applied by pointing from the annotation to the element they annotate, they can be stored and managed externally. If $annotation-collection points to a collection of annotations, the stylesheets will add them to the document before it is processed.

To achieve this:

Create a collection of shared annotations and store them somewhere. The stylesheets will copy only the top-level annotation elements (/*/annotation). The document element doesn’t matter.

Use the annotates attribute on the annotations to point at elements in the document you’re transforming.

Annotations can point in either direction, but you will get ID/IDREF validation errors if you attempt to point from the document into the annotation collection because the annotation collection won’t be present when you validate. If your use case requires pointing in that direction, you will have better luck with a pipeline that combines the two documents before validating.

Run your transformation with $annotation-collection set to the URI of the document that contains your collection of annotations.

The stylesheets will apply annotations to the elements identified. Extra annotations, annotations that don’t point to elements that actually exist in the document being transformed, will be ignored.

$annotation-mark — Identifying mark for annotations.

Parameter:

{}annotation-mark

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

<xsl:param name="annotation-mark">
   <sup>⌖</sup>
</xsl:param>

Description

When annotations are rendered, the $annotation-mark is inserted at each location where an annotation occurs.

If JavaScript is used for annotations (see $annotation-style), clicking on the mark will bring up the annotation; if JavaScript is not used, the marks are numbered and the annotations appear as a form of footnote.

$annotation-placement — Determines where the annotation mark is placed.

Parameter:

{}annotation-placement

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$annotation-placement := 'after'

Description

When annotations are rendered, $annotation-placement determines where the $annotation-mark is placed. If the value is after, the mark or marks are placed at the very end of the element being annotated. If the value is before, the marks are placed at the very beginning of the element being annotated.

Each individual annotation can determine its placement by placing before or after in its role attribute.

$annotation-style — Selects the annotation style.

Parameter:

{}annotation-style

Defined in:

param.xsl

Used in:

param.xsl, modules/chunk-cleanup.xsl

Synopsis

$annotation-style := 'javascript'

Description

An annotation can be used to add annotations to arbitrary elements. Annotations are formatted something like footnotes, they appear at the bottom of the page and are linked from the point of the annotation. There are two annotation styles, “javascript” and “inline”.

If the annotation style is “javascript”, a script reference will be added. The script hides the annotations at the bottom of the page and instead renders them as modal dialogs when the marks are clicked. The presentation is accessible in the absence of JavaScript.

If the annotation style is “inline”, then the script is not included and the default presentation is used. No other values are supported at this time.

$annotations-js — Script to support popup (JavaScript) annotations.

Parameter:

{}annotations-js

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$annotations-js := 'js/annotations.js'

Description

If popup (JavaScript) annotations appear in the document, a link to this script will be added to the document. This script must contain the JavaScript necessary to support the popup annotations feature.

$auto-toc — Automatically generate tables of contents.

Parameter:

{}auto-toc

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.0.10

Synopsis

$auto-toc as xs:string := 'true'

Description

If this parameter is true, then a table of contents, or more generally, “lists of titles”, will be generated. If it is not true, such lists will only appear where an explicit toc element appears. An empty toc can be used to identify the place where an automatically generated list should appear. In either case, if the toc is not empty, then the hand-authored list appears instead of an automatically generated one.

Which elements will have an automatically generated list of titles is determined by how elements are processed in the m:toc mode.

$bibliography-collection — An external collection of bibliography entries.

Parameter:

{}bibliography-collection

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$bibliography-collection as xs:string := ''

Description

It’s often convenient to share a common bibliography across many documents. If $bibliography-collection points to a bibliography, the stylesheets will automatically populate bibliography entries in the document being transformed.

To achieve this:

Create a shared bibliography and store it somewhere. Make sure that each entry in your shared bibliography has a unique xml:id value.

Run your transformation with $bibliography-collection set to the URI of that document.

In the document you’re transforming, refer to the shared entries with completely empty biblioentry or bibliomixed elements that have the same xml:id as an entry in the shared bibliography.

The stylesheets will copy those entries into your document before processing it.

$bibliography-style — The bibliography style.

Parameter:

{}bibliography-style

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$bibliography-style as xs:string := 'default'

Description

Bibliographies are complicated and many different styles exist. Creating properly formatted bibliographies from raw bibliography entries is especially challenging. (This parameter does not apply to formatting bibliomixed entries.)

default

The default style. This is controlled by the biblioentry template. See $v:templates. All biblioentry elements will be processed in m:biblioentry mode.

iso690

Attempts to implement ISO 690 bibliographic formatting. All biblioentry elements will be processed in m:biblio690 mode. This is adapted from the examples in Bibliography according to ISO 690 and ISO 690-2 standards.

The default style specified by $bibliography-style can be overridden on a case-by-case basis with the db processing instruction using the bibliography-style pseudo-attribute. This must appear in the bibliography or bibliolist that contains the entries.

$books-inherit-from — Identifies what inherited numeration applies to books.

Parameter:

{}books-inherit-from

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$books-inherit-from as xs:string := ''

Description

If book numbers inherit from their ancestors, these are the ancestors they inherit from.

See Section 3.6, “Controlling numeration”.

$books-number-from — Identifies where book numeration begins.

Parameter:

{}books-number-from

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$books-number-from as xs:string := 'set'

Description

Book numbers (if books are numbered) begin from here.

See Section 3.6, “Controlling numeration”.

root

Books are numbered from the beginning of the document.

set

Books are numbered from their parent set.

$callout-default-column — Default column for callouts.

Parameter:

{}callout-default-column

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$callout-default-column := 60

Description

When callouts are used in program listings (or screens), if the column is not specified for a callout, it will appear in this column.

$callout-unicode-start — Initial callout character.

Parameter:

{}callout-unicode-start

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$callout-unicode-start := 9311

Description

When callouts are rendered, for example in programlistingco, this is the beginning of the range of characters to be used for callout “bugs”. This is the decimal value of the Unicode code point that is the “zero” point in the list, the one just before the first character.

The default value is 9311 which means the first callout will be 9312, U2460, “①”.

$cals-table-width-threshold — Determines how carefully to measure CALS table widths.

Parameter:

{}cals-table-width-threshold

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.6.1

Synopsis

$cals-table-width-threshold as xs:integer := 1

Description

CALS tables columns can have widths specified in relative and absolute terms. If the sum of the absolute widths exceeds the nominal page width by $cals-table-width-threshold pixels, the relative widths are ignored. (No attempt is made to divide up the remaining width according to the relative widths.)

The computation involves floating point calculations and may have rounding errors. Setting the threshold to 1 (rather than 0) reduces false positives.

$chunk — Produce chunked output?

Parameter:

{}chunk

Defined in:

param.xsl

Used in:

main.xsl, param.xsl, modules/chunk-cleanup.xsl

Synopsis

$chunk as xs:string? := ()

Description

Specifying any value for this parameter turns on “chunking”, see Section 2.7, ““Chunked” output”. The value of the parameter is taken as the filename for the root chunk, unless some other mechanism identifies an alternate value.

$chunk-exclude — XPath expressions for excluding chunks.

Parameter:

{}chunk-exclude

Defined in:

param.xsl

Used in:

param.xsl, modules/chunk.xsl

Synopsis

$chunk-exclude as xs:string* := ('self::db:partintro',
                                 'self::*[ancestor::db:partintro]',
                                 'self::db:annotation',
                                 'self::db:section[not(preceding-sibling::db:section)]',
                                 'self::db:sect1[not(preceding-sibling::db:sect1)]',
                                 'self::db:toc')

Description

This parameter is only relevant when chunking is being performed, see Section 2.7, ““Chunked” output”. This parameter contains a list of XPath expressions. When chunking is being applied, for any element that could be a chunk (see $chunk-include), each expression is evaluated with that element as the context item. If the effective boolean value of any expression is true, the element will not become a chunk.

The default value for this parameter is:

('self::db:partintro',
'self::*[ancestor::db:partintro]',
'self::db:toc')

In other words partintro, all of the descendants of partintro, and toc are explicitly excluded from being chunks.

The namespaces in $chunk-filter-namespaces will be in-scope when this expression is evaluated.

$chunk-include — XPath expressions for identifying potential chunks.

Parameter:

{}chunk-include

Defined in:

param.xsl

Used in:

param.xsl, modules/chunk.xsl

Synopsis

$chunk-include as xs:string* := ('parent::db:set',
                                 'parent::db:book',
                                 'parent::db:part',
                                 'parent::db:reference',
                                 'self::db:refentry',
                                 'self::db:section',
                                 'self::db:sect1')

Description

This parameter is only relevant when chunking is being performed, see Section 2.7, ““Chunked” output”. This parameter contains a list of XPath expressions. When chunking is being applied, for every element in the document, each expression is evaluated with that element as the context item. If the effective boolean value of any expression is true, the element is a candidate for chunking. It will become a chunk unless $chunk-exclude excludes it or, in the special case of recursive sections, if it is nested too deeply.

The default value for this parameter is:

('parent::db:set',
'parent::db:book',
'parent::db:part',
'parent::db:reference',
'self::db:refentry',
'self::db:section',
'self::db:sect1')

In other words all of the direct children of set, book, part, reference will become chunks (the special case of info is automatically excluded); refentry, section, and sect1 become chunks anywhere they appear. In the case of recursive sections, $chunk-section-depth also applies.

The namespaces in $chunk-filter-namespaces will be in-scope when this expression is evaluated.

$chunk-nav — Add keyboard navigation to chunks?

Parameter:

{}chunk-nav

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$chunk-nav as xs:string := 'true'

Description

If $chunk-nav is true, keyboard navigation will be added to chunked output. This is accomplished by adding the $chunk-nav-js script to the generated HTML.

Table 1. Default keyboard navigation keys

Key | Navigation
N or → | Next sibling
P or ← | Previous sibling
U | Parent
H or Home | Home

Notes:

The ↑ used to be a shortcut for “parent”, like U, but that breaks the ability to navigate up and down the page with the arrow keys. It was removed in version 2.0.3.

$chunk-nav-js — Script to support keyboard navigation.

Parameter:

{}chunk-nav-js

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$chunk-nav-js as xs:string := 'js/chunk-nav.js'

Description

If chunk navigation is enabled, this script is added to each chunk to support keyboard navigation.

$chunk-output-base-uri — Output base URI for chunks.

Parameter:

{}chunk-output-base-uri

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

<xsl:param
           name="chunk-output-base-uri"
           as="xs:string">
   <xsl:choose>
      <xsl:when test="not($v:chunk)"><!-- it doesn't actually matter -->
         <xsl:sequence select="''"/>
      </xsl:when>
      <xsl:when use-when="function-available('ext:cwd')" test="true()">
         <xsl:sequence select="ext:cwd()"/>
      </xsl:when>
      <xsl:otherwise>
         <xsl:message terminate="yes" select="'You must specify the $chunk-output-base-uri'"/>
      </xsl:otherwise>
   </xsl:choose>
</xsl:param>

Description

This parameter identifies the output directory where “chunks” will be stored. If the stylesheet is not producing chunked results (see Section 2.7, ““Chunked” output”), this parameter has no effect.

If the ext:cwd() extension function (see Section 2.6, “Extension functions”) is available, its value will be the default value for this parameter. If the extension isn’t available, you must provide a value for this parameter.

☝

Important

If you’re using the stylesheets from Maven, the static-base-uri() will be something like https://cdn.docbook.org/release/… and resolving the current working directory against that won’t be useful. It’s better in those cases to specify the parameter explicitly with a file: URI. (And note that it may need to be a file:/path URI, not a file:///path URI, in order to match correctly.)

$chunk-renumber-footnotes — Renumber footnotes when chunking?

Parameter:

{}chunk-renumber-footnotes

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$chunk-renumber-footnotes := 'true'

Description

If this parameter is true, footnotes will be renumbered within chunks. See $v:chunk-renumber-footnotes.

$chunk-section-depth — Returns the chunking depth for recursive sections.

Parameter:

{}chunk-section-depth

Defined in:

param.xsl

Used in:

param.xsl, modules/chunk.xsl

Synopsis

$chunk-section-depth := 1

Description

This parameter is only relevant when chunking is being performed, see Section 2.7, ““Chunked” output”. For recursive sections (section, and refsection), if the section would be a chunk according to $chunk-include, it is further tested against $chunk-section-depth. If it is nested more deeply than $chunk-section-depth, it will not be considered for chunking.

ⓘ

Note

In principle, this parameter is unnecessary as it could be represented by $chunk-exclude expressions. However, changing the section depth is a common customization, so it’s handled as a separate parameter.

$classsynopsis-indent — Indent for classsynopsis members.

Parameter:

{}classsynopsis-indent

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$classsynopsis-indent := '  '

Description

Elements inside a class synopsis (field and method declarations, for example) will be indented by this amount.

$component-numbers — Are components numbered?

Parameter:

{}component-numbers

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$component-numbers as xs:string := 'true'

Description

If $component-numbers is true, components (chapters, appendixes, etc.) that do not have an explicit label will be labeled with their component number.

See Section 3.6, “Controlling numeration”.

$component-numbers-inherit — Include component labels in section labels?

Synopsis

$component-numbers-inherit as xs:string := 'false'

Description

This parameter is no longer used. See Section 3.6, “Controlling numeration”.

$components-inherit-from — Identifies what inherited numeration applies to components.

Parameter:

{}components-inherit-from

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$components-inherit-from as xs:string := ''

Description

If component numbers inherit from their ancestors, these are the ancestors they inherit from.

See Section 3.6, “Controlling numeration”.

$components-number-from — Identifies where component numeration begins.

Parameter:

{}components-number-from

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$components-number-from as xs:string := 'book'

Description

Component numbers (if components are numbered) begin from here.

See Section 3.6, “Controlling numeration”.

root

Components are numbered from the beginning of the document.

set

Components are numbered from their nearest ancestor set.

book

Components are numbered from their nearest ancestor book.

division

Components are numbered from their parent division.

$control-js — Script to support theme selection.

Parameter:

{}control-js

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$control-js as xs:string := 'js/controls.js'

Description

If the $theme-picker is enabled, a link to this script will be added to the document. This script must contain the JavaScript necessary to support the theme controls.

$copy-verbatim-js — Script to support dynamic copy button on verbatim listings.

Parameter:

{}copy-verbatim-js

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$copy-verbatim-js := 'js/copy-verbatim.js'

Description

This script creates a dynamic “copy-to-clipboard” button on verbatim listings. The copied text will not include any callouts or other decorations in the listing.

$copyright-collapse-years — Collapse sequential copyright years into a range?

Parameter:

{}copyright-collapse-years

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$copyright-collapse-years := true()

Description

If true, sequential copyright years will be collapsed into a range.

For example,

<copyright>
<year>1993</year>
<year>1997</year>
<year>1998</year>
<year>1999</year>
<holder>Jane Smith</holder>
</copyright>

might be rendered: “Copyright © 1993, 1997–1999 Jane Smith”.

If $copyright-collapse-years is false, that wold be rendered: “Copyright © 1993, 1997, 1998, 1999 Jane Smith”.

See also $copyright-year-range-separator and $copyright-year-separator.

$copyright-year-range-separator — Separator character for copyright year ranges.

Parameter:

{}copyright-year-range-separator

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$copyright-year-range-separator := '–'

Description

When a sequence of copyright years is collapsed into a range, this character is used to separate the first and last years.

See also $copyright-collapse-years and $copyright-year-separator.

$copyright-year-separator — Separator character for copyright years.

Parameter:

{}copyright-year-separator

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$copyright-year-separator := ', '

Description

When a series of copyright years (or year ranges) is formatted, this string is used to separate them.

See also $copyright-year-range-separator and $copyright-collapse-years.

$cos-number-from — Controls numeration of co elements.

Parameter:

{}cos-number-from

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$cos-number-from as xs:string := 'verbatim section'

Description

Numeration of co elements starts from the most recent node in any of the following categories:

books

See Section 3.6

components

See Section 3.6

sections

See Section 3.6

verbatims

Despite its name, this category incudes not only computeroutput, literallayout, programlisting, screen, imageobjectco, programlistingco and screenco, but also classsynopsis, cmdsynopsis, constructorsynopsis, destructorsynopsis, enumsynopsis, fieldsynopsis, funcsynopsis, macrosynopsis, methodsynopsis, packagesynopsis, typedefsynopsis, unionsynopsis and synopsis.

With the default value, callout numbers will be counted separately for every verbatim or synopsis element, if any (with sections as a fallback). If you don't want a reset for callouts numeration in the whole book, set this parameter to books.

$date-date-format, $date-dateTime-format — Format strings for dates and dateTimes.

Parameter:

{}date-date-format

{}date-dateTime-format

Defined in:

param.xsl (2)

Used in:

main.xsl, param.xsl

Synopsis

$date-date-format := '[D01] [MNn,*-3] [Y0001]'

$date-dateTime-format := '[H01]:[m01] [D01] [MNn,*-3] [Y0001]'

Description

The most convenient format for storing dates that will be machine processed: sorted, indexed, etc, is ISO 8601. When publishing these dates, it’s often desirable to use a different format, one more familiar to readers.

A pubdate that conforms to an ISO 8601 date (“yyyy-mm-dd”) will be formatted with the $date-date-format; one that conforms to an ISO 8601 dateTime (“yyyy-mm-ddThh:mm:ss”) will be formatted with the $date-dateTime-format.

See also f:date-format().

$dc-metadata — Output Dublin Core metadata?

Parameter:

{}dc-metadata

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$dc-metadata as xs:string := 'true'

Description

If this parameter is true, the head element of each result document will contain meta elements for Dublin Core metadata that can be derived from the source document.

$debug — Debugging flags.

Parameter:

{}debug

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Static:

Yes

Synopsis

$debug as xs:string := ''

Description

The $debug parameter contains a space separated list of flags. Depending on which flags are enabled, various additional debugging messages will be emitted during processing.

The following flags are supported:

callouts

Display additional information about callout processing.

cals-align-char

Display additional information about the computation of character alignment processing in CALS tables.

chunk-cleanup

Display additional information about chunk cleanup processing.

chunks

Display additional information about chunk selection.

db4to5

Display additional information about the DocBook 4.x to 5.x upgrade process.

dynamic-profile

Display additional information about dynamic profiling.

dynamic-profile-suppress

Display additional information about what elements are suppressed by dynamic profiling.

image-properties

Display additional information about the results of the extracting properties from images. This will display all of the properties available from each image.

image-markup

Display the markup generated for media objects.

intermediate-results

Output the resolved names of intermediate result documents ($transformed-docbook-input and $transformed-docbook-output) if they are used.

intra-chunk-links

Display additional information about the resolution of intra-chunk references. to links.

intra-chunk-refs

Display additional information about intra-chunk references.

mediaobject-uris

Display additional information about how media object URIs are constructed.

linkbase

Display additional information about how XLink linkbases are resolved.

localization

Display additional information about localization data.

numeration

Display additional information about how elements are numbered (in titles, in cross references, etc.)

objects

Display additional information about how media objects are selected.

pipeline

Display additional information about the pipeline processing stages.

profile

Display additional information about profiling.

profile-suppress

Display additional information about what elements are suppressed by profiling.

properties

Display additional information about the properties associated with a verbatim environment.

render-verbatim

Display additional information about how verbatim environments are rendered.

tables

Display additional information about how tables are rendered.

template-matches

Display additional information about how title page templates are selected.

templates

Display additional information about title page templates.

templates-matches

Display the title page template that matched for a particular element.

verbatim

Display additional information about how verbatim elements are processed.

xlink

Display additional information about XLink resolution.

$default-float-style — Default float style.

Parameter:

{}default-float-style

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$default-float-style := 'left'

Description

The floatstyle attribute on formal objects (figure, etc.) indicates that they should float. This is achieved by adding the float style as a class value in the HTML output. If the value of floatstyle is “float”, then the $default-float-style will be applied. In other words, the CSS classes will be “float left” (as long as $default-float-style is “left”). If any other value is given for floatstyle, then the CSS classes will be “float value”.

$default-language — Default language.

Parameter:

{}default-language

Defined in:

param.xsl

Used in:

main.xsl, param.xsl, modules/chunk-cleanup.xsl

Used by:

t:top-nav, t:bottom-nav

Synopsis

$default-language := 'en'

Description

If the stylesheets need to generate text (the names of labels such as “Chapter”, for example), they attempt to do so in the same language as the document. This is determined by finding the nearast in-scope xml:lang attribute from the context where the generated text is required.

If there is no in-scope xml:lang attribute, or if there is no localization available for the language specified, the $default-language is used instead.

$default-length-magnitude, $default-length-unit — The magnitude and units of the default length.

Parameter:

{}default-length-magnitude

{}default-length-unit

Defined in:

param.xsl (2)

Used in:

main.xsl, param.xsl

Synopsis

$default-length-magnitude := 25.0

$default-length-unit := '%'

Description

If the stylesheet encounters a length that it cannot parse, the default magnitude and unit are used for that length. See Section 5.2, “Lengths and units”.

$default-templates-uri — The URI of the default templates file.

Parameter:

{}default-templates-uri

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$default-templates-uri as xs:string := 'templates.xml'

Description

The URI of a file with default title page templates. If it is relative, it will be resolve against the static base URI of the stylesheet.

$default-theme — Default theme.

Parameter:

{}default-theme

Defined in:

param.xsl

Used in:

param.xsl, modules/chunk-cleanup.xsl

Synopsis

$default-theme as xs:string := ''

Description

If a $default-theme is specified, its value will be added to the class attribute on the html element(s) generated. The actual theme implementation is performed in CSS. See $theme-list for a list of themes. You can add your own themes with custom CSS (with m:html-head-links mode, for example).

$division-numbers — Are divisions numbered?

Parameter:

{}division-numbers

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$division-numbers as xs:string := 'true'

Description

If $division-numbers is true, divisions (books, parts, references, etc.) that do not have an explicit label will be labeled with their division number.

See also $v:title-properties.

$division-numbers-inherit — Include division labels in component labels?

Synopsis

$division-numbers-inherit as xs:string := 'false'

Description

This parameter is no longer used. See Section 3.6, “Controlling numeration”.

$divisions-inherit-from — Identifies what inherited numeration applies to divisions.

Parameter:

{}divisions-inherit-from

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$divisions-inherit-from as xs:string := ''

Description

If division numbers inherit from their ancestors, these are the ancestors they inherit from.

See Section 3.6, “Controlling numeration”.

$divisions-number-from — Identifies where division numeration begins.

Parameter:

{}divisions-number-from

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$divisions-number-from as xs:string := 'book'

Description

Divisions numbers (if divisions are numbered) begin from here.

See Section 3.6, “Controlling numeration”.

root

Divisions are numbered from the beginning of the document.

set

Divisions are numbered from their nearest ancestor set.

book

Divisions are numbered from their parent book.

$docbook-transclusion — Enable DocBook transclusion processing.

Parameter:

{}docbook-transclusion

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$docbook-transclusion := 'false'

Description

The $docbook-transclusion controls whether or not DocBook transclusion processing (see Transclusion) is performed. The default at present is false because I don’t believe it’s in widespread use and transclusion processing on large documents can be quite slow. If either of those conditions change, the default may become true in some future version of the stylesheets.

$dynamic-profile-error — How are errors in dynamic profiling handled?

Parameter:

{}dynamic-profile-error

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$dynamic-profile-error := 'ignore'

Description

If an error occurs evaluating a dynamic profiling expression, what should happen? That depends on the setting of $dynamic-profile-error:

ignore

The error is ignored. This has no effect on whether or not the element is included.

include

The error is ignored and the expression is considered to have returned a value of “true”.

exclude

The error is ignored and the expression is considered to have returned a value of “false”.

error

Raises the dbe:DYNAMIC-PROFILE-EVAL-ERROR exception.

any other value

Raises the dbe:INVALID-DYNAMIC-PROFILE-ERROR exception.

$dynamic-profile-variables — Dynamic profiling variables.

Parameter:

{}dynamic-profile-variables

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$dynamic-profile-variables as map(xs:QName, item()*)? := ()

Description

The dynamic profile variables are passed to each of the pre- and post-processing transformations in addition to the standard parameters. See Section 5.7, “The pre- and post-processing pipeline”.

$dynamic-profiles — Is dynamic profiling enabled?

Parameter:

{}dynamic-profiles

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$dynamic-profiles as xs:string := 'false'

Description

If this parameter is true, dynamic profiling will be applied to the document. See Section 2.9.4, “Dynamic profiling”.

$experimental-pmuj — Insert reverse links.

Parameter:

{}experimental-pmuj

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$experimental-pmuj := 'false'

Description

If $experimental-pmuj is true, then links will be inserted from link targets back to link sources. In other words, if clicking on “A” jumps you to “B”, the stylesheets will add a link at “B” that jumps you back back to “A”. (Pmuj is jump spelled backwards.)

⚠

Caution

This feature is entirely experimental. It may change in arbitrary ways or it may be abandoned.

Support is limited at the moment to inlines and formal objects that have title pages. There’s currently no where to insert markup for every possible element that could be a link target.

Pmuj’s from title pages should probably be inserted in the heading, not above it, just because the styling would be nicer.

$fallback-js — Script to support audio/video fallback.

Parameter:

{}fallback-js

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$fallback-js := 'js/fallback.js'

Description

Apparently, there’s no declarative way to offer an HTML fallback message when all of the audio or video sources in a media object are unusable. Instead, it has to be done with JavaScript.

This parameter identifies the JavaScript file to load for this support. It must define a global function named docbook_object_fallback that takes the source node as a paramter.

To disable fallback, set this parameter to the empty sequence or the empty string.

Place this script in the head of the document and do not defer loading it.

$footnote-numeration — How are footnotes numbered?

Parameter:

{}footnote-numeration

Defined in:

param.xsl

Used in:

main.xsl, param.xsl, modules/chunk-cleanup.xsl

Synopsis

$footnote-numeration := ('1')

Description

There are different styles of footnote numeration. This parameter contains a list of the symbols that should be used. If there could be more footnotes than symbols in the list, the last symbol in the list must be a character suitable for formatting numbers.

For example, if the sequence in $footnote-numeration is “*”, “†”, “a”, then the first footnote will be marked with “*”, the second with “†”, the third with “a”, the forth with “b”, and so on.

When chunking, footnotes may be renumbered within each chunk (see $chunk-renumber-footnotes).

$formal-object-numbers — Are formal objects numbered?

Parameter:

{}formal-object-numbers

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.7.4

Synopsis

$formal-object-numbers as xs:string := 'true'

Description

If $formal-object-numbers is true, formal objects (figures, tables, etc.) that do not have an explicit label will be labeled with their section number.

See Section 3.6, “Controlling numeration”.

$formal-object-title-placement — Specify placement of title on formal elements.

Parameter:

{}formal-object-title-placement

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$formal-object-title-placement := 'after table:before formalgroup:before'

Description

Formal elements are elements with a title that are often displayed with a caption: figure, table, example and equation. The $formal-object-title-placement parameter determines if the title precedes or follows the element itself.

The parameter consists of a series of tokens, “before”, “after”, or “element : position”. The named forms (e.g., figure:before) take precedence with the unnamed form serving as a default for any that don’t have named forms.

$formal-objects-inherit-from — Identifies what inherited numeration applies to formal-objects.

Parameter:

{}formal-objects-inherit-from

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$formal-objects-inherit-from as xs:string := 'component'

Description

If formal object numbers inherit from their ancestors, these are the ancestors they inherit from.

See Section 3.6, “Controlling numeration”.

$formal-objects-number-from — Identifies where formal-object numeration begins.

Parameter:

{}formal-objects-number-from

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$formal-objects-number-from as xs:string := 'component'

Description

Formal object numbers (if formal objects are numbered) begin from here.

See Section 3.6, “Controlling numeration”.

root

Formal objects are numbered from the beginning of the document.

set

Formal objects are numbered from their nearest ancestor set.

book

Formal objects are numbered from their nearest ancestor book.

division

Formal objects are numbered from their nearest ancestor division.

component

Formal objects are numbered from their nearest ancestor component.

section

Formal objects are numbered from their parent section.

$formalgroup-nested-object-title-placement — Specify placement of title on formal elements inside formalgroup .

Parameter:

{}formalgroup-nested-object-title-placement

Defined in:

param.xsl

Used in:

param.xsl

Since:

2.0.13

Synopsis

$formalgroup-nested-object-title-placement := 'after'

Description

The $formal-object-title-placement parameter controls how formal object titles are displayed generally. The $formalgroup-nested-object-title-placement parameter specifies how formal object titles are displayed when the formal object is inside a formalgroup. It has the same format as $formal-object-title-placement.

$funcsynopsis-default-style — Default style for function synopses.

Parameter:

{}funcsynopsis-default-style

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$funcsynopsis-default-style := 'kr'

Description

The funcsynopsis element can be rendered in several styles. The $funcsynopsis-default-style parameter determines which style is used by default.

$funcsynopsis-table-threshold — Maximium width of a function synopsis.

Parameter:

{}funcsynopsis-table-threshold

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$funcsynopsis-table-threshold := 40

Description

When rendering funcsynopsis elements, the width of the synopsis depends on the number of parameters and the lengths of their names and types. If the width of the funcsynopsis would exceed $funcsynopsis-table-threshold characters, the presentation switches from an inline style to a tabular style. The tabular style aligns the parameters up vertically after the function name.

$funcsynopsis-trailing-punctuation — Trailing punctuation in function synopses.

Parameter:

{}funcsynopsis-trailing-punctuation

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$funcsynopsis-trailing-punctuation := ';'

Description

This punctuation character is added after the end of a funcsynopisis. The default value of “;” is appropriate for C and other languages that use “;” as statement separator.

$generate-html-page — Generate the HTML page structure around the styled document.

Parameter:

{}generate-html-page

Defined in:

param.xsl

Used in:

docbook.xsl, param.xsl

Used by:

t:docbook

Synopsis

$generate-html-page as xs:string := 'true'

Description

If this parameter is true, then a complete HTML page will be generated for the transformed document: an html tag, head and body tags, etc. If it’s false, then only the “raw” transformed content will be produced. This is true for both the primary output and any secondary result documents.

ⓘ

Note

When the “raw” output option is selected, links to the CSS stylesheets, scripts, and other interactive features will not be generated. You must make sure those are provided in some other way.

$generate-index — Automatically generate an index?

Parameter:

{}generate-index

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$generate-index := 'true'

Description

If a document contains an empty setindex, index, or indexdiv, and $generate-index is true, then an index will automatically be generated from any indexterms found in the document.

$generate-nested-toc — Determines if subsubections appear in the table of contents.

Synopsis

$generate-nested-toc as xs:string := 'not(f:section(.))
                                     or (f:section(.) and f:section-depth(.) le $vp:section-toc-depth)'

Description

This parameter is no longer used. Instead, you can control the elements that appear in a table of contents with the m:toc-nested mode.

$generate-toc — Generate a table-of-contents?

Synopsis

$generate-toc as xs:string := '(empty(parent::*) and self::db:article)
                              or self::db:set or self::db:book
                              or self::db:part or self::db:reference'

Description

This parameter is no longer used. Instead, you can control the elements that contain a table of contents with the m:toc mode.

$generate-trivial-toc — Generate a trivial table-of-contents?

Parameter:

{}generate-trivial-toc

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$generate-trivial-toc as xs:string := 'false'

Description

If the $generate-trivial-toc parameter is true, a table of contents will be generated even if it consists of only a single entry. Otherwise, such “trivial” tables of contents will be elided.

This parameter applies only to top-level tables of contents. Nested tables of contents will be generated even if they consist of only a single entry.

$generated-id-root — The string generated as the unique identifier for the root of the tree.

Parameter:

{}generated-id-root

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$generated-id-root := 'R'

Description

When f:generate-id() is constructing a unique identifier for an element, it walks up the ancestors of that element. If it reaches the root of the tree, it uses $generated-id-root to mark that location.

$generated-id-sep — The string generated to separate parts of a unique identifier.

Parameter:

{}generated-id-sep

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$generated-id-sep := '_'

Description

When f:generate-id() is constructing a unique identifier for an element, it walks up the ancestors of that element. To make the identifiers easier to read, and to disambiguate values, it places $generated-id-sep between each component that it uses.

ⓘ

Note

Historically, a “.” was used as the separator. However, if JavaScript is going to be used to process the HTML documents that the stylesheet produces, that may be inconvenient. (Because selectors use “.” to separate element names from class values.)

$generator-metadata — Output generator metadata?

Parameter:

{}generator-metadata

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$generator-metadata as xs:string := 'true'

Description

If this parameter is true, the head element of each result document will contain a meta element with the name generator that identifies the stylesheet and processor used to produce the result.

$gentext-language — Specifies language for generated text.

Parameter:

{}gentext-language

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$gentext-language := ()

Description

The language used for generated text (words “Chapter” and “Figure”, for example) usually depends on the language of the (section of) the document where they appear. If $gentext-language is specified, that language will be used for all generated text, regardless of the context.

$glossary-automatic-divisions — Divide glossaries into sections?

Parameter:

{}glossary-automatic-divisions

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$glossary-automatic-divisions := 'false'

Description

If $glossary-automatic-divisions is true, the entries in an automatically constructed glossary will be grouped. The actual grouping is performed by the t:glossary-divisions template. This parameter is false by default for backwards compatibility.

Automatic divisions can be specified on a per-glossary basis with a db processing instruction using the glossary-divisions pseudo-attribute with a value of true or false.

This parameter only applies if $glossary-sort-entries is true and the glossary is not already grouped with glossdiv elements by hand.

$glossary-collection — An external collection of glossary entries.

Parameter:

{}glossary-collection

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$glossary-collection as xs:string := ''

Description

It’s often convenient to share a common glossary across many documents. If $glossary-collection points to a glossary, the stylesheets will automatically populate glossary entries in the document being transformed.

To achieve this:

Create a shared glossary and store it somewhere.

In the document you’re transforming, add an empty glossary with @role='auto'.

Run your transformation with $glossary-collection set to the URI of that document.

The stylesheets will copy referenced entries into your document before processing it.

You may specify per-document glossary collections with the db processing instruction using the glossary-collection pseudo-attribute. This must appear in the root element of your main document. If per-document glossary collections are provided, they are processed in the order provided before the global collection.

If multiple definitions for the same term appear in a glossary collection, only the first term is used.

$glossary-sort-entries — Sort glossaries?

Parameter:

{}glossary-sort-entries

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$glossary-sort-entries := 'true'

Description

If $glossary-sort-entries is true, the entries in a glossary or glosslist will be sorted before transformation. This saves the author from the burden of maintaining the list in a strictly alphabetic order.

$html-extension — The extension used for HTML output when chunking.

Parameter:

{}html-extension

Defined in:

param.xsl

Used in:

param.xsl, modules/chunk.xsl

Used by:

f:chunk-filename()

Synopsis

$html-extension := '.html'

Description

When using chunking (see Section 2.7, ““Chunked” output”), the resulting HTML documents will have this extension by default.

$image-ignore-scaling — Ignore scaling?

Parameter:

{}image-ignore-scaling

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$image-ignore-scaling as xs:boolean := false()

Description

If this parameter is true, all of the scaling attributes on images are ignored. Images will be displayed at their intrinsic size.

$image-nominal-height — Nominal height of an image.

Parameter:

{}image-nominal-height

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$image-nominal-height := '4in'

Description

If the extension functions necessary to determine the intrinsic height of an image are unavailable, or if the height cannot be determined, this value will be used as the assumed intrinsic height of the image.

$image-nominal-width — Nominal width of an image.

Parameter:

{}image-nominal-width

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$image-nominal-width := $nominal-page-width

Description

If the extension functions necessary to determine the intrinsic width of an image are unavailable, or if the width cannot be determined, this value will be used as the assumed intrinsic width of the image.

$image-property-warning — Warn if image properties cannot be obtained?

Parameter:

{}image-property-warning

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$image-property-warning := true()

Description

This flag controls whether or not an xsl:message is emitted when the ext:image-properties() extension function is unavailable.

$index-on-type, $index-on-role — Make distinct indexes based on role and type?

Parameter:

{}index-on-type

{}index-on-role

Defined in:

param.xsl (2)

Used in:

main.xsl, param.xsl

Synopsis

$index-on-type := 'true'

$index-on-role := 'true'

Description

DocBook supports the creation of different types of index. A book that documents an API might have a general index, for example, and also an index of functions, an index of variables, etc.

Typed indexes are created by specifying the index type in the type or role attribute. If $index-on-type is true, then separate indexes will be generated based on type values. If $index-on-role is true, then separate indexes will be generated based on role values.

$index-show-entries — Make index entries visible in the text?

Parameter:

{}index-show-entries

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$index-show-entries := ()

Description

If this value is non-empty, small markers will be left in the text where indexterm elements appear. This is probably not appropriate for final publication, but it can be a useful way to review the level of indexing.

$indexed-section-groups — Generate index entries grouped by section.

Parameter:

{}indexed-section-groups

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$indexed-section-groups := 'true'

Description

Before the introduction of this parameter, an automatically generated index contained only one index entry for any given section. If the $indexed-section-groups parameter is true, an index entry will be generated for every indexterm, with a span surrounding all of the entries for each section. This results in a more complete index while still preserving the ability to see in which sections the terms occur.

$inline-xlink-href — Output href values after links?

Parameter:

{}inline-xlink-href

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$inline-xlink-href as xs:string := 'false'

Description

If this parameter is true, when a linking element is rendered (one that uses an explicit xlink:href attribute), the link will be printed after the reference. This setting is enabled by default in the paged media stylesheets. It currently has no effect in the online stylesheets (but might in the future).

$label-wrapper — Additional wrapper around label and separator.

Parameter:

{}label-wrapper

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.7.2

Synopsis

$label-wrapper as xs:string? := ()

Description

By default, when the stylesheets output a title for a labeled element (chapter, section, table, etc.), the label is wrapped in a span with the class “label” and the separator (if there is one) between the label and the content is wrapped in a span with the class “sep”. For example:

  |<h3><span class="label">3</span><span class="sep">. </span>Section Title</h3>

If $label-wrapper is non-empty, then the label and the separator are further wrapped in a span with a class that contains the string value of $label-wrapper. For example, if $label-wrapper is “lwrap”:

  |<h3><span class="lwrap">
  |  <span class="label">3</span><span class="sep">. </span>
  |</span>Section Title</h3>

This allows you to group all of the parts together for CSS styling.

$lists-of-equations — Generate a list of equations?

Parameter:

{}lists-of-equations

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$lists-of-equations as xs:string := 'false'

Description

If true, a list of equations will be generated. By default, they are only generated for books and sets.

This is a pseudo-boolean parameter. It is considered true if it has the value '1’, ‘yes’, or ‘true’. Any other value is considered false.

$lists-of-examples — Generate a list of examples?

Parameter:

{}lists-of-examples

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$lists-of-examples as xs:string := 'true'

Description

If true, a list of examples will be generated. By default, they are only generated for books and sets.

This is a pseudo-boolean parameter. It is considered true if it has the value '1’, ‘yes’, or ‘true’. Any other value is considered false.

$lists-of-figures — Generate a list of figures?

Parameter:

{}lists-of-figures

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$lists-of-figures as xs:string := 'true'

Description

If true, a list of figures will be generated. By default, they are only generated for books and sets.

This is a pseudo-boolean parameter. It is considered true if it has the value '1’, ‘yes’, or ‘true’. Any other value is considered false.

$lists-of-procedures — Generate a list of figures?

Parameter:

{}lists-of-procedures

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$lists-of-procedures as xs:string := 'false'

Description

If true, a list of procedures will be generated. By default, they are only generated for books and sets.

This is a pseudo-boolean parameter. It is considered true if it has the value '1’, ‘yes’, or ‘true’. Any other value is considered false.

$lists-of-tables — Generate a list of tables?

Parameter:

{}lists-of-tables

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$lists-of-tables as xs:string := 'true'

Description

If true, a list of tables will be generated. By default, they are only generated for books and sets.

This is a pseudo-boolean parameter. It is considered true if it has the value '1’, ‘yes’, or ‘true’. Any other value is considered false.

$local-conventions — Transformation for local conventions.

Parameter:

{}local-conventions

Defined in:

param.xsl

Used in:

docbook.xsl, param.xsl

Used by:

$v:standard-transforms

Synopsis

$local-conventions as xs:string? := ()

Description

This parameter allows you to specify a tranformation for local markup conventions. This book uses several non-DocBook tagging conventions as a typing convenience, <att> for <tag class="attribute">, for example. These can be translated back into proper DocBook markup by the $local-conventions stylesheet. This stylesheet is run during the $v:standard-transforms, just before validation (see $relax-ng-grammar).

For example, the test suite stylesheet that transforms pseudo-DocBook elements “att” and “mode” into valid DocBook markup looks like this:

            <?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns="http://docbook.org/ns/docbook"
                xmlns:db="http://docbook.org/ns/docbook"
                xmlns:xs="http://www.w3.org/2001/XMLSchema"
                exclude-result-prefixes="db xs"
                version="3.0">

<xsl:template match="db:att">
  <tag class="attribute">
    <xsl:copy-of select="@* except @class"/>
    <xsl:apply-templates/>
  </tag>
</xsl:template>

<xsl:template match="db:mode">
  <code role="{string-join(
                distinct-values((@role/string(), 'mode')),
                ' ')}">
    <xsl:copy-of select="@* except @role"/>
    <xsl:apply-templates/>
  </code>
</xsl:template>

<xsl:template match="element()">
  <xsl:copy>
    <xsl:apply-templates select="@*,node()"/>
  </xsl:copy>
</xsl:template>

<xsl:template match="attribute()|text()|comment()
                     |processing-instruction()">
  <xsl:copy/>
</xsl:template>

</xsl:stylesheet>

$mathml-js — JavaScript library supporting MathML.

Parameter:

{}mathml-js

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$mathml-js as xs:string := 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-svg.js'

Description

If your documents use MathML, this library will be included to support MathML rendering. MathJax is a popular choice. See also $mathml-js-config.

Some libraries support formats other than MathML, see $mathml-js-role.

$mathml-js-config — Configuration script for MathML.

Parameter:

{}mathml-js-config

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$mathml-js-config as xs:string? := ()

Description

If this parameter is set, it will be added (as a script) to the output before the $mathml-js script. This can contain, for example, configuration settings for the MathML renderer.

$mathml-js-role — Class that identifies MathML support.

Parameter:

{}mathml-js-role

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$mathml-js-role as xs:string? := 'tex'

Description

If your document contains MathML, JavaScript support for MathML is included automatically. If the rendering library that you’re using supports other formats, for example MathJax supports TeX, then you may want to include the library on pages that don’t contain MathML.

If the $mathml-js-role parameter is specified, the MathML support will be added to any page that contains a mathphrase element with that role. If the role is set to the empty string (as distinct from the empty sequence), the script will be added unconditionally.

$mediaobject-accessibility — Accessibility settings for media objects.

Parameter:

{}mediaobject-accessibility

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$mediaobject-accessibility as xs:string := 'summary details'

Description

The $mediaobject-accessibility parameter determines how accessibility features are added to media objects (image, video, and audio elements).

The value of this parameter is a space-separated list of strings. If the list contains:

summary

A summary attribute will be added if there is an alt element or a textobject containing a single phrase is available.

details

A details element will be added to the div that surrounds the image if there is a textobject containing anything other than a single phrase available.

a11y-metadata

Metadata will be provided using the conventions described in EPUB Accessibility.

The list may contain either or both values. If other values are present, they are ignored.

See Example 1, “An example of media object accessibility”.

<mediaobject>
   <alt>This is a skeuomorphic “postage stamp” with the
DocBook logo.</alt>
   <imageobject>
      <imagedata fileref="media/stamp400x256.png"/>
   </imageobject>
   <textobject>
      <para>This is a skeuomorphic image of a “postage
stamp.” Centrally, it features the DocBook wood
duck logo. the word “DocBook” appears on the left
hand side, rotated 90° counter-clockwise. The
DocBook tag line, “The Source for Documentation”
is printed in the upper-right corner.
</para>
   </textobject>
</mediaobject>

Example 1. An example of media object accessibility

One possible rendering of such an example:

Inspection of the HTML will reveal that the summary attribute is present on the div that wraps the figure and a details element precedes the image. These may or may not be rendered by your user agent depending on its accessibility features and settings.

See also $table-accessibility.

$mediaobject-details-placement — Specify placement of details on media objects.

Parameter:

{}mediaobject-details-placement

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.0.13

Synopsis

$mediaobject-details-placement := 'before'

Description

If a details element is generated for a media object, this parameter determines if it goes before or after the object.

The parameter consists of a series of tokens, “before”, “after”, or “element : position”. The named forms (e.g., figure:before) take precedence with the unnamed form serving as a default for any that don’t have named forms.

$mediaobject-exclude-extensions — Exclude media objects by extension.

Parameter:

{}mediaobject-exclude-extensions

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$mediaobject-exclude-extensions as xs:string := ".eps .ps .pdf"

Description

The mediaobject element (and inlinemediaobject) can contain several, alternative objects. The $mediaobject-exclude-extensions parameter provides a way to exclude some of them.

One common use case is to provide two versions of each image, one as a bitmap, perhaps a PNG , and another as a vector, perhaps an EPS . Then $mediaobject-exclude-extensions can be used to exclude “.eps” images from the web format and “.png” images from the print (or paged media) format.

$mediaobject-grouped-by-type — Are media grouped by type?

Parameter:

{}mediaobject-grouped-by-type

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.0.8

Synopsis

$mediaobject-grouped-by-type as xs:string := 'false'

Description

If $mediaobject-grouped-by-type is true, an extra directory level is implicit in the input path. Images are grouped by type, so image.png is assumed to be in $mediaobject-input-base-uri/png/image.png.

The f:mediaobject-amend-uri() function adds the type, which is computed by f:mediaobject-type().

$mediaobject-input-base-uri — Base URI of images and other media in the XML sources.

Parameter:

{}mediaobject-input-base-uri

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$mediaobject-input-base-uri as xs:string? := ()

Description

Computing the correct URI for media objects (images, videos, audio files, etc.) is complicated. See Section 5.4.1, “Mediaobject URIs”. The $mediaobject-input-base-uri is used to compute the absolute base URI of input media objects.

If the “cwd” extension function is available, then the default value of this parameter is the current working directory. Otherwise, the default value is the empty string.

The current working directory is only likely to be a useful value for this parameter if you are running the processor in the same directory where your XML source files are stored. See $v:mediaobject-input-base-uri.

$mediaobject-output-base-uri — Base URI of images and other media in the output.

Parameter:

{}mediaobject-output-base-uri

Defined in:

param.xsl

Used in:

main.xsl, param.xsl, modules/chunk-cleanup.xsl

Synopsis

$mediaobject-output-base-uri as xs:string? := ()

Description

Computing the correct URI for media objects (images, videos, audio files, etc.) is complicated. See Section 5.4.1, “Mediaobject URIs”. The $mediaobject-output-base-uri is used to compute the base URI of media objects in the output.

It defaults to the empty string. See $v:mediaobject-output-base-uri.

$mediaobject-output-paths — Preserve input mediaobject paths in output.

Parameter:

{}mediaobject-output-paths

Defined in:

param.xsl

Used in:

param.xsl, modules/chunk-cleanup.xsl

Synopsis

$mediaobject-output-paths as xs:string := 'true'

Description

If $mediaobject-output-paths is true, media object locations are assumed to be correct, relative to the resource base URI. For example, if the fileref is path/to/image.svg, that relative path will be preserved as the relative location against the resource base URI in the output.

If this parameter is false, then the path component of media objects is discarded. All media objects are assumed to be in the location identified by the resource base URI. In other words, path/to/image.svg will be treated as if it was simply image.svg.

$mediaobject-percentage-of-intrinsic-size — Compute media object percentage sizes based on intrinsic size.

Parameter:

{}mediaobject-percentage-of-intrinsic-size

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.7.0

Synopsis

$mediaobject-percentage-of-intrinsic-size as xs:string := 'false'

Description

When the width or depth of a media object is specified as a percentage, it is supposed to be a percentage of the available space. All versions of the DocBook xslTNG Stylesheets before version 2.7.0 incorrectly calculate percentages against the intrinsic size of the image.

This has been corrected in 2.7.0, but the previous, incorrect behavior can be preserved by setting $mediaobject-percentage-of-intrinsic-size to true.

ⓘ

Note

Percentages are problematic in any event as the stylesheets don’t usually know the actual width that will be available when the document is formatted. Most often, this results in a calculation against the $image-nominal-height and $image-nominal-width.

Available widths can sometimes be calculated, for example in CALS tables, but depth percentages are always resolved against the nominal height.

$mediaobject-video-element — Use the video element?

Parameter:

{}mediaobject-video-element

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$mediaobject-video-element as xs:string := 'video'

Description

This element identifies the element to use for video content. The default starting in version 1.11.0 is video where it had previously been iframe.

Video is a bit complicated, the video element works best for local video sources but won’t work for embedding content from other sites. If all of your content is embedded, specifying iframe here will be simplest.

If you need a mixture, of styles, it can be specified on a per-video basis with the db processing instruction using the video pseudo-attribute.

ⓘ

Note

The only supported values are iframe and video; you cannot use this parameter or the processing instruction to insert arbitrary element names.

$message-level — How chatty should status messages be?

Parameter:

{}message-level

Defined in:

param.xsl

Used in:

main.xsl, param.xsl, modules/chunk-cleanup.xsl

Synopsis

$message-level as xs:integer := 1

Description

Broadly speaking, there are three kinds of messages that the stylesheets produce: debugging messages, status messages, and errors. Debugging messages are controled by the $debug parameter. Error messages cause stylesheet processing to abort. Status messages fall somewhere in between. They alert you to facts about your document that you might want to fix, for example, broken cross references. If you ignore them, the stylesheets will produce some output.

Previously, status messages were always printed. This parameter has been introduced to provide more control. If $message-level is 0, most status messages will be suppressed. A value greater than 0 will cause some or all status messages to be printed. (At the time of this writing, all messages are at level 1, but it’s possible that more detailed messaging will be introduced in the future.)

$nominal-page-width — The nominal page width.

Parameter:

{}nominal-page-width

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Used by:

$image-nominal-width

Synopsis

$nominal-page-width := '6in'

Description

To calculate the width of the columns in some complex CALS tables, the stylesheets need to know the page width. The $nominal-page-width is used for this value.

$number-single-appendix — Number a single appendix?

Parameter:

{}number-single-appendix

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$number-single-appendix := 'true'

Description

If a book (or other element) has several appendixes, they will be numbered, usually “A”, “B”, “C”, etc. If there is only a single appendix, it will be numbered if $number-single-appendix is true. Otherwise, it will be unnumbered.

This can be used to create the numbered title “Appendix” for a single appendix.

$olink-databases — External olink databases.

Parameter:

{}olink-databases

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$olink-databases as xs:string := ''

Description

The $olink-databases parameter is a comma separated list of URIs. Each URI should contain an olink target database.

$on-unhandled-elements — How to process unhandled elements.

Parameter:

{}on-unhandled-elements

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.5.1

Synopsis

$on-unhandled-elements as xs:string := 'fail'

Description

This parameter controls how unhandled elements (for example, extension elements added in a custom schema) should be processed.

terminate

Generates an error messages and aborts the transformation.

render

Renders the tag name in the output, styled in red and yellow.

custom

Processes the template in the m:unhandled mode. These must be defined in a customization layer; there are no templates in this mode in the standard stylesheets.

$orderedlist-item-numeration — Numeration for nested ordered lists.

Parameter:

{}orderedlist-item-numeration

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$orderedlist-item-numeration := '1aiAI'

Description

The $orderedlist-item-numeration parameter controls the numeration style of nested orderedlist elements. Items in the top-level list will use the numeration style of the first character in $orderedlist-item-numeration, items in the second-level list will use the numeration style of the second character in the string, etc. If the list depth exceeds the number of characters in the $orderedlist-item-numeration, selection “wraps back around” to the first character.

In other words, if the string is “1ai”: list items at the first, fourth, seventh, tenth, etc. depth will have arabic numeration. List items at the second, fifth, eight, eleventh, etc. depth will have lowercase alpha numeration, etc.

$othername-in-middle — Treat othername as a middle name.

Parameter:

{}othername-in-middle

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$othername-in-middle := 'true'

Description

If $othername-in-middle is true, then the first othername in a personname will be presented as the person’s “middle” name. See t:person-name.

$output-media — The intended output media.

Parameter:

{}output-media

Defined in:

main.xsl, param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$output-media := 'screen'

Description

The $output-media parameter identifies the intended output medium, screen or print. It can be used to make conditional transformations.

$oxy-markup — Is Oxygen change tracking markup rendered?

Parameter:

{}oxy-markup

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$oxy-markup := 'false'

Description

If $oxy-markup is true, then the change tracking processing instructions that Oxygen inserts into the document will be transformed into elements marked with CSS classes for rendering in the output.

Rendering Oxygen change markup can be specified on a document-by-document basis with a db processing instruction. If the oxy-markup pseudo-attribute is true, the markup will be rendered. This processing instruction must be in the info element of the document element.

$page-style — Select the page style.

Parameter:

{}page-style

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$page-style as xs:string := 'article'

Description

This value selects the page style. The page style is reflected in the class attribute on the root html element. It is then used by the CSS stylesheets. A page style of “value” will be added to the class attribute as “value-style”.

The CSS print stylesheets support two styles: article and book. The book style places new components on a right-hand page and adjusts the inner margin for binding.

$pagetoc-dynamic — Make the on-page ToC dynamic?

Parameter:

{}pagetoc-dynamic

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$pagetoc-dynamic := 'true'

Description

If this value is true, and the on-page ToC is displayed, then it will be updated dynamically to reflect the readers position. This has two consequences. First, the section titles that are currently in view will be highlighted. The default highlighting is to make them a little darker and place a bullet next to them. The highlighting can be changed with CSS. Second, a clickable symbol is added in the upper left corner. This lets the reader toggle between dynamic, non-dynamic, and hidden views.

If the on-page ToC is not dynamic, then no highlighting is performed.

The clickable symbols can be changed as well, but it requires adding a bit more JavaScript to the page. Ensure that your code runs first and set the following properties:

1 |window.DocBook = {};
  |window.DocBook.pagetoc = {};
  |window.DocBook.pagetoc.decorated = "ON";
  |window.DocBook.pagetoc.plain = "OFF";
5 |window.DocBook.pagetoc.hidden = "HIDDEN";

The values can be strings or markup, such as an img element.

$pagetoc-elements — Elements that should have an on-page ToC.

Parameter:

{}pagetoc-elements

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$pagetoc-elements := ''

Description

This parameter is a space-separated list of element names (local names). An on-page ToC will be generated for elements with these names.

$pagetoc-js — Script to support the on-page ToC.

Parameter:

{}pagetoc-js

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$pagetoc-js := 'js/pagetoc.js'

Description

If the on-page ToC is enabled, a link to this script will be added to the document. This script must contain the JavaScript necessary to support the on-page ToC feature.

$paper-size — Select the paper style.

Parameter:

{}paper-size

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$paper-size as xs:string? := ()

Description

This value selects the paper size. The paper size is reflected in the class attribute on the root html element. It is then used by the CSS stylesheets.

The CSS print stylesheets support three page sizes: A4, A5, and (US) Letter. Additional sizes can be implemented in CSS.

$persistent-toc — Generate a persistent Table of Contents?

Parameter:

{}persistent-toc

Defined in:

param.xsl

Used in:

main.xsl, param.xsl, modules/chunk-cleanup.xsl, modules/chunk-output.xsl

Synopsis

$persistent-toc := 'false'

Description

If this value is true, then a persistent ToC will be generated.

$persistent-toc-css — Persistent ToC CSS.

Parameter:

{}persistent-toc-css

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$persistent-toc-css := 'css/docbook-toc.css'

Description

If the persistent ToC popup is enabled, a link to this CSS file will be added to the HTML HEAD.

$persistent-toc-filename — Name of file that holds the persistent ToC.

Parameter:

{}persistent-toc-filename

Defined in:

param.xsl

Used in:

param.xsl, modules/chunk-output.xsl

Since:

2.0.2

Synopsis

$persistent-toc-filename as xs:string? := 'persistent-toc.html'

Description

When the $persistent-toc parameter is true, the persistent ToC will be stored either in each HTML file, or in a single file that is loaded dynamically. If $persistent-toc-filename is not empty, then it will be used as the name for an external file that will be loaded when the ToC is requested.

$persistent-toc-js — Script to support the persistent ToC.

Parameter:

{}persistent-toc-js

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$persistent-toc-js := 'js/persistent-toc.js'

Description

If the persistent ToC is enabled, a link to this script will be added to the document. This script must contain the JavaScript necessary to support the persistent ToC feature.

$persistent-toc-search — Generate a search box in the persistent ToC.

Parameter:

{}persistent-toc-search

Defined in:

param.xsl

Used in:

param.xsl, modules/chunk-output.xsl

Synopsis

$persistent-toc-search := 'true'

Description

If this value is true, then a search box is added to the top of the persistent Table of Contents (ToC). Any string typed into this search box will be used to filter the entries shown below it.

The filter is a case-insensitive regular expression match against the text of each line in the ToC where arbitrary characters may occur anywhere in the string. In other words, the text “cat” will generate the regular expression “c.*a.*t.*” for the purpose of searching.

This setting has no effect if $persistent-toc is false.

$personal-name-style — The style for formatting personal names.

Parameter:

{}personal-name-style

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$personal-name-style := ()

Description

The stylesheets can format personal names in a variety of ways. This is usually locale dependent. If $personal-name-style is specified, it wil be used in preferance to the locale dependent style. See t:person-name.

$pixels-per-inch — The number of pixels per inch.

Parameter:

{}pixels-per-inch

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$pixels-per-inch := 96.0

Description

If the stylesheets need to convert between absolute and relative units (see Section 5.2, “Lengths and units”), this value is used to convert lengths into pixels. If $pixels-per-inch has the value 96, then 25% of a 6in width is 144px.

$prefer-xrefstyle — Always use xrefstyle if present on xref .

Parameter:

{}prefer-xrefstyle

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.8.0

Synopsis

$prefer-xrefstyle as xs:string := 'false'

Description

The processing expectations of xref from DocBook: The Definitive Guide are shown in Figure 1, “Processing expectations of the xref element”.

Under ordinary circumstances, the xref points to some element with its linkend attribute and the processing system generates appropriate cross-reference text. There are three ways for the author to influence the generated text:

If the endterm attribute is specified on xref, the content of the element pointed to by endterm will be used as the text of the cross-reference.

Otherwise, if the object pointed to has a specified xreflabel, the content of that attribute will be used as the cross-reference text.

Finally, the author may specify a keyword (or other information) in the xrefstyle attribute. Unlike endterm and xreflabel which have rigid semantics, the content of the xrefstyle attribute is simply additional information for the processing system. What effect it has, if any, is dependent on the processing system.

Figure 1. Processing expectations of the xref element

This hierarchy has the unfortunate consequence that once an element has an xreflabel, any xref that links to it will ignore the xrefstyle attribute on the xref.

If $prefer-xrefstyle is true, then xrefstyle is given higher priority than xreflabel. This parameter is false by default for backwards compatibility (and conformance to the guide).

$presentation-css — CSS to support presentation mode.

Parameter:

{}presentation-css

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$presentation-css := 'css/presentation.css'

Description

If presentation mode is enabled, a link to this CSS file will be added to the document.

$presentation-js — Script to support presentation mode.

Parameter:

{}presentation-js

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$presentation-js := 'js/presentation.js'

Description

If presentation mode is enabled, a link to this script will be added to the document. This script must contain the JavaScript necessary to support the presentation mode features.

$presentation-mode — Format the output for use as a presentation?

Parameter:

{}presentation-mode

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.1.5

Synopsis

$presentation-mode := 'false'

Description

If this parameter is true, the presentation mode CSS and JavaScript links will be included.

$procedure-step-numeration — Numeration for nested procedure steps.

Parameter:

{}procedure-step-numeration

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$procedure-step-numeration := '1aiAI'

Description

The $procedure-step-numeration parameter controls the numeration style of nested steps and substeps in a procedure. Steps at the top level will use the numeration style of the first character in $procedure-step-numeration, substeps at the second-level will use the numeration style of the second character in the string, etc. If the step depth exceeds the number of characters in the $procedure-step-numeration, selection “wraps back around” to the first character.

In other words, if the string is “1ai”: steps at the first, fourth, seventh, tenth, etc. depth will have arabic numeration. Steps at the second, fifth, eight, eleventh, etc. depth will have lowercase alpha numeration, etc.

$productionset-lhs-rhs-separator — Separator in productions.

Parameter:

{}productionset-lhs-rhs-separator

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$productionset-lhs-rhs-separator := ':='

Description

A productionset consists of non-terminals on the “left hand side” (LHS) and the productions that they expand to on the “right hand side” (RHS). When formatted, this string will be used as the separator between the left- and right-hand sides.

$profile-arch — Profile tokens for “arch”

Parameter:

{}profile-arch

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$profile-arch := ''

Description

The tokens (separated by $profile-separator) specified for $profile-arch are matched against the values in the arch attribute. See Section 2.9, “Effectivity attributes and profiling”.

$profile-audience — Profile tokens for “audience”

Parameter:

{}profile-audience

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$profile-audience := ''

Description

The tokens (separated by $profile-separator) specified for $profile-audience are matched against the values in the audience attribute. See Section 2.9, “Effectivity attributes and profiling”.

$profile-condition — Profile tokens for “condition”

Parameter:

{}profile-condition

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$profile-condition := ''

Description

The tokens (separated by $profile-separator) specified for $profile-condition are matched against the values in the condition attribute. See Section 2.9, “Effectivity attributes and profiling”.

$profile-conformance — Profile tokens for “conformance”

Parameter:

{}profile-conformance

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$profile-conformance := ''

Description

The tokens (separated by $profile-separator) specified for $profile-conformance are matched against the values in the conformance attribute. See Section 2.9, “Effectivity attributes and profiling”.

$profile-lang — Profile tokens for “xml:lang”

Parameter:

{}profile-lang

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$profile-lang := ''

Description

The tokens (separated by $profile-separator) specified for $profile-lang are matched against the values in the xml:lang attribute. See Section 2.9, “Effectivity attributes and profiling”.

$profile-os — Profile tokens for “os”

Parameter:

{}profile-os

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$profile-os := ''

Description

The tokens (separated by $profile-separator) specified for $profile-os are matched against the values in the os attribute. See Section 2.9, “Effectivity attributes and profiling”.

$profile-outputformat — Profile tokens for “outputformat”

Parameter:

{}profile-outputformat

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$profile-outputformat := ''

Description

The tokens (separated by $profile-separator) specified for $profile-outputformat are matched against the values in the outputformat attribute. See Section 2.9, “Effectivity attributes and profiling”.

$profile-revision — Profile tokens for “revision”

Parameter:

{}profile-revision

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$profile-revision := ''

Description

The tokens (separated by $profile-separator) specified for $profile-revision are matched against the values in the revision attribute. See Section 2.9, “Effectivity attributes and profiling”.

$profile-revisionflag — Profile tokens for “revisionflag”

Parameter:

{}profile-revisionflag

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$profile-revisionflag := ''

Description

The tokens (separated by $profile-separator) specified for $profile-revisionflag are matched against the values in the revisionflag attribute. See Section 2.9, “Effectivity attributes and profiling”.

$profile-role — Profile tokens for “role”

Parameter:

{}profile-role

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$profile-role := ''

Description

The tokens (separated by $profile-separator) specified for $profile-role are matched against the values in the role attribute. See Section 2.9, “Effectivity attributes and profiling”.

$profile-security — Profile tokens for “security”

Parameter:

{}profile-security

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$profile-security := ''

Description

The tokens (separated by $profile-separator) specified for $profile-security are matched against the values in the security attribute. See Section 2.9, “Effectivity attributes and profiling”.

$profile-separator — The profile separator character.

Parameter:

{}profile-separator

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$profile-separator := ';'

Description

The profiling parameters (and the profiling attributes) are strings. Profiling operates on sets of tokens. The strings in each case are divided into tokens by separating them at the $profile-separator character. Common values for separator include “;” and “ “ (space). See Section 2.9, “Effectivity attributes and profiling”.

$profile-userlevel — Profile tokens for “userlevel”

Parameter:

{}profile-userlevel

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$profile-userlevel := ''

Description

The tokens (separated by $profile-separator) specified for $profile-userlevel are matched against the values in the userlevel attribute. See Section 2.9, “Effectivity attributes and profiling”.

$profile-vendor — Profile tokens for “vendor”

Parameter:

{}profile-vendor

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$profile-vendor := ''

Description

The tokens (separated by $profile-separator) specified for $profile-vendor are matched against the values in the vendor attribute. See Section 2.9, “Effectivity attributes and profiling”.

$profile-wordsize — Profile tokens for “wordsize”

Parameter:

{}profile-wordsize

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$profile-wordsize := ''

Description

The tokens (separated by $profile-separator) specified for $profile-wordsize are matched against the values in the wordsize attribute. See Section 2.9, “Effectivity attributes and profiling”.

$qandadiv-default-toc — Generate a table-of-contents for qandadiv elements?

Parameter:

{}qandadiv-default-toc

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$qandadiv-default-toc := $qandaset-default-toc

Description

If this parameter is true, by default a table-of-contents will be generated at the beginning of each qandadiv.

$qandaset-default-label — The default label for qandaset elements.

Parameter:

{}qandaset-default-label

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$qandaset-default-label := 'number'

Description

Question and answers can be rendered with a few different labeling styles. This parameter selects the default style.

$qandaset-default-toc — Generate a table-of-contents for qandaset elements?

Parameter:

{}qandaset-default-toc

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Used by:

$qandadiv-default-toc

Synopsis

$qandaset-default-toc := 'true'

Description

If this parameter is true, by default a table-of-contents will be generated at the beginning of each qandaset.

$refentry-generate-name — Use “Name” as the title of a refentry .

Parameter:

{}refentry-generate-name

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$refentry-generate-name := true()

Description

If $refentry-generate-name is true, the title of the refentry page will be the word “Name”. Otherwise its value depends on the setting of $refentry-generate-title. Generally, exactly one of $refentry-generate-name or $refentry-generate-title should be true.

$refentry-generate-title — Use the subject of the page as the title of a refentry .

Parameter:

{}refentry-generate-title

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$refentry-generate-title := false()

Description

If $refentry-generate-title is true, the title of the refentry page will be the subject of the page (the refentrytitle, refdescriptor, or the first refname). Generally, exactly one of $refentry-generate-name or $refentry-generate-title should be true.

$relax-ng-grammar — Validation grammar.

Parameter:

{}relax-ng-grammar

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$relax-ng-grammar as xs:string? := ()

Description

If $relax-ng-grammar is provided, then the $v:standard-transforms will validate the document against the provided grammar.

$resource-base-uri — Base URI of additional resources.

Parameter:

{}resource-base-uri

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$resource-base-uri := './'

Description

Web pages rely on additional resources (CSS, JavaScript, etc.) to render properly. The $resource-base-uri is used as the base URI for these resources.

$revhistory-style — Rendering style for revhistory elements.

Parameter:

{}revhistory-style

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$revhistory-style := 'table'

Description

The revhistory element can be rendered as a list or a table. If $revhistory-style is “table>”, it will be rendered using the tabular style, if it is “list”, it will be rendered using the list style.

Example 1, “An example of char alignment” shows an example of a revhistory element.

<revhistory>
<revision>
<revnumber>1.0.0</revnumber>
<date>2020-07-27</date>
<author>
<personname>Norman Tovey-Walsh</personname>
</author>
<revdescription>
<para>Version 1.0.0 released.</para>
</revdescription>
</revision>
<revision>
<revnumber>0.0.1</revnumber>
<date>2020-05-08T06:24:00Z</date>
<author>
<personname>Norman Tovey-Walsh</personname>
</author>
<revremark>Development begins.</revremark>
</revision>
</revhistory>

Example 1. An example of char alignment

It is shown rendered as a table in Figure 1, “An example of revhistory rendered as a table”.

Revision History

1.0.0
27 Jul 2020
Norman Tovey-Walsh

Version 1.0.0 released.

0.0.1
06:24 08 May 2020
Norman Tovey-Walsh

Development begins.

Figure 1. An example of revhistory rendered as a table

The same revhistory is shown rendered as a list in Figure 2, “An example of revhistory rendered as a list”.

Revision History

1.0.0, 27 Jul 2020, Norman Tovey-Walsh

Version 1.0.0 released.

0.0.1, 06:24 08 May 2020, Norman Tovey-Walsh

Development begins.

Figure 2. An example of revhistory rendered as a list

The default style specified by $revhistory-style can be overridden on a case-by-case basis with the db processing instruction using the revhistory-style pseudo-attribute.

$section-numbers — Are sections numbered?

Parameter:

{}section-numbers

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$section-numbers as xs:string := 'true'

Description

If $section-numbers is true, sections that do not have an explicit label will be labeled with their section number.

See Section 3.6, “Controlling numeration”.

$section-numbers-inherit — Include ancestor section labels?

Synopsis

$section-numbers-inherit := 'true'

Description

This parameter is no longer used. See Section 3.6, “Controlling numeration”.

$section-toc-depth — Depth of sections in the table of contents.

Parameter:

{}section-toc-depth

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$section-toc-depth := 'unbounded'

Description

When generating a Table of Contents, the $section-toc-depth determines the maximum depth of section to include. See also $generate-toc and $generate-nested-toc.

The $section-toc-depth should be a positive integer or the token unbounded to indicate arbitrary depth.

$sections-inherit-from — Identifies what inherited numeration applies to sections.

Parameter:

{}sections-inherit-from

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$sections-inherit-from as xs:string := 'section'

Description

If section numbers inherit from their ancestors, these are the ancestors they inherit from.

See Section 3.6, “Controlling numeration”.

$sections-number-from — Identifies where (top-level) section numeration begins.

Parameter:

{}sections-number-from

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$sections-number-from as xs:string := 'component'

Description

Top-level section numbers (if sections are numbered) begin from here.

This parameter only applies to top-level sections. Nested sections are always numbered sequentially within their parent section.

See Section 3.6, “Controlling numeration”.

root

Top-level sections are numbered from the beginning of the document.

set

Top-level sections are numbered from their nearest ancestor set.

book

Top-level sections are numbered from their nearest ancestor book.

division

Top-level sections are numbered from their nearest ancestor division.

component

Top-level sections are numbered from their parent component.

$segmentedlist-style — Choose segmented list presentation style.

Parameter:

{}segmentedlist-style

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$segmentedlist-style := 'table'

Description

Segmented lists can be presented in two different ways: as lists or tables. The default is determined by $segmentedlist-style which must be either “list” or “table”.

Consider the following segmentedlist of (some of) the US states and their capitals:

 1 |<segmentedlist>
   |<segtitle>State</segtitle>
   |<segtitle>Capital</segtitle>
   |<seglistitem>
 5 |<seg>Alabama</seg>
   |<seg>Montgomery</seg>
   |</seglistitem>
   |<seglistitem>
   |<seg>Alaska</seg>
10 |<seg>Anchorage</seg>
   |</seglistitem>
   |<seglistitem>
   |<seg>Arkansas</seg>
   |<seg>Little Rock</seg>
15 |</seglistitem>
   |</segmentedlist>

This can be rendered as a table, as shown in Figure 1, “Segmented list formatted as a table”:

State | Capital
Alabama | Montgomery
Alaska | Anchorage
Arkansas | Little Rock

Figure 1. Segmented list formatted as a table

Or as a list, as shown in Figure 2, “Segmented list formatted as a list”:

State: Alabama

Capital: Montgomery

State: Alaska

Capital: Anchorage

State: Arkansas

Capital: Little Rock

Figure 2. Segmented list formatted as a list

The style can be selected on a per-list basis with the db processing instruction using the segmentedlist-style pseudo-attribute. A table-summary pseudo-attribute is also provided for the table summary in tabular presentations.

$sets-inherit-from — Identifies what inherited numeration applies to sets.

Parameter:

{}sets-inherit-from

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$sets-inherit-from as xs:string := ''

Description

If set numbers inherit from their ancestors, these are the ancestors they inherit from.

See Section 3.6, “Controlling numeration”.

$sets-number-from — Identifies where set numeration begins.

Parameter:

{}sets-number-from

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$sets-number-from as xs:string := 'set'

Description

Set numbers (if sets are numbered) begin from here.

See Section 3.6, “Controlling numeration”.

root

Sets are numbered from the beginning of the document.

set

Sets are numbered from their parent set.

$show-remarks — Show remark elements?

Parameter:

{}show-remarks

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$show-remarks := 'false'

Description

The remark element is useful for editorial comments and other notes that are not intended to appear in the final publication. If $show-remarks is true, then they will be included in the transformed result. Otherwise, they are omitted.

$sidebar-as-aside — Render sidebar as an aside?

Parameter:

{}sidebar-as-aside

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$sidebar-as-aside := false()

Description

The HTML aside element has specific semantics. Whether or not those semantics are consistent with the way sidebar is used in your DocBook documents is an open question. If $sidebar-as-aside is true, sidebar elements will be rendered as HTML aside elements, otherwise they will be rendered as div elements.

$sort-collation — Sorting collation.

Parameter:

{}sort-collation

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$sort-collation := 'http://www.w3.org/2005/xpath-functions/collation/html-ascii-case-insensitive'

Description

When items (the terms in a glossary, for example) are sorted, this collation is used.

$table-accessibility — Accessibility settings for tables.

Parameter:

{}table-accessibility

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$table-accessibility as xs:string := 'summary details'

Description

The $table-accessibility parameter determines how accessibility features are added to CALS tables*.

The value of this parameter is a space-separated list of strings. If the list contains:

summary

A summary attribute will be added to the table if an alt element or a textobject containing a single phrase is available.

details

A details element will be added if there is a textobject containing anything other than a single phrase available.

The list may contain either or both values. If other values are present, they are ignored.

See Example 1, “An example of table accessibility”.

<table frame="all">
   <title>Square numbers</title>
   <alt>The first four whole numbers
and their squares.</alt>
   <textobject>
      <para>This table shows the first four whole numbers
and their squares. (The square of a number is that
number times itself.)
</para>
   </textobject>
   <tgroup cols="2" colsep="1" rowsep="1">
      <thead>
         <row>
            <entry>
               <inlineequation>
                  <mathphrase>n</mathphrase>
               </inlineequation>
            </entry>
            <entry>
               <inlineequation>
                  <mathphrase>n<superscript>2</superscript>
                  </mathphrase>
               </inlineequation>
            </entry>
         </row>
      </thead>
      <tbody>
         <row>
            <entry>1</entry>
            <entry>1</entry>
         </row>
         <row>
            <entry>2</entry>
            <entry>4</entry>
         </row>
         <row>
            <entry>3</entry>
            <entry>9</entry>
         </row>
         <row>
            <entry>4</entry>
            <entry>16</entry>
         </row>
      </tbody>
   </tgroup>
</table>

Example 1. An example of table accessibility

One possible rendering of such an example:

Table 1. Square numbers

n | n²
1 | 1
2 | 4
3 | 9
4 | 16

Inspection of the HTML will reveal that the summary attribute is present on the element that wraps the table and a details element precedes it. These may or may not be rendered by your user agent depending on its accessibility features and settings.

See also $mediaobject-accessibility.

*

This parameter does not apply to HTML tables because the HTML table model supports these features directly.

$table-footnote-numeration — How are footnotes numbered in tables?

Parameter:

{}table-footnote-numeration

Defined in:

param.xsl

Used in:

main.xsl, param.xsl, modules/chunk-cleanup.xsl

Synopsis

$table-footnote-numeration := ('a')

Description

There are different styles of footnote numeration. This parameter contains a list of the symbols that should be used to mark footnotes in tables. If there could be more footnotes than symbols in the list, the last symbol in the list must be a character suitable for formatting numbers. See $footnote-numeration.

Footnote number begins with the first symbol in each table.

$theme-picker — Allow users to select themes?

Parameter:

{}theme-picker

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$theme-picker as xs:string := 'false'

Description

If this parameter is true, a JavaScript “theme picker” will be included in the document. This is provided through a hamburger menu in the upper-right corner. Given that one of the ostensible goals of providing themes is accessibility, it’s somewhat ironic that this feature is not especially accessible. Suggestions welcome.

$titleabbrev-passthrough — Pass titleabbrev elements through to the HTML.

Parameter:

{}titleabbrev-passthrough

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$titleabbrev-passthrough as xs:string := 'true'

Description

The titleabbrev element allows an author to provide an abbreviated title. This is used, for example, in the Table of Contents and in other “lists of titles” (LoT).

The actual titles of books, chapters, sections, etc. come from the title element. But if downstream processing generates an LoT dynamically, for example the on-page table of contents, it’s useful to have access to the titleabbrev content.

Unfortunately, HTML doesn’t provide an obvious mechanism to pass content that should not be rendered. (Simply suppressing the content with CSS is insufficient in this case because the abbreviated title really shouldn’t appear even if CSS is not available.) The only element that won’t render is the script element.

If this parameter is true, the rendered titleabbrev content will be embedded in the header using a script element. For example:

1 |<header>
  |<h1>
  |  <script type="text/html" class="titleabbrev"
  |  >Buckaroo Banzai</script>The Adventures of
5 |  Buckaroo Banzai Across the 8th Dimension
  |</h1>
  |</header>

If it’s present, the on-page ToC feature will render the abbreviated title. This parameter is true by default. Abbreviated titles are relatively uncommon and the presence of extra script elements isn’t likely to be a problem. But if your environment has hard requirements to avoid script elements, this feature can be disabled by setting the parameter to “false”.

$transclusion-id-fixup — Transclusion ID fixup.

Parameter:

{}transclusion-id-fixup

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$transclusion-id-fixup as xs:string := 'none'

Description

These stylesheets attempt to implement Transclusion. This parameter specifies the ID fixup.

$transclusion-link-scope — Transclusion link scope.

Parameter:

{}transclusion-link-scope

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$transclusion-link-scope as xs:string := 'global'

Description

These stylesheets attempt to implement Transclusion. This parameter specifies the link scope.

$transclusion-prefix-separator — Transclusion separator.

Parameter:

{}transclusion-prefix-separator

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$transclusion-prefix-separator as xs:string := '---'

Description

These stylesheets attempt to implement Transclusion. This parameter provides the separator for auto-generated prefixes.

$transclusion-suffix — Transclusion suffix.

Parameter:

{}transclusion-suffix

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$transclusion-suffix as xs:string := ''

Description

These stylesheets attempt to implement Transclusion. This parameter specifies the suffix used for transcluded IDs.

$transform-after — Transform the process document.

Parameter:

{}transform-after

Defined in:

param.xsl

Used in:

docbook.xsl, param.xsl

Used by:

t:docbook

Synopsis

$transform-after := ()

Description

Identifies the transform(s) that should be applied after the document has been transformed to HTML. See Section 5.7, “The pre- and post-processing pipeline”.

$transform-before — Transform the preprocessed document.

Parameter:

{}transform-before

Defined in:

param.xsl

Used in:

docbook.xsl, param.xsl

Synopsis

$transform-before := ()

Description

Identifies the transform(s) that should be applied before the document is transformation into HTML (but after the standard transformations). See Section 5.7, “The pre- and post-processing pipeline”.

$transform-original — Transform the original document.

Parameter:

{}transform-original

Defined in:

param.xsl

Used in:

docbook.xsl, param.xsl

Synopsis

$transform-original := ()

Description

Identifies the transform(s) that should be applied to the original document. See Section 5.7, “The pre- and post-processing pipeline”.

$transformed-docbook-input — URI for transformed DocBook input.

Parameter:

{}transformed-docbook-input

Defined in:

param.xsl

Used in:

docbook.xsl, param.xsl

Used by:

t:docbook

Synopsis

$transformed-docbook-input as xs:string? := ()

Description

Broadly speaking, the DocBook transformation process has three phases:

The DocBook input supplied by the user is run through a series of transformations to produce a document that is ready to be transformed to HTML. (See Section 5.7, “The pre- and post-processing pipeline”.)

That document is transformed into “HTML”. It’s not really HTML (yet) because some aspects (footnotes, chunking, etc.) are not yet resolved. (See $transformed-docbook-output.)

The “HTML” from the previous step is transformed to produce one (or more) HTML results.

If the $transformed-docbook-input parameter is not the empty sequence, it is assumed to be a URI. It will be made absolute against the base URI of the input document. The transformed DocBook that results from step 1 above will be output to that location.

$transformed-docbook-output — URI for transformed DocBook output.

Parameter:

{}transformed-docbook-output

Defined in:

param.xsl

Used in:

docbook.xsl, param.xsl

Used by:

t:docbook

Synopsis

$transformed-docbook-output as xs:string? := ()

Description

Broadly speaking, the DocBook transformation process has three phases:

The DocBook input supplied by the user is run through a series of transformations to produce a document that is ready to be transformed to HTML. (See $transformed-docbook-input.)

That document is transformed into “HTML”. It’s not really HTML (yet) because some aspects (footnotes, chunking, etc.) are not yet resolved.

The “HTML” from the previous step is transformed to produce one (or more) HTML results.

If the $transformed-docbook-output parameter is not the empty sequence, it is assumed to be a URI. It will be made absolute against the base URI of the input document. The transformed “HTML” that results from step 2 above will be output to that location.

$translate-suppress-elements — Elements in which translation is suppressed.

Parameter:

{}translate-suppress-elements

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.1.3

Synopsis

$translate-suppress-elements := ''

Description

This parameter is a list of (local) element names. Any output for these elements will have the translate attribute with the value “no”.

$unwrap-paragraphs — Attempt to unwrap paragraphs that contain block elements?

Parameter:

{}unwrap-paragraphs

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.0.13

Synopsis

$unwrap-paragraphs as xs:string := 'false'

Description

DocBook allows “block elements” (tables, figures, etc.) inside paragraphs or between paragraphs. The question of whether or not a table, figure, etc. is part of a paragraph is an editorial one. If you put the block element in the DocBook para, it will be in the resulting HTML p element.

Except, that’s not valid HTML. HTML deprives you of the editorial choice. If $unwrap-paragraphs is true, the stylesheets will attempt to unwrap block elements inside paragraphs, producing a sequence of paragraphs and blocks.

Note that with this option, a p element identified with an ID attribute is not guaranteed to contain all of the content that the DocBook paragraph contained.

$use-docbook-css — Create links to standard DocBook CSS stylesheets?

Parameter:

{}use-docbook-css

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$use-docbook-css as xs:string := 'true'

Description

If this parameter is true, then the output will contain links to the standard DocBook CSS stylesheets:

  |<link href="{$resource-base-uri}css/docbook.css"
  |rel="stylesheet" media="screen"/>
  |<link href="{$resource-base-uri}css/docbook-paged.css"
  |rel="stylesheet" media="print"/>

If $use-minified-css is true, then the links will be to minified CSS stylesheets. You can quickly disable all of these links by setting this parameter to false. There are a number of other stylesheets that are only conditionally included, see $verbatim-syntax-highlight-css and $persistent-toc-css. User defined stylesheets are added with $user-css-links.

$use-id-as-filename — Use id as filename when chunking.

Parameter:

{}use-id-as-filename

Defined in:

param.xsl

Used in:

param.xsl, modules/chunk.xsl

Used by:

f:chunk-filename()

Since:

2.5.0

Synopsis

$use-id-as-filename as xs:string := 'false'

Description

If this parameter is true, when a document is being chunked, the xml:id of a chunk will be used as the filename unless a processing instruction overrides it.

$use-label-numeration — Should label attributes be used for numeration?

Parameter:

{}use-label-numeration

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.7.4

Synopsis

$use-label-numeration as xs:string := 'false'

Description

All of the number parameters ($component-numbers, $division-numbers, $section-numbers, $formal-object-numbers) state that numbering only applies if there’s no explicit label. But the stylesheets actually ignore the label. If this parameter is true, then the label attribute, if present, will be used as the label. This parameter is false by default only for backwards compatibility.

See Section 3.6, “Controlling numeration”.

$use-minified-css — Create links to minified CSS?

Parameter:

{}use-minified-css

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$use-minified-css as xs:string := 'false'

Description

If this parameter is true, then the links to standard DocBook CSS stylesheets will be to minified versions instead of the “ordinary” versions. This does not effect links in $user-css-links.

$user-css-links — A list of user-defined CSS stylesheets.

Parameter:

{}user-css-links

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$user-css-links := ()

Description

This parameter is a space separated list of CSS stylesheets. Each will be added to the output after the standard stylesheets.

$user-document-class — Additional user-defined class added to document root elements.

Parameter:

{}user-document-class

Defined in:

param.xsl

Used in:

param.xsl, modules/chunk-cleanup.xsl

Since:

2.6.1

Synopsis

$user-document-class as xs:string := ''

Description

The value of this parameter is added to the top-level element’s class attribute. This provides an additional way of styling different document types with CSS.

$variablelist-panelset — Enable the “panelset” rendering for variable lists?

Parameter:

{}variablelist-panelset

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.2.1

Synopsis

$variablelist-panelset as xs:string := 'true'

Description

If this parameter is true, a “panel set” rendering may be selected for variablelist elements by placing panelset in its role attribute. In interactive presentations, these render as selectable, alternative “panels”. In other presentations, they render as a normal list.

Why

Panels are often used to show equivalent code samples in different languages (Groovy or Kotlin, JavaScript or TypeScript) or different versions of a language (Python 2.x or Python 3.x).

What

The actual content of the individual panels is constrainted only by the content model of listitem in variablelist.

How

With the panelset role attribute value. But note that in print output, this option is false by default.

$variablelist-termlength-threshold — Threshold value for considering varlistentry terms “long”

Parameter:

{}variablelist-termlength-threshold

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$variablelist-termlength-threshold := 20

Description

If the sum of the lengths of the term elements in a varlistentry exceeds this threshold, the variable list will have a “long” class. This can be used in CSS or in other downstream processing to decide whether or not the terms and their corresponding list items should be aligned side-by-side.

The length computation is just the number of characters. No attempt is made to adjust for wide or narrow characters.

$varlistentry-separate-terms — Output separate terms for variable list entries?

Parameter:

{}varlistentry-separate-terms

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.1.5

Synopsis

$varlistentry-separate-terms := 'false'

Description

If this parameter is true, each term in a varlistentry will be output in its own dt.

$vendor-css — Additional, vendor specific CSS.

Parameter:

{}vendor-css

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.2.2

Synopsis

$vendor-css as xs:string* := ()

Description

If this parameter allows you to add an additional stylesheet for vendor-specific CSS. This can be used, for example, to customize the CSS used for different paged media engines.

Two such stylesheets are provided:

vendor-ahf-portrait.css

An extension for the AntennaHouse Formatter that prints landscape material without rotating the page headers and footers.

This version is intended for documents that are printed in portrait orientation.

vendor-ahf-landscape.css

An extension for the AntennaHouse Formatter that prints portrait material without rotating the page headers and footers.

This version is intended for documents that are printed in landscape orientation.

$verbatim-callouts — A list determining how callouts are processed.

Parameter:

{}verbatim-callouts

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$verbatim-callouts as xs:string := 'linecolumn lines lineranges-first'

Description

The $verbatim-callouts parameter is a space separated list of token values. These token values determine which kinds of callouts in a programlistingco or screenco will be processed and how.

linecolumn

If “linecolumn” appears in the list then callouts that have a units attribute of linecolumn and specify both a line and column will be processed. A callout marker will be placed on the line and before the column indicated. Additional lines and columns will be added to the listing if necessary.

lines

If “lines” appears in the list then callouts that have a units attribute of linecolumn and specify only a line will be processed. A callout marker will be placed on the line and before the $callout-default-column.

lineranges-first

If “lineranges-first” appears in the list then callouts that have a units attribute of linerange will be processed. A callout marker will be placed on the first line and before the $callout-default-column.

Only one of lineranges-first and lineranges-all should be specified.

lineranges-all

If “lineranges-first” appears in the list then callouts that have a units attribute of linerange will be processed. A callout marker will be placed on every line in the range before the $callout-default-column.

Only one of lineranges-first and lineranges-all should be specified.

There is no support for areas with a units value of “calspair” or “linecolumnpair”. They are always ignored.

$verbatim-default-language — Default language for programlisting verbatim environments.

Parameter:

{}verbatim-default-language

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.5.0

Synopsis

$verbatim-default-language := 'none'

Description

If the language attribute is provided on a verbatim environment, that will be reflected in the output as a language-language class value. This is used by some browser-based syntax highlighters for language identification and can be used for styling.

When a programlisting doesn’t specify a language, the value of $verbatim-default-language will be used to construct one. No class will be output if the default language is the empty sequence. The default language only applies to programlisting elements.

$verbatim-embellish-linenumbers — Attempt to add line numbers to verbatim environments?

Parameter:

{}verbatim-embellish-linenumbers

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.5.0

Synopsis

$verbatim-embellish-linenumbers := 'true'

Description

When formatting verbatim environments, this flag controls whether or not any attempt will be done to number lines. Enabling this flag doesn’t necessarily mean that the embellishments will succeed (that depends on other settings; see Section 2.11.2, “Syntax highlighter”).

If this flag is true, line numbering may be attempted. If it is not, the listings will always be presented without line numbers. This parameter has no effect if $verbatim-embellishments is “false”.

$verbatim-embellishments — Attempt to embellish verbatim environments?

Parameter:

{}verbatim-embellishments

Defined in:

param.xsl

Used in:

main.xsl, param.xsl, modules/chunk-cleanup.xsl

Since:

2.5.0

Synopsis

$verbatim-embellishments := 'true'

Description

When formatting verbatim environments, this flag controls whether or not any attempt will be done to number lines, add syntax highlighting, or identify callouts. Enabling this flag doesn’t necessarily mean that the embellishments will succeed (that depends on other settings; see Section 2.11.2, “Syntax highlighter”).

If this flag is true, embellishments may be attempted. If it is not, the listings will always be presented without embellishment.

$verbatim-line-style — List of verbatim elements to be rendered in the line style.

Parameter:

{}verbatim-line-style

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$verbatim-line-style := 'programlisting programlistingco
                         screen screenco synopsis'

Description

This parameter is a space-separated list of element names (local names). Verbatim elements that appear in this list will be formatted using the line style by default. For a discussion of verbatim elements and styles, see Section 2.11.1, “Verbatim style”.

$verbatim-number-every-nth — Line numbering frequency.

Parameter:

{}verbatim-number-every-nth

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$verbatim-number-every-nth := 5

Description

When formatting verbatim environments with line numbers, every $verbatim-number-every-nth line is numbered.

$verbatim-number-first-line — Number the first line?

Parameter:

{}verbatim-number-first-line

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$verbatim-number-first-line := 'true'

Description

When formatting verbatim environments with line numbers, if $verbatim-number-first-line line is true, the first line will be numbered even it isn’t one of the $verbatim-number-every-nth lines.

$verbatim-number-minlines — Shortest listing to number.

Parameter:

{}verbatim-number-minlines

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$verbatim-number-minlines := '5'

Description

When formatting verbatim environments with line numbers, environments less than $verbatim-number-minlines in length will not be numbered.

$verbatim-number-separator — Separator between line numbers and lines.

Parameter:

{}verbatim-number-separator

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$verbatim-number-separator := '|'

Description

When formatting verbatim environments with line numbers, this separator is inserted (wrapped in a span with a class of nsep) between the line number and the text of the line.

In most presentations, CSS prevents the nsep from being displayed; instead, a CSS border is used as a separator. The $verbatim-number-separator is most often seen with text-only browsers.

$verbatim-numbered-elements — Verbatim environments that should be numbered.

Parameter:

{}verbatim-numbered-elements

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$verbatim-numbered-elements := 'programlisting programlistingco'

Description

This parameter is a space-separated list of element names (local names). Verbatim elements that appear in this list will be formatted with line numbers. For a discussion of verbatim elements and styles, see Section 2.11.1, “Verbatim style”.

$verbatim-plain-style — List of verbatim elements to be rendered in the plain style.

Parameter:

{}verbatim-plain-style

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$verbatim-plain-style as xs:string := 'address literallayout funcsynopsisinfo classsynopsisinfo'

Description

This parameter is a space-separated list of element names (local names). Verbatim elements that appear in this list will be formatted using the plain style by default. For a discussion of verbatim elements and styles, see Section 2.11.1, “Verbatim style”.

See also $v:verbatim-plain-style.

$verbatim-space — The space character to use when padding verbatim lines.

Parameter:

{}verbatim-space

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$verbatim-space := ' '

Description

When a verbatim line has to be padded in order to get a callout to appear in the correct column, this character will be used as the padding character. For a discussion of verbatim elements and styles, see Section 2.11.1, “Verbatim style”.

$verbatim-style-default — The default verbatim style.

Parameter:

{}verbatim-style-default

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$verbatim-style-default := 'lines'

Description

The default verbatim style for verbatim environments that do not specify a style explicitly. For a discussion of verbatim elements and styles, see Section 2.11.1, “Verbatim style”.

$verbatim-syntax-highlight-css — Stylesheet for syntax highlighting.

Parameter:

{}verbatim-syntax-highlight-css

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$verbatim-syntax-highlight-css := 'css/pygments.css'

Description

If the $verbatim-syntax-highlight-languages parameter is non-empty, then this stylesheet will be linked from the HTML document. The purpose of this stylesheet is to provide styling (fonts, colors, etc.) for syntax highlighted verbatim listings.

$verbatim-syntax-highlight-languages — Languages for which syntax highlighting should be performed.

Parameter:

{}verbatim-syntax-highlight-languages

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$verbatim-syntax-highlight-languages := 'python perl html xml xslt xquery javascript json css'

Description

This parameter is a space-separated list of programming languages. If the Pygments syntax highlighter is available, the stylesheets can apply syntax highlighting to program listings. If the program listing language (as specified in the language attribute) appears in the list of $verbatim-syntax-highlight-languages, syntax highlighting will be attempted.

ⓘ

Note

Syntax highlighting is incompatible with inline markup in the program listing; the embedded markup will be ignored.

The examples in this guide show syntax highlighting applied to XML.

See also $v:verbatim-syntax-highlight-options and $v:verbatim-syntax-highlight-pygments-options.

$verbatim-syntax-highlighter — Selects the syntax highlighter.

Parameter:

{}verbatim-syntax-highlighter

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$verbatim-syntax-highlighter as xs:string := 'pygments'

Description

This parameter specifies the syntax highlighter to use. Most of the parameters related to syntax highlighting only work if the pygments highlighter is selected. However, that requires running an external process which might not be available and which, even if it is available, has an impact on performance. Using Pygments has the advantage that the stylesheets have more control over the process and it is available both for online and paged media formats.

The alternative to running an external program is to use JavaScript to highlight the listing in the browser. This is faster at formatting time, but limits syntax highlighting to those environments where JavaScript is available.

The following options are supported:

pygments

This is the default highlighter.

highlight.js

Uses the highlight.js JavaScript library to perform syntax highlighting. The $highlight-js-head-elements variable determines what CSS stylesheets and JavaScript libraries are loaded for this option.

Version 11.10.0 of highlight.js is included, configured to highlight the following languages: abnf, apache, asciidoc, bash, c, cmake, coffeescript, cpp, csharp, css, diff, go, gradle, groovy, http, ini, java, javascript, json, kotlin, latex, less, lisp, lua, makefile, markdown, nginx, objectivec, perl, pgsql, php, php-template, plaintext, powershell, protobuf, python, python-repl, r, ruby, rust, scala, scheme, scss, shell, sql, swift, typescript, xml, yaml. Only the default CSS is included.

Version 2.9.0 of highlightjs-line-numbers.js is also included.

prism

Uses the Prism JavaScript library to perform syntax highlighting. The $prism-js-head-elements variable determines what CSS stylesheets and JavaScript libraries are loaded for this option.

none

Disables syntax highlighting but also suppresses messages about features that are not available because syntax highlighting is disabled.

$verbatim-table-style — List of verbatim elements to be rendered in the table style.

Parameter:

{}verbatim-table-style

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$verbatim-table-style := ''

Description

This parameter is a space-separated list of element names (local names). Verbatim elements that appear in this list will be formatted using the table style by default. For a discussion of verbatim elements and styles, see Section 2.11.1, “Verbatim style”.

$verbatim-trim-leading-blank-lines — Trim leading blank lines off of verbatim environments?

Parameter:

{}verbatim-trim-leading-blank-lines

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Since:

2.1.2

Synopsis

$verbatim-trim-leading-blank-lines := 'false'

Description

If a verbatim environment is processed with a syntax highlighter, the highlighter may remove leading blank lines. This option will produce that result for verbatim environments that are not syntax highlighted.

If leading blank lines aren’t significant, setting $verbatim-trim-leading-blank-lines will cause the stylesheets to trim blank (that is, entirely empty) lines from the beginning of verbatim environments.

(This parameter is false by default for backwards compatibility.)

$verbatim-trim-trailing-blank-lines — Trim trailing blank lines off of verbatim environments?

Parameter:

{}verbatim-trim-trailing-blank-lines

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$verbatim-trim-trailing-blank-lines := 'true'

Description

Trailing blank lines can be introduced into verbatim environments in a number of ways. Transcluded text files may have trailing blank lines, for example, and authors often put a newline before the closing tag of an environment.

This can produce spurious looking listings in the documentation. If trailing newlines aren’t significant, setting $verbatim-trim-trailing-blank-lines will cause the stylesheets to trim blank (that is, entirely empty) lines from the end of verbatim environments.

$warn-about-missing-localizations — Warn about missing localization?

Parameter:

{}warn-about-missing-localizations

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$warn-about-missing-localizations as xs:string := 'true'

Description

If this parameter is true, then warning messages will be issued for missing localizations.

$xlink-arclist-after — Suffix used for inline rendering of a list of XLink arcs.

Parameter:

{}xlink-arclist-after

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$xlink-arclist-after := '] '

Description

When rendering a list of XLinks inline, this precedes the list.

$xlink-arclist-before — Prefix used for inline rendering of a list of XLink arcs.

Parameter:

{}xlink-arclist-before

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$xlink-arclist-before := ' ['

Description

When rendering a list of XLinks inline, this precedes the list.

$xlink-arclist-sep — Link separator used when rendering a list of XLink arcs.

Parameter:

{}xlink-arclist-sep

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$xlink-arclist-sep := ', '

Description

When rendering a list of XLinks inline, this separates the links.

$xlink-arclist-titlesep — Title separator used when rendering a list of XLink arcs.

Parameter:

{}xlink-arclist-titlesep

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$xlink-arclist-titlesep := ': '

Description

When rendering a list of XLinks inline, this separates the link titles.

$xlink-icon-closed — Icon indicating hidden XLink links.

Parameter:

{}xlink-icon-closed

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$xlink-icon-closed := ()

Description

If the JavaScript presentation of extended XLinks is used, this icon marks the place where a multi-ended link can be revealed. The default icon is ▶ (&#x25B6;). See also: $xlink-icon-open.

$xlink-icon-open — XLink CSS.

Parameter:

{}xlink-icon-open

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$xlink-icon-open := ()

Description

If the JavaScript presentation of extended XLinks is used, this icon marks the place where a multi-ended link has been revealed. The default icon is ▼ (&#x25BC;).

ⓘ

Note

The default icons are quite large compared to running text of the same size. To compensate, they’re styled at a font-size of 70%. If you select different icons, you may need to adjust the font-size associated with the xlink-arc-list class.

$xlink-js — Script to support extended XLinks.

Parameter:

{}xlink-js

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$xlink-js := 'js/xlink.js'

Description

If the extended XLinks appear in the document, a link to this script will be added to the document. This script must contain the JavaScript necessary to support rendering extended XLinks.

$xlink-style — Presentation style for XLink extended links.

Parameter:

{}xlink-style

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$xlink-style := 'document'

Description

The stylesheets support XLink extended links. Extended links make it possible to have one-to-many links. That is, a single link such as DocBook [DocBook.org, DocBook on Wikipedia] may point to more than one target. Three styles are supported:

inline

Renders a link to each target inline after the originating link.

javascript

Uses JavaScript to render the links in a drop-down menu.

document

The preceding XLink styles apply to the entire document, you cannot specify inline presentation in some cases and JavaScript presentation in others. However, if you specify “document” as the value for $xlink-style, then a db processing instruction in the document’s top-level info element can be used to control the presentation. Specify the style in the xlink-style pseudo-attribute.

If the document style is selected and no processing instruction specifying a style exists, the $xlink-style-default style will be selected.

$xlink-style-default — Default XLink style.

Parameter:

{}xlink-style-default

Defined in:

param.xsl

Used in:

main.xsl, param.xsl

Synopsis

$xlink-style-default := 'inline'

Description

Specifies the default XLink style if “document” is specified for the $xlink-style and no processing instruction specifying a style exists.

Must be either “inline” or “javascript”.

$xspec — Are we running XSpec tests?

Parameter:

{}xspec

Defined in:

param.xsl

Used in:

param.xsl

Synopsis

$xspec as xs:string := 'false'

Description

This parameter is only true if the stylesheets are running in the context of the XSpec test harness. This allows tests to be crafted such that normal variations (Saxon HE vs. EE, the version of the stylesheets, or the current time, for example) don’t introduce spurious differences in the results, causing tests to fail.

II. Variables reference

Table of Contents

$arg-choice-def-close-str, …

$err:DYNAMIC-PROFILE-EVAL-ERROR

$err:DYNAMIC-PROFILE-SYNTAX-ERROR

$err:INTERNAL-HIGHLIGHT-ERROR

$err:INTERNAL-RENUMBER-ERROR

$err:INVALID-AREAREFS

$err:INVALID-CALS

$err:INVALID-CONSTRAINT

$err:INVALID-DYNAMIC-PROFILE-ERROR

$err:INVALID-INJECT

$err:INVALID-NAME-STYLE

$err:INVALID-PRODUCTIONRECAP

$err:INVALID-RESULTS-REQUESTED

$err:INVALID-TEMPLATE

$err:INVALID-TRANSFORM

$v:personal-name-styles

$v:VERSION

$v:VERSION-ID

$v:admonition-icons

$v:annotation-close

$v:as-json

$v:as-xml

$v:bridgehead-map

$v:chunk

$v:chunk-filter-namespaces

$v:chunk-renumber-footnotes

$v:custom-localizations

$v:debug

$v:formal-object-title-placement

$v:formalgroup-nested-object-title-placement

$v:highlight-js-head-elements

$v:image-nominal-height

$v:image-nominal-width

$v:invisible-characters

$v:localization-base-uri

$v:mathml-js-roles

$v:media-type-default

$v:media-type-map

$v:mediaobject-details-placement

$v:mediaobject-exclude-extensions

$v:mediaobject-input-base-uri

$v:mediaobject-output-base-uri

$v:nominal-page-width

$v:olink-databases

$v:pi-db-attributes-are-uris

$v:prism-js-head-elements

$v:standard-transforms

$v:templates

$v:theme-list

$v:title-groups

$v:title-properties

$v:titlepage-default

$v:toc-close

$v:toc-open

$v:unit-scale

$v:user-title-groups

$v:user-title-properties

$v:user-xref-groups

$v:user-xref-properties

$v:verbatim-callouts

$v:verbatim-line-style

$v:verbatim-number-every-nth

$v:verbatim-number-first-line

$v:verbatim-number-minlines

$v:verbatim-numbered-elements

$v:verbatim-plain-style

$v:verbatim-properties

$v:verbatim-space

$v:verbatim-syntax-highlight-languages

$v:verbatim-syntax-highlight-options

$v:verbatim-syntax-highlight-pygments-options

$v:verbatim-table-style

$v:xref-groups

$v:xref-properties

$arg-choice-def-close-str, $v:arg-choice-def-open-str, $v:arg-choice-opt-close-str, $v:arg-choice-opt-open-str, $v:arg-choice-plain-close-str, $v:arg-choice-plain-open-str, $v:arg-choice-req-close-str, $v:arg-choice-req-open-str, $v:arg-or-sep, $v:arg-rep-def-str, $v:arg-rep-norepeat-str, $v:arg-rep-repeat-str — Punctuation marks used in formatting cmdsynopsis.

Variable:

{http://docbook.org/ns/docbook/variables}arg-choice-def-close-str

{http://docbook.org/ns/docbook/variables}arg-choice-def-open-str

{http://docbook.org/ns/docbook/variables}arg-choice-opt-close-str

{http://docbook.org/ns/docbook/variables}arg-choice-opt-open-str

{http://docbook.org/ns/docbook/variables}arg-choice-plain-close-str

{http://docbook.org/ns/docbook/variables}arg-choice-plain-open-str

{http://docbook.org/ns/docbook/variables}arg-choice-req-close-str

{http://docbook.org/ns/docbook/variables}arg-choice-req-open-str

{http://docbook.org/ns/docbook/variables}arg-or-sep

{http://docbook.org/ns/docbook/variables}arg-rep-def-str

{http://docbook.org/ns/docbook/variables}arg-rep-norepeat-str

{http://docbook.org/ns/docbook/variables}arg-rep-repeat-str

Defined in:

modules/variable.xsl (12)

Used in:

main.xsl

Synopsis

<xsl:variable name="v:arg-choice-opt-open-str">
   <span class="cmdpunct">[</span>
</xsl:variable>

<xsl:variable name="v:arg-choice-opt-close-str">
   <span class="cmdpunct">]</span>
</xsl:variable>

<xsl:variable name="v:arg-choice-req-open-str">
   <span class="cmdpunct">{</span>
</xsl:variable>

<xsl:variable name="v:arg-choice-req-close-str">
   <span class="cmdpunct">}</span>
</xsl:variable>

<xsl:variable name="v:arg-choice-plain-open-str">
   <xsl:text/>
</xsl:variable>

<xsl:variable name="v:arg-choice-plain-close-str">
   <xsl:text/>
</xsl:variable>

<xsl:variable name="v:arg-choice-def-open-str">
   <span class="cmdpunct">[</span>
</xsl:variable>

<xsl:variable name="v:arg-choice-def-close-str">
   <span class="cmdpunct">]</span>
</xsl:variable>

<xsl:variable name="v:arg-rep-repeat-str">
   <span class="cmdpunct">…</span>
</xsl:variable>

<xsl:variable name="v:arg-rep-norepeat-str">
   <xsl:text/>
</xsl:variable>

<xsl:variable name="v:arg-rep-def-str">
   <xsl:text/>
</xsl:variable>

<xsl:variable name="v:arg-or-sep">
   <span class="cmdpunct"> | </span>
</xsl:variable>

Description

The cmdsynopsis element is used to model the syntax of command line interfaces. Broadly, a command line interface consists of a command followed by a variety of options. These options can be optional or required and may or may not be repeatable.

User expections about how these should be formatted vary by platform and publisher. The $v:arg-… variables are designed to make it easy to adapt to many common forms of presentation. Each contains (usually) a single character used as a delimiter:

Variable | Use in a synopsis | Defaulta
$v:arg-choice-def-close-str | Follows a default option | ]
$v:arg-choice-def-open-str | Precedes a default option | [
$v:arg-choice-opt-close-str | Follows an optional option | ]
$v:arg-choice-opt-open-str | Precedes an optional option | [
$v:arg-choice-plain-close-str | Follows an option identified as “plain” | (empty string)
$v:arg-choice-plain-open-str | Precedes an option identified as “plain” | (empty string)
$v:arg-choice-req-close-str | Follows a required option | }
$v:arg-choice-req-open-str | Precedes a required option | {
$v:arg-or-sep | Separator between options in an “or” group | |
$v:arg-rep-def-str | Identifies a repeatable default option | (empty string)
$v:arg-rep-norepeat-str | Identifies a non-repeatable option | (empty string)
$v:arg-rep-repeat-str | Identifies an explicitly repeatable option | …

a

Each of the default characters is placed in an HTML span with the class “cmdpunct”.

A contrived cmdsynopsis appears in Example 1, “An example of a cmdsynopsis”.

<cmdsynopsis>
   <command>command</command>
   <arg choice="plain">
      <option>--path <replaceable>PATH</replaceable>
      </option>
   </arg>
   <arg>-opt</arg>
   <arg choice="req">-req</arg>
   <arg rep="repeat">-D<replaceable>name</replaceable>
   </arg>
   <group>
      <arg choice="plain">-M</arg>
      <arg choice="plain">-MD</arg>
   </group>
</cmdsynopsis>

Example 1. An example of a cmdsynopsis

One possible rendering of such a synopsis:

command --path PATH [-opt] {-req} [-Dname…] [-M | -MD]

$err:DYNAMIC-PROFILE-EVAL-ERROR — Error evaluating dynamic profile expression.

Variable:

{http://docbook.org/ns/docbook/errors}DYNAMIC-PROFILE-EVAL-ERROR

Defined in:

modules/errors.xsl

Used in:

Not used.

Synopsis

$dbe:DYNAMIC-PROFILE-EVAL-ERROR := xs:QName('dbe:DYNAMIC-PROFILE-EVAL-ERROR')

Description

This error is raised if the variable referenced in a dynamic profile expression (see Section 2.9, “Effectivity attributes and profiling”) is not available and the $dynamic-profile-error configuration is “error”.

$err:DYNAMIC-PROFILE-SYNTAX-ERROR — Internal error processing dynamic profiles.

Variable:

{http://docbook.org/ns/docbook/errors}DYNAMIC-PROFILE-SYNTAX-ERROR

Defined in:

modules/errors.xsl

Used in:

Not used.

Synopsis

$dbe:DYNAMIC-PROFILE-SYNTAX-ERROR := xs:QName('dbe:DYNAMIC-PROFILE-SYNTAX-ERROR')

Description

This is an internal error. It indicates that the syntax of a dynamic profiling expression was unrecognized. Since dynamic profiling should only be applied to expressions that have been recognized, this error should never happen.

$err:INTERNAL-HIGHLIGHT-ERROR — Internal error in syntax highlighting.

Variable:

{http://docbook.org/ns/docbook/errors}INTERNAL-HIGHLIGHT-ERROR

Defined in:

modules/errors.xsl

Used in:

highlight.xsl

Synopsis

$dbe:INTERNAL-HIGHLIGHT-ERROR := xs:QName('dbe:INTERNAL-HIGHLIGHT-ERROR')

Description

This is an internal error that should never happen. It indicates that stylesheet processing of program listings attempted to use the syntax highlighter when the syntax highlighter was known to be unavailable. If you see this error, please file an issue for it.

$err:INTERNAL-RENUMBER-ERROR — Internal error in chunk formatting.

Variable:

{http://docbook.org/ns/docbook/errors}INTERNAL-RENUMBER-ERROR

Defined in:

modules/errors.xsl

Used in:

modules/chunk-cleanup.xsl

Synopsis

$dbe:INTERNAL-RENUMBER-ERROR := xs:QName('dbe:INTERNAL-RENUMBER-ERROR')

Description

This is an internal error that should never happen. It indicates that stylesheet processing of footnotes during “chunking” has gone awry. If you see this error, please file an issue for it.

$err:INVALID-AREAREFS — Callout area refers to invalid target.

Variable:

{http://docbook.org/ns/docbook/errors}INVALID-AREAREFS

Defined in:

modules/errors.xsl

Used in:

main.xsl

Synopsis

$dbe:INVALID-AREAREFS := xs:QName('dbe:INVALID-AREAREFS')

Description

This error indicates that a calloutlist includes an ID/IDREF link to a callout, but the element identified by the ID is not an areaset, area, or callout.

This should be identified as a validation error by a Schematron rule.

$err:INVALID-CALS — CALS table is invalid.

Variable:

{http://docbook.org/ns/docbook/errors}INVALID-CALS

Defined in:

modules/errors.xsl

Used in:

Not used.

Synopsis

$dbe:INVALID-CALS := xs:QName('dbe:INVALID-CALS')

Description

This error is raised if a CALS table is invalid. The following error conditions give rise to this error:

The number of columns in the table exceeds the specified cols value on tgroup.

There is a named reference to a colspec but no colspec with that name exists.

There is a named reference to a spanspec but no spanspec with that name exists.

$err:INVALID-CONSTRAINT — Incorrect constraint reference.

Variable:

{http://docbook.org/ns/docbook/errors}INVALID-CONSTRAINT

Defined in:

modules/errors.xsl

Used in:

main.xsl

Synopsis

$dbe:INVALID-CONSTRAINT := xs:QName('dbe:INVALID-CONSTRAINT')

Description

This error is raised if a constraint link points to something other than a constraintdef.

This should be identified as a validation error by a Schematron rule.

$err:INVALID-DYNAMIC-PROFILE-ERROR — Invalid value specified for $dynamic-profile-error.

Variable:

{http://docbook.org/ns/docbook/errors}INVALID-DYNAMIC-PROFILE-ERROR

Defined in:

modules/errors.xsl

Used in:

Not used.

Synopsis

$dbe:INVALID-DYNAMIC-PROFILE-ERROR := xs:QName('dbe:INVALID-DYNAMIC-PROFILE-ERROR')

Description

This error is raised if the value of $dynamic-profile-error is not a recognized value.

$err:INVALID-INJECT — Invalid callout area specification.

Variable:

{http://docbook.org/ns/docbook/errors}INVALID-INJECT

Defined in:

modules/errors.xsl

Used in:

main.xsl

Synopsis

$dbe:INVALID-INJECT := xs:QName('dbe:INVALID-INJECT')

Description

This error is raised if a programlistingco or screenco contains invalid areas. This can arise from invalid markup, unsupported units in an area, or unparseable coordinates in an area.

$err:INVALID-NAME-STYLE — Invalid name style.

Variable:

{http://docbook.org/ns/docbook/errors}INVALID-NAME-STYLE

Defined in:

modules/errors.xsl

Used in:

main.xsl

Synopsis

$dbe:INVALID-NAME-STYLE := xs:QName('dbe:INVALID-NAME-STYLE')

Description

This error indicates that a request was made to format a personal name (see t:person-name) with an unknown style name.

$err:INVALID-PRODUCTIONRECAP — Incorrect production reference.

Variable:

{http://docbook.org/ns/docbook/errors}INVALID-PRODUCTIONRECAP

Defined in:

modules/errors.xsl

Used in:

main.xsl

Synopsis

$dbe:INVALID-PRODUCTIONRECAP := xs:QName('dbe:INVALID-PRODUCTIONRECAP')

Description

This error is raised if a productionrecap link points to something other than a production.

This should be identified as a validation error by a Schematron rule.

$err:INVALID-RESULTS-REQUESTED — Invalid result form parameter.

Variable:

{http://docbook.org/ns/docbook/errors}INVALID-RESULTS-REQUESTED

Defined in:

modules/errors.xsl

Used in:

docbook.xsl

Used by:

t:docbook

Synopsis

$dbe:INVALID-RESULTS-REQUESTED := xs:QName('dbe:INVALID-RESULTS-REQUESTED')

Description

This error is raised if the $result parameter passed to t:docbook is not one of “raw-results”, “chunked-results”, or “main-document”.

$err:INVALID-TEMPLATE — Invalid template reference.

Variable:

{http://docbook.org/ns/docbook/errors}INVALID-TEMPLATE

Defined in:

modules/errors.xsl

Used in:

main.xsl

Synopsis

$dbe:INVALID-TEMPLATE := xs:QName('dbe:INVALID-TEMPLATE')

Description

This error is raised if a template reference names a template that does not exist.

$err:INVALID-TRANSFORM — Error processing a transform.

Variable:

{http://docbook.org/ns/docbook/errors}INVALID-TRANSFORM

Defined in:

modules/errors.xsl

Used in:

docbook.xsl

Used by:

t:docbook

Synopsis

$dbe:INVALID-TRANSFORM := xs:QName('dbe:INVALID-TRANSFORM')

Description

The lists of transforms in $transform-original $transform-before, and $transform-after must either be strings (the stylesheet location) or a map that specifies the stylesheet location and other properties.

This error is raised if an element of the list is neither a map nor a string.

$personal-name-styles — The list of known personal name styles.

Variable:

{http://docbook.org/ns/docbook/variables}personal-name-styles

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:personal-name-styles := ('first-last', 'last-first', 'FAMILY-given')

Description

The stylesheets can format personal names in a variety of ways. This variable contains the list of known ways, see t:person-name.

$v:VERSION — The stylesheet version.

Variable:

{http://docbook.org/ns/docbook/variables}VERSION

Defined in:

VERSION.xsl

Used in:

main.xsl

Synopsis

$v:VERSION := '2.8.0'

Description

This variable holds the version number of the stylesheets.

$v:VERSION-ID — A unique version identifier.

Variable:

{http://docbook.org/ns/docbook/variables}VERSION-ID

Defined in:

VERSION.xsl

Used in:

main.xsl

Synopsis

$v:VERSION-ID := '42a7a63f'

Description

Generally speaking the $VERSION is sufficient to identify the stylesheets. The $VERSION-ID adds a unique identifier derived from the latest git commit.

$v:admonition-icons — Admonition icons.

Variable:

{http://docbook.org/ns/docbook/variables}admonition-icons

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

<xsl:variable name="v:admonition-icons">
   <tip>☞</tip>
   <note>ⓘ</note>
   <important>☝</important>
   <caution>⚠</caution>
   <warning>🛑</warning>
   <danger>⚡</danger>
</xsl:variable>

Description

These are the icons that will be presented next to admonitions. They’re single Unicode characters in the default distribution, but they can be replaced by graphics or other markup.

$v:annotation-close — Annotation close button.

Variable:

{http://docbook.org/ns/docbook/variables}annotation-close

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

<xsl:variable name="v:annotation-close"
              as="element()">
   <span>╳</span>
</xsl:variable>

Description

The contents of this variable will be rendered as the “close” icon for popup annotations.

$v:as-json — Map for serializing JSON.

Variable:

{http://docbook.org/ns/docbook/variables}as-json

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:as-json := map {'method':'json','indent':true()}

Description

This is a convience variable for serializing maps as JSON. Used mostly in debugging.

$v:as-xml — Map for serializing XML.

Variable:

{http://docbook.org/ns/docbook/variables}as-xml

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:as-xml := map {'method':'xml','indent':true()}

Description

This is a convience variable for serializing maps as JSON. Used mostly in debugging.

$v:bridgehead-map — Maps bridgehead renderas values.

Variable:

{http://docbook.org/ns/docbook/variables}bridgehead-map

Defined in:

modules/sections.xsl

Used in:

main.xsl

Synopsis

<xsl:variable name="v:bridgehead-map"
              as="map(*)">
   <xsl:map>
      <xsl:map-entry key="'sect1'" select="'h2'"/>
      <xsl:map-entry key="'sect2'" select="'h3'"/>
      <xsl:map-entry key="'sect3'" select="'h4'"/>
      <xsl:map-entry key="'sect4'" select="'h5'"/>
      <xsl:map-entry key="'sect5'" select="'h5'"/>
      <xsl:map-entry key="'sect6'" select="'h5'"/>
      <xsl:map-entry key="'block'" select="'div'"/>
   </xsl:map>
</xsl:variable>

Description

The bridgehead element allows the author to insert a heading without regard to the logical structure of the document. This variable controls how the values provided in the renderas attribute map to HTML. If there is no mapping for the specified rendering, it is rendered as a div.

$v:chunk — Are we chunking on this run?

Variable:

{http://docbook.org/ns/docbook/variables}chunk

Defined in:

modules/variable.xsl

Used in:

main.xsl, param.xsl, modules/chunk.xsl, modules/chunk-cleanup.xsl, modules/chunk-output.xsl

Used by:

$chunk-output-base-uri, f:chunk()

Synopsis

$v:chunk as xs:boolean := not(normalize-space($chunk) = '')

Description

If $v:chunk is true, then the stylesheets are producing chunked output. See Section 2.7, ““Chunked” output”.

$v:chunk-filter-namespaces — Namespace context for chunking expressions.

Variable:

{http://docbook.org/ns/docbook/variables}chunk-filter-namespaces

Defined in:

modules/variable.xsl

Used in:

modules/chunk.xsl

Synopsis

<xsl:variable name="v:chunk-filter-namespaces"
              as="namespace-node()*">
   <xsl:namespace name="db" select="'http://docbook.org/ns/docbook'"/>
</xsl:variable>

Description

When the $chunk-include and $chunk-exclude expressions are evaluated, the namespace bindings in this variable will be in-scope.

$v:chunk-renumber-footnotes — Renumber footnotes when chunking?

Variable:

{http://docbook.org/ns/docbook/variables}chunk-renumber-footnotes

Defined in:

modules/variable.xsl

Used in:

modules/chunk-cleanup.xsl

Synopsis

$v:chunk-renumber-footnotes as xs:boolean := f:is-true($chunk-renumber-footnotes)

Description

Footnotes are generally numbered (or otherwise marked, see $footnote-numeration) sequentially throughout a document. If the document is being broken into chunks, it may seem odd if the only footnote in a chunk is labeled “⁵”. If $v:chunk-renumber-footnotes is true, the stylesheets will attempt to renumber footnotes in each chunk so that they begin at the first mark in each chunk.

ⓘ

Note

If your document uses footnoteref and the reference and the footnote are in different chunks, this may lead to very confusing numeration!

$v:custom-localizations — Customize localizations.

Variable:

{http://docbook.org/ns/docbook/variables}custom-localizations

Defined in:

modules/variable.xsl

Used in:

main.xsl

Since:

2.0.0

Synopsis

$v:custom-localizations as document-node()? := ()

Description

Provides overrides for localization. See Chapter 4, Localization.

$v:debug — Debugging flags.

Variable:

{http://docbook.org/ns/docbook/variables}debug

Defined in:

modules/variable.xsl

Used in:

docbook.xsl, main.xsl, modules/chunk-cleanup.xsl, modules/chunk-output.xsl

Used by:

t:docbook

Static:

Yes

Synopsis

$v:debug as xs:string* := tokenize($debug, '[,\s]+') ! normalize-space(.)

Description

The $v:debug variable contains a sequence of debugging flags. These are derived from tokenizing the $debug parameter value.

$v:formal-object-title-placement — Placement of formal object titles.

Variable:

{http://docbook.org/ns/docbook/variables}formal-object-title-placement

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:formal-object-title-placement as map(xs:string,xs:string) := fp:parse-key-value-pairs( tokenize($formal-object-title-placement, '\s+'))

Description

This variable, usually derived from $formal-object-title-placement is a map from element (local) names to placements. The placement is either “before” or “after”.

$v:formalgroup-nested-object-title-placement — Placement of formal object titles within a formalgroup.

Variable:

{http://docbook.org/ns/docbook/variables}formalgroup-nested-object-title-placement

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:formalgroup-nested-object-title-placement as map(xs:string,xs:string) := fp:parse-key-value-pairs( tokenize($formal-object-title-placement, '\s+'))

Description

This variable, usually derived from $formalgroup-nested-object-title-placement is a map from element (local) names to placements. The placement is either “before” or “after”.

$v:highlight-js-head-elements — CSS and JavaScript to support highlight.js.

Variable:

{http://docbook.org/ns/docbook/variables}highlight-js-head-elements

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

<xsl:variable name="v:highlight-js-head-elements"
              as="element()*">
   <link rel="stylesheet"
         href="{fp:add-resource-base-uri('css/highlight-11.10.0.min.css')}"/>
   <script src="{fp:add-resource-base-uri('js/highlight-11.10.0.min.js')}"/>
   <xsl:choose>
      <xsl:when test="f:is-true($verbatim-embellish-linenumbers)">
         <script src="{fp:add-resource-base-uri('js/highlightjs-line-numbers-2.9.0.min.js')}"/>
         <script>hljs.configure({languages:[]}); hljs.highlightAll(); hljs.initLineNumbersOnLoad();</script>
      </xsl:when>
      <xsl:otherwise>
         <script>hljs.configure({languages:[]}); hljs.highlightAll();</script>
      </xsl:otherwise>
   </xsl:choose>
</xsl:variable>

Description

If the highlight.js syntax highlighter is selected (see $verbatim-syntax-highlighter), these elements are added to the head element to load and configure the highlighter.

Starting with the DocBook xslTNG Stylesheets version 1.4.1, any link elements will be added to the head element before links to user-defined CSS files so that property overrides may be specified.

$v:image-nominal-height — Nominal height of an image.

Variable:

{http://docbook.org/ns/docbook/variables}image-nominal-height

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:image-nominal-height := f:parse-length($image-nominal-height)

Description

If the extension functions necessary to determine the intrinsic height of an image are unavailable, or if the height cannot be determined, this value will be used as the assumed intrinsic height of the image. This is generally the parsed value of $image-nominal-height.

$v:image-nominal-width — Nominal width of an image.

Variable:

{http://docbook.org/ns/docbook/variables}image-nominal-width

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:image-nominal-width := f:parse-length($image-nominal-width)

Description

If the extension functions necessary to determine the intrinsic width of an image are unavailable, or if the width cannot be determined, this value will be used as the assumed intrinsic width of the image. This is generally the parsed value of $image-nominal-width.

$v:invisible-characters — A list of characters that are invisible in verbatim environments.

Variable:

{http://docbook.org/ns/docbook/variables}invisible-characters

Defined in:

modules/verbatim.xsl

Used in:

main.xsl

Synopsis

$v:invisible-characters := ('︀', '︁', '︂', '︃', '︄', '︅', '︆', '︇', '︈', '︉', '︊', '︋', '︌', '︍', '︎', '️', '​')

Description

When callouts are being inserted into a verbatim environment, the stylesheets must count the characters in each line in order to find the correct column. The characters in this list are considered invisible and do not increase the column count as they’re passed.

$v:localization-base-uri — Base URI for localization data files.

Variable:

{http://docbook.org/ns/docbook/variables}localization-base-uri

Defined in:

modules/variable.xsl

Used in:

main.xsl

Since:

2.0.0

Synopsis

$v:localization-base-uri := resolve-uri('../locale/', static-base-uri())

Description

This is the base URI used to resolve references to localization data.

$v:mathml-js-roles — “MathML” roles.

Variable:

{http://docbook.org/ns/docbook/variables}mathml-js-roles

Defined in:

modules/variable.xsl

Used in:

modules/chunk-cleanup.xsl

Synopsis

$v:mathml-js-roles as xs:string* := tokenize($mathml-js-role, '\s+')

Description

See $mathml-js-role. The value can actually be a whitespace separated list of roles.

$v:media-type-default — Default media type.

Variable:

{http://docbook.org/ns/docbook/variables}media-type-default

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:media-type-default as xs:string := 'application/octet-stream'

Description

When attempting to determine the media type of a file, the stylesheets use the $v:media-type-map to check for a media type based on the filename (or URI) extension. If there’s no extension or if the extension isn’t in that map, this value is used.

$v:media-type-map — Mapping from extensions to media types.

Variable:

{http://docbook.org/ns/docbook/variables}media-type-map

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

<xsl:variable name="v:media-type-map"
              as="map(xs:string, xs:string)">
   <xsl:map>
      <xsl:map-entry key="'.aac'" select="'audio/aac'"/>
      <xsl:map-entry key="'.abw'" select="'application/x-abiword'"/>
      <xsl:map-entry key="'.arc'" select="'application/x-freearc'"/>
      <xsl:map-entry key="'.avif'" select="'image/avif'"/>
      <xsl:map-entry key="'.avi'" select="'video/x-msvideo'"/>
      <xsl:map-entry key="'.azw'" select="'application/vnd.amazon.ebook'"/>
      <xsl:map-entry key="'.bin'" select="'application/octet-stream'"/>
      <xsl:map-entry key="'.bmp'" select="'image/bmp'"/>
      <xsl:map-entry key="'.bz'" select="'application/x-bzip'"/>
      <xsl:map-entry key="'.bz2'" select="'application/x-bzip2'"/>
      <xsl:map-entry key="'.cda'" select="'application/x-cdf'"/>
      <xsl:map-entry key="'.csh'" select="'application/x-csh'"/>
      <xsl:map-entry key="'.css'" select="'text/css'"/>
      <xsl:map-entry key="'.csv'" select="'text/csv'"/>
      <xsl:map-entry key="'.doc'" select="'application/msword'"/>
      <xsl:map-entry key="'.docx'"
                     select="'application/vnd.openxmlformats-officedocument.wordprocessingml.document'"/>
      <xsl:map-entry key="'.eot'" select="'application/vnd.ms-fontobject'"/>
      <xsl:map-entry key="'.epub'" select="'application/epub+zip'"/>
      <xsl:map-entry key="'.gz'" select="'application/gzip'"/>
      <xsl:map-entry key="'.gif'" select="'image/gif'"/>
      <xsl:map-entry key="'.htm'" select="'text/html'"/>
      <xsl:map-entry key="'.html'" select="'text/html'"/>
      <xsl:map-entry key="'.ico'" select="'image/vnd.microsoft.icon'"/>
      <xsl:map-entry key="'.ics'" select="'text/calendar'"/>
      <xsl:map-entry key="'.jar'" select="'application/java-archive'"/>
      <xsl:map-entry key="'.jpeg'" select="'image/jpeg'"/>
      <xsl:map-entry key="'.jpg'" select="'image/jpeg'"/>
      <xsl:map-entry key="'.js'" select="'text/javascript'"/>
      <xsl:map-entry key="'.json'" select="'application/json'"/>
      <xsl:map-entry key="'.jsonld'" select="'application/ld+json'"/>
      <xsl:map-entry key="'.mid'" select="'audio/midi'"/>
      <xsl:map-entry key="'.midi'" select="'audio/midi'"/>
      <xsl:map-entry key="'.mjs'" select="'text/javascript'"/>
      <xsl:map-entry key="'.m3u8'" select="'application/x-mpegURL'"/>
      <xsl:map-entry key="'.mp3'" select="'audio/mpeg'"/>
      <xsl:map-entry key="'.mp4'" select="'video/mp4'"/>
      <xsl:map-entry key="'.mpeg'" select="'video/mpeg'"/>
      <xsl:map-entry key="'.mpkg'" select="'application/vnd.apple.installer+xml'"/>
      <xsl:map-entry key="'.mov'" select="'video/quicktime'"/>
      <xsl:map-entry key="'.odp'" select="'application/vnd.oasis.opendocument.presentation'"/>
      <xsl:map-entry key="'.ods'" select="'application/vnd.oasis.opendocument.spreadsheet'"/>
      <xsl:map-entry key="'.odt'" select="'application/vnd.oasis.opendocument.text'"/>
      <xsl:map-entry key="'.oga'" select="'audio/ogg'"/>
      <xsl:map-entry key="'.ogv'" select="'video/ogg'"/>
      <xsl:map-entry key="'.ogx'" select="'application/ogg'"/>
      <xsl:map-entry key="'.opus'" select="'audio/opus'"/>
      <xsl:map-entry key="'.otf'" select="'font/otf'"/>
      <xsl:map-entry key="'.png'" select="'image/png'"/>
      <xsl:map-entry key="'.pdf'" select="'application/pdf'"/>
      <xsl:map-entry key="'.php'" select="'application/x-httpd-php'"/>
      <xsl:map-entry key="'.ppt'" select="'application/vnd.ms-powerpoint'"/>
      <xsl:map-entry key="'.pptx'"
                     select="'application/vnd.openxmlformats-officedocument.presentationml.presentation'"/>
      <xsl:map-entry key="'.rar'" select="'application/vnd.rar'"/>
      <xsl:map-entry key="'.rtf'" select="'application/rtf'"/>
      <xsl:map-entry key="'.sh'" select="'application/x-sh'"/>
      <xsl:map-entry key="'.svg'" select="'image/svg'"/>
      <!-- not image/svg+xml for epub -->
      <xsl:map-entry key="'.tar'" select="'application/x-tar'"/>
      <xsl:map-entry key="'.tif'" select="'image/tiff'"/>
      <xsl:map-entry key="'.tiff'" select="'image/tiff'"/>
      <xsl:map-entry key="'.ts'" select="'video/mp2t'"/>
      <xsl:map-entry key="'.ttf'" select="'font/ttf'"/>
      <xsl:map-entry key="'.txt'" select="'text/plain'"/>
      <xsl:map-entry key="'.text'" select="'text/plain'"/>
      <xsl:map-entry key="'.vsd'" select="'application/vnd.visio'"/>
      <xsl:map-entry key="'.wav'" select="'audio/wav'"/>
      <xsl:map-entry key="'.weba'" select="'audio/webm'"/>
      <xsl:map-entry key="'.webm'" select="'video/webm'"/>
      <xsl:map-entry key="'.webp'" select="'image/webp'"/>
      <xsl:map-entry key="'.wmv'" select="'video/x-ms-wmv'"/>
      <xsl:map-entry key="'.woff'" select="'font/woff'"/>
      <xsl:map-entry key="'.woff2'" select="'font/woff2'"/>
      <xsl:map-entry key="'.xhtml'" select="'application/xhtml+xml'"/>
      <xsl:map-entry key="'.xls'" select="'application/vnd.ms-excel'"/>
      <xsl:map-entry key="'.xlsx'"
                     select="'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'"/>
      <xsl:map-entry key="'.xml'" select="'application/xml'"/>
      <xsl:map-entry key="'.xul'" select="'application/vnd.mozilla.xul+xml'"/>
      <xsl:map-entry key="'.zip'" select="'application/zip'"/>
      <xsl:map-entry key="'.7z'" select="'application/x-7z-compressed'"/>
   </xsl:map>
</xsl:variable>

Description

When attempting to determine the media type of a file, the stylesheets use this map to check for a media type based on the filename (or URI) extension.

This mapping is derived from Mozilla’s list of common types. The “.3gp” and “.3g2” extensions have been removed because they have multiple mappings. The “.text”, “.mov”, “.m3u8”, and “.wmv” extensions have been added. The media type for “.svg” has been simplified to just “image/svg” because that seems to be what EPUB readers require.

$v:mediaobject-details-placement — Placement of formal object titles.

Variable:

{http://docbook.org/ns/docbook/variables}mediaobject-details-placement

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:mediaobject-details-placement as map(xs:string,xs:string) := fp:parse-key-value-pairs( tokenize($mediaobject-details-placement, '\s+'))

Description

This variable, usually derived from $mediaobject-details-placement is a map from element (local) names to placements. The placement is either “before” or “after”.

$v:mediaobject-exclude-extensions — Exluded media type extensions.

Variable:

{http://docbook.org/ns/docbook/variables}mediaobject-exclude-extensions

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:mediaobject-exclude-extensions := tokenize($mediaobject-exclude-extensions, '\s+')

Description

This variable simply contains the list of excluded extensions constructed from the $mediaobject-exclude-extensions parameter.

$v:mediaobject-input-base-uri — Base URI of images and other media in the XML sources.

Description

This variable was replaced with f:mediaobject-input-base-uri().

$v:mediaobject-output-base-uri — Base URI of images and other media in the output.

Variable:

{http://docbook.org/ns/docbook/variables}mediaobject-output-base-uri

Defined in:

modules/variable.xsl

Used in:

Not used.

Synopsis

<xsl:variable name="v:mediaobject-output-base-uri"
              as="xs:string?">
   <xsl:message use-when="'mediaobject-uris' = $v:debug"
                select="'Mediaobject out. base URI:',                        if (empty($mediaobject-output-base-uri))                        then ()                        else if (ends-with($mediaobject-output-base-uri, '/'))                             then $mediaobject-output-base-uri                             else $mediaobject-output-base-uri || '/'"/>
   <xsl:sequence select="if (empty($mediaobject-output-base-uri))                         then ()                         else if (ends-with($mediaobject-output-base-uri, '/'))                              then $mediaobject-output-base-uri                              else $mediaobject-output-base-uri || '/'"/>
</xsl:variable>

Description

This value is calculated from the $mediaobject-output-base-uri parameter. If the parameter is the empty string, then this value is the empty sequence. Otherwise, this value is the value of the $mediaobject-output-base-uri parameter, which is assumed to be absolute. A trailing slash will be added to the parameter value if it is not present.

$v:nominal-page-width — The nominal page width.

Variable:

{http://docbook.org/ns/docbook/variables}nominal-page-width

Defined in:

modules/variable.xsl

Used in:

docbook.xsl, main.xsl

Used by:

t:docbook

Synopsis

$v:nominal-page-width := f:parse-length($nominal-page-width)

Description

To calculate the width of the columns in some complex CALS tables, the stylesheets need to know the page width. The $nominal-page-width is used for this value. It is generally the value of $nominal-page-width parsed as a length (see Section 5.2, “Lengths and units”).

$v:olink-databases — External olink databases.

Variable:

{http://docbook.org/ns/docbook/variables}olink-databases

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

<xsl:variable name="v:olink-databases"
              as="element(h:targetdb)*">
   <xsl:if test="normalize-space($olink-databases) != ''">
      <xsl:for-each select="tokenize($olink-databases, ',\s*') ! normalize-space(.)">
         <xsl:variable name="db" select="resolve-uri(., static-base-uri())"/>
         <xsl:try>
            <xsl:variable name="olinkdb" select="doc($db)/h:targetdb"/>
            <xsl:if test="empty($olinkdb)">
               <xsl:message select="'No targets in olinkdb:', $db"/>
            </xsl:if>
            <xsl:sequence select="$olinkdb"/>
            <xsl:catch>
               <xsl:message select="'Failed to load olinkdb:', $db"/>
            </xsl:catch>
         </xsl:try>
      </xsl:for-each>
   </xsl:if>
</xsl:variable>

Description

The $v:olink-databases variable is usually derived from the $olink-databases parameter. It must contain a sequence of olink target databases.

$v:pi-db-attributes-are-uris — Controls which “db” processing instruction pseudo-attributes are URIs.

Variable:

{http://docbook.org/ns/docbook/variables}pi-db-attributes-are-uris

Defined in:

../standalone-functions.xsl

Used in:

main.xsl

Synopsis

$v:pi-db-attributes-are-uris as xs:string* := ('glossary-collection', 'bibliography-collection', 'annotation-collection')

Description

The “db” processing instruction can be used to provide configuration values within a document. For example:

  |<?db xlink-style='inline' glossary-collection='../gcollection.xml'?>

In this example, xlink-style is just a string value, but glossary-collection is a URI. When the value in question is a URI, it must be made absolute against the base URI of the processing instruction on which it occurs. The $v:pi-db-attributes-are-uris variable determines which pseudo-attributes are considered URIs. Their values are made absolute when the processing instruction is parsed.

$v:prism-js-head-elements — CSS and JavaScript to support Prism.

Variable:

{http://docbook.org/ns/docbook/variables}prism-js-head-elements

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

<xsl:variable name="v:prism-js-head-elements"
              as="element()*">
   <link rel="stylesheet" href="{fp:add-resource-base-uri('css/prism.css')}"/>
   <script src="{fp:add-resource-base-uri('js/prism.js')}"/>
</xsl:variable>

Description

If the prism syntax highlighter is selected (see $verbatim-syntax-highlighter), these elements are added to the head element to load and configure the highlighter.

Starting with the DocBook xslTNG Stylesheets version 1.4.1, any link elements will be added to the head element before links to user-defined CSS files so that property overrides may be specified.

$v:standard-transforms — The standard pre-processing transformations.

Variable:

{http://docbook.org/ns/docbook/variables}standard-transforms

Defined in:

docbook.xsl

Used in:

docbook.xsl

Synopsis

<xsl:variable name="v:standard-transforms"
              as="map(*)*">
   <xsl:map>
      <xsl:map-entry key="'stylesheet-location'"
                     select="resolve-uri('transforms/00-logstruct.xsl', static-base-uri())"/>
   </xsl:map>
   <xsl:map>
      <xsl:map-entry key="'stylesheet-location'"
                     select="resolve-uri('transforms/10-xinclude.xsl', static-base-uri())"/>
      <xsl:map-entry key="'functions'"
                     select="'Q{http://docbook.org/extensions/xslt}xinclude'"/>
      <xsl:map-entry key="'test'" select="'exists(//xi:include)'"/>
   </xsl:map>
   <xsl:map>
      <xsl:map-entry key="'stylesheet-location'"
                     select="resolve-uri('transforms/20-db4to5.xsl', static-base-uri())"/>
      <xsl:map-entry key="'test'">
      not(namespace-uri(/*) = 'http://docbook.org/ns/docbook')
    </xsl:map-entry>
      <xsl:map-entry key="'extra-params'"
                     select="map { QName('', 'base-uri'): 'base-uri(/*)' }"/>
   </xsl:map>
   <xsl:map>
      <xsl:map-entry key="'stylesheet-location'"
                     select="resolve-uri('transforms/30-transclude.xsl', static-base-uri())"/>
      <xsl:map-entry key="'test'" select="'f:is-true($docbook-transclusion)'"/>
   </xsl:map>
   <xsl:map>
      <xsl:map-entry key="'stylesheet-location'"
                     select="resolve-uri('transforms/40-profile.xsl', static-base-uri())"/>
      <xsl:map-entry key="'test'">
         f:is-true($dynamic-profiles)
      or $profile-lang != ''         or $profile-revisionflag != ''
      or $profile-role != ''         or $profile-arch != ''
      or $profile-audience != ''     or $profile-condition != ''
      or $profile-conformance != ''  or $profile-os != ''
      or $profile-outputformat != '' or $profile-revision != ''
      or $profile-security != ''     or $profile-userlevel != ''
      or $profile-vendor != ''       or $profile-wordsize != ''
    </xsl:map-entry>
   </xsl:map>
   <xsl:map>
      <xsl:map-entry key="'stylesheet-location'"
                     select="resolve-uri('transforms/50-normalize.xsl', static-base-uri())"/>
   </xsl:map>
   <xsl:map>
      <xsl:map-entry key="'stylesheet-location'"
                     select="resolve-uri('transforms/52-calstables.xsl', static-base-uri())"/>
   </xsl:map>
   <xsl:map>
      <xsl:map-entry key="'stylesheet-location'"
                     select="resolve-uri('transforms/55-oxy-markup.xsl', static-base-uri())"/>
      <xsl:map-entry key="'test'">
      f:is-true(f:pi(/*/db:info, 'oxy-markup', $oxy-markup))
      and exists(//processing-instruction()[starts-with(name(), 'oxy_')])
    </xsl:map-entry>
   </xsl:map>
   <xsl:map>
      <xsl:map-entry key="'stylesheet-location'"
                     select="resolve-uri('transforms/60-annotations.xsl', static-base-uri())"/>
      <xsl:map-entry key="'test'" select="'exists(//db:annotation)'"/>
   </xsl:map>
   <xsl:map>
      <xsl:map-entry key="'stylesheet-location'"
                     select="resolve-uri('transforms/70-xlinkbase.xsl', static-base-uri())"/>
   </xsl:map>
   <xsl:if test="exists($local-conventions)">
      <xsl:map>
         <xsl:map-entry key="'stylesheet-location'" select="$local-conventions"/>
      </xsl:map>
   </xsl:if>
   <xsl:map>
      <xsl:map-entry key="'stylesheet-location'"
                     select="resolve-uri('transforms/75-validate.xsl', static-base-uri())"/>
      <xsl:map-entry key="'functions'"
                     select="'Q{http://docbook.org/extensions/xslt}validate-with-relax-ng'"/>
      <xsl:map-entry key="'test'" select="'normalize-space($relax-ng-grammar) != '''''"/>
   </xsl:map>
</xsl:variable>

Description

This variable contains the list of preprocessing transforms applied to each document. You can add transformations that operate on the original document ($transform-original) or on the result of these transforms, but before the DocBook HTML transformation occurs ($transform-before), or after the HTML transformation ($transform-after).

You shouldn’t need to modify this variable unless you want to remove or reorder the standard transforms, or insert your own into the middle.

$v:templates — Custom templates for title pages.

Variable:

{http://docbook.org/ns/docbook/variables}templates

Defined in:

modules/templates.xsl

Used in:

main.xsl

Synopsis

<xsl:variable name="v:templates"
              as="document-node()">
   <xsl:document/>
</xsl:variable>

Description

The stylesheets use templates, as described in Section 5.5, “Templates”, to determine the formatting of title pages*. Any templates provided in $v:templates will be used preferentially to whatever builtin templates exist.

*

The term “title pages” should be understood very broadly here. Anything that has a title has a title page, even if that “page” consists of only a single heading.

$v:theme-list — Enumerates available themes.

Variable:

{http://docbook.org/ns/docbook/variables}theme-list

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

<xsl:variable name="v:theme-list"
              as="element()*">
   <theme name="Materials dark" id="materials-dark" dark="true"/>
   <theme name="Materials light" id="materials-light" dark="false"/>
</xsl:variable>

Description

This variable is part of the experimental themes feature. It enumerates the available themes. Each theme has three parts, a name, an ID, and (optionally) an indication of whether or not it’s a “dark” theme.

Themes are implemented in CSS. If the $theme-picker is enabled, it will be possible for the reader to select a theme. The theme names are used for this purpose.

The ID value is used as a class on the html element. Everything else about the theme is implemented in CSS. To add a new theme, provide a set of CSS rules that apply when the ID class is in effect.

The dark mode setting is only used as a default. If the document does not specify a $default-theme, if the user has never selected a theme, if the user has enabled dark mode at the operating system level, and if the browser makes this fact available, the first “dark” theme will automatically be selected.

$v:title-groups — Controls how titles are formatted.

Variable:

{http://docbook.org/ns/docbook/variables}title-groups

Defined in:

modules/titles.xsl

Used in:

main.xsl

Since:

2.0.0

Synopsis

<xsl:variable name="v:title-groups"
              as="element()+">
   <xsl:sequence select="$v:user-title-groups"/>
   <title xpath="self::db:section|self::db:sect1                 |self::db:sect2|self::db:sect3|self::db:sect4|self::db:sect5                 |self::db:refsection|self::db:refsect1|self::db:refsect2|self::db:refsect3"
          group="{if (f:is-true($section-numbers))                  then 'title-numbered'                  else 'title-unnumbered'}"/>
   <title xpath="self::db:article|self::db:preface|self::db:chapter|self::db:appendix"
          group="{if (f:is-true($component-numbers))                  then 'title-numbered'                  else 'title-unnumbered'}"/>
   <title xpath="self::db:set" group="title-unnumbered"/>
   <title xpath="self::db:book|self::db:part|self::db:reference"
          group="{if (f:is-true($division-numbers))                  then 'title-numbered'                  else 'title-unnumbered'}"/>
   <title xpath="self::db:figure[parent::db:formalgroup]                 |self::db:table[parent::db:formalgroup]                 |self::db:equation[parent::db:formalgroup]                 |self::db:example[parent::db:formalgroup]"
          group="{if (f:is-true($formal-object-numbers))                  then 'subfigure-title-numbered'                  else 'subfigure-title-unnumbered'}"/>
   <title xpath="self::db:figure|self::db:table|self::db:equation|self::db:example|self::db:procedure"
          group="{if (f:is-true($formal-object-numbers))                  then 'title-numbered'                  else 'title-unnumbered'}"/>
   <title xpath="self::db:formalgroup"
          group="{if (f:is-true($formal-object-numbers))                  then 'title-numbered'                  else 'title-unnumbered'}"/>
   <title xpath="self::db:step|self::db:listitem[parent::db:orderedlist]"
          group="title-unnumbered"/>
   <title xpath="self::db:glosssee|self::db:glossseealso"
          group="title-unnumbered"/>
   <title xpath="self::db:see|self::db:seealso" group="title-unnumbered"/>
   <title xpath="self::db:question|self::db:answer" group="title-numbered"/>
   <title xpath="self::*" group="title-unnumbered"/>
</xsl:variable>

Description

The title groups variable determines which template group is used for a title. See Chapter 4, Localization.

$v:title-properties — Controls how titles are formatted.

Description

Replaced by $v:title-groups.

$v:titlepage-default — Default template for title pages.

Variable:

{http://docbook.org/ns/docbook/variables}titlepage-default

Defined in:

modules/templates.xsl

Used in:

main.xsl

Synopsis

<xsl:variable name="v:titlepage-default"
              as="element()">
   <titlepage-default>
      <header>
         <apply-templates select="db:title">
            <div class="title">
               <content/>
            </div>
         </apply-templates>
      </header>
   </titlepage-default>
</xsl:variable>

Description

Title pages, taken loosely to mean anything with a title, are formatted using templates, see Section 5.5, “Templates”. If a template doesn’t exist for a particular context, the $v:titlepage-default template is used.

$v:toc-close — Persistent ToC close button.

Variable:

{http://docbook.org/ns/docbook/variables}toc-close

Defined in:

modules/variable.xsl

Used in:

modules/chunk-output.xsl

Synopsis

<xsl:variable name="v:toc-close"
              as="element()">
   <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAABYlAAAWJQFJUiTwAAAAtklEQVQ4jaWT0Q3DIAxEz52AEbyB2cDZhBEY3SNcPyqqBEwqpZaQAHNP5jBCEiJCPAiSIgAeiUe8zoveO9x9e9jd0XtfKwHA1hpHtNY49rO8u59zn4mqMiJSyFkcEVTVFQCAtdYFMotrrXN111JnyA/xCsggN2JeXmGEmaGU8l2XUmBm29fZuh0RW2PTK2SGZcamADPb3nmGmNkKOI7j1rAzJG2kcWhqkstQ1QX+/2ciKU/FJOUN6JFZYWpmK3sAAAAASUVORK5CYII="
        alt="X"/>
</xsl:variable>

Description

The contents of this variable will be rendered as the “close” icon for the persistent ToC.

$v:toc-open — Persistent ToC open button.

Variable:

{http://docbook.org/ns/docbook/variables}toc-open

Defined in:

modules/variable.xsl

Used in:

modules/chunk-output.xsl

Synopsis

<xsl:variable name="v:toc-open"
              as="element()">
   <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAAQCAYAAAAWGF8bAAAACXBIWXMAABYlAAAWJQFJUiTwAAABDklEQVQ4je2UUW3EMAyGv0wDUAhlkDBIyuAYXCEclEJoGZRBUgYOgzJoGHgPW6o7rWq35+2TIkWW9duW7N+oKuM46jiOGGMAaNsW5xzee5xzn8EvRESXZUFEWNcVAFWl73v6vjcGUIAYIyEEANZ1RUSY55lSCo/HA4BhGGiahtvthnOOtm0BSCnRdd1eVAGNMeoR27aptVattbpt22FOjFGrzjsX1I7q/4q3y4xf8i/4FwT3Pcw5Y4zBWvujfQMopZBzJuf8XbCeVyWEgHOO+/2+x0SEaZpIKSEih0X2Wz6jdlxKuezaqL7qpZS0lLKbw/M4ANba3RyapiGE8OJGqOrpizGq916999VATvM/AGFn1sxsVjL5AAAAAElFTkSuQmCC"
        alt="[toc]"/>
</xsl:variable>

Description

The contents of this variable will be rendered as the “open” icon for the persistent ToC.

$v:unit-scale — List of known measurement units and their sizes.

Variable:

{http://docbook.org/ns/docbook/variables}unit-scale

Defined in:

modules/units.xsl

Used in:

main.xsl

Synopsis

<xsl:variable name="v:unit-scale"
              as="map(*)">
   <xsl:map>
      <xsl:map-entry key="'px'" select="1.0"/>
      <xsl:map-entry key="'in'" select="$pixels-per-inch"/>
      <xsl:map-entry key="'m'" select="$pixels-per-inch div 2.54 * 100.0"/>
      <xsl:map-entry key="'cm'" select="$pixels-per-inch div 2.54"/>
      <xsl:map-entry key="'mm'" select="$pixels-per-inch div 25.4"/>
      <xsl:map-entry key="'pt'" select="$pixels-per-inch div 72.0"/>
      <xsl:map-entry key="'pc'" select="$pixels-per-inch div 6.0"/>
      <xsl:map-entry key="'em'" select="$pixels-per-inch div 6.0"/>
      <xsl:map-entry key="'barleycorn'" select="$pixels-per-inch div 3.0"/>
   </xsl:map>
</xsl:variable>

Description

The $v:unit-scale map contains a set of measurement units and their absolute length in terms of pixels (as computed with $pixels-per-inch).

Recognized units at the time of this writing are shown in Figure 1, “Recognized units of measure”.

Unit | Size
px | 1.0
in | $pixels-per-inch
m | $pixels-per-inch div 2.54 * 100.0
cm | $pixels-per-inch div 2.54
mm | $pixels-per-inch div 25.4
pt | $pixels-per-inch div 72.0
pc | $pixels-per-inch div 6.0
em | $pixels-per-inch div 6.0
barleycorn | $pixels-per-inch div 3.0

Figure 1. Recognized units of measure

See also Section 5.2, “Lengths and units”.

$v:user-title-groups — Controls how titles are formatted.

Variable:

{http://docbook.org/ns/docbook/variables}user-title-groups

Defined in:

modules/titles.xsl

Used in:

main.xsl

Since:

2.0.0

Synopsis

<xsl:variable name="v:user-title-groups"
              as="element()*"/>

Description

This variable contains user-supplied overrides to $v:title-groups. See that variable for more details.

$v:user-title-properties — Controls how titles are formatted.

Description

Replaced by $v:user-title-groups.

$v:user-xref-groups — Controls how cross-references are formatted.

Variable:

{http://docbook.org/ns/docbook/variables}user-xref-groups

Defined in:

modules/xref.xsl

Used in:

main.xsl

Since:

2.0.0

Synopsis

<xsl:variable name="v:user-xref-groups"
              as="element()*"/>

Description

This variable contains user-supplied overrides to $v:xref-groups. See that variable for more details.

$v:user-xref-properties — Controls how cross-references are formatted.

Description

Replaced by $v:user-xref-groups.

$v:verbatim-callouts — A list determining how callouts are processed.

Variable:

{http://docbook.org/ns/docbook/variables}verbatim-callouts

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:verbatim-callouts as xs:string* := tokenize($verbatim-callouts, '\s+')

Description

This value is a sequence constructed automatically from the $verbatim-callouts parameter.

$v:verbatim-line-style — List of verbatim elements to be rendered in the line style.

Variable:

{http://docbook.org/ns/docbook/variables}verbatim-line-style

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:verbatim-line-style := tokenize($verbatim-line-style, '\s+')

Description

The elements whose local names appear in this list will be formatted using the line verbatim style by default. For a discussion of verbatim elements and styles, see Section 2.11.1, “Verbatim style”.

This list is usually constructed from the $verbatim-line-style parameter.

$v:verbatim-number-every-nth — Line numbering frequency.

Variable:

{http://docbook.org/ns/docbook/variables}verbatim-number-every-nth

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:verbatim-number-every-nth := xs:integer($verbatim-number-every-nth)

Description

When formatting verbatim environments with line numbers, every $verbatim-number-every-nth line is numbered.

This value is usually constructed from the $verbatim-number-every-nth parameter.

$v:verbatim-number-first-line — Always number the first line of a verbatim listing?

Variable:

{http://docbook.org/ns/docbook/variables}verbatim-number-first-line

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:verbatim-number-first-line := f:is-true($verbatim-number-first-line)

Description

When formatting verbatim environments with line numbers, the first line will be numbered (irrespective of the setting of $v:verbatim-number-every-nth if this value is true.

This value is usually constructed from the $verbatim-number-first-line parameter.

$v:verbatim-number-minlines — Shortest listing to number.

Variable:

{http://docbook.org/ns/docbook/variables}verbatim-number-minlines

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:verbatim-number-minlines := xs:integer($verbatim-number-minlines)

Description

When formatting verbatim environments with line numbers, environments less than $verbatim-number-minlines in length will not be numbered.

This value is usually constructed from the $verbatim-number-minlines parameter.

$v:verbatim-numbered-elements — Identifies verbatim elements that should have line numbers.

Variable:

{http://docbook.org/ns/docbook/variables}verbatim-numbered-elements

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:verbatim-numbered-elements as xs:string* := tokenize($verbatim-numbered-elements, '\s+')

Description

A list of the verbatim environments that should be numbered.

This value is usually constructed from the $verbatim-numbered-elements parameter.

$v:verbatim-plain-style — List of verbatim elements to be rendered in the plain style.

Variable:

{http://docbook.org/ns/docbook/variables}verbatim-plain-style

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:verbatim-plain-style as xs:string* := tokenize($verbatim-plain-style, '\s+')

Description

The elements whose local names appear in this list will be formatted using the plain verbatim style by default. For a discussion of verbatim elements and styles, see Section 2.11.1, “Verbatim style”.

This list is usually constructed from the $verbatim-plain-style parameter.

$v:verbatim-properties — Controls the verbatim properties of an element.

Variable:

{http://docbook.org/ns/docbook/variables}verbatim-properties

Defined in:

modules/verbatim.xsl

Used in:

main.xsl

Synopsis

$v:verbatim-properties as array(map(*))

Description

When processing a verbatim environment, this array of maps is consulted to determine what properties apply to the verbatim environment. Most simple, global customizations of verbatim environments can be achieved by setting the $verbatim-line-style, $verbatim-plain-style, $verbatim-callouts, and $verbatim-numbered-elements parameters.

$v:verbatim-space — The space character to use when padding verbatim lines.

Variable:

{http://docbook.org/ns/docbook/variables}verbatim-space

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

<xsl:variable name="v:verbatim-space"
              as="node()">
   <xsl:value-of select="substring($verbatim-space || ' ', 1, 1)"/>
</xsl:variable>

Description

When a verbatim line has to be padded in order to get a callout to appear in the correct column, this character will be used as the padding character. For a discussion of verbatim elements and styles, see Section 2.11.1, “Verbatim style”.

This character is usually constructed from the $verbatim-space parameter. Unlike the $verbatim-space, this variable must be a node not a string.

$v:verbatim-syntax-highlight-languages — Languages for which syntax highlighting should be performed.

Variable:

{http://docbook.org/ns/docbook/variables}verbatim-syntax-highlight-languages

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:verbatim-syntax-highlight-languages := tokenize($verbatim-syntax-highlight-languages, '\s+')

Description

The $verbatim-syntax-highlight-languages is a single string for the convenience of users. This variable contains the languages as a list.

$v:verbatim-syntax-highlight-options — Syntax highlighting options.

Variable:

{http://docbook.org/ns/docbook/variables}verbatim-syntax-highlight-options

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:verbatim-syntax-highlight-options := map { }

Description

If the Pygments syntax highlighter is applied, the $verbatim-syntax-highlight-options are applied.

Three options are recognized:

language

The programming language to use for syntax highlighting. This option is required.

show-command

If the show-command option is true (“1”, “yes”, or “true”), then the pygmentize command will be printed. This is a debugging option.

show-result

If the show-result option is true (“1”, “yes”, or “true”), then the string returned from pygmentize will be printed. This is a debugging option.

ⓘ

Note

Syntax highlighting with Pygments requires spawning an external process for each highlighted environment. This can add significantly to the processing time if there are many such environments.

$v:verbatim-syntax-highlight-pygments-options — Pygments options.

Variable:

{http://docbook.org/ns/docbook/variables}verbatim-syntax-highlight-pygments-options

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:verbatim-syntax-highlight-pygments-options := map { }

Description

If the Pygments syntax highlighter is applied, the $verbatim-syntax-highlight-pygments-options are applied.

Each key/value pair in the map will be passed to pygmentize as a -Pkey=value option.

$v:verbatim-table-style — List of verbatim elements to be rendered in the table style.

Variable:

{http://docbook.org/ns/docbook/variables}verbatim-table-style

Defined in:

modules/variable.xsl

Used in:

main.xsl

Synopsis

$v:verbatim-table-style := tokenize($verbatim-table-style, '\s+')

Description

The elements whose local names appear in this list will be formatted using the line verbatim style by default. For a discussion of verbatim elements and styles, see Section 2.11.1, “Verbatim style”.

This list is usually constructed from the $verbatim-table-style parameter.

$v:xref-groups — Controls how cross-references are formatted.

Variable:

{http://docbook.org/ns/docbook/variables}xref-groups

Defined in:

modules/xref.xsl

Used in:

main.xsl

Since:

2.0.0

Synopsis

<xsl:variable name="v:xref-groups"
              as="element()+">
   <xsl:sequence select="$v:user-xref-groups"/>
   <crossref xpath="self::db:section[ancestor::db:preface]"
             group="xref"
             template="section-in-preface"/>
   <crossref xpath="self::db:section" group="xref-number-and-title"/>
   <crossref xpath="self::db:chapter|self::db:appendix"
             group="xref-number-and-title"/>
   <crossref xpath="self::db:part|self::db:reference" group="xref-number-and-title"/>
   <crossref xpath="self::db:figure|self::db:example|self::db:table                    |self::db:procedure|self::db:equation                    |self::db:formalgroup"
             group="xref-number-and-title"/>
   <crossref xpath="self::*" group="xref"/>
</xsl:variable>

Description

The cross-reference groups variable determines which template group is used for a cross-reference. See Chapter 4, Localization.

$v:xref-properties — Controls how cross-references are formatted.

Description

Replaced by $v:xref-groups.

III. Function reference

Table of Contents

ext:cwd

ext:image-metadata

ext:image-properties

ext:pygmentize

ext:pygmentize-available

ext:validate-with-relax-ng

ext:xinclude

f:absolute-length

f:attributes

f:available-bibliographies

f:available-glossaries

f:biblioentries

f:cals-colsep

f:cals-rowsep

f:check-gentext

f:chunk

f:chunk-filename

f:chunk-title

f:citations

f:conditional-orientation-class

f:css-length

f:css-property

f:date-format

f:empty-length

f:equal-lengths

f:flatten-path

f:generate-id

f:gentext

f:gentext-letters

f:gentext-letters-for-language

f:global-syntax-highlighter

f:glossentries

f:glossrefs

f:href

f:id

f:in-scope-language

f:intra-number-separator

f:is-empty-length

f:is-true

f:l10n-language

f:l10n-token

f:label-separator

f:language

f:languages

f:length-string

f:length-units

f:locales

f:make-length

f:mediaobject-amend-uri

f:mediaobject-input-base-uri

f:mediaobject-type

f:number-separator

f:object-align

f:object-contentheight

f:object-contentwidth

f:object-height

f:object-properties

f:object-scale

f:object-scalefit

f:object-valign

f:object-width

f:orderedlist-item-number

f:orderedlist-item-numeration

f:orderedlist-startingnumber

f:orientation-class

f:parse-length

f:pi

f:pi-attributes

f:post-label-punctuation

f:refsection

f:relative-length

f:relative-path

f:section

f:section-depth

f:spaces

f:step-number

f:step-numeration

f:syntax-highlight

f:target

f:template

f:tokenize-on-char

f:translate-attribute

f:unique-id

f:uri-scheme

f:verbatim-callout

f:verbatim-numbered

f:verbatim-style

f:verbatim-syntax-highlighter

f:verbatim-trim-leading

f:verbatim-trim-trailing

f:xlink-style

f:xpointer-idref

ext:cwd — Returns the current working directory.

Function:

{http://docbook.org/extensions/xslt}cwd#0

Synopsis

ext:cwd(
) as xs:string

Description

This extension function returns the current working directory from which the processor was executed.

ext:image-metadata — Return intrinsic properties of an image.

Function:

{http://docbook.org/extensions/xslt}image-metadata#1

Synopsis

ext:image-metadata(
$filename as xs:string) as map(*)

Description

This extension function returns a map of metadata properties about the image, including its intrinsic size: its width and height in pixels. If the size can be determined, the map returned will have a “width” key whose value is the width of the image and a “height” key whose value is the height of the image. Both sizes will be integer values.

This function uses the metadata-extractor library. The map may contain other properties as well.

If the media was successfully parsed with metadata-extractor, all of the properties identified by the extractor will be returned. Each property name will be converted to lowercase and spaces will be replaced with hyphens. (In other words, a property with the tag name “Palette Colour Count” will appear in the map with a key of “palette-colour-count”.)

Property values that appear to be data/time values* will be converted to strings that are valid ISO 8601 date/time values. Any control characters that can’t appear in XML but that appear in a value will be replaced with Unicode references, \uxxxx. For example, a null byte will be replaced with \u0000.

If the media isn’t successfully parsed with metadata-extractor,

If it appears to be a PDF document, the function will search for the “MediaBox” or “CropBox” in the first 100 lines of the PDF. If either is found, its dimensions are used to calculate the width and height. If both are present, CropBox is preferred.

If it appears to be an SVG document, the function will search for width and height attributes on the root element. All of the attributes of the root element will be returned as properties, using Clark names.

If the width and height properties exist, they will always be integers. This means that if an image has a property with the name width or height and its value isn’t an integer, it will not be returned.

If the $debug parameter includes the token image-properties, the stylesheets will print every property returned in an xsl:message.

*

A value that matches the regular expression “^\d\d\d\d:\d\d:\d\d \d\d:\d\d:\d\d$” is assumed to be a date/time. This is the format of date/time values used in EXIF metadata for most properties that have a date/time value.

ext:image-properties — Return intrinsic properties of an image.

Function:

{http://docbook.org/extensions/xslt}image-properties#1

Synopsis

ext:image-properties(
$filename as xs:string) as map(*)

Description

This extension function returns the intrinsic size of an image: its width and height in pixels. If the size can be determined, the map returned will have a “width” key whose value is the width of the image and a “height” key whose value is the height of the image. Both sizes will be integral numbers of pixels.

The ext:image-metadata() function provides better results. It should be preferred unless the metadata-extractor libraries are unavailable.

ext:pygmentize — Syntax highlight a listing with pygmentize.

Function:

{http://docbook.org/extensions/xslt}pygmentize#1

{http://docbook.org/extensions/xslt}pygmentize#2

{http://docbook.org/extensions/xslt}pygmentize#3

Synopsis

ext:pygmentize(
$listing as xs:string) as xs:string

ext:pygmentize( | $listing as xs:string,
| $options as item()) as xs:string

ext:pygmentize( | $listing as xs:string,
| $options as item(),
$pygments-options as map(xs:string,xs:string)) as xs:string

Description

This extension function runs the pygmentize command to add syntax highlighting to a listing.

The second argument can either be map, in which case the key-value pairs of the map constitute the options, or it can be a single string. If it’s a single string, it’s interpreted as if it was a map with the key “language” and the string as the value.

The third argument must be a map. Each key-value pair will be passed to pygmentize as “-Pkey=value”.

The function returns the string output from pygmentize. It must be parsed with parse-xml if you wish to process it as XML.

Be aware that pygmentize strips leading blank lines off of the source listing. If you’re selecting portions of a listing with XInclude, make sure not to select leading blank lines in the listing if you are trying to accurately count the lines.

ext:pygmentize-available — Returns true if pygmentize is available.

Function:

{http://docbook.org/extensions/xslt}pygmentize-available#0

Synopsis

ext:pygmentize-available(
) as xs:boolean

Description

In order to run Pygments on listings, the ext:pygmentize() extension function must be available and the pygmentize (pygmentize.exe on Windows) command must be available on the host system.

If it’s inconvenient to put pygmentize on the system path, you can specify an explicit location with the Java system property org.docbook.xsltng.extensions.pygmentize. The value of the property should be the fully qualified path name of the executable.

This function returns true if it successfully finds the pygmentize command on the system path.

ext:validate-with-relax-ng — Validates with RELAX NG.

Function:

{http://docbook.org/extensions/xslt}validate-with-relax-ng#2

{http://docbook.org/extensions/xslt}validate-with-relax-ng#3

Synopsis

ext:validate-with-relax-ng( | $node as node(),
| $schema as item()) as map(xs:string, item())

ext:validate-with-relax-ng( | $node as node(),
| $schema as item(),
$options as map(xs:string, xs:string)) as map(xs:string, item())

Description

This extension function validates the node provided against the schema. The schema can be either a string (the URI of the RELAX NG grammar file) or a node (a RELAX NG grammar document). There is no support for the RELAX NG Compact Syntax at this time.

The available options are assert-valid which defaults to true() and dtd-compatibility which isn’t actually supported yet.

If assert-valid is true() and the document is not valid according to the grammar provided, an exception is raised.

If assert-valid is false(), or the document is valid, the map returned will contain the following keys:

valid

A boolean indicating whether or not the document was valid.

document

The validated document. Today, this always returns the same node, but it may eventually return an augmented document.

errors

An array of maps containing the type (warning, error, or fatal-error), message, line, and column where an error occurred. If the document is valid, the errors key will not be present.

ext:xinclude — Performs XInclude processing.

Function:

{http://docbook.org/extensions/xslt}xinclude#1

{http://docbook.org/extensions/xslt}xinclude#2

Synopsis

ext:xinclude(
$node as node()) as node()*

ext:xinclude( | $node as node(),
| $options as map(xs:QName, item()*)) as node()*

Description

Performs XInclude processing on node and all of its descendants. The options “fixup-xml-base” and “fixup-xml-lang” are true() by default.

f:absolute-length — Returns the absolute length of a unit of measurement.

Function:

{http://docbook.org/ns/docbook/functions}absolute-length#1

Defined in:

modules/units.xsl

Used in:

main.xsl

Synopsis

f:absolute-length(
$length as map(*)) as xs:integer

Description

For a given unit of measurement, returns the absolute length in terms of pixels. For a discussion of units, see Section 5.2, “Lengths and units”.

See also $pixels-per-inch, $default-length-magnitude, and $default-length-unit.

f:attributes — Returns the attribute that apply to an output element.

Function:

{http://docbook.org/ns/docbook/functions}attributes#2

{http://docbook.org/ns/docbook/functions}attributes#4

Defined in:

modules/functions.xsl (2)

Used in:

main.xsl

Synopsis

f:attributes( | $node as element(),
| $attributes as attribute()*) as attribute()*

f:attributes( | $node as element(),
| $attributes as attribute()*,
$extra-classes as xs:string*,
$exclude-classes as xs:string*) as attribute()*

Description

Most output elements have attributes: any xml:id attributes in the source are reflected in the output as id attributes, most elements get a class attribute, etc. The f:attributes() function is called to determine what those attributes should be.

In practice, the way this usually works is the element is processed in the m:attributes mode and that template calls f:attributes() to generate the actual attribute nodes.

f:available-bibliographies — Returns a list of all available bibliographies.

Function:

{http://docbook.org/ns/docbook/functions}available-bibliographies#1

{http://docbook.org/ns/docbook/functions}available-bibliographies#2

Defined in:

../standalone-functions.xsl (2)

Used in:

main.xsl

Since:

2.2.0

Synopsis

f:available-bibliographies(
$term as element())

f:available-bibliographies( | $term as element(),
| $collections as xs:string*)

Description

The bibliographies available are all of the bibliographys in the current document plus any that are referenced with db processing instructions using the bibliography-collection pseudo-attribute in the root element.

In the two-argument form, a list of additional URIs may be passed. In common usage, the $bibliography-collection parameter is passed this way. (It’s not referenced directly because these functions are available for use outside of the stylesheets, for example in Schematron rules, in standalone-functions.xsl.)

The $term argument is only used to establish the context document for finding bibliographies in the current document.

f:available-glossaries — Returns a list of all available glossaries.

Function:

{http://docbook.org/ns/docbook/functions}available-glossaries#1

{http://docbook.org/ns/docbook/functions}available-glossaries#2

Defined in:

../standalone-functions.xsl (2)

Used in:

main.xsl

Since:

2.2.0

Synopsis

f:available-glossaries(
$term as element())

f:available-glossaries( | $term as element(),
| $collections as xs:string*)

Description

The glossaries available are all of the glossarys in the current document plus any that are referenced with db processing instructions using the glossary-collection pseudo-attribute in the root element.

In the two-argument form, a list of additional URIs may be passed. In common usage, the $glossary-collection parameter is passed this way. (It’s not referenced directly because these functions are available for use outside of the stylesheets, for example in Schematron rules, in standalone-functions.xsl.)

The $term argument is only used to establish the context document for finding glossaries in the current document.

f:biblioentries — Returns a list of all bibliographic entries for a citation.

Function:

{http://docbook.org/ns/docbook/functions}biblioentries#1

{http://docbook.org/ns/docbook/functions}biblioentries#2

Defined in:

../standalone-functions.xsl (2)

Used in:

main.xsl

Since:

2.2.0

Synopsis

f:biblioentries(
$term as element()) as element()*

f:biblioentries( | $term as element(),
| $collections as xs:string*) as element()*

Description

Returns all the biblioentry or bibliomixed elements that have an abbrev that matches a citation. The internal bibliography of the input document is always taken into account.

In the form with only one argument, external bibliographies are also taken into account if they are designated in the input document with a <?db biblioary-collection='URIs'?> processing instruction. In the form with two arguments, you can specify a list of URIs of the external bibliographies.

When more than one entry is found, the result sequence will start with entries from the internal bibliography, if any.

The function is designed so that it can be used independently from the xslTNG stylesheets. You can, for example, integrate it in a Schematron rule that checks whether every citation has exactly one corresponding bibliographic entry while authoring your document.

f:cals-colsep — Returns the “colsep” value associated with a CALS table cell.

Function:

{http://docbook.org/ns/docbook/functions}cals-colsep#3

Defined in:

modules/tablecals.xsl

Used in:

main.xsl

Synopsis

f:cals-colsep( | $cols as xs:integer,
| $cell as element(),
$last-col-colsep as xs:boolean) as xs:string?

Description

The column separator, or “colsep”, associated with a CALS table cell depends on a variety of factors: colspec, and spanspec elements as well as the attributes on the cell itself and its ancestors.

This function returns the value that applies to the specified cell.

f:cals-rowsep — Returns the “rowsep” value associated with a CALS table cell.

Function:

{http://docbook.org/ns/docbook/functions}cals-rowsep#3

Defined in:

modules/tablecals.xsl

Used in:

main.xsl

Synopsis

f:cals-rowsep( | $row as element(db:row),
| $cell as element(),
$last-row-rowsep as xs:boolean) as xs:string?

Description

The row separator, or “rowsep”, associated with a CALS table cell depends on a variety of factors: colspec, and spanspec elements as well as the attributes on the cell itself and its ancestors.

This function returns the value that applies to the specified cell.

f:check-gentext — Returns generated text.

Description

Generated text has been reworked, see Chapter 4, Localization.

f:chunk — Returns chunking attributes.

Function:

{http://docbook.org/ns/docbook/functions}chunk#1

Defined in:

modules/chunk.xsl

Used in:

main.xsl

Synopsis

f:chunk(
$node as element()) as attribute()*

Description

This function returns the db-chunk and perhaps other chunking-related attributes for the given node.

f:chunk-filename — Returns the filename to use for a particular chunk.

Function:

{http://docbook.org/ns/docbook/functions}chunk-filename#1

Defined in:

modules/chunk.xsl

Used in:

modules/chunk.xsl

Used by:

f:chunk()

Synopsis

f:chunk-filename(
$node as element()) as xs:string

Description

When chunking, see Section 2.7, ““Chunked” output”, this function is called to determine the filename for a chunk. The default implementation considers relevant db processing instructions (filename, href, and basename pseudo-attributes) as well as the generated ID of the element.

f:chunk-title — Returns the title of a chunk.

Function:

{http://docbook.org/ns/docbook/functions}chunk-title#1

Defined in:

modules/chunk-cleanup.xsl

Used in:

modules/chunk-cleanup.xsl

Used by:

t:bottom-nav

Synopsis

f:chunk-title(
$chunk as element()?) as node()*

Description

When the title of a neighboring chunk is required (for header or footer navigation, for example), this function can be used to obtain the title of that chunk.

This function must return the HTML-formatted title, not the DocBook title.

f:citations — Returns the citations for a term.

Function:

{http://docbook.org/ns/docbook/functions}citations#1

{http://docbook.org/ns/docbook/functions}citations#2

Defined in:

../standalone-functions.xsl (2)

Used in:

main.xsl

Since:

2.2.0

Synopsis

f:citations(
$term as element()) as element()*

f:citations( | $term as element(),
| $root as document-node()) as element()*

Description

Returns all of the citation elements in the document that match $term. The document is identified by $root, if specified, otherwise the document is the one that $term appears in.

f:conditional-orientation-class — Returns an element’s orientation if it differs from its parent.

Function:

{http://docbook.org/ns/docbook/functions}conditional-orientation-class#1

Defined in:

modules/functions.xsl

Used in:

main.xsl

Since:

2.2.2

Synopsis

f:conditional-orientation-class(
$node as element()) as xs:string?

Description

Determines if the element specified should be printed in portrait or landscape orientation. If that value is the same as the parent element’s value, an empty sequence is returned instead.

This avoids “double rotation” of, for example, a landscape table within a landscape chapter.

f:css-length — Returns a length in the format of a CSS property.

Function:

{http://docbook.org/ns/docbook/functions}css-length#2

Defined in:

modules/objects.xsl

Used in:

main.xsl

Synopsis

f:css-length( | $property as xs:string,
| $length as map(*)?) as xs:string?

Description

Returns the CSS property specified with the corresponding length, if the length exists. Returns the empty sequence otherwise.

f:css-property — Returns a CSS property for a given value.

Function:

{http://docbook.org/ns/docbook/functions}css-property#2

Defined in:

modules/objects.xsl

Used in:

main.xsl

Synopsis

f:css-property( | $property as xs:string,
| $value as xs:string?) as xs:string?

Description

If the specified value exists, a string formatted as a CSS property is returned. If the value doesn’t exist, an empty sequence is returned.

f:date-format — Returns the format string for a date.

Function:

{http://docbook.org/ns/docbook/functions}date-format#1

Defined in:

modules/functions.xsl

Used in:

main.xsl

Synopsis

f:date-format(
$context as element()) as xs:string

Description

Dates may be stored in a variety of formats and the pubdate element even allows inline markup. The f:date-format() function determines how a date will be formatted:

If the date contains embedded markup, the special value “apply-templates” is returned to indicate that string formatting isn’t appropriate.

If the date conforms to an ISO 8601 date, the $date-date-format string is returned.

If the date conforms to an ISO 8601 dateTime, the $date-dateTime-format string is returned.

If the date does not conform to either of those date formats, “apply-templates” is returned.

If the date conforms to a date or dateTime, the author may override the format string by providing a db processing instruction with a date-format pseudo-attribute.

Example 1, “Several dates in ISO 8601 formats” shows an example of several dates that may be formatted in more familiar forms.

<para>The Unix epoch begins at
<date>1970-01-01T00:00:00Z</date>.
Grace Hopper was born on <date>1906-12-09</date>.
That was a <date><?db date-format="[F]"?>1906-12-09</date>.
I was born on a <date>Friday</date>.</para>

Example 1. Several dates in ISO 8601 formats

With default formats, these are formatted as shown:

The Unix epoch begins at 00:00 01 Jan 1970. Grace Hopper was born on 09 Dec 1906. That was a Sunday. I was born on a Friday.

f:empty-length — Returns a map that represents an empty length.

Function:

{http://docbook.org/ns/docbook/functions}empty-length#0

Defined in:

modules/units.xsl

Used in:

main.xsl

Synopsis

f:empty-length(
) as map(*)

Description

Lengths are compound objects. Lengths consist of a magnitude (a number) and a unit: 3 inches, for example, or 11.9 barleycorns⌖² in the case of absolute lengths. For relative lengths, the unit is something relative like percent.

These are represented as maps internally and f:empty-length() returns a length with no magnitude or units.

Annotations

⌖²

Yes, that’s a real unit. It’s equal to ⅓ of an inch. I’ll leave it to Wikipedia to explain the details. Just looking at the chart of imperial units makes me want to add them all!

Image credit: 42CrMo4, Christoph Päper

f:equal-lengths — Returns true if two lengths are equal.

Function:

{http://docbook.org/ns/docbook/functions}equal-lengths#2

Defined in:

modules/units.xsl

Used in:

main.xsl

Synopsis

f:equal-lengths( | $a as map(*)?,
| $b as map(*)?) as xs:boolean

Description

Lengths (see Section 5.2, “Lengths and units”) are stored in maps and so are not directly comparable. This function returns true if two lengths are equal.

f:flatten-path — Removes “.” and “..” segments from the path of a URI.

Function:

{http://docbook.org/ns/docbook/functions}flatten-path#1

Defined in:

../standalone-functions.xsl

Used in:

main.xsl

Since:

2.6.0

Synopsis

f:flatten-path(
$hierarchical-uri as xs:string) as xs:anyURI

Description

This function removes . and .. segments from the path portion of a (assumed to be hierarchical) URI. It issues a warning (but does not cause the stylesheet to fail) if an attempt is made to navigate beyond the root.

f:generate-id — Generate a unique identifier for an element.

Function:

{http://docbook.org/ns/docbook/functions}generate-id#1

{http://docbook.org/ns/docbook/functions}generate-id#2

Defined in:

modules/functions.xsl (2)

Used in:

main.xsl, modules/chunk.xsl

Used by:

f:chunk-filename()

Synopsis

f:generate-id(
$node as element()) as xs:string

f:generate-id( | $node as element(),
| $use-xml-id as xs:boolean) as xs:string

Description

This function returns a unique ID for an element. The ID is generated from the names of the ancestors and preceding siblings of the element. This value will be consistent across different transformations as long as the ancestors and preceding siblings remain unchanged.

If use-xml-id is true and there’s an element with a xml:id attribute among the ancestors, the unique identifier is rooted at that element, rather than traversing all the way to the root of the document.

Disabling this feature by setting use-xml-id to false allows for the creation of globally unique IDs with f:unique-id().

f:gentext — Returns generated text.

Description

Generated text now uses m:gentext. See Chapter 4, Localization.

f:gentext-letters — Returns the letters for the in-scope language.

Function:

{http://docbook.org/ns/docbook/functions}gentext-letters#1

Defined in:

modules/functions.xsl

Used in:

Not used.

Synopsis

f:gentext-letters(
$node as element()) as element(l:letters)?

Description

This function works calls f:language() on the specified node and then calls f:gentext-letters-for-language() with that language.

f:gentext-letters-for-language — Returns the letters for a language.

Function:

{http://docbook.org/ns/docbook/functions}gentext-letters-for-language#1

Defined in:

modules/functions.xsl

Used in:

main.xsl

Synopsis

f:gentext-letters-for-language(
$node as element()) as element(l:letters)?

Description

Returns a language-specific list of letters. These are used, for example, to construct the divisions in an index.

f:global-syntax-highlighter — Returns the global syntax highlighter.

Function:

{http://docbook.org/ns/docbook/functions}global-syntax-highlighter#1

Defined in:

modules/functions.xsl

Used in:

main.xsl, modules/chunk-cleanup.xsl

Since:

2.5.0

Synopsis

f:global-syntax-highlighter(
$context as node()) as xs:string

Description

The global syntax highlighter is usually specified with the $verbatim-syntax-highlighter parameter. However, mostly as an aid to testing, you can also use the db processing instruction syntax-highlighter pseudo-attribute in the root element.

This will override the default highlighter for the specific document.

f:glossentries — Returns a list of all glossentries for a term.

Function:

{http://docbook.org/ns/docbook/functions}glossentries#1

{http://docbook.org/ns/docbook/functions}glossentries#2

Defined in:

../standalone-functions.xsl (2)

Used in:

main.xsl

Since:

2.2.0

Synopsis

f:glossentries(
$term as element()) as element(db:glossentry)*

f:glossentries( | $term as element(),
| $collections as xs:string*) as element(db:glossentry)*

Description

Returns all glossentry elements that are targeted by $term, which must either by a glossterm or a firstterm element. The internal glossary of the input document is always taken into account.

In the form with only one argument, external glossaries are also taken into account if they are designated in the input document with a <?db glossary-collection='URIs'?> processing instruction. In the form with two arguments, you can specify a list of URIs of the external glossaries.

When there is more than one glossentry found, the result sequence will start with entries from the internal glossary, if any.

The functions design allows its use independent from the xslTNG stylesheets. You can, for example, integrate it in a Schematron rule that checks whether every glossterm has exactly one corresponding glossentry while authoring your document. That’s why the function can't use the $glossary-collection transformation parameter.

f:glossrefs — Returns the glossary references for a term.

Function:

{http://docbook.org/ns/docbook/functions}glossrefs#1

{http://docbook.org/ns/docbook/functions}glossrefs#2

Defined in:

../standalone-functions.xsl (2)

Used in:

main.xsl

Since:

2.2.0

Synopsis

f:glossrefs(
$term as element()) as element()*

f:glossrefs( | $term as element(),
| $root as node()) as element()*

Description

Returns all of the glossterm and firstterm elements in the document that match $term. The document is identified by $root, if specified, otherwise the document is the one that $term appears in.

f:href — Returns the href link to a node.

Function:

{http://docbook.org/ns/docbook/functions}href#2

Defined in:

modules/functions.xsl

Used in:

main.xsl

Synopsis

f:href( | $context as node(),
| $node as element()) as xs:string

Description

This function generates a value for an HTML href attribute at the position of the context that will link to the node.

f:id — Returns an ID for the element.

Function:

{http://docbook.org/ns/docbook/functions}id#1

Defined in:

modules/functions.xsl

Used in:

main.xsl

Synopsis

f:id(
$node as element()) as xs:string

Description

This function returns the ID of the element. If the element has an xml:id attribute, the value of that attribute is returned. Otherwise, the function constructs a unique ID value for the element.

The simplest way to construct a unique ID is with the f:generate-id() function. However, those values are only unique within the context of a single transformation and tend to vary over time. This can break anchors used in published documents and leads to spurious differences between documents.

The stylesheets generate their own unique IDs with f:generate-id().

f:in-scope-language — Returns the in-scope-language associated with an element.

Function:

{http://docbook.org/ns/docbook/functions}in-scope-language#1

Defined in:

modules/gentext.xsl

Used in:

Not used.

Since:

2.0.0

Synopsis

f:in-scope-language(
$target as node()) as xs:string

Description

Returns the value of the nearest in-scope xml:lang attribute or $default-language if no such attribute exists.

f:intra-number-separator — Return the intra-number separator.

Description

Separators are now part of the generated text template, see Chapter 4, Localization.

f:is-empty-length — Tests if a length is empty.

Function:

{http://docbook.org/ns/docbook/functions}is-empty-length#1

Defined in:

modules/units.xsl

Used in:

main.xsl

Synopsis

f:is-empty-length(
$length as map(*)?) as xs:boolean

Description

Returns true if the length is empty. For a discussion of units and lengths, see Section 5.2, “Lengths and units”.

f:is-true — Determines if a given value represents “true”

Function:

{http://docbook.org/ns/docbook/functions}is-true#1

Defined in:

modules/functions.xsl

Used in:

docbook.xsl, main.xsl, modules/chunk.xsl, modules/chunk-cleanup.xsl, modules/chunk-output.xsl

Used by:

f:chunk-filename(), t:docbook

Synopsis

f:is-true(
$value) as xs:boolean

Description

There are several conventions for indicating “true” or “false”. XSLT uses the words “yes” and “no” in many places. The XML Schema data type for xs:boolean uses “true” and “false” but also “1” and “0”.

The f:is-true() function returns true() for any of “true()”, “yes”, “true”, or a value that can be cast to an integer if that integer is not zero. It returns false() for any of “false()”, “no”, “false”, a value that can be cast to an integer that is zero, or the empty sequence.

It reports an error for any other value and returns “true()”.

f:l10n-language — Returns the best matching localization language.

Function:

{http://docbook.org/ns/docbook/functions}l10n-language#1

Defined in:

modules/functions.xsl

Used in:

main.xsl

Synopsis

f:l10n-language(
$target as element()) as xs:string

Description

This function returns the localization language that best matches the language of the $target node. If $gentext-language is specified, it is always returned. The $default-language will be returned if there is no localization available for the declared language of the $target.

f:l10n-token — Returns the gentext token for a key.

Function:

{http://docbook.org/ns/docbook/functions}l10n-token#2

{http://docbook.org/ns/docbook/functions}l10n-token#3

Defined in:

modules/l10n.xsl (2)

Used in:

main.xsl, modules/chunk-output.xsl

Since:

2.0.0

Synopsis

f:l10n-token( | $context as element(),
| $key as xs:string) as item()*

f:l10n-token( | $context as element(),
| $lang as xs:string,
$key as xs:string) as item()*

Description

This function returns the gentext token for a key. This is usually accomplished by looking in the localization, but if you need an override for a specific element, you can replace this function.

f:label-separator — Returns the label separator.

Function:

{http://docbook.org/ns/docbook/functions}label-separator#1

Defined in:

modules/functions.xsl

Used in:

Not used.

Synopsis

f:label-separator(
$node as element()) as node()*

Description

The label separator separates a label from the number or title that follows it.

f:language — Returns the language associated with an element.

Description

Renamed f:in-scope-language().

f:languages — Returns all of the localizations used by a document.

Function:

{http://docbook.org/ns/docbook/functions}languages#1

Defined in:

modules/gentext.xsl

Used in:

Not used.

Since:

2.0.0

Synopsis

f:languages(
$context as document-node()) as xs:string+

Description

Returns all of the localizations that might be used in formatting this document.

f:length-string — Returns the string representation of a length.

Function:

{http://docbook.org/ns/docbook/functions}length-string#1

Defined in:

modules/units.xsl

Used in:

Not used.

Synopsis

f:length-string(
$length as map(*)?) as xs:string?

Description

For a given length (see Section 5.2, “Lengths and units”), returns the relative or absolute length formatted as a string. Relative lengths are formatted as the length followed by a literal “*” (e.g., “3*”). Absolute lengths are formatted as the length followed by the unit (e.g., “2.54cm”).

f:length-units — Returns the units associated with a length.

Function:

{http://docbook.org/ns/docbook/functions}length-units#1

Defined in:

modules/units.xsl

Used in:

Not used.

Synopsis

f:length-units(
$length as xs:string?) as xs:string?

Description

For a given length (see Section 5.2, “Lengths and units”), returns the units associated with the length. Returns an empty sequence for relative lengths.

f:locales — Returns the locales detected in the document.

Description

Replaced by f:languages().

f:make-length — Construct a length from constituent parts.

Function:

{http://docbook.org/ns/docbook/functions}make-length#1

{http://docbook.org/ns/docbook/functions}make-length#2

{http://docbook.org/ns/docbook/functions}make-length#3

Defined in:

modules/units.xsl (3)

Used in:

main.xsl

Synopsis

f:make-length(
$relative as xs:double) as map(*)

f:make-length( | $magnitude as xs:double,
| $unit as xs:string) as map(*)

f:make-length( | $relative as xs:double,
| $magnitude as xs:double,
$unit as xs:string) as map(*)

Description

These functions construct a length (see Section 5.2, “Lengths and units”) from either a relative magnitude, an absolute magnitude and a unit, or both.

f:mediaobject-amend-uri — Amend the URI for media objects.

Function:

{http://docbook.org/ns/docbook/functions}mediaobject-amend-uri#1

Defined in:

modules/objects.xsl

Used in:

main.xsl

Synopsis

f:mediaobject-amend-uri(
$uri as xs:string) as xs:string

Description

After the media object URI has been calculated, f:mediaobject-amend-uri() is called. This is an opportunity to update the URI so that the media object will be found.

The default version of this function returns the URI unchanged unless $mediaobject-grouped-by-type is true. If media objects are grouped by type, the media object type is added to the URI. The media object type is determined by calling f:mediaobject-type().

Suppose, for example, that the calculated URI is file:///path/to/image.jpg and the f:mediaobject-type() returns “jpeg”. In that case, the URI returned will be file:///path/to/jpeg/image.jpg.

☝

Important

Consider how this function interacts with the m:mediaobject-output-adjust mode. In particular, beware that the value processed in the m:mediaobject-output-adjust mode will already have been updated by f:mediaobject-amend-uri().

f:mediaobject-input-base-uri — Identify the input base URI for media.

Function:

{http://docbook.org/ns/docbook/functions}mediaobject-input-base-uri#1

Defined in:

modules/objects.xsl

Used in:

main.xsl

Synopsis

f:mediaobject-input-base-uri(
$node as element()) as xs:string

Description

This value is calculated from the $mediaobject-input-base-uri parameter. If the parameter is the empty string, then this value is the empty sequence. Otherwise, this value is the absolute URI that results from resolving the value of the $mediaobject-input-base-uri parameter against the base URI of the input document.

In previous versions of the stylesheet, this value was computed once as a global variable. It was changed to a function because of failures resolving the base URI of documents when using XSpec.

f:mediaobject-type — Return the type of a media object.

Function:

{http://docbook.org/ns/docbook/functions}mediaobject-type#1

Defined in:

modules/objects.xsl

Used in:

main.xsl

Synopsis

f:mediaobject-type(
$uri as xs:string) as xs:string?

Description

If $mediaobject-grouped-by-type is true, this function will be called to determine the type of each media object. The default version simply returns the media object extension, if there is one. (The type of image.png is png.)

f:number-separator — Returns the number separator.

Description

Separators are now part of the generated text template, see Chapter 4, Localization.

f:object-align — Returns the alignment of a media object.

Function:

{http://docbook.org/ns/docbook/functions}object-align#1

Defined in:

modules/objects.xsl

Used in:

main.xsl

Synopsis

f:object-align(
$info as map(*)) as xs:string?

Description

By default, this function simply returns the value of the object’s align attribute.

f:object-contentheight — Returns the content height of an object.

Function:

{http://docbook.org/ns/docbook/functions}object-contentheight#2

Defined in:

modules/objects.xsl

Used in:

main.xsl

Synopsis

f:object-contentheight( | $info as map(*),
| $intrinsicheight as map(*)) as map(*)

Description

Returns the content height, for reasons of historical accident, in the contentdepth attribute. This function returns the height of an object as a length (see Section 5.2, “Lengths and units”), if it has one. If the height is specified as a percentage, and the intrinsic size of the object is known, the an absolute length equal to that percentage of the intrinsic size is returned.

If $image-ignore-scaling is true, or no contentdepth is specified for the object, the empty sequence is returned.

f:object-contentwidth — Returns the content width of an object.

Function:

{http://docbook.org/ns/docbook/functions}object-contentwidth#2

Defined in:

modules/objects.xsl

Used in:

main.xsl

Synopsis

f:object-contentwidth( | $info as map(*),
| $intrinsicwidth as map(*)) as map(*)

Description

Returns the content width. This function returns the width of an object as a length (see Section 5.2, “Lengths and units”), if it has one. If the width is specified as a percentage, and the intrinsic size of the object is known, the an absolute length equal to that percentage of the intrinsic size is returned.

If $image-ignore-scaling is true, or no contentwidth is specified for the object, the empty sequence is returned.

f:object-height — Returns the height (depth) of a mediaobject.

Function:

{http://docbook.org/ns/docbook/functions}object-height#1

Defined in:

modules/objects.xsl

Used in:

main.xsl

Synopsis

f:object-height(
$info as map(*)) as map(*)

Description

The height of a mediaobject is specified, for reasons of historical accident, in the depth attribute. This function returns the height of an object as a length (see Section 5.2, “Lengths and units”), if it has one. If $image-ignore-scaling is true, or no depth is specified for the object, the empty sequence is returned.

f:object-properties — Returns the properties of an object.

Function:

{http://docbook.org/ns/docbook/functions}object-properties#1

{http://docbook.org/ns/docbook/functions}object-properties#2

Defined in:

modules/objects.xsl (2)

Used in:

main.xsl

Synopsis

f:object-properties(
$uri as xs:string) as map(xs:string, xs:anyAtomicType)

f:object-properties( | $uri as xs:string,
| $image-file as xs:boolean) as map(xs:string, xs:anyAtomicType)

Description

If the extension functions are available, the stylesheets will interrogate images for their properties. The goal is to return, at a minimum, the height and width of the image. This is used to compute viewport and scaling factors. If the image metadata extension is available, then considerably more information my be returned in the map.

For example, the image metadata properties of the Amaryllis photograph in Figure 1, “An amaryllis” are:

Property name | Property value a
blue-colorant | (0.1431, 0.0606, 0.7141)
blue-trc | 0.0, 0.0000763, 0.0001526, 0.000228…
class | Display Device
cmm-type | Lino
color-space | RGB
component-1 | Y component: Quantization table 0, …
component-2 | Cb component: Quantization table 1,…
component-3 | Cr component: Quantization table 1,…
compression-type | Baseline
data-precision | 8 bits
detected-file-type-long-name | Joint Photographic Experts Group
detected-file-type-name | JPEG
detected-mime-type | image/jpeg
device-manufacturer | IEC
device-mfg-description | IEC http://www.iec.ch
device-model | sRGB
device-model-description | IEC 61966-2.1 Default RGB colour sp…
expected-file-name-extension | jpg
green-colorant | (0.3851, 0.7169, 0.0971)
green-trc | 0.0, 0.0000763, 0.0001526, 0.000228…
height | 336
image-height | 336 pixels
image-width | 500 pixels
luminance | (76.0365, 80, 87.1246)
measurement | 1931 2° Observer, Backing (0, 0, 0)…
media-black-point | (0, 0, 0)
media-white-point | (0.9505, 1, 1.0891)
number-of-components | 3
number-of-tables | 4 Huffman tables
primary-platform | Microsoft Corporation
profile-connection-space | XYZ
profile-copyright | Copyright (c) 1998 Hewlett-Packard …
profile-date/time | 1998-02-09T06:49:00
profile-description | sRGB IEC61966-2.1
profile-size | 3144
red-colorant | (0.4361, 0.2225, 0.0139)
red-trc | 0.0, 0.0000763, 0.0001526, 0.000228…
resolution-units | inch
signature | acsp
tag-count | 17
technology | CRT
thumbnail-height-pixels | 0
thumbnail-width-pixels | 0
version | 2.1.0
viewing-conditions | view (0x76696577): 36 bytes
viewing-conditions-description | Reference Viewing Condition in IEC6…
width | 500
x-resolution | 72 dots
xyz-values | 0.964 1 0.825
y-resolution | 72 dots
aSome values have been truncated to prevent the table from becoming unwieldy. These values an be identified by a trailing ellipsis (…).

Figure 1. An amaryllis

f:object-scale — Returns the scaling factor for an object.

Function:

{http://docbook.org/ns/docbook/functions}object-scale#1

Defined in:

modules/objects.xsl

Used in:

main.xsl

Synopsis

f:object-scale(
$info as map(*)) as xs:double

Description

Returns the scaling factor for an object. Scaling only applies if $image-ignore-scaling is false and the object has a scale attribute.

f:object-scalefit — Scale object to fit?

Function:

{http://docbook.org/ns/docbook/functions}object-scalefit#1

Defined in:

modules/objects.xsl

Used in:

main.xsl

Synopsis

f:object-scalefit(
$info as map(*)) as xs:boolean

Description

This function determines whether or not an object should be scaled to fit its container.

f:object-valign — Returns the vertical alignment of a media object.

Function:

{http://docbook.org/ns/docbook/functions}object-valign#1

Defined in:

modules/objects.xsl

Used in:

main.xsl

Synopsis

f:object-valign(
$info as map(*)) as xs:string?

Description

By default, this function simply returns the value of the object’s valign attribute. If it doesn’t have a valign attribute, the value “middle” is returned, because that’s what previous versions of stylesheets for DocBook did.

f:object-width — Returns the width of a mediaobject.

Function:

{http://docbook.org/ns/docbook/functions}object-width#1

Defined in:

modules/objects.xsl

Used in:

main.xsl

Synopsis

f:object-width(
$info as map(*)) as map(*)

Description

This function returns the width of an object as a length (see Section 5.2, “Lengths and units”), if it has one. If $image-ignore-scaling is true, or no width is specified for the object, the empty length is returned.

f:orderedlist-item-number — Returns the item number of an item in an ordered list.

Function:

{http://docbook.org/ns/docbook/functions}orderedlist-item-number#1

Defined in:

modules/functions.xsl

Used in:

main.xsl

Synopsis

f:orderedlist-item-number(
$node as element(db:listitem)) as xs:integer+

Description

Returns the item number of a list item. This is always an integer, even if it will be formatted as a letter, roman numeral, or other symbol. For nested lists, this function returns the fully qualified item number. For example, for the second item in the fourth item in the third item of a list, it will return (2, 4, 3).

f:orderedlist-item-numeration — Returns the item numeration format for an ordered list.

Function:

{http://docbook.org/ns/docbook/functions}orderedlist-item-numeration#1

Defined in:

modules/functions.xsl

Used in:

main.xsl

Synopsis

f:orderedlist-item-numeration(
$node as element(db:listitem)) as xs:string

Description

Computes the numeration for the specified list item. See $orderedlist-item-numeration.

f:orderedlist-startingnumber — Returns the starting number of an ordered list.

Function:

{http://docbook.org/ns/docbook/functions}orderedlist-startingnumber#1

Defined in:

modules/functions.xsl

Used in:

main.xsl

Synopsis

f:orderedlist-startingnumber(
$list as element(db:orderedlist)) as xs:integer

Description

In most orderedlist elements, the first item in the list is item number “1”. However, the startingnumber attribute can specify a different initial number and, in the case of continued lists, the starting number depends on the ending number of the preceding list.

The f:orderedlist-startingnumber() returns the number of the first list item in an ordered list.

f:orientation-class — Returns the class value to use for an element’s orientation.

Function:

{http://docbook.org/ns/docbook/functions}orientation-class#1

Defined in:

modules/functions.xsl

Used in:

main.xsl

Since:

2.2.2

Synopsis

f:orientation-class(
$node as element()) as xs:string?

Description

Determines if the element specified should be printed in portrait or landscape orientation. The default is assumed to be portrait.

f:parse-length — Parse a string into a length.

Function:

{http://docbook.org/ns/docbook/functions}parse-length#1

Defined in:

modules/units.xsl

Used in:

main.xsl

Synopsis

f:parse-length(
$length as xs:string?) as map(*)

Description

This function parses a string such as “4in” or “3.14cm” or “50%” into a length. It will fall back to a distance of the $default-length-magnitude and $default-length-unit if the string cannot be parsed as a length.

f:pi — Returns DocBook processing-instruction property values.

Function:

{http://docbook.org/ns/docbook/functions}pi#2

{http://docbook.org/ns/docbook/functions}pi#3

Defined in:

../standalone-functions.xsl (2)

Used in:

main.xsl, modules/chunk.xsl

Used by:

f:chunk-filename()

Synopsis

f:pi( | $context as node()?,
| $property as xs:string) as xs:string?

f:pi( | $context as node()?,
| $property as xs:string,
$default as xs:string*) as xs:string*

Description

Several DocBook elements have alternate presentations that can be specified with global parameters. Many of them can also be set on a per-element basis with a db processing instruction. The date format, for example, can be changed in this way as described in the f:date-format() function.

The f:pi() function takes a context and the name of a property. It returns the value specified for that property from all of the db processing instructions in the specified context. The three argument version allows you to specify a default value. It will be returned if there are no values specified for the property in that context.

f:pi-attributes — Returns processing-instruction pseudo-attributes as attributes.

Function:

{http://docbook.org/ns/docbook/functions}pi-attributes#1

Defined in:

../standalone-functions.xsl

Used in:

main.xsl

Synopsis

f:pi-attributes(
$pis as processing-instruction()*) as element()?

Description

Using pseudo-attributes in a db processing instruction is a convenient mechanism for providing additional options to the stylesheets. But processing them is tedious. This function gathers together the pseudo-attributes specified in a series of processing instructions and returns them as attributes on an element. If the same property occurs more than once in the sequence, the last value will be returned.

f:post-label-punctuation — Punctuation that follows a label.

Description

Generated text has been reworked, see Chapter 4, Localization.

f:refsection — Is this a section in a refentry?

Function:

{http://docbook.org/ns/docbook/functions}refsection#1

Defined in:

modules/functions.xsl

Used in:

main.xsl

Synopsis

f:refsection(
$node as element()) as xs:boolean

Description

Returns true if the node is a section in a refentry, a refsection, refsect1, refsect2, or refsect3 element.

f:relative-length — Returns the relative portion of a length, if it has one.

Function:

{http://docbook.org/ns/docbook/functions}relative-length#1

Defined in:

modules/units.xsl

Used in:

main.xsl

Synopsis

f:relative-length(
$length as map(*)) as xs:double

Description

For a given length, returns the relative length if it has one. For lengths that have no relative component, returns 0.0. For a discussion of units, see Section 5.2, “Lengths and units”.

f:relative-path — Give two file paths, what’s the relative path between them?

Function:

{http://docbook.org/ns/docbook/functions}relative-path#2

Defined in:

modules/functions.xsl

Used in:

main.xsl

Synopsis

f:relative-path( | $base as xs:string,
| $path as xs:string) as xs:string

Description

This function attempts to determine the relative path between two absolute paths. For example, given a base path of /a/base/uri/path/ and a path of /a/base/uri/with/other, the results is ../with/other.

If the path is an absolute URI (that isn’t a file: URI), then the URI is returned unchanged.

f:section — Is this a section?

Function:

{http://docbook.org/ns/docbook/functions}section#1

Defined in:

modules/functions.xsl

Used in:

Not used.

Synopsis

f:section(
$node as element()) as xs:boolean

Description

Returns true if the node is a section, a section or sect1-5 element.

f:section-depth — Returns the section depth of a node.

Function:

{http://docbook.org/ns/docbook/functions}section-depth#1

Defined in:

modules/functions.xsl

Used in:

main.xsl

Synopsis

f:section-depth(
$node as element()?) as xs:integer

Description

Returns the section depth of a node, that is, how many section elements are among its ancestors.

f:spaces — Returns a string of spaces.

Function:

{http://docbook.org/ns/docbook/functions}spaces#1

Defined in:

modules/functions.xsl

Used in:

main.xsl

Synopsis

f:spaces(
$length as item()*) as xs:string?

Description

This function returns a string of $length spaces. If $length:

is empty, an empty sequence is returned.

is an integer, or castable to an integer, a string of that length is returned. If the length is negative, an empty sequence is returned.

is anything else, the length of the string value of $length is used as the length.

In other words:

f:spaces(()) is ‘()’,

f:spaces(0) is ‘’ (no spaces),

f:spaces(-1) is ‘()’,

f:spaces(2) is ‘  ’ (two spaces),

f:spaces("1") is ‘ ’ (one space), and

f:spaces("test") is ‘    ’ (four spaces).

This function accepts a sequence to support the empty sequence. If it’s passed a sequence of more than one item, it treats that as if the string values of the items had been concatenated together. This can have slightly surprising consequences as “('a', '3', '0')” will return a string of three spaces whereas “('0', '3', '0')” will return a string of thirty.

f:step-number — Returns the step number of a step in an procedure.

Function:

{http://docbook.org/ns/docbook/functions}step-number#1

Defined in:

modules/functions.xsl

Used in:

main.xsl

Synopsis

f:step-number(
$node as element(db:step)) as xs:integer+

Description

Returns the step number of step in a procedure. This is always an integer, even if it will be formatted as a letter, roman numeral, or other symbol. For steps nested in side substeps, this function returns the fully qualified item number. For example, for the second substep in the fourth substep in the third step of a procedure, it will return (2, 4, 3).

f:step-numeration — Returns the step numeration format for a step.

Function:

{http://docbook.org/ns/docbook/functions}step-numeration#1

Defined in:

modules/functions.xsl

Used in:

main.xsl

Synopsis

f:step-numeration(
$node as element(db:step)) as xs:string

Description

Computes the numeration for the specified step. See $procedure-step-numeration.

f:syntax-highlight — Performs syntax highlighting.

Function:

{http://docbook.org/ns/docbook/functions}syntax-highlight#1

{http://docbook.org/ns/docbook/functions}syntax-highlight#2

{http://docbook.org/ns/docbook/functions}syntax-highlight#3

Defined in:

highlight.xsl (3)

Used in:

main.xsl, highlight.xsl

Used by:

f:syntax-highlight(), f:syntax-highlight()

Synopsis

f:syntax-highlight(
$source as xs:string)

f:syntax-highlight( | $source as xs:string,
| $language as xs:string)

f:syntax-highlight( | $source as xs:string,
| $options,
$pyoptions as map(xs:string,xs:string)) as node()*

Description

Verbatim environments that specify a language can be syntax highlighted. Syntax highlighting adds additional spans so that, for example, CSS can be used to make keyword bold or quoted strings a different color.

Syntax highlighting requires an extension function. The list of languages that will be syntax highlighted is taken from $verbatim-syntax-highlight-languages.

f:target — Returns the element identified by a particular id.

Function:

{http://docbook.org/ns/docbook/functions}target#2

Defined in:

modules/functions.xsl

Used in:

main.xsl

Synopsis

f:target( | $id as xs:string,
| $context as node()) as element()*

Description

The item with the specified ID that is in the same document as $context item is returned.

f:template — Returns the title page template for an element.

Function:

{http://docbook.org/ns/docbook/functions}template#2

Defined in:

modules/templates.xsl

Used in:

main.xsl

Synopsis

f:template( | $context as element(),
| $default as element()) as element()

Description

Returns the title page template that should be used for an element. If no template is found, returns the $default template.

f:tokenize-on-char — Tokenize a string at a specific character.

Function:

{http://docbook.org/ns/docbook/functions}tokenize-on-char#2

Defined in:

modules/functions.xsl

Used in:

Not used.

Synopsis

f:tokenize-on-char( | $string as xs:string,
| $char as xs:string) as xs:string*

Description

This function tokenizes a string at a specific character (not a regular expression). If the specified character is a regular expression meta-character, it is automatically escaped.

f:translate-attribute — Controls the translate attribute.

Function:

{http://docbook.org/ns/docbook/functions}translate-attribute#1

Defined in:

modules/functions.xsl

Used in:

main.xsl

Since:

2.1.3

Synopsis

f:translate-attribute(
$node as element()) as xs:boolean?

Description

When computing what attributes to put on elements in the output, this function is called to check whether a translate attribute should be output:

If it returns true, a translate attribute with the value “yes” will be output.

If it returns false, a translate attribute with the value “no” will be output.

If it returns the empty sequence, no translate attribute will be output.

The default implementation of this function checks the (local) name of the element with the $translate-suppress-elements list.

f:unique-id — Returns an ID for the element.

Function:

{http://docbook.org/ns/docbook/functions}unique-id#1

Defined in:

modules/functions.xsl

Used in:

Not used.

Synopsis

f:unique-id(
$node as element()) as xs:string

Description

This function returns a globally unique ID for the element. This allows a transformation to disambiguate between different elements that happen to have the same xml:id, as can occur if transclusion is performed.

f:uri-scheme — Returns the scheme portion of a URI.

Function:

{http://docbook.org/ns/docbook/functions}uri-scheme#1

Defined in:

modules/functions.xsl

Used in:

main.xsl, modules/chunk-cleanup.xsl

Since:

2.0.6

Synopsis

f:uri-scheme(
$uri as xs:string) as xs:string?

Description

If the URI begins with a scheme, this function returns the scheme. Otherwise, it returns an empty sequence.

f:verbatim-callout — Return the callout style for a verbatim environment.

Function:

{http://docbook.org/ns/docbook/functions}verbatim-callout#1

Defined in:

modules/verbatim.xsl

Used in:

main.xsl

Since:

2.5.0

Synopsis

f:verbatim-callout(
$context as element()) as xs:string*

Description

This function examines a verbatim environment, the $context, and returns the value of the A db processing instruction with a verbatim-highlight pseudo-attribute may be used to override the $verbatim-callouts parameter on a case-by-case basis.

The pseudo-attribute name is “highlight” for backwards compatibility. The function is named “callout” to make it clear(er) that this is unrelated to syntax highlighting.

f:verbatim-numbered — Returns true if the listing should be numbered.

Function:

{http://docbook.org/ns/docbook/functions}verbatim-numbered#1

Defined in:

modules/verbatim.xsl

Used in:

main.xsl

Synopsis

f:verbatim-numbered(
$context as element()) as xs:boolean

Description

The f:verbatim-numbered() function returns true of the specified verbatim listing should be numbered. This will be true if:

The linenumbering attribute is specified and has the value numbered,

the element’s name is listed in $verbatim-numbered-elements, or

a db processing instruction with a verbatim-numbered pseudo-attribute that is true is specified.

There are two overriding conditions that will force the value to be false: first, if the linenumbering attribute is specified and has the value unnumbered, the listing will not be numbered. Second if the listing has a db processing instruction with a verbatim-style pseudo attribute that specifies the “plain” style. Listings in the plain style cannot be numbered, attempting to do so will generate a warning message from the stylesheets.

f:verbatim-style — Returns the style of a verbatim listing.

Function:

{http://docbook.org/ns/docbook/functions}verbatim-style#1

Defined in:

modules/verbatim.xsl

Used in:

main.xsl

Synopsis

f:verbatim-style(
$context as element()) as xs:string

Description

The f:verbatim-style() function returns the style of presentation that should be used for the specified verbatim listing.

If a db processing instruction with a verbatim-style pseudo-attribute is present, the value of that pseudo-attribute will be returned. Otherwise, it will be “lines” if the element’s name is listed in $verbatim-line-style, “plain” if the element’s name is listed in $verbatim-plain-style, or “raw”.

f:verbatim-syntax-highlighter — Return the syntax highlighter style for a verbatim environment.

Function:

{http://docbook.org/ns/docbook/functions}verbatim-syntax-highlighter#1

Defined in:

modules/verbatim.xsl

Used in:

main.xsl

Since:

2.5.0

Synopsis

f:verbatim-syntax-highlighter(
$context as element()) as xs:string

Description

This function examines a verbatim environment, the $context, and returns the value of the A db processing instruction with a syntax-highlighter pseudo-attribute may be used to override the f:global-syntax-highlighter() on a case-by-case basis.

Not all overrides are possible. You can’t, in general, use a JavaScript-based renderer, or a different JavaScript-based renderer, on a case-by-case basis.

f:verbatim-trim-leading — Return true if leading blank lines should be trimmed.

Function:

{http://docbook.org/ns/docbook/functions}verbatim-trim-leading#1

Defined in:

modules/verbatim.xsl

Used in:

main.xsl

Synopsis

f:verbatim-trim-leading(
$context as element()) as xs:boolean

Description

This function examines a verbatim environment, the $context, and returns true if leading blank lines should be trimmed from it. A db processing instruction with a verbatim-trim-leading pseudo-attribute may be used to override the $verbatim-trim-leading-blank-lines parameter on a case-by-case basis.

f:verbatim-trim-trailing — Return true if trailing blank lines should be trimmed.

Function:

{http://docbook.org/ns/docbook/functions}verbatim-trim-trailing#1

Defined in:

modules/verbatim.xsl

Used in:

main.xsl

Synopsis

f:verbatim-trim-trailing(
$context as element()) as xs:boolean

Description

This function examines a verbatim environment, the $context, and returns true if trailing blank lines should be trimmed from it. A db processing instruction with a verbatim-trim-trailing pseudo-attribute may be used to override the $verbatim-trim-trailing-blank-lines parameter on a case-by-case basis.

f:xlink-style — Returns the XLink style for this document.

Function:

{http://docbook.org/ns/docbook/functions}xlink-style#1

Defined in:

modules/xlink.xsl

Used in:

main.xsl

Synopsis

f:xlink-style(
$document as document-node()) as xs:string

Description

The stylesheets support XLink extended links. See $xlink-style for more details.

f:xpointer-idref — Parses an XPointer for a same-document ID reference.

Function:

{http://docbook.org/ns/docbook/functions}xpointer-idref#1

Defined in:

modules/xlink.xsl

Used in:

main.xsl

Synopsis

f:xpointer-idref(
$xpointer) as xs:string?

Description

In DocBook, there are generally two ways to refer to other elements in the current document by ID: using the linkend (or linkends) attribute or using the xlink:href attribute.

The f:xpointer-idref() function returns the ID portion of an XPointer that is a reference to another ID in the current document.

In other words:

f:xpointer-idref('#foo') is foo,

f:xpointer-idref('id(foo)') is foo,

and f:xpointer-idref('http://example.org/#foo') is the empty sequence.

IV. Template reference

Table of Contents

t:audio-fallback

t:biblioentry

t:bottom-nav

t:chunk-cleanup

t:chunk-footnotes

t:chunk-output

t:docbook

t:generate-index

t:glossary-divisions

t:index-zone-reference

t:inline

t:mediaobject-img

t:mediaobject-viewport

t:person-name

t:person-name-family-given

t:person-name-first-last

t:person-name-last-first

t:person-name-list

t:table-footnotes

t:top-nav

t:video-fallback

t:xlink

t:audio-fallback — Generate fallback for audio.

Description

Audio fallback is now supported with $fallback-js.

t:biblioentry — Format a biblioentry element.

Template:

{http://docbook.org/ns/docbook/templates}biblioentry

Defined in:

modules/templates.xsl

Used in:

main.xsl

Synopsis

<xsl:template name="t:biblioentry"/>

Description

Unlike bibliomixed, where the author is expected to provide most of the formatting, biblioentry is a bag of metadata. On the one hand, this opens up the possibility of producing different bibliographic styles from the same entry. On the other hand, it greatly complicates formatting.

The default t:biblioentry template uses a header template (see Section 5.5, “Templates”).

t:bottom-nav — Generate bottom-of-page navigation links.

Template:

{http://docbook.org/ns/docbook/templates}bottom-nav

Defined in:

modules/chunk-cleanup.xsl

Used in:

modules/chunk-cleanup.xsl

Synopsis

<xsl:template name="t:bottom-nav">
                  <xsl:param name="chunk" as="xs:boolean"/>
  <xsl:param name="node" as="element()"/>
  <xsl:param name="prev" as="element()?"/>
  <xsl:param name="next" as="element()?"/>
  <xsl:param name="up" as="element()?"/>
  <xsl:param name="top" as="element()?"/>
                </xsl:template>

Description

This template generates the bottom-of-page nav element. When chunking is performed, this should provide links between pages.

t:chunk-cleanup — Cleanup the HTML markup for a DocBook document.

Template:

{http://docbook.org/ns/docbook/templates}chunk-cleanup

Defined in:

docbook.xsl

Used in:

docbook.xsl

Used by:

t:docbook

Synopsis

<xsl:template name="t:chunk-cleanup">
                  <xsl:param name="source" as="document-node()"/>
  <xsl:param name="docbook" as="document-node()"/>
                </xsl:template>

Description

This mode performs cleanup tasks on the HTML document that results from DocBook processing. This process moves footnotes and annotations when necessary, generates navigation elements, etc.

t:chunk-footnotes — Processes footnotes in a chunk.

Template:

{http://docbook.org/ns/docbook/templates}chunk-footnotes

Defined in:

modules/chunk-cleanup.xsl

Used in:

modules/chunk-cleanup.xsl

Synopsis

<xsl:template name="t:chunk-footnotes">
                  <xsl:param name="footnotes" as="element()*"/>
                </xsl:template>

Description

When chunking is being performed (see Section 2.7, ““Chunked” output”), all of the footnotes that should appear in a chunk are processed with this template.

t:chunk-output — Generate chunked output for a DocBook document.

Template:

{http://docbook.org/ns/docbook/templates}chunk-output

Defined in:

docbook.xsl

Used in:

docbook.xsl

Used by:

t:docbook

Synopsis

<xsl:template name="t:chunk-output">
                  <xsl:param name="source" as="document-node()"/>
  <xsl:param name="docbook" as="document-node()"/>
                </xsl:template>

Description

This mode processes the $persistent-toc if requested and generates individual documents for each chunk. Like the XPath transform function, this template returns a map. You must process the map to store the documents.

t:docbook — Process a DocBook document.

Template:

{http://docbook.org/ns/docbook/templates}docbook

Defined in:

docbook.xsl

Used in:

docbook.xsl

Synopsis

<xsl:template name="t:docbook">
                  <xsl:param name="return" as="xs:string"/>
                </xsl:template>

Description

This mode processes a DocBook document. It’s usually called automatically by the root template in the stylesheets. You only need to call it explicitly if you have an override for the root template and want to do some specialized processing.

The template has a single parameter, return, which selects what should be constructed by the template:

main-document, the default value

Returns the primary output of the stylesheet.

raw-results

Returns a map with two keys, document containing the original DocBook document processed and output containing the transformed result.

chunked-results

Returns a map with two keys, document containing the original DocBook document processed and chunks containing a map from output URIs to documents.

Any other value is an error.

t:generate-index — Generate a back-of-the-book style index.

Template:

{http://docbook.org/ns/docbook/templates}generate-index

Defined in:

modules/index.xsl

Used in:

main.xsl

Synopsis

<xsl:template name="t:generate-index">
                  <xsl:param name="scope"/>
                </xsl:template>

Description

This template is called when an empty index tag is found the document and automatic index generation is enabled. Automatic index generation is enabled if either the $generate-index is true or a db processing instruction with an autoindex pseudo-attribute is true. If the autoindex pseudo-attribute is explicitly false, automatic index generation is suppressed for the index in which it appears.

t:glossary-divisions — Groups entries in a glossary.

Template:

{http://docbook.org/ns/docbook/templates}glossary-divisions

Defined in:

modules/glossary.xsl

Used in:

main.xsl

Synopsis

<xsl:template name="t:glossary-divisions">
                  <xsl:param name="terms" as="element(db:glossentry)+"/>
                </xsl:template>

Description

If $glossary-automatic-divisions is true, this template is used to construct the divisions. By default, it makes groups based on the (upper-case) first letter of the terms. It does not add a grouping wrapper if there’s only one group.

t:index-zone-reference — Process index zone references.

Template:

{http://docbook.org/ns/docbook/templates}index-zone-reference

Defined in:

modules/index.xsl

Used in:

main.xsl

Synopsis

<xsl:template name="t:index-zone-reference">
                  <xsl:param name="scope"/>
  <xsl:param name="role"/>
  <xsl:param name="type"/>
  <xsl:param name="lang"/>
  <xsl:param name="zones" as="xs:string*"/>
                </xsl:template>

Description

This template is called to generate index references for terms that have a zone attribute. It is only called when generating an index.

t:inline — Process an inline element.

Template:

{http://docbook.org/ns/docbook/templates}inline

Defined in:

modules/inlines.xsl

Used in:

main.xsl

Synopsis

<xsl:template name="t:inline">
                  <xsl:param name="namemap"/>
  <xsl:param name="class" as="xs:string*"/>
  <xsl:param name="local-name-as-class" as="xs:boolean"/>
  <xsl:param name="extra-attributes" as="attribute()*"/>
  <xsl:param name="content"/>
                </xsl:template>

Description

All of the inline elements are processed by t:inline. This provides a common place to handle the fact that any of them might be a link. Several parameters exist to handle variations in presentation:

namemap

Maps the element to a particular HTML element. Defaults to span.

class

A list of tokens that should be added to the element’s class attribute.

local-name-as-class

If this is true, the local name of the DocBook element being processed will be added to the classes.

content

The element content. By default, this is obtained by applying XSLT templates to the element’s content.

extra-attributes

Extra attributes to be added to the element.

t:mediaobject-img — Generate a mediaobject img.

Template:

{http://docbook.org/ns/docbook/templates}mediaobject-img

Defined in:

modules/objects.xsl

Used in:

main.xsl

Synopsis

<xsl:template name="t:mediaobject-img">
                  <xsl:param name="sourcefile" as="xs:string"/>
  <xsl:param name="filename" as="xs:string"/>
  <xsl:param name="styles" as="xs:string*"/>
  <xsl:param name="viewport" as="map(*)?"/>
  <xsl:param name="imageproperties" as="map(*)?"/>
                </xsl:template>

Description

This template is called to generate the img element for a media object.

t:mediaobject-viewport — Construct the “viewport” for media objects.

Template:

{http://docbook.org/ns/docbook/templates}mediaobject-viewport

Defined in:

modules/objects.xsl

Used in:

main.xsl

Since:

2.7.0

Synopsis

<xsl:template name="t:mediaobject-viewport">
                  <xsl:param name="info" as="map(*)"/>
  <xsl:param name="inherited-nominal-width" as="map(*)"/>
                </xsl:template>

Description

If your DocBook markup for media objects includes any of the size or scaling adjustment attributes, this template is called to construct the HTML markup that implements those adjustments.

ⓘ

Note

Prior to version 2.7.0, this was a function. It was changed into a template to support the tunnel parameter that manages the nominal width available.

t:person-name — Formats a personal name.

Template:

{http://docbook.org/ns/docbook/templates}person-name

Defined in:

modules/info.xsl

Used in:

main.xsl

Synopsis

<xsl:template name="t:person-name">
                  <xsl:param name="style" as="xs:string"/>
                </xsl:template>

Description

This template formats a personal name according to the specified style. This template must only be called when the current context item is a personname. The personname element can be used in two different ways, it can just contain the name:

<personname>Norman Walsh</personname>

or it can contain the name with markup:

<personname><givenname>Norman</givenname>
<surname>Walsh</surname></personname>

How the name is formatted depends on which form of markup is used and which style is selected. Several styles are supported:

If the name contains no markup, it is simply formatted as is.

If the style is “FAMILY-given”, it is formatted with t:person-name-family-given and generally produces the family name in upper case followed by the given name. For example: “WALSH Norman”.

If the style is “last-first”, it is formatted with t:person-name-last-first and generally produces the family name followed by the given name separated by a comma. For example: “Walsh, Norman”.

If the style is “first-last”, it is formatted with t:person-name-first-last and generally produces the given name followed by the family name. For example: “Norman Walsh”.

Any other value raises dbe:INVALID-NAME-STYLE.

ⓘ

Given names

Historically, DocBook used firstname for the given name of a person. In DocBook 5.1, the givenname element was introduced as an alternative. The stylesheets treat them identically.

The stylesheets attempt to determine what style to use for each personname:

First, by looking at that the role attribute on that element. If any of styles from the $v:personal-name-styles list appear in the role, that style will be selected. (If more than one style appears, the results are undefined.)

If the personname doesn’t identify a style, and if it’s a child of author, editor, or othercredit, the role attirbute of its parent is inspected.

If the $personal-name-style is defined, it is is selected.

If a style still hasn’t been selected the style in the localization file is used.

Personal names are notoriously complicated (see Names). DocBook includes several tags for identifying parts of names:

firstname or givenname

for a given name,

surname

for a family name,

lineage

for lineage (such as “Jr” or “III”),

honorific

for an honorific title (such as “Dr” or “Ms”), and

othername

for everything else.

In all likelihood, if your document contains a variety of personal names, you will need to use roles to disambiguate special cases and you will have to provide alternate or additional templates to format them.

t:person-name-family-given — Formats a personal name in the “FAMILY-given” style.

Template:

{http://docbook.org/ns/docbook/templates}person-name-family-given

Defined in:

modules/info.xsl

Used in:

main.xsl

Synopsis

<xsl:template name="t:person-name-family-given"/>

Description

The “FAMILY-given” style formats a personal name as the family name (surname) in upper-case, followed by the first given name (if there is one), followed by the text “[FAMILY given]”. See t:person-name.

Example 1, “The FAMILY-given name style” shows an example of a personal name to be formatted with the “FAMILY-given” style.

<para>The author is
<personname role="FAMILY-given">
      <givenname>Norman</givenname>
      <surname>Walsh</surname>
      <othername>David</othername>
   </personname>.</para>

Example 1. The FAMILY-given name style

That would be formatted as:

The author is WALSH Norman [FAMILY Given].

t:person-name-first-last — Formats a personal name in the “first-last” style.

Template:

{http://docbook.org/ns/docbook/templates}person-name-first-last

Defined in:

modules/info.xsl

Used in:

main.xsl

Synopsis

<xsl:template name="t:person-name-first-last"/>

Description

The “first-last” style formats a personal name as: the first honorific, followed by the given name, followed possibly by the “middle name”, followed by the surname, followed by the lineage. See t:person-name.

If an othername is provided and if $othername-in-middle is true, then the first othername will be treated as a “middle name” and presented between the given and family names.

Example 1, “The first-last name style” shows an example of a personal name to be formatted with the “first-last” style.

<para>The author is
<personname role="first-last">
      <givenname>Norman</givenname>
      <surname>Walsh</surname>
      <othername>David</othername>
   </personname>.</para>

Example 1. The first-last name style

That would be formatted as:

The author is Norman David Walsh.

t:person-name-last-first — Formats a personal name in the “last-first” style.

Template:

{http://docbook.org/ns/docbook/templates}person-name-last-first

Defined in:

modules/info.xsl

Used in:

main.xsl

Synopsis

<xsl:template name="t:person-name-last-first"/>

Description

The “last-first” style formats a personal name as the family name (surname) followed by the first given name (if there is one). If both a family name and a given name are present, they are separated by a comma. See t:person-name.

Example 1, “The last-first name style” shows an example of a personal name to be formatted with the “last-first” style.

<para>The author is
<personname role="last-first">
      <givenname>Norman</givenname>
      <surname>Walsh</surname>
      <othername>David</othername>
   </personname>.</para>

Example 1. The last-first name style

That would be formatted as:

The author is Walsh, Norman.

t:person-name-list — Formats a sequence of personal names.

Template:

{http://docbook.org/ns/docbook/templates}person-name-list

Defined in:

modules/info.xsl

Used in:

main.xsl

Synopsis

<xsl:template name="t:person-name-list"/>

Description

Formats a sequence of names:

If the sequence consists of a single name, it is formatted.

If the sequence consists of exactly two names, they are formatted with “and” between them where “and” is taken from the in-scope language localization file. It is the item with the key “author-sep2”.

If the sequence consists of more than two names, all but the last are separated by “, “ (the localization item with the key “author-sep”). The last is separated by “, and” (the localization item with the key “author-seplast”).

t:table-footnotes — Process table footnotes.

Template:

{http://docbook.org/ns/docbook/templates}table-footnotes

Defined in:

modules/footnotes.xsl

Used in:

main.xsl

Synopsis

<xsl:template name="t:table-footnotes">
                  <xsl:param name="footnotes" as="element(db:footnote)+"/>
                </xsl:template>

Description

The t:table-footnotes template is called to process footnotes at the bottom of a table.

t:top-nav — Generate top-of-page navigation links.

Template:

{http://docbook.org/ns/docbook/templates}top-nav

Defined in:

modules/chunk-cleanup.xsl

Used in:

modules/chunk-cleanup.xsl

Synopsis

<xsl:template name="t:top-nav">
                  <xsl:param name="chunk" as="xs:boolean"/>
  <xsl:param name="node" as="element()"/>
  <xsl:param name="prev" as="element()?"/>
  <xsl:param name="next" as="element()?"/>
  <xsl:param name="up" as="element()?"/>
  <xsl:param name="top" as="element()?"/>
                </xsl:template>

Description

This template generates the top-of-page nav element. When chunking is performed, this should provide links between pages.

t:video-fallback — Generate fallback for video.

Description

Video fallback is now supported with $fallback-js.

t:xlink — Supports hypertext linking.

Template:

{http://docbook.org/ns/docbook/templates}xlink

Defined in:

modules/xlink.xsl

Used in:

main.xsl

Synopsis

<xsl:template name="t:xlink">
                  <xsl:param name="content"/>
                </xsl:template>

Description

In DocBook, most elements can be links. The t:xlink template is called for each element that might be participating in a link. This includes both simple links (any inline element with an xlink:href attribute) and extended links.

V. Mode reference

Table of Contents

m:annotation-content

m:ansi

m:ansi-table

m:attributes

m:back-cover

m:biblio690

m:biblioentry

m:bibliomixed

m:callout-bug

m:callout-link

m:chunk-cleanup

m:chunk-filename

m:chunk-output

m:chunk-title

m:chunk-write

m:copyright-years

m:crossref

m:crossref-inherit-separator

m:crossref-label

m:crossref-label-separator

m:crossref-number

m:crossref-number-separator

m:crossref-prefix

m:crossref-suffix

m:crossref-title

m:details

m:details-attribute

m:docbook

m:footnote-number

m:footnotes

m:generate-titlepage

m:gentext

m:gentext-list

m:head-additions

m:headline

m:headline-label

m:headline-label-separator

m:headline-number

m:headline-number-separator

m:headline-prefix

m:headline-suffix

m:headline-title

m:highlight-options

m:html-body-script

m:html-head

m:html-head-last

m:html-head-links

m:html-head-script

m:htmltable

m:imagemap

m:index-div

m:index-primary

m:index-secondary

m:index-see

m:index-seealso

m:index-tertiary

m:kr

m:kr-args

m:kr-table

m:kr-table-args

m:link

m:list-of-equations

m:list-of-examples

m:list-of-figures

m:list-of-procedures

m:list-of-tables

m:list-of-titles

m:mediaobject-end

m:mediaobject-info

m:mediaobject-output-adjust

m:mediaobject-start

m:mediaobject-uris

m:panelset

m:persistent-toc

m:production-number

m:pygments-options

m:revhistory-list

m:revhistory-table

m:seglist-table

m:segtitle-in-seg

m:synopfragment-bug

m:synopsis

m:title

m:titlepage

m:to-uppercase

m:toc

m:toc-entry

m:toc-nested

m:unhandled

m:annotation-content — Mode for the content of annotations.

Mode:

{http://docbook.org/ns/docbook/modes}annotation-content

Defined in:

modules/annotations.xsl

Description

Annotations, like footnotes, have markers and wrappers that are necessary to support their presentation. The m:annotation-content mode is used to process the actual body of the annotation.

m:ansi — Mode for processing funcsynopsis elements in the “ANSI” style.

Mode:

{http://docbook.org/ns/docbook/modes}ansi

Defined in:

modules/programming.xsl (14)

Description

The funcsynopsis element has several possible renderings. This mode is used when the “ANSI” style of rendering has been selected and a non-tabular layout is being used.

See also: m:ansi-table, m:kr, m:kr-table, $funcsynopsis-default-style, $funcsynopsis-table-threshold, and $funcsynopsis-trailing-punctuation.

m:ansi-table — Mode for processing funcsynopsis elements in the “ANSI” style.

Mode:

{http://docbook.org/ns/docbook/modes}ansi-table

Defined in:

modules/programming.xsl (14)

Description

The funcsynopsis element has several possible renderings. This mode is used when the “ANSI” style of rendering has been selected and a table will be used for layout.

See also: m:ansi, m:kr, m:kr-table, $funcsynopsis-default-style, $funcsynopsis-table-threshold, and $funcsynopsis-trailing-punctuation.

m:attributes — Mode for processing attributes.

Mode:

{http://docbook.org/ns/docbook/modes}attributes

Defined in:

modules/attributes.xsl (32)

Description

Each DocBook element in the source document produces a primary HTML element in the result document. The attributes associated with that primary element are obtained by processing the DocBook element in the m:attributes mode.

m:back-cover — Mode for processing the back cover of books and sets.

Mode:

{http://docbook.org/ns/docbook/modes}back-cover

Defined in:

modules/divisions.xsl

Since:

2.1.4

Description

When a book or set is transformed, it is processed in the m:back-cover mode to generate a back cover. This processing occurs at the end of the transformation; any content generated by the back cover template will occur at the end of the document.

The default processing in this mode is to do nothing, no back cover is generated. An example of what you might put in your customization layer is:

1 |<xsl:template match="*" mode="m:back-cover">
  |  <section class="back-cover">
  |    <xsl:if test="not($output-media = 'print')">
  |      <xsl:attribute name="db-chunk" select="'back-cover' || $html-extension"/>
5 |      <xsl:attribute name="db-navigable" select="'true'"/>
  |    </xsl:if>
  |    <!-- Contents of back cover goes here -->
  |  </section>
  |</xsl:template>

The context item for this template is the book or set being processed. One approach is to put the additional material needed for the back cover (author biographies, images, etc.) in the info element of the book or set. These can then be formatted for the back cover.

For print covers, you are likely to need additional CSS styling. For chunked output, the cover will be the “next” link from what would otherwise be the last chunk of the document if the db-navigable attribute is true. If the db-navigable attribute is not true, some other link to the cover must be provided.

m:biblio690 — Mode for processing ISO 690 biblioentry bibliographic entries.

Mode:

{http://docbook.org/ns/docbook/modes}biblio690

Defined in:

modules/biblio690.xsl (33)

Since:

2.0.1

Description

DocBook bibliographic entries come in two forms: raw and cooked. The biblioentry form is the “raw” form. When the $bibliography-style parameter is “iso690”, this mode is used to process biblioentry elements.

m:biblioentry — Mode for processing biblioentry bibliographic entries.

Mode:

{http://docbook.org/ns/docbook/modes}biblioentry

Defined in:

modules/bibliography.xsl (11)

Description

DocBook bibliographic entries come in two forms: raw and cooked. The biblioentry form is the “raw” form. The m:biblioentry mode is used to process these elements.

m:bibliomixed — Mode for processing bibliomixed bibliographic entries.

Mode:

{http://docbook.org/ns/docbook/modes}bibliomixed

Defined in:

modules/bibliography.xsl (7)

Description

DocBook bibliographic entries come in two forms: raw and cooked. The bibliomixed form is the “cooked” form. The m:bibliomixed mode is used to process these elements.

m:callout-bug — Mode for producing callout marks.

Mode:

{http://docbook.org/ns/docbook/modes}callout-bug

Defined in:

modules/verbatim.xsl (3)

Description

Callouts are processed in this mode to produce the callout marks (or “bugs”) used to indicate cross references between the callouts and their corresponding areas. This mode should only produce the mark, for example “①”. See m:callout-link.

By default, callouts are numbered sequentially from 1 within each listing. However, a db processing instruction placed in the areaspec can specify a different starting number. If the starting-callout-number pseudo-attribute is an integer, that’s used as the starting number. If it has the special value “continues”, then numbering continues sequentially after the last callout number used in the preceding verbatim listing.

m:callout-link — Mode for producing callout links.

Mode:

{http://docbook.org/ns/docbook/modes}callout-link

Defined in:

modules/lists.xsl (2)

Description

Callouts in a calloutlist can link back to the corresponding point in the listing or on the image. This mode is used to produce those links.

m:chunk-cleanup — Post-process HTML chunks.

Mode:

{http://docbook.org/ns/docbook/modes}chunk-cleanup

Defined in:

modules/chunk-cleanup.xsl (16)

Description

Every HTML chunk is processed with the m:chunk-cleanup mode. This mode makes sure that footnotes and annotations appear in the chunks where their references appear, adds navigation to the top and bottom of each chunk, etc. See Section 2.7, ““Chunked” output”.

m:chunk-filename — Selects the chunk filename.

Mode:

{http://docbook.org/ns/docbook/modes}chunk-filename

Defined in:

modules/chunk.xsl (19)

Description

Every element that is identified as a chunk, see Section 2.7, ““Chunked” output”, will be called in the m:chunk-filename mode to obtain the filename for that chunk.

m:chunk-output — Performs the final-pass of processing on chunks.

Mode:

{http://docbook.org/ns/docbook/modes}chunk-output

Defined in:

modules/chunk-output.xsl (7)

Description

Chunks (see Section 2.7, ““Chunked” output”) are constructed in several passes. The last pass is in the m:chunk-output mode. This mode makes last minute adjustments and produces the individual chunk documents.

m:chunk-title — Generates the page title for the chunk.

Mode:

{http://docbook.org/ns/docbook/modes}chunk-title

Defined in:

modules/chunk-cleanup.xsl (4)

Description

The page title, the title in the HTML head, is generated by processing the heading in this mode. This mode is responsible for removing markup from the title.

m:chunk-write — Create result documents for chunks.

Mode:

{http://docbook.org/ns/docbook/modes}chunk-write

Defined in:

docbook.xsl

Description

When all of the chunk processing is finished, each chunk is processed in m:chunk-write mode. By default, this mode creates XSL result documents for each chunk.

m:copyright-years — Mode for processing copyright years.

Mode:

{http://docbook.org/ns/docbook/modes}copyright-years

Defined in:

modules/info.xsl

Description

The year elements in a copyright are processed in this mode. This mode handles the separation (and possible collapsing) of years.

See also $copyright-year-range-separator and $copyright-year-separator, and $copyright-collapse-years.

m:crossref — Produce a cross-reference to the element.

Mode:

{http://docbook.org/ns/docbook/modes}crossref

Defined in:

modules/xref.xsl

Description

The m:crossref mode is used to generate a cross-reference.

m:crossref-inherit-separator — Produce the inherit separator.

Obsolete as of version 2.0.0.

Description

Separators are now part of the generated text template, see Chapter 4, Localization.

m:crossref-label — Produce the label in a cross-reference.

Mode:

{http://docbook.org/ns/docbook/modes}crossref-label

Defined in:

modules/xref.xsl (9)

Description

The m:crossref-label mode is used to generate the label in a cross-reference.

m:crossref-label-separator — Produce the cross-reference label separator.

Obsolete as of version 2.0.0.

Description

Separators are now part of the generated text template, see Chapter 4, Localization.

m:crossref-number — Produce the number in a cross-reference.

Mode:

{http://docbook.org/ns/docbook/modes}crossref-number

Defined in:

modules/xref.xsl

Description

The m:crossref-number mode is used to generate the number in a cross-reference.

m:crossref-number-separator — Produce the cross-reference number separator.

Mode:

{http://docbook.org/ns/docbook/modes}crossref-number-separator

Defined in:

modules/xref.xsl

Description

The m:crossref-number-separator mode is used to generate the separator between a number and what follows it in a cross-reference.

m:crossref-prefix — Produce the cross-reference prefix.

Obsolete as of version 2.0.0.

Description

Prefixes are now part of the generated text template, see Chapter 4, Localization.

m:crossref-suffix — Produce the cross-reference suffix.

Mode:

{http://docbook.org/ns/docbook/modes}crossref-suffix

Defined in:

modules/xref.xsl

Description

The m:crossref-suffix mode is used to generate any text that follows a cross reference.

m:crossref-title — Produce the title in a cross-reference.

Mode:

{http://docbook.org/ns/docbook/modes}crossref-title

Defined in:

modules/xref.xsl (6)

Description

The m:crossref-title mode formats the title in a cross-reference.

m:details — Produce details about a media object.

Mode:

{http://docbook.org/ns/docbook/modes}details

Defined in:

modules/objects.xsl (2)

Description

This mode is used to produce the details about a media object, such as a long description.

m:details-attribute — Produce the short summary for a media object.

Obsolete as of version 2.0.17.

Description

This mode is used to produce a short detail summary about a media object. This is most often used as the alt text for the object.

m:docbook — The primary mode for processing DocBook elements.

Mode:

{http://docbook.org/ns/docbook/modes}docbook

Defined in:

main.xsl (2), modules/admonitions.xsl, modules/annotations.xsl (2), modules/attributes.xsl (4), modules/bibliography.xsl (6), modules/blocks.xsl (19), modules/components.xsl, modules/divisions.xsl, modules/footnotes.xsl (3), modules/glossary.xsl (11), modules/index.xsl (14), modules/info.xsl (16), modules/inlines.xsl (103), modules/l10n.xsl, modules/links.xsl (6), modules/lists.xsl (23), modules/msgset.xsl (7), modules/objects.xsl (13), modules/programming.xsl (24), modules/publishers.xsl (3), modules/refentry.xsl (11), modules/sections.xsl (2), modules/tablecals.xsl (9), modules/tablehtml.xsl (4), modules/templates.xsl, modules/titles.xsl, modules/toc.xsl (9), modules/unhandled.xsl (2), modules/verbatim.xsl (7), modules/xlink.xsl (4), modules/xref.xsl

Description

The m:docbook mode is the primary mode for processing DocBook elements. Critically, this means that if you import the DocBook stylesheets and wish to override some of the templates, you must make sure that those templates are defined in the m:docbook mode.

m:footnote-number — Mode for generating footnote numbers.

Mode:

{http://docbook.org/ns/docbook/modes}footnote-number

Defined in:

modules/chunk-cleanup.xsl, modules/footnotes.xsl

Description

A footnote processed in m:footnote-number mode renders the footnote number (or other symbol) associated with that footnote.

m:footnotes — Mode for processing footnotes.

Mode:

{http://docbook.org/ns/docbook/modes}footnotes

Defined in:

modules/footnotes.xsl

Description

Perhaps unsurprisingly, footnote elements are processed in m:footnotes. On the first pass, they’re rendered inline with appropriate footnote markers. The “chunk cleanup” pass moves them to an appropriate location.

m:generate-titlepage — Generate a title page.

Mode:

{http://docbook.org/ns/docbook/modes}generate-titlepage

Defined in:

modules/templates.xsl

Description

All “block” elements that have a title (or another feature that constitutes a title) are processed in the m:generate-titlepage mode to generate their “title page”. Don’t be mislead by the term “title page”. For many elements, the title page consists of nothing more than a single header element.

m:gentext — Generate localization-specific text for an element.

Mode:

{http://docbook.org/ns/docbook/modes}gentext

Defined in:

modules/gentext.xsl (2)

Since:

2.0.0

Description

This mode is used to generate text by applying the appropriate locale-specific template, see Chapter 4, Localization. When you apply templates in this mode, there are three parameters you can pass:

group (required)

This identifies the localization group.

key

This identifies the localization key. If not provided, the local name of the context item is used.

content

The content of the element. If not provided, the empty sequence is used.

For example, in the context of a book containing several chapters,

1 |<xsl:apply-templates select="db:chapter[1]" mode="m:gentext">
  |  <xsl:with-param name="group" select="'title'"/>
  |  <xsl:with-param name="content">
  |    <xsl:apply-templates select="db:chapter[1]/db:info/db:title/node()"/>
5 |  </xsl:with-param>
  |</xsl:apply-templates>

Would generate something like Chapter 1 The Title.

Lists are generated with the m:gentext-list mode.

m:gentext-list — Generate localization-specific list for a sequence.

Mode:

{http://docbook.org/ns/docbook/modes}gentext-list

Defined in:

modules/l10n.xsl

Since:

2.0.0

Description

This mode is used to generate a list with local-specific separators, see Chapter 4, Localization. When you apply templates in this mode, there are two parameters you can pass:

list (required)

A sequence of one or more items.

name

This identifies the localization key. If not provided, the local name of the context item is used.

For example, in the context of an authorgroup,

1 |<xsl:apply-templates select="." mode="m:gentext-list">
  |  <xsl:with-param name="list" as="item()+">
  |    <xsl:apply-templates select="*"/>
  |  </xsl:with-param>
5 |</xsl:apply-templates>

Would generate different markup depending on the number of authors. For example, in the English localization, it would generate:

Author Name

for a single author

Author Name and Second Author

for two authors

Author Name, Second Author, and Third Author

for three authors

Author Name, Second Author, Third Author, and Fourth Author

for four authors

And so on.

Generated text not associated with lists is generated with the m:gentext mode.

m:head-additions — Additional head items.

Mode:

{http://docbook.org/ns/docbook/modes}head-additions

Defined in:

modules/head.xsl

Description

This mode can be used by a customization layer to add additional items to the HTML head element.

m:headline — Produce a headline title.

Mode:

{http://docbook.org/ns/docbook/modes}headline

Defined in:

modules/titles.xsl

Description

This mode produces the “headline” title for an element. This generally appears in the text where the element is formatted, but may also occur in the table of contents, the index, and other places.

m:headline-label — Produce the label for a headline title.

Mode:

{http://docbook.org/ns/docbook/modes}headline-label

Defined in:

modules/titles.xsl (5)

Description

The m:headline-label mode is used to generate the label in a headline.

m:headline-label-separator — Produce the headline label separator.

Obsolete as of version 2.0.0.

Description

Separators are now part of the generated text template, see Chapter 4, Localization.

m:headline-number — Produce the headline number.

Mode:

{http://docbook.org/ns/docbook/modes}headline-number

Defined in:

modules/titles.xsl (10)

Description

The m:headline-number mode is used to generate the number in a headline.

m:headline-number-separator — Produce the headline number separator.

Obsolete as of version 2.0.0.

Description

Separators are now part of the generated text template, see Chapter 4, Localization.

m:headline-prefix — Generate the headline prefix.

Obsolete as of version 2.0.0.

Description

Prefix text is now part of the generated text template, see Chapter 4, Localization.

m:headline-suffix — Produce the headline suffix.

Obsolete as of version 2.0.0.

Description

Suffix text is now part of the generated text template, see Chapter 4, Localization.

m:headline-title — Produce the headline title.

Mode:

{http://docbook.org/ns/docbook/modes}headline-title

Defined in:

modules/titles.xsl (6)

Description

The m:headline-title mode is used to format the title element in a headline.

m:highlight-options — Determine the syntax highlighting options for an element.

Mode:

{http://docbook.org/ns/docbook/modes}highlight-options

Defined in:

modules/verbatim.xsl

Description

A verbatim element that will be syntax highlighted is processed in this mode to determine the options for the syntax highlighter. The template must return a map. The default template returns the language attribute if one is present.

m:html-body-script — Add script elements to the end of a document.

Mode:

{http://docbook.org/ns/docbook/modes}html-body-script

Defined in:

modules/head.xsl

Deprecated since:

2.1.0

Deprecated

The technique described here is no longer necessary. Modern browsers accept a defer attribute on the script tag to explicitly specify when scripts are to execute.

Description

One way to assure that JavaScript will only be invoked by the user agent after the DOM tree has been constructed is to put the script elements for that code at the end of the file.

The root element of each result document is formatted once in the m:html-body-script mode. Any elements constructed in this mode will be added to the end of the HTML body. The built-in implementation does nothing; this mode exists as an extensibility point. See also m:html-head-script.

m:html-head — Construct the HTML head element.

Mode:

{http://docbook.org/ns/docbook/modes}html-head

Defined in:

modules/head.xsl (5)

Description

The m:html-head mode is used to produce the head element. This should include all of the metadata, links, scripts, etc. necessary to render the document correctly.

It is not supposed to be necessary to override this template. You can customize what is produced with the m:html-head-script, m:html-head-links, and m:html-head-last modes.

The order of elements produced in the head is:

Elements generated by the stylesheets automatically (title, scripts, links, and other elements).

Elements generated in m:html-head-script mode.

Elements generated in m:html-head-links mode.

Elements in the HTML namespace that are in the source document’s info.

Elements generated in m:html-head-last mode.

In addition, elements generated in m:html-body-script occur near the end of the HTML body element.

m:html-head-last — Add elements to the end of the head of a document.

Mode:

{http://docbook.org/ns/docbook/modes}html-head-last

Defined in:

modules/head.xsl

Description

Any elements constructed in m:html-head-last mode will be added to the very end of the HTML head element. The built-in implementation does nothing; this mode exists as an extensibility point.

m:html-head-links — Add link elements to the head of a document.

Mode:

{http://docbook.org/ns/docbook/modes}html-head-links

Defined in:

modules/head.xsl

Description

Any elements constructed in m:html-head-links mode will be added to the HTML head element. The built-in implementation does nothing; this mode exists as an extensibility point.

m:html-head-script — Add link elements to the head of a document.

Mode:

{http://docbook.org/ns/docbook/modes}html-head-script

Defined in:

modules/head.xsl

Description

Any elements constructed in m:html-head-script mode will be added to the HTML head element. The built-in implementation does nothing; this mode exists as an extensibility point.

m:htmltable — Mode for processing HTML table elements.

Mode:

{http://docbook.org/ns/docbook/modes}htmltable

Defined in:

modules/tablehtml.xsl (2)

Description

Where DocBook uses the HTML table model, it copies the definitions of the table elements (and the attributes on those elements) from HTML. The m:htmltable mode simply copies those elements and attributes to the result. When processing the contents of table cells, processing switches back to m:docbook mode.

m:imagemap — Construct an HTML imagemap.

Mode:

{http://docbook.org/ns/docbook/modes}imagemap

Defined in:

modules/objects.xsl

Description

The imageobjectco element is processed in this mode to construct an HTML image map.

m:index-div — Mode for generating divisions in an index.

Mode:

{http://docbook.org/ns/docbook/modes}index-div

Defined in:

modules/index.xsl

Description

Index processing, that is, the process of generating an index, involves collecting all of the indexterms together, collating them, and rendering them.

The terms are grouped alphabetically and each group is processed in the m:index-div mode.

m:index-primary — Mode for generating primary index entries.

Mode:

{http://docbook.org/ns/docbook/modes}index-primary

Defined in:

modules/index.xsl

Description

When generating an index, each distinct indexterm is processed in m:index-primary mode to output its primary entry.

m:index-secondary — Mode for generating secondary index entries.

Mode:

{http://docbook.org/ns/docbook/modes}index-secondary

Defined in:

modules/index.xsl

Description

When generating an index, each distinct secondary indexterm is processed in m:index-secondary mode to output its secondary entry.

m:index-see — Mode for generating index “see” entries.

Mode:

{http://docbook.org/ns/docbook/modes}index-see

Defined in:

modules/index.xsl

Description

When generating an index, each indexterm that defines a “see” index cross-reference is processed in m:index-see mode to output the cross-reference.

m:index-seealso — Mode for generating index “see also” entries.

Mode:

{http://docbook.org/ns/docbook/modes}index-seealso

Defined in:

modules/index.xsl

Description

When generating an index, each indexterm that defines a “see also” index cross-reference is processed in m:index-seealso mode to output the cross-reference.

m:index-tertiary — Mode for generating index tertiary entries.

Mode:

{http://docbook.org/ns/docbook/modes}index-tertiary

Defined in:

modules/index.xsl

Description

When generating an index, each distinct tertiary indexterm is processed in m:index-tertiary mode to output its tertiary entry.

m:kr — Mode for processing funcsynopsis elements in the “K&R” style.

Mode:

{http://docbook.org/ns/docbook/modes}kr

Defined in:

modules/programming.xsl (14)

Description

The funcsynopsis element has several possible renderings. This mode is used when the “K&R” style of rendering has been selected and a non-tabular layout is being used.

See also: m:kr-table, m:ansi, m:ansi-table, $funcsynopsis-default-style, $funcsynopsis-table-threshold, and $funcsynopsis-trailing-punctuation.

m:kr-args — Mode for processing function arguments.

Mode:

{http://docbook.org/ns/docbook/modes}kr-args

Defined in:

modules/programming.xsl (7)

Description

This mode is used to process the parameters of a funcsynopsis in th K&R style. See $funcsynopsis-default-style.

m:kr-table — Mode for processing funcsynopsis elements in the “K&R” style.

Mode:

{http://docbook.org/ns/docbook/modes}kr-table

Defined in:

modules/programming.xsl (14)

Description

The funcsynopsis element has several possible renderings. This mode is used when the “K&R” style of rendering has been selected and a table will be used for layout.

See also: m:kr, m:ansi, m:ansi-table, $funcsynopsis-default-style, $funcsynopsis-table-threshold, and $funcsynopsis-trailing-punctuation.

m:kr-table-args — Mode for processing function arguments in a table.

Mode:

{http://docbook.org/ns/docbook/modes}kr-table-args

Defined in:

modules/programming.xsl (7)

Description

When the tabular presentation of a “K&R” funcsynopsis is being generated, this mode is used to process the function arguments.

m:link — Process inline links.

Mode:

{http://docbook.org/ns/docbook/modes}link

Defined in:

modules/links.xsl (3)

Description

DocBook allows xlink:href to appear on most elements. All inline elements are processed in m:link mode to add a link around them if they specify an xlink:href.

m:list-of-equations — Mode for generating a list of equations.

Mode:

{http://docbook.org/ns/docbook/modes}list-of-equations

Defined in:

modules/toc.xsl

Description

If $lists-of-equations is true, then a list of equations will be generated. This mode is used to process the equation elements (if any) to produce that list.

m:list-of-examples — Mode for generating a list of examples.

Mode:

{http://docbook.org/ns/docbook/modes}list-of-examples

Defined in:

modules/toc.xsl

Description

If $lists-of-examples is true, then a list of examples will be generated. This mode is used to process the example elements (if any) to produce that list.

m:list-of-figures — Mode for generating a list of figures.

Mode:

{http://docbook.org/ns/docbook/modes}list-of-figures

Defined in:

modules/toc.xsl

Description

If $lists-of-figures is true, then a list of figures will be generated. This mode is used to process the figure elements (if any) to produce that list.

m:list-of-procedures — Mode for generating a list of procedures.

Mode:

{http://docbook.org/ns/docbook/modes}list-of-procedures

Defined in:

modules/toc.xsl

Description

If $lists-of-procedures is true, then a list of procedures will be generated. This mode is used to process the procedure elements (if any) to produce that list.

m:list-of-tables — Mode for generating a list of tables.

Mode:

{http://docbook.org/ns/docbook/modes}list-of-tables

Defined in:

modules/toc.xsl

Description

If $lists-of-tables is true, then a list of tables will be generated. This mode is used to process the table elements (if any) to produce that list.

m:list-of-titles — Mode for generating a list-of-titles.

Mode:

{http://docbook.org/ns/docbook/modes}list-of-titles

Defined in:

modules/toc.xsl

Since:

2.0.0

Description

When a list of titles (figures, tables, equations, etc.) is created, each element is processed in this mode to produce the list item that will appear in the list.

m:mediaobject-end — Process the end of media objects.

Mode:

{http://docbook.org/ns/docbook/modes}mediaobject-end

Defined in:

modules/objects.xsl (3)

Description

Media objects (both the mediaobject and inlinemediaobject containers as well as the imageobjects etc. inside them) are processed in this mode after the primary content has been rendered.

For mediaobject, this mode is responsible for outputting the caption, but may also be used to output accessibility details, legal notices, etc. See also m:mediaobject-start.

m:mediaobject-info — Compute properties for a media object.

Mode:

{http://docbook.org/ns/docbook/modes}mediaobject-info

Defined in:

modules/objects.xsl (4)

Description

The media object elements are processed in this mode to extract their properties (input and output URIs, content types, etc.). See Section 5.4, “Processing mediaobjects”.

m:mediaobject-output-adjust — Adjust the URI references to media objects.

Mode:

{http://docbook.org/ns/docbook/modes}mediaobject-output-adjust

Defined in:

modules/chunk-cleanup.xsl

Description

Once the stylesheets have used the $mediaobject-input-base-uri, $mediaobject-output-base-uri, and $mediaobject-output-paths to compute the URI of a media reference, the reference is processed in m:mediaobject-output-adjust mode. This is the stylesheet’s opportunity to make any final adjustments.

The context item for the template will be the attribute that contains the author’s original value. The adjusted value is passed in as the $adjusted-uri parameter. The value returned by the template is used in the HTML.

Here is an example that groups images, audio, and video files in their own directories:

 1 |<xsl:template match="@*" mode="m:mediaobject-output-adjust">
   |  <xsl:param name="adjusted-uri" as="xs:string"/>
   |
   |  <xsl:choose>
 5 |    <xsl:when test="exists(f:uri-scheme(.))">
   |      <!-- Don't mess with absolute URIs... -->
   |      <xsl:sequence select="$adjusted-uri"/>
   |    </xsl:when>
   |    <xsl:otherwise>
10 |      <xsl:variable name="type" as="xs:string">
   |        <xsl:choose>
   |          <xsl:when test="../self::h:img">image</xsl:when>
   |          <xsl:when test="ancestor::h:video">video</xsl:when>
   |          <xsl:when test="ancestor::h:audio">audio</xsl:when>
15 |          <xsl:otherwise>
   |            <xsl:sequence select="'media-cleanup-err'"/>
   |          </xsl:otherwise>
   |        </xsl:choose>
   |      </xsl:variable>
20 |
   |      <xsl:variable name="parts" select="tokenize($adjusted-uri, '/')"/>
   |      <xsl:sequence select="string-join($parts[position() lt last()], '/')
   |                            || (if (count($parts) gt 1) then '/' else '')
   |                            || $type || '/'
25 |                            || $parts[position() eq last()]"/>
   |    </xsl:otherwise>
   |  </xsl:choose>
   |</xsl:template>

In other words, if the adjusted URI for an image is path/to/somewhere.png, this template will return path/to/image/somewhere.png and make similar adjustments to the audio and video paths.

m:mediaobject-start — Process the start of media objects.

Mode:

{http://docbook.org/ns/docbook/modes}mediaobject-start

Defined in:

modules/objects.xsl (4)

Description

Media objects (both the mediaobject and inlinemediaobject containers as well as the imageobjects etc. inside them) are processed in this mode immediately after the start tag. Templates in this mode can output attributes, such as summary or alt, as well as additional accessibility elements; it may also be used to output legal notices, etc. that should precede the primary content.

If the $mediaobject-accessibility parameter includes a11y-metadata then any short accessibility summary will be output in a meta element with the property value a11y:accessibilitySummary. In addition, any meta elements in the info will be processed in this mode as well (so they can also be output using accessibility meta properties. See also m:mediaobject-end.

m:mediaobject-uris — Compute URIs for media objects.

Mode:

{http://docbook.org/ns/docbook/modes}mediaobject-uris

Defined in:

modules/objects.xsl

Description

The media object elements are processed in this mode to extract their input and output URIs.

m:panelset — Process variable list elements for a panel set.

Mode:

{http://docbook.org/ns/docbook/modes}panelset

Defined in:

modules/lists.xsl (3)

Since:

2.2.2

Description

When variablelist elements are processed for a $variablelist-panelset, they are processed in this mode. This mode makes it possible to override the templates for selected elements. Be aware, however, that the HTML markup is quite constrained for panel sets.

m:persistent-toc — Mode for generating the persistent table of contents.

Mode:

{http://docbook.org/ns/docbook/modes}persistent-toc

Defined in:

modules/toc.xsl (3)

Since:

2.0.0

Description

If $persistent-toc is true, the document will be processed in this mode to produce the contents of the persistent ToC. By default, this produces the same ToC as the m:toc mode.

m:production-number — Mode for production numbers.

Mode:

{http://docbook.org/ns/docbook/modes}production-number

Defined in:

modules/programming.xsl

Description

When a productionset is being formatted, the m:production-number mode is used to produce the prodution numbers.

m:pygments-options — Calculate the Pygments options for an element.

Mode:

{http://docbook.org/ns/docbook/modes}pygments-options

Defined in:

modules/verbatim.xsl

Description

When the Pygments syntax highlighter is being used, every element that will be highlighted is processed in this mode to generate options for the Pygments process.

m:revhistory-list — Mode to generate a “list” presentation of revhistory.

Mode:

{http://docbook.org/ns/docbook/modes}revhistory-list

Defined in:

modules/blocks.xsl

Description

The revhistory element can be rendered as a list or a table (see $revhistory-style). The m:revhistory-list mode is used to render it as a list.

m:revhistory-table — Mode to generate a “table” presentation of revhistory.

Mode:

{http://docbook.org/ns/docbook/modes}revhistory-table

Defined in:

modules/blocks.xsl

Description

The revhistory element can be rendered as a list or a table (see $revhistory-style). The m:revhistory-table mode is used to render it as a list.

m:seglist-table — Process a segmentedlist as a table.

Mode:

{http://docbook.org/ns/docbook/modes}seglist-table

Defined in:

modules/lists.xsl (4)

Description

Segmented lists can be presented in either a list format or a table format. If the tabular format is selected, the segmentedlist is processed in this mode to generate the table.

m:segtitle-in-seg — Mode for processing segment titles in a segment.

Mode:

{http://docbook.org/ns/docbook/modes}segtitle-in-seg

Defined in:

modules/lists.xsl

Description

In a segmentedlist, each segtitle is processed once for each segment. This processing occurs in the m:segtitle-in-seg mode.

m:synopfragment-bug — Mode for generating the mark for a synopfragementref.

Mode:

{http://docbook.org/ns/docbook/modes}synopfragment-bug

Defined in:

modules/programming.xsl

Description

The synopfragment element allows a synopsis (for example a cmdsynopsis) to move common fragments out-of-line. The location where these fragments occur in the primary synopsis is indicated with a synopfragmentref. The stylesheets will generate a mark, analogous to the marks used for footnotes or callouts, to connect the reference to the fragment. The fragment will be processed in m:synopfragment-bug to produce that mark.

m:synopsis — Mode for processing programming language synopses.

Mode:

{http://docbook.org/ns/docbook/modes}synopsis

Defined in:

modules/programming.xsl (10)

Description

The elements of class, method, and field synopses are processed in this mode.

m:title — Format a title.

Mode:

{http://docbook.org/ns/docbook/modes}title

Defined in:

modules/titles.xsl

Description

This mode is used to format titles when they appear in headlines or cross references.

m:titlepage — Format elements for the title page.

Mode:

{http://docbook.org/ns/docbook/modes}titlepage

Defined in:

modules/titlepage.xsl (9)

Description

Elements that appear on the title page are processed in this mode to produce the text that will appear on the title page.

m:to-uppercase — Produce content in upper-case.

Mode:

{http://docbook.org/ns/docbook/modes}to-uppercase

Defined in:

modules/info.xsl (4)

Description

When formatting personal names in a style that requires converting a name to upper case (see t:person-name), this mode is used to generate the upper-case name.

m:toc — Mode for generating lists of titles (e.g, the table of contents)

Mode:

{http://docbook.org/ns/docbook/modes}toc

Defined in:

modules/blocks.xsl (4), modules/toc.xsl (2)

Description

Elements are processed in m:toc when automatically constructing a Table of Contents (or, more generally, any list of titles).

Where a generated list of titles appears is controlled by several parameters. For manual control, place an empty toc element where you would like it to appear. If the toc element is not valid where you would like the list to appear, use the db-toc processing instruction instead. These must appear as the direct children of the element for which the list is being constructed.

See also $generate-toc, $generate-nested-toc, $annotate-toc, $lists-of-figures, $lists-of-tables, $lists-of-examples, $lists-of-equations, $lists-of-procedures, and $section-toc-depth.

m:toc-entry — Format content for a list-of-titles.

Mode:

{http://docbook.org/ns/docbook/modes}toc-entry

Defined in:

modules/toc.xsl (6)

Description

When an element appears in the Table of Contents (or other list of titles), it is formatted in this mode to produce the entry in the list.

m:toc-nested — What elements are “nested” in a Table of Contents.

Mode:

{http://docbook.org/ns/docbook/modes}toc-nested

Defined in:

modules/toc.xsl (4)

Since:

2.0.0

Description

The elements processed in the m:toc mode determine where a Table of Contents will appear. When a Table of Contents does appear, the children of the starting element are processed in the m:toc-nested mode to determine which of them appear. This mode, for example, handles the maximum nesting depth of sections in the ToC.

m:unhandled — Process unhandled elements.

Mode:

{http://docbook.org/ns/docbook/modes}unhandled

Description

When $on-unhandled-elements is set to custom, elements with no other matching template will be processed in this mode. Note that there are no templates in this mode in the standard stylesheets. This is an extensibility point for customization layers.

VI. Processing instruction reference

Table of Contents

DocBook-xslTNG-version

current-dateTime

db

system-property

DocBook-xslTNG-version — Resolves to the DocBook stylesheet version.

Processing instruction:

DocBook-xslTNG-version

Description

The DocBook-xslTNG-version processing instruction will be replaced by the version number of the stylesheets.

For example:

<para>This document was formatted with the <citetitle>DocBook
xslTNG Stylesheets</citetitle>
version <?DocBook-xslTNG-version?>.</para>

Will render like this:

This document was formatted with the DocBook xslTNG Stylesheets version 2.8.0.

current-dateTime — Resolves to a formatted date/time string.

Processing instruction:

current-dateTime

Description

The current-dateTime processing instruction will be replaced by a formatted date and time. The date and time is controlled by three pseudo-attributes:

dateTime

The ISO 8601 date or date/time to format. If not specified, defaults to the current date/time. If a date (and not a date/time) is specified, a default time of noon is assumed.

offset

An ISO 8601 day/time duration or year/month duration. This value will be added to the dateTime that is to be formatted.

format

The format string to use. If not specified, the $date-dateTime-format is used.

For example:

<para>Published on
<?current-dateTime format="[F]"?>.</para>

Will render like this:

Published on Sunday.

db — Provides additional control over rendering.

Processing instruction:

db

Description

The db processing instruction provides additional control over the rendering of a number of elements. It doesn’t produce any output directly.

See also:

$align-char-*

$bibliography-style

$glossary-automatic-divisions

$glossary-collection

$mediaobject-video-element

$oxy-markup

$revhistory-style

$segmentedlist-style

$xlink-style

f:available-bibliographies

f:available-glossaries

f:chunk-filename

f:date-format

f:global-syntax-highlighter

f:pi

f:pi-attributes

f:verbatim-callout

f:verbatim-numbered

f:verbatim-style

f:verbatim-syntax-highlighter

f:verbatim-trim-leading

f:verbatim-trim-trailing

t:generate-index

m:callout-bug

system-property — Resolves to an XSLT system property.

Processing instruction:

system-property

Description

The system-property processing instruction will be replaced by the corresponding system property.

For example:

<para>This document was formatted with
<?system-property xsl:product-name?>
version <?system-property xsl:product-version?> on
<?current-dateTime format="[D01] [MNn,*-3] [Y0001]"?>.
</para>

Will render like this:

This document was formatted with SAXON version HE 12.9 on 26 Apr 2026.

Appendix B. GNU Free Documentation License

                   Version 1.1, March 2000

 Copyright (C) 2000  Free Software Foundation, Inc.
     51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

3. COPYING IN QUANTITY

If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.

List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).

State on the Title page the name of the publisher of the Modified Version, as the publisher.

Preserve all the copyright notices of the Document.

Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.

Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.

Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.

Include an unaltered copy of this License.

Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.

Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.

In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.

Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.

Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.

Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."

6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

8. TRANSLATION

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

Copyright (c)  YEAR  YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
A copy of the license is included in the section entitled "GNU
Free Documentation License".

If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

Copyright

DocBook xslTNG
Copyright © 2020–2026 Norman Walsh.
All Rights Reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation. A copy of the license is included in Appendix B, GNU Free Documentation License.

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book and the authors were aware of a trademark claim, the designations have been printed in caps or initial caps.

While every precaution has been taken in the preparation of this book, the publisher and author assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.