I've been doing a fair bit with DocBook recently. Both the Cascading User Guide and a section on Cascading, I hope to be included in the upcoming Hadoop: The Definitive Guide, were written in DocBook. Unfortunately, finding a reasonable DocBook tool chain was difficult, so I had to adopt the Velocity DocBook Framework and make some modifications. I've published a draft of my efforts on GitHub: DocBook Framework and DocBook Template.
The tool chain works for me, but this is definitely a freshman effort so YMMV.
Feel free to clone the repo and make improvements, and I'll be glad to merge them back in. I'll continue to push up any modifications I come up with as well.
Note there is code here that can scrape JUnit tests so they can be embedded into the final document.
There is also a SVG to PNG converter. PNG seems to work best with HTML, and SVG with PDF. In your DocBook XML, use 'roles' to identify which image should be used.
I use OmniGraffle to create my images and export them as SVG.
Finally, there is an 'edit' ant command that copies a version of the DocBook xml to a 'edit' directory so external tools can modify the xml in context with all the includes (junit source and images). Calling the 'edit' command again will copy back any edits to the src tree. I'm sure there is a better approach, but it works and is simple.
Btw, the tool chain has only been tested with DocBook 5.
Enjoy...
Leave a comment