DocBook Build Management...
...so I've been slowly talking the guys at work into using DocBook for all of our future documentation, in order to get all the files looking consistantly on both Windows and Linux ( and because I'm a rabid DocBook advocate ). Anyway, for it to actually be any use we needed a build system that worked both under Windows and Linux, and now OS/X - as we're a Java shop and everyone has Java on their systems, the choice of platform was rather moot. My initial introduction of DocBook into the office was a simple document under a "doc" directory of one of the small projects I was working on, but if everyone was going to use it - I needed something more generic. The first steps were to simply setup a new module in the CVS tree called documents, drop in the required library files ( saxon, fop, jimi ) and the DocBook XSL distribution, a source directory containing a lone DocBook XML file, and a build file using Jakarta Ant. Initially as a proof of concept, the build file was hardcoded to build the document into both a PDF and chunked HTML. The second step was the largest hurdle - getting our QA/Documentation guy to use DocBook, knowing peoples reaction to raw XML when their used to Microsoft Office, I presented people with XMLMind XMLEditor which provides a graphical XML editor, using CSS to stylise the content, and whilst it's a far cry from Office - it provides an easy to use, graphical editor, which is 90% of the battle. XXE is also Java based so continues to fit nicely with the cross-platform requirement. Finally a new project came up at work, and after repetitive moaning about the inconsistent look of the documents being produced one of the other guys in the office declared we'd use DocBook and that was that. It happened, of course - those same guys started grumbling at XXE and its small "issues" but they stuck with it, anyway, on the otherside of the fence there was me - with a funky build system that only built one file. Yuck - and so the refactoring begun. The third phase, and the first of the refactorings was to modularize my build script, so that I could call my build procedure passing in a filename, this was soon to also be annoying as I had to keep modifying the build script whenever we added a new document, or moved the document. The process needed to be dynamic, and flexable, and easy, and that comes in tomorrows entry...
Comments (2)
Something to look at in the future will be OpenOffice's docbook support. I also used XMLMind which I found really good when you apply a CSS stylesheet to make the editing look similar to the output you would normally get in HTML.
http://xml.openoffice.org/xmerge/docbook/ and
http://www.docbook.org/wiki/moin.cgi/OpenOffice
Jason Lea
Thanks for the great blog article.
we took the opposite approach to xml editing - but we'll benefit greatly from your autobuild process - great work!
more about our content editing approach - docbook is hugely powerful, but our gui-addicted users wouldn't go xml so we went wiki. Working in wiki, with all the web-based opportunities and foibles, was a great way to collaborate around the content and control the formatting options.
For building out, converting from wiki to DocBook, and picking up Meta data from the wiki's page was our solution. So far, we've got a high degree of consistency and collaboration, and we're beginning to use more and more of the DocBook capabilities (next up, indexing and cross-reference renaming!).
mickazoid [micki001@concentric.net]