21.2. Introduction

One of the main advantages of DocBook is that there is complete separation between the content and presentation. DocBook is a pure XML markup format used for technical documentation. In spite of the hundreds of tags which DocBook supports, only a very small subset of its features are currently used for the DHIS2 documentation. Since DocBook can be transformed into a wide variety of formats (HTML, PDF, etc) and is a text-based format, it serves as an ideal format for documentation of the system.

There exist a wide range of text editors which can be used for the creation of DocBook files. A fairly complete list of possibilities is located here. It is currently recommended to use the <oXygen/>® XML editor for editing DocBook source files. In principle, any text editing program or XML editor can be used to author DocBook files. Other good possibilities are excellent and freely available text editorjEdit with the XML plugin installed, or the cross-platform Emacs text editor. Both of these programs support editing DocBook XML.

One of the key concepts to keep in mind when authoring documentation in DocBook, or other presentation neutral formats, is that the content of the document should be considered first. The presentation of the document will take place in a separate transformation step, whereby the source XML will be rendered into different formats, such as HTML and PDF. It is therefore important that the document is well organised and structured, with appropriate tags and structural elements being considered.

It is good practice to break your document in to various sections using the sect tag. It is easy to make use of the modular nature of DocBook, and split very complex chapters into smaller, more manageable pieces. This concept is essentially the same as Microsoft Word® or other word processing programs. DocBook will automatically take care of numbering the sections for you when the document is produced.

Two other important elements are the itemizedlist and numberedlist. These are quite similar, but an itemised list corresponds to a bulleted list, which a numbered list will be rendered with each element being numbered sequentially. Other key elements are screenshot and table which should be self-explanatory.

The reader is referered to the DocBook documentation for a more in-depth description of the exact elements which are availbale to be used. Currently, the DHIS2 documentation is using version 5.0 of DocBook.