Dhis2 Documentation Guide
Dhis2 Documentation Guide
Dhis2 Documentation Guide
2.17
© 2006-2014
DHIS2 Documentation Team
Revision 1313
Version 2.17 2014-11-25 11:30:30
Warranty: THIS DOCUMENT IS PROVIDED BY THE AUTHORS ''AS IS'' AND ANY EXPRESS
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS MANUAL AND PRODUCTS MENTIONED HEREIN,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License: Permission is granted to copy, distribute and/or modify this document under the terms of the
GNU Free Documentation License, Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy
of the license is included in the source of this documentation, and is available here online: http://
www.gnu.org/licenses/fdl.html.
ii
DHIS2 Documentation Guide Contents
iii
DHIS2 Documentation Guide DHIS 2 Documentation System Overview
1.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 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.
Note
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 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.
In order to start adding or editing the documentation, you should first perform a checkout of the source code. If you do
not already have a GitHub account, you will need to get one. This can be done here. Once you register with GitHub,
1
DHIS2 Documentation Guide Getting the document source
you will need to request access to the dhis2-documenters group. Login to GitHub, and then file an issue here. Your
request will need to be approved by the group administrators. Once you have been granted access to the group, you
can commit changes to the documentation branch and send and receive notifications if you wish.
Once you have installed git on your system, you will need to download the document source. Just follow this procedure:
1. Make sure you have git installed.
2. On Windows systems, visit https://github.com/dhis2/dhis2docs and press "Clone in Desktop". If you are using the
command line, just type git clone [email protected]:dhis2/dhis2docs.git
3. The download process should start and all the documentation source files will be downloaded to the folder that
you specified.
4. The DHIS2 documents depend on other branches for their documentation. Be sure to keep these these up to date
as well. When you build the documentation, the necessary submodules will be downloaded automatically as part
of the build process ,if you have not already done so.
To get started with the bibliography, download a copy of JabRef and open the /src/bibliography/
dhis2_bibliography.bib file. . Add some new references, then export the bibliography back to the /src/
docbkx/en/dhis2_bibliography.xml file, using the DocBook 4.4 export format. The updated bibliography will
automatically be included in the documentation after you commit your changes.
2
DHIS2 Documentation Guide Linking documents together
image can be specified to occupy 80% of the available page width. For screen shots in landscape format, this seems to
be an appropriate amount. You may need to experiment a bit to obtain a proper width for your image. Alternatively,
you can edit the resolution of the image itself, in order to obtain a proper size during rendering.
<screenshot>
<screeninfo>DHIS2 Login screen</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="dhis2_login_screen.jpg" format="JPG" width="80%"/>
</imageobject>
</mediaobject>
</screenshot>
For other images, depending on their size, a different value may be necessary. If you do not specify a width for you
image, and its intrinsic size is larger than the available screen width, the image may overflow in certain document
types with a fixed width, such as PDF.
Should you wish to link several articles together into a book, DocBook provides a mechanism to assign an id to a
section. In the example below, a section has been assigned an id. This id must be unique within the document.
<section id="mod2_1">
<title>Getting started with DHIS2</title> ....
In order to include an article into a book, an Xinclude statement must be used. The following example shows how.
<chapter>
<title>Getting started with DHIS2</title>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhis2_user_man_mod2.xml"
xpointer="mod2_1" encoding="UTF-8"/>
...
Note that the file name and id have been assigned in the parent document, referring to the actual file (href) and particular
fragment of the child document that should be referenced in the parent document (xpointer).
Including chapters in a book is very simple. The example below illustrates how:
In this case, there is no need to explicitly reference a part of the document, unless you only want to include a portion
of the chapter. If you want to use a section of the chapter, you can assign an id to that section, and then reference that
section through an xpointer.
3
DHIS2 Documentation Guide Building the documentation
the pom.xml file in the main dhis2docs 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.
Latest builds of the documentation are available from the DHIS2 website. The latest snapshot builds are available
through the continuous integration server located here.
If you have any questions, or cannot find that you can get started, just send an email with your problem to
<[email protected]>.