5.6. Multi-format Documentation with DocBook

DocBook is a set of definitions (DTD) for either XML and SGML languages particularly well-suited for books and papers about computer hardware and software.

Its over ten years long history proved its flexibility and usability in many projects. In particular DocBook is used in O'Reilly, xfree86, GNOME, KDE, FreeBSD, The Linux Documentation Project, PHP...

DocBook format is platform independent, concerned on meaning and different parts can be developed independently so since MegaPOV 1.0 DocBook is also used for the MegaPOV documentation. Usually features included in MegaPOV are included in whole package together with original documentation delivered by the author of a particular patch. It would speedup MegaPOV creation if the authors of patches could deliver their documentation in DocBook format. Such documentation is free from decoration, Java Script effects and other additions. Following chapter is filled with guidelines for those authors who want to speedup our documentation creation. Our experience can also help you to create your own documentation for other projects.

Before you will start work with DocBook it could be good to make review on:

to recognize features of DocBook and its syntax. No doubts it is much easier to play with DocBook when you have some HTML experience.

5.6.1. Environment for DocBook documentation

To work with DocBook you have to setup your environment for it. First thing you may be interested is definition of DocBook (DTD). MegaPOV uses XML (http://www.oasis-open.org/committees/docbook/xml/4.2/docbook-xml-4.2.zip) version because SGML one will be dropped in the future.

In order to get good environment you have to collect tools for:

  • validating:

    • XMLLINT - http://www.jclark.com/sp/nsgmls.htm
    • XMLLINT - http://xmlsoft.org/xmldtd.html
    • XMLVALID - http://www.elcel.com/products/xmlvalid.html

    In case of MegaPOV XMLVALID because it seems the most stable and fastest but it is available only for Windows console.

  • XSLT processing and converting into other formats:

    • XSLTPROC - http://xmlsoft.org/XSLT/
    • SAXON - http://saxon.sourceforge.net/
    • XALAN - http://xml.apache.org/xalan-j/

    In case of MegaPOV either XSLTPROC and SAXON are used. In case of PDF output also FOP (http://xml.apache.org/fop/) was used.

Other free XML tools can be found at http://www.garshol.priv.no/download/xmltools/.

5.6.2. Editing DocBook documentation

You do not need any special tool to edit DocBook files. Any text or HTML editor is enough. Some editors has some support for XML files (like Win-POV) however it is not required.

For simple examples of DocBook files please look at:

  • http://www.docbook.org/tdg/en/html/ch04.html#simple.document
  • http://xslt-process.sourceforge.net/docbook-example.xml

It is not purpose of this documentation to describe how DocBook document should look like however in order to get better understanding of DocBook syntax complete sources of this documentation are available within MegaPOV site.

For simpler usage book.xml introduces set of entities with:

  • names of persons
  • names of keywords and options
  • references to main parts

Maintaining it that way makes editing easier because we can then simple change markup for all tokens in all places editing only one file. Also patch writer can use those entities to make it easier to connect various documentations from various patch writers into one documentation.

5.6.3. Converting DocBook documents

In order to convert DocBook documentation into different formats you need ready for use style-sheets and templates available within http://docbook.sourceforge.net/projects/xsl/ repository. They delivers XSLT files to perform conversion into several formats. Conversion achieved this way is not perfect because authors can't decide what is your favorite appearance of documentation. You have to use so called "customization layer" over their files. MegaPOV has own customization layer. You can find it (*.xsl) where whole sources of documentation are.