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

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

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:

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

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