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: 

1. DocBook DTD (optional)
2. DocBook XSL stylesheets
3. 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):

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:

DocBook 5 The Definitive Guide

Install xsltproc and FOP to generate a PDF from a docbook document

http://www.sagehill.net/docbookxsl/Parameters.html#ParameterSyntax 

http://www.napcsweb.com/blog/2008/03/03/working-with-docbook-on-windows/

http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/docbooksys/segmentedhtml/ch03s03.html#DocBookSys-Chapter3-XML-Install-libxml-Windows

Convert Broken HTML to XHTML

I recently made the decision to refactor a 600 page software manual. That’s a daunting task, so why did I do it? The old format was barely working, inflexible, required a truly awful propriety tool, and cost the company considerable time and money when changes (such as translations) were required.
The underlying pages were in HTML, or at least the closest thing to HTML that still actually worked. In reality, the code was awful; there were broken tags and redundant tags all over the place. The editor in question (developed by a small company in Hawaii) is nothing more than a wrapper around Microsoft’s free HTML Help Workshop tool. I decided to clean up the HTML (read: convert it to XHTML), dump the editor and dynamically build the manual the same way I’ve done at companies in the past. This is an ongoing project, but here’s how I handled the task of cleaning up ~600 HTML files, so they were in valid XHTML.
Resources:
HTML - Special Entity Codes
HTML Tidy
Online RegExr Test Tool and Interactive Tutorial
Sublime Text Editor

- running a Regular Expression replace in the Sublime Text editor
Step 1: Clean up the HTML with HTML Tidy
HTML Tidy is convenient way to repair poor HTML. It doesn’t fix everything, but it does help and it makes the code look a lot better since it will fix much of indentation. So the first thing I did was run this HTML Tidy command on all the files.
I ran this in Git Bash after turning off word wrap in tidy settings file. Even with the word wrap option, HTML Tidy inserted more newlines than you’d expect, so it isn’t perfect, but it made a big difference.
$ find /C/Manual -type f -name "*.htm" -exec tidy -f errors.txt -m -utf8 -i {} \;
Note that you can remove the HTML Tidy watermark pretty easily using find/replace in Sublime. And that is a nice segue to the next step.
Step 2: Simple Find/Replace in Sublime
Using the “Find in Files…” feature, it’s easy to make simple text substitutions in Sublime. For example, to be XHTML compliant, I need to convert &nbsp; to &#160;, <BR> to <br/>, and many other examples.
I also needed to simply remove some tags. For example, tags added when someone pasted text from Microsoft Word into the editor (e.g., <o:p> and </o:p>).
Sublime will help you figure out the syntax to match just the current open file, all open files, or a whole directory structure. For example, in the “Where” box for Replace, you might enter c:\directory\test,*.htm to match all .htm files.
Step3: RegEx Find/Replace in Sublime
Simple find/replace actions got me part way there, but they wouldn’t solve all the issues I had to deal with in the broken HTML. The next step was to use Regular Expressions to enable some more sophisticated corrections.
One example, was attributes within HTML tags (such as size, height, etc.) that weren’t enclosed in quotation marks. Browsers will deal with that transgression, but it’s not valid XHTML. I had to find a quick way to add the quotes around these attributes in ~600 files. The answer was find/replace using regular expressions in Sublime.
Find: (size=)([0-9])
This creates two capturing groups with “size=” as the first and any number of 0-9 characters as the second.
Replace: $1"$2"
This replace command encloses the second capturing group in quotation marks. For example, size=100 becomes size=”100”.
Well that’s all for now. I hope you found this helpful. I encourage you to try the RegExr online tool; it’s helpful when refining regular expressions.