Welcome the company of trees

docpond - Docbook duck dwelling



I was always impressed with CSS Zengarden in showcasing what one can do with CSS. Using the same HTML plugging in different CSS radically changing the design. The HTML was however heavy on id and class definitions that I never got around to writing.[1] With Docbook the design is not that wild but the semantic groundwork is already taken care of. Once you know how you would like your section to look it is easily identifiable.

But what Docbook added was a extra layer of formatting to learn. Now you not only should know HTML, CSS and possibly FO but XSLT and probably a few more acronyms. With the basic XML easy to write I always found a CSS Zengarden like place missing, where I could easily look at different styles, or use different styles, or if just parts were interesting looking into how that design was made.

The DocBook XSL: The Complete Guide is of course a great resource, and provides some nice snippets that can enhance the look of a document, but understanding XSL can be quite daunting, if you just want to print a nice looking article quickly.

Sure, part of the problem is that design is not easy and not free, but with the open source heritage of Docbook it might be possible to start sharing some designs. Actually it was after buying and reading a book from Richard L. Hamilton Hamilton09 I found his blog and there the reference to his IEEE DocBook Customization. Having been an amateur user of Docbook since around 2000 I was astound that I had missed it. Here I could now take all my simple articles I had been hacking away on and get a real IEEE feel to them, even if I just used fop. Sure I had written a few scientific articles in Latex but the semantic idea of Docbook I have liked more. Now I almost had both. [2] After reading Robert BringhurstBringhurst08I became even more inspired to try to add more flavours to the default Docbook style.


So with that background I came up with the idea to collect XLST/CSS or other format packages and make them easy to use, either for a standard Docbook article or book. Thanks to the Wood Duck on the Docbook cover, I figured a good place to gather all the ducks, err docs would be in a pond. So I have started to collect some styles in the Docpond.

The Docpond is so far a work in progress. We'll see how far it gets. There is an open git repository.

git clone https://source.tree.se/git/docpond.git

Adjust default.html.xsl and default.pdf.xsl to point to where you have your stock style sheets stored. Current default is the Debian installation path file:///usr/share/xml/docbook/stylesheet/docbook-xsl-ns/html/docbook.xsl Making the examples requires a few tools : make, python, cutycapt, convert, xsltproc and fop. The Makefile have just been tested on a Debian system. Then just run make and the transforms will be generated, with preview both as document and as image.

The generated result is currently published at Docpond. This is a simple representation of the transforms. I will make it look prettier time permitting and if it becomes a valuable resource.


[Managing Writers] Richard L. Hamilton. Copyright © 2009 Richard L. Hamilton. 978-0-9822191-0-2. XML Press. Managing Writers. A Real World Guide to Managing Technical Documentation.

[Bringhurst] Robert Bringhurst. Copyright © 1992, 1996, 2004, 2005, 2008 Robert Bringhurst. 0-88179-206-3. Hartley & Marks. The Elelments of Typographic Style.

[1] The comments in the http://www.csszengarden.com/ HTML source starting on line 22 also indicates that the design is a bit over done on purpose

[2] Yes, Latex or Tex are hard to beat when it comes to research papers. I do not think I would dare to use MML for that yet, although I have made some simple experiments.