DocBook 5 Install and Setup for Windows
It has been a long time since I used a system such as DocBook. When writing Pragmatic Augmented Reality I used the Pragmatic PML framework, which is essentially a simplified version of DocBook.
Currently, I only want to set up DocBook to publish HTML--I may be adding PDF later. Finding the installation and set up instructions for DocBook on Windows was not easy. I discovered a couple of old (and short) versions of this and that's where I started.
Unlike most Windows applications, there is no installer for DocBook. Installing is the same as downloading the executables (and other files), copying them to the location you want and then adding that location to your Windows Path. The Windows DocBook setup essentially has three pieces:
B. LIBXML2: I downloaded libxml2-2.7.8.win32.
If you want the newer libxml2 kit to convert your XML to HTML, you can get it from:
ftp://xmlsoft.org/libxml2/win32/64bit/, or ftp://xmlsoft.org/libxml2/win32/. But I'd try to get the old one working first. I haven't bothered to upgrade.
C. ICONV: I download iconv-1.9.2.win32
D: ZLIB1: I downloaded zlib-1.2.5.
After grabbing the tools, make sure you set up your Windows Path Variable. To set up the path for my system, I appended this: C:\docbook\libxslt-1.0.9-bin\bin;C:\docbook\libxml2-2.7.8.win32\bin;C:\docbook\iconv-1.9.2.win32\bin;C:\docbook\zlib-1.2.5\bin;
Once you have the tools installed. Run this command: xsltproc -version
The results should look something like this:
stephen.cawood@OLIFANTS /s/GitHub
$ xsltproc -version
Using libxml 20708, libxslt 10126 and libexslt 815
xsltproc was compiled against libxml 20706, libxslt 10126 and libexslt 815
libxslt 10126 was compiled against libxml 20706
libexslt 815 was compiled against libxml 20706
And the successful output should like like the image below.
To add a CSS stylesheet to your HTML output, use a command similar to this:
stephen.cawood@OLIFANTS /c/docbook
$ xsltproc --output outputFile.html --stringparam html.stylesheet help.css /c/docbook/docbook-xsl
-1.79.0/html/docbook.xsl testDocBook.xml
Note: If you want to build PDFs, you'll need to download and install FOP for Windows.
References:
Currently, I only want to set up DocBook to publish HTML--I may be adding PDF later. Finding the installation and set up instructions for DocBook on Windows was not easy. I discovered a couple of old (and short) versions of this and that's where I started.
Unlike most Windows applications, there is no installer for DocBook. Installing is the same as downloading the executables (and other files), copying them to the location you want and then adding that location to your Windows Path. The Windows DocBook setup essentially has three pieces:
- DocBook DTD (optional)
- DocBook XSL stylesheets
- Tools:
- libxml2
- libxsl
- iconv
- zlib1
1. Unless you're using a tool that supports DocBook (such as XMetal), you'll need to use one or more of the DocBook schemas. To do this, download and unzip the DocBook XML 5.x.x DTD from: http://docbook.org/schemas/5x.html. This is optional since the stylesheets reference web versions of the DTD by default and you can edit DocBook files in any XML/text editor--I prefer Sublime Text because it's cross-platform and awesome.
2. Download and unzip the DocBook XSL 1.x.x stylesheets from: http://sourceforge.net/projects/docbook/files/docbook-xsl/
I copied the files into C:\docbook\xsl
3. Download the tools. You can get versions of all 4 from here: ftp://ftp.zlatkovic.com/libxml/
A. XSLTPROC: Download xsltproc: libxslt-1.1.26.win32 from ftp://ftp.zlatkovic.com/libxml/
Unzip the folders and copy the files to c:\windows or another location that's in your Windows path. I prefer to copy them somewhere else (e.g., C:\docbook and add that directory to the path variable):
Unzip the folders and copy the files to c:\windows or another location that's in your Windows path. I prefer to copy them somewhere else (e.g., C:\docbook and add that directory to the path variable):
B. LIBXML2: I downloaded libxml2-2.7.8.win32.
If you want the newer libxml2 kit to convert your XML to HTML, you can get it from:
ftp://xmlsoft.org/libxml2/win32/64bit/, or ftp://xmlsoft.org/libxml2/win32/. But I'd try to get the old one working first. I haven't bothered to upgrade.
C. ICONV: I download iconv-1.9.2.win32
D: ZLIB1: I downloaded zlib-1.2.5.
After grabbing the tools, make sure you set up your Windows Path Variable. To set up the path for my system, I appended this: C:\docbook\libxslt-1.0.9-bin\bin;C:\docbook\libxml2-2.7.8.win32\bin;C:\docbook\iconv-1.9.2.win32\bin;C:\docbook\zlib-1.2.5\bin;
Once you have the tools installed. Run this command: xsltproc -version
The results should look something like this:
stephen.cawood@OLIFANTS /s/GitHub
$ xsltproc -version
Using libxml 20708, libxslt 10126 and libexslt 815
xsltproc was compiled against libxml 20706, libxslt 10126 and libexslt 815
libxslt 10126 was compiled against libxml 20706
libexslt 815 was compiled against libxml 20706
You will need a sample file to test your setup. Start with something dead simple like this (testDocBook.xml):
And the successful output should like like the image below.
To add a CSS stylesheet to your HTML output, use a command similar to this:
stephen.cawood@OLIFANTS /c/docbook
$ xsltproc --output outputFile.html --stringparam html.stylesheet help.css /c/docbook/docbook-xsl
-1.79.0/html/docbook.xsl testDocBook.xml
Note: If you want to build PDFs, you'll need to download and install FOP for Windows.
References: