Tools and Tips for Writing DocBook Documentation

Jurjen Bokma

June 2007


DocBook can be edited using various editors We use the nXML mode package (also here) to author DocBook under Emacs. See also my DocBook-under-Debian-HOWTO for a more in-depth explanation. A few handy shortcuts in nXML-mode:

A good reference is DocBook: The Definitive Guide. A list of templates would be handy. DocBook XSL: The Complete Guide is another excellent piece of documentation, as are the docs that come with the docbook-xsl-doc package under Debian.

Conversion to XHTML is done with


      
xsltproc \
--stringparam  base.dir  $(@D)/ \
--stringparam  use.id.as.filename 1 \
--stringparam  root.filename  ''  \
--stringparam chunker.output.encoding UTF-8 \
/usr/share/xml/docbook/stylesheet/nwalsh/xhtml/onechunk.xsl \
file.xml
      

      
    

in which case the id of the top level tag is the basename of the file that is generated [54]

As of september 2008, things have changed a bit: docbook.org has brought out docbook V5.0 with the new Definitive Guide.



[54] It also gets an extension: html in this case.