DocBook 5 XML for Windows

Dr. Berndt E. Schwerdtfeger

Copyright © 2004-2019 Berndt E. Schwerdtfeger

First published 2004-07-19

Revision History
Revision 1.16 Date: 2020-01-24
updated to DocBook version 5.1 and FOP version 2.3
Revision 1.0 Date: 2004-07-19
initial version

Table of Contents

Introduction
Purpose
Assumptions and Prerequisites
Formatting process
Licenses
DocBook 5 System based on XML
Packages needed
Download the packages
Installing the packages
FOP processing
HTML output
pdf output

Summary

This article describes how to install a documentation system based on DocBook 5 XML on a Windows system.

Introduction

Purpose

In this paper I describe how to install a professional documentation system on a Windows platform, which is based on the DocBook and XML standards. I will not explain how to write DocBook XML source text. Instead you might want to look up the DocBook Wiki as a good source for books, tutorials and other DocBook documentation.

My goal is to describe the environment, including its installation and configuration, and give some examples of its usage.

This new revision reflects new releases of required packages and updates the hyperlinks to the Internet.

Assumptions and Prerequisites

I assume that you

  • want to use the XML variant of DocBook and the XSL stylesheets of DocBook
  • have a reasonably current Java Run Time environment installed

You can download the up-to-date version of the OpenSource Java Development Kit from OpenSource Java Development Kit .

Formatting process

The same source document written in DocBook 5 XML can be used to produce pdf or HTML output through the same formatting objects processor FOP. Internally this is done in two steps as a transformation and a formatting.

  1. the transformation uses DocBook stylesheets provided with DocBook.
  2. the formatting is only necessary to generate the pdf file.

Licenses

The necessary packages are available under the Apache License. The appropriate web sites for downloading these packages will be given below.

DocBook 5 System based on XML

Packages needed

The following packages are required

  • DocBook 5 in XML and stylesheets in XSL,
  • Apache FOP

The current version of DocBook 5 is 5.1 released 2016-11-22. The version 5.0 was a complete rewrite in RELAX NG. The DocBook stylesheets are at version 1.79.1 released 2018-07-13.

The current version of Apache FOP is 2.3 released 2018-05-18.

Download the packages

DocBook packages

The DocBook package for XML can be downloaded from the DocBook organisation at their DocBook XML download site. Download the DocBook 5.1 zip archive.

The DocBook XSL stylesheets are located at Sourceforge docbook-xsl, download the latest files (version 1.79.1 as of 2019-10-23).

The Apache FOP package

Locate the FOP package from the Apache FOP binaries.

Installing the packages

Install DocBook and FOP

Unpack the zip archives into some convenient place. On my system I have chosen the directories

  • c:\xml
  • c:\xml\xsl
  • c:\xml\fop-2.3

Configuring FOP

You need to do three things

  1. set the environment variable JAVA_HOME to the path pointing to your Java installation
  2. add the FOP directory to your PATH
  3. add the FOP java archive subdirectories to your CLASSPATH

On my system I have set JAVA_HOME=\PROGRA~1\Java\jdk-13.0.1, and added c:\xml\fop-2.3\fop to the PATH as well as c:\xml\fop-2.3\fop\build;c:\xml\fop-2.3\fop\lib to CLASSPATH.

FOP processing

HTML output

The generation of HTML output is performed by

fop -xml filename.xml -xsl \xml\xsl\html\docbook.xsl -foout filename.html

pdf output

The generation of pdf output is performed by

fop -c fop.xconf -param paper.type A4 -xml filename.xml -xsl \xml\xsl\fo\docbook.xsl -pdf filename.pdf

For A4 paper you set e.g. the page height="11.69in" and width="8.26in" in the FOP configuration file fop.xconf.