DocBook XML Environment for Windows

Dr. Berndt E. Schwerdtfeger

First published 2004-07-19

Revision History
Revision 158 2011-04-28
updated to FOP version 1.0
Revision 1.0 2004-07-19
initial draft

Table of Contents

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

This article describes how to install a documentation system based on DocBook 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. Updated versions have been published in 2005 and 2007, the revision history has been shortend. The document is now under subversion control.

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 Java from the Free Java Download site at Oracle .

Formatting process

The same source document written in DocBook 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 System based on XML

Packages needed

The following packages are required

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

The latest version of DocBook is 5.1. The release 5.0 was a complete rewrite in RELAX NG. In this paper I will continue to use DocBook V4.5 (released 2006-10-03). The DocBook stylesheets are at version 1.76.1 (released 2010-11-01). The stable release 1.0 of Apache FOP was released 2010-07-21.

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 4.5 zip archive.

The DocBook XSL stylesheets are located at Sourceforge docbook-xsl, download version 1.76.1.

The Apache FOP package

Locate the FOP package from the Apache XML project . You may download from an appropriate mirror, depending on your location.

For Germany you may for example access the FU Berlin ftp mirror, which is organized by projects. Download the FOP java version 1.0 binary zip archive.

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\docbook-xml-4.5
  • c:\xml\docbook-xsl-1.76.1
  • c:\xml\fop-1.0

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\jre6, and added c:\xml\fop-1.0; to PATH as well as c:\xml\fop-1.0\build;c:\xml\fop-1.0\lib to CLASSPATH.

FOP processing

HTML output

The generation of HTML output is performed by

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

pdf output

The generation of pdf output is performed by

fop -xml filename.xml -xsl \xml\docbook-xsl-1.76.1\fo\docbook.xsl -pdf filename.pdf [-param paper.type A4] [-param ulink.footnotes 1] [-param fop1.extensions 1]

The last three optional parameters set the paper size to A4 format, set the url references to footnotes and generate pdf bookmarks.

Makefile example

This is the listing of my makefile makefile to generate this very document

# makefile for building xdocenv
# $Date: 2011-04-29 13:25:54 +0200 (Fri, 29 Apr 2011) $ $Revision: 158 $

source = xdocenv.xml xdocgen.xml xdocins.xml xdocfop.xml

all : html pdf
install : all copy
copy :
       	cp xdocenv.pdf xdocenv.html \
       	c:/progra~1/apache~1/apache2.2/htdocs/doku/xdocenv
html : xdocenv.html
xdocenv.html : $(source)
       	fop -xml xdocenv.xml \
       	-xsl /xml/docbook-xsl-1.76.1/html/docbook.xsl \
       	-foout xdocenv.html
pdf : xdocenv.pdf
xdocenv.pdf : $(source)
       	fop -xml xdocenv.xml     \
       	-xsl /xml/docbook-xsl-1.76.1/fo/docbook.xsl \
       	-param paper.type A4     \
       	-param ulink.footnotes 1 \
       	-param fop1.extensions 1 \
       	-pdf xdocenv.pdf
.PHONY : clean
clean :
       	rm -f xdocenv.pdf xdocenv.html