Introduction

Introduction One of the main advantages of DocBook is that there is complete separation between the -content and presentation. DocBook is a pure XML format, and is well documented. It is believed that only a very small subset of its features will be required in order to achieve much higher quality documentation for DHIS. There are some 400 separate mark-up elements that cater to almost any level of technical documentation needs, but in reality, only a few dozen of these element will probably need to be employed to achieve high-quality documentation for DHIS 2, both for printed as well as on-line formats such as HTML or integrated help systems within the application itself. Therefore, there are wide range of possibilities in terms of which editor can be used for the creation of DocBook files. A fairly complete list of possibilities is located here. It is currently recommended to use Syntext Serna Free for editing DocBook source files as WYSIWYG. In principle, any text editing program or XML editor will be capable of being used to create DocBook files. +content and presentation. DocBook is a pure XML format, and is well documented. It is believed that only a very small subset of its features will be required in order to achieve much higher quality documentation for DHIS. There are some 400 separate mark-up elements that cater to almost any level of technical documentation needs, but in reality, only a few dozen of these element will probably need to be employed to achieve high-quality documentation for DHIS 2, both for printed as well as on-line formats such as HTML or integrated help systems within the application itself. Therefore, there are wide range of possibilities in terms of which editor can be used for the creation of DocBook files. A fairly complete list of possibilities is located here. It is currently recommended to use WYSIWYG Syntext Serna Free editor for editing DocBook source files. In principle, any text editing program or XML editor can be used to author DocBook files. It is not recommended to use the editor XMLmind XML Editor Personal Edition (also known as XXE Personal), as the editor "silently" places unneeded whitespace and other ornamentation to the DocBook source which makes collaborative editing of documents very difficult. 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 in the first instance. The presentation of the document will take place in a separate step, where it will be rendered into different formats, such as HTML and PDF. It is therefore important that the document is will organised and structured, with appropriate DocBook tags and structural elements being considered. - It is good practise to break your document in to various sections using the + It is good practice to break your document in to various sections using the "sect", or section element. Section elements can also be nested within each other, such as "Section 1" and "Section 2". 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.

@@ -104,7 +104,7 @@ Handling multilingual documentation The directory structure of the documentation has been created in order to facilitate the creation of documents in any language. If you want to create a new set of documents in a given language, simply create a new directory in the dhis2-docbook-docs/src/docbkx/ directory. Be sure to use the ISO 639-1 code for the language you are going to create documents in. A complete list of these codes can be found here. Add a new folder for -images in a sub-directory , replacing XX with the actual ISO 639-1 code for the language you will create documents in. You will also need to edit the pom.xml file in the main dhis2-docbook-docs directory. If you are unsure of what changes need to be made to this file, ask on the mailing list first, as this file controls the generation of all the documentation. +images in a sub-directory , replacing XX with the actual ISO 639-1 code for the language you will create documents in. You will also need to edit the pom.xml file in the main dhis2-docbook-docs directory. If you are unsure of what changes need to be made to this file, ask on the mailing list first, as this file controls the generation of all the documentation.