21.10. Building the documentation

One of the key advantages of the DocBook format is that the source documentation can be transformed into a wide variety of formats, including HTML, chunked HTML, XHTML, PDF, and a number of other formats. There are a wide variety of tools that are capable of performing this task. Basically the XML source of the document is transformed using the standard DocBook XSL style sheets into the desired output format. The complete list of tools capable of transforming DocBook will not be listed here, but a few examples are provided below.

Latest builds of the documentation are available from the DHIS2 website. The latest snapshot builds and previous versions of the documentation are available through a searchable site located here.

21.10.1. Building the documentation with Apache maven

In order to transform the documentation source files to different formats, such as HTML or PDF, you will need to install the Apache Maven program. You can get a copy here or by installing it through your package manager if you are using Linux. Just execute the command mvn clean package on Windows or on Linux from the /dhis2-docbook-docs directory. Maven will start to download the necessary components to transform the documents into HMTL,PDF and RTF. Once the process has completed (be patient the first time, as there are a number of components that must be downloaded), all of the target document types will be generated in the /dhis2docs/target/docbkx directory in respective sub-directories.

21.10.2. Building with xmlto

xmlto is a useful utility available on Linux platforms for transforming DocBook documents into many different formats. More information on the package can be found here. If you do not want to use Apache Maven for some reason, you can install xmlto through your package manager. Once you have installed xmlto you can just execute

xmlto [htmlfile_to_transform]

where the file_to_transform parameter is the name of the file you wish to transform. There are many other formats available, such as PDF, PS, JavaHelp and others.