DocBook Rules!

During the relaunch of bclary.com last year, I decided to use a custom vocabulary to author content on this site. Over the last year as my dissatisfaction has grown, I have moved from an xml-based document type which wrapped XHTML to a mixed namespace version of XHTML and now to DocBook.

I first began considering the use of DocBook as the JavaScript Bootcamp grew and grew beyond my capabilities to manage as XHTML. The lack of semantics, structure and off-the-shelf tools to process the content made the already difficult task almost impossible and definitely impossible to do well.

I have begun a project documenting “ECMA 357 - ECMAScript for XML” where a tool such as DocBook is essential. It helps that I have begun using Emacs and nxml-mode but the default set of tools, namely the DocBook XSL transforms, leave a gap in my ability to include executable examples. Fortunately, it is possible to apply a small change which allows me to control the creation of inline, executable javascript through the use of the programlisting element and the role attribute.

            
    <programlisting role="javascript">
    document.write('Hello World!');
    </programlisting>
    
          

            
    <programlisting role="javascript" id="clickme">
    function clickme()
    {
    alert('Hello World!');
    }
    </programlisting>
          

Cool, heh? The only drawback I have found so far is nxml-mode's reformatting of the contents of programlisting elements when reindenting a document.

The next step will be to wean myself from the old document format where I still keep the meta data used to drive this site, but that can wait until I have more time.

Thanks to Richard Stallman, Norm Walsh and friends, James Clark, and Daniel Veillard for the wonderful tools.