How DocBook XSL Transforms XML to HTML, PDF, and EPUB

DocBook XSL stylesheets provide a robust processing framework that converts semantic DocBook XML documents into diverse publishing formats, including single or chunked HTML, print-ready PDF, and reflowable EPUB e-books. By decoupling content semantics from presentation, these stylesheets parse the structured elements of a technical book—such as chapters, sections, code listings, and callouts—and map them to format-specific presentation structures via an XSLT processor.

The Transformation Pipeline

The transformation workflow relies on an XSLT processor (such as xsltproc or Saxon) that takes two primary inputs: the source DocBook XML document and a specific DocBook XSL stylesheet. The processor evaluates the XML source tree against predefined template rules in the stylesheet and generates the target output format.

Generating HTML

For web delivery, DocBook XSL provides stylesheets that convert XML elements directly into modern HTML or XHTML structures.

• Single-Page HTML (html/docbook.xsl): Translates the entire XML document into a single HTML file, suitable for short technical articles or documentation that benefits from continuous scrolling.
• Chunked HTML (html/chunk.xsl): Splits the document into multiple interlinked HTML pages based on structural boundaries, such as chapters or appendices. It automatically generates navigation controls (Next, Previous, Home) and a top-level table of contents.

During this process, semantic tags like <para> become <p>, <programlisting> becomes <pre class="programlisting">, and structural elements like <chapter> are wrapped in <section> or <div> tags with appropriate CSS classes.

Generating PDF via XSL-FO

DocBook XSL does not generate PDF files directly; instead, it uses a two-stage process mediated by XSL Formatting Objects (XSL-FO).

1. XML to XSL-FO (fo/docbook.xsl): The XSLT processor transforms the DocBook XML into an intermediate .fo file. This file contains precise instructions regarding page geometry, margins, running headers, footers, column layouts, hyphenation, and font properties.
2. FO to PDF: An FO processor (such as Apache FOP, Antenna House Formatter, or RenderX XEP) reads the intermediate .fo file, calculates page breaks and layout constraints, and compiles the final binary PDF file.

Generating EPUB

For digital readers, DocBook XSL provides specialized stylesheets (epub/docbook.xsl for EPUB 2 and epub3/chunk.xsl for EPUB 3) that automate the packaging requirements of the EPUB standard.

1. Content Generation: The stylesheet splits the source XML into individual, validated XHTML content documents for each chapter and section.
2. Manifest and Navigation: It automatically generates required metadata files, including the Open Packaging Format (content.opf) manifest, the table of contents navigation document, and the EPUB NCX file.
3. Packaging: The generated files, along with images and CSS stylesheets, are bundled and zipped into a standardized .epub container file adhering to Open Container Format specifications.

Customization Layer

All output formats share a common customization methodology. Developers write custom XSLT wrapper stylesheets (driver files) that import the standard DocBook XSL stylesheets and override specific template rules or configuration parameters. This allows publishers to adjust fonts, brand colors, page dimensions, table formatting, and numbering schemes across all formats while maintaining a single, format-agnostic XML source file.