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. 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. +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. 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. + + 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. @@ -146,7 +149,7 @@ 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 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 + Latest builds of the documentation are available from the DHIS2 website. The latest snapshot builds are available through the continuous integration server located here.

Building the documentation with Apache maven In order to transform the documentation source files to different formats, such as HTML @@ -162,10 +165,7 @@

Committing your changes back to Launchpad Once you have finished editing your document, you will need to commit your changes back to -Launchpad. Open up a command prompt on Windows or a shell on Linux, and navigate to the folder where you have placed your documentation. If you have added any new files or folders to your local repository, you will need to add them to the source tree with the bzr add command, followed by the folder or file name(s) that you have added Once you have added all of your new files, you should update you local repository to make sure there are no conflicts. -

- bzr update -

+Launchpad. Open up a command prompt on Windows or a shell on Linux, and navigate to the folder where you have placed your documentation. If you have added any new files or folders to your local repository, you will need to add them to the source tree with the bzr add command, followed by the folder or file name(s) that you have added Once you have added all of your new files, you should update you local repository to make sure there are no conflicts using the following command bzr update If there are conflicts, bazaar will notify you of this. Your conflicts can also be listed by using the bzr conflicts command. If there are conflicts in a file, bazaar will create three versions of the file: @@ -178,7 +178,7 @@ filename.OTHER - corresponding to the common parts of the file, the local version and the version on the server respectively. The files will contain markers to indicate areas in conflict. After resolving the conflicts by editing each file and removing the conflict markers, use bzr resolve. This will tell bazaar that the conflict is resolved, and clean up the BASE, THIS, OTHER files. + These files correspond to the common parts of the file, the local version and the version on the server respectively. The files will contain markers to indicate areas in conflict. After resolving the conflicts by editing each file and removing the conflict markers, use bzr resolve. This will tell bazaar that the conflict is resolved, and clean up the BASE, THIS, OTHER files. Once your source code is updated and any conflicts resolved, commit you changes with an informative message about the changes you have made:

bzr commit -m "Created Amharic translation of documentation" === modified file 'src/docbkx/en/dhis2_preface.xml' --- src/docbkx/en/dhis2_preface.xml 2011-09-14 11:02:00 +0000 +++ src/docbkx/en/dhis2_preface.xml 2011-09-14 18:18:56 +0000 @@ -23,5 +23,6 @@ Program listings usually contain some type of computer code. They will be displayed with a shaded background and a different font. Commands will be displayed in bold text, and represent a command which would need to be executed on the operating system or database. - Links to external web sites or cross references will be displayed in blue text, and underlined like this. + Links to external web sites or cross references will be displayed in blue text, and underlined like this.. + Bibliographic references will displayed in square brackets like this Store2007. A full reference can be found in the bibliography contained at the end of this document.