Working With DocBook

Working With DocBook

Lance Hendrix

Revision History
13 April, 2013
Creation Date


In the process of creating documentation, I have been working with DocBook and wanted to document some of the things I have found, especially as relates to DocBook to XHTML (HTML) generation as well as what I have done with integration of DocBook with Apache Forrest for site generation.

More information on DocBook with a general overview can be found on the DocBook wikipedia page.

1. Purpose of this Document

The primary purpose of this document is to record some of the nuances of working with DocBook and especially with integration to Forrest so that I have a record of what I have done and how I got it working. It is also my hope that others may find some of this information helpful.

Please note that this exercise is not intended to replace the documentation provided by the DocBook project or the DocBook XSLT. There are also much more comprehensive sources of configuration information and How-Tos on the Internet; however, the intention here is to cover some more anecdotal information that I have discovered and that I had to piece together often through trial and error as I was learning how to (and am still learning, BTW) use DocBook for my particular purposes.

2. Acknowledgements

There is no way that I would ever have been able to work through how I am using DocBook without some good information on the web. First I would like to thank www.docbook.org for the documentation provided and OASIS (find reference and ulink) for continuing to support and move the innovation of DocBook forward.

3. Valuable Links

4. Why DocBook?

The first question you may ask is why DocBook. I decided to use DocBook because I wanted a be able to write an a format that separated the content from the publishing format. That is, I didn't want to create content that could be published in any format. Given my technical background, XML seemed to be a good starting point where I could create content and tag it with rich metadata that hopefully could then be used to generate reasonable formats for publishing as a web page (my primary purpose) or any other format such as sending to a publisher for printing hardcopy, etc.

While I would have liked the ease of using a WYSIWYG editor like Microsoft Word or even OpenOffice, the limitations of those formats in my estimation eliminated them as options. They are good word processors, but when it comes to writing content to be published as web pages (and integrated into a publishing pipeline), they did not seem to fit the bill. Further, I wanted to be able to generate HTML and have that integrated into a publishing platform for consumption on the Internet.

5. Working with DocBook

While some may find working in raw XML with a text editor sufficient, my lack of detailed knowledge of the structure and schema of proper/correct DocBook XML format meant that I wanted to find at a minimum an XML editor that could help me with the structure of my documents. A nice to have would be an editor that also allowed me at least some nicities around editing DocBook similar to what a typical modern word processor would allow. I started off using XMLMind and found that to be sufficient, especially given the price point, but I have eventually migrated over to OxygenXML, which is quite a bit more expensive (as of the last time I compared the two), but I find OxygenXML to be worth the larger price tag.

6. DocBook to HTML Nuances

This section describe nuances of the DocBook to HTML transforms provided by the DocBook XSL project (find and insert link to project and to sourceforge) that I have used and find of interest.

6.1. XSLT Parameters of Interest

Pull the parameters from the forrest/cocoon transform configuration...

6.2. XREF and HTML Local Links

Have to use an "anchor" DocBook element in the section title in order to get the XSLT to generate a link that works from DocBook to HTML rather than using the title element's id attribute.

6.3. Line Numbering in Program Listings

Describe how line numbering works in "<programlisting>" tags... Had to set the attribute as well as use some parameters in the XSL for HTML generation (set them in the cocoon/forrest config files).

7. DocBook and Apache Forrest

Describe the nuances of working with DocBook when using Apache Forrest to generate a site.