dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #12500
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 328: Added more bibliography sources and updated the documentation on how to use the bibliographic dat...
------------------------------------------------------------
revno: 328
committer: Jason P. Pickering <jason.p.pickering@xxxxxxxxx>
branch nick: dhis2-docbook-docs
timestamp: Thu 2011-06-09 10:50:51 +0200
message:
Added more bibliography sources and updated the documentation on how to use the bibliographic database. Minor edits to the documentation documentation.
modified:
src/bibliography/dhis2_bibliography.bib
src/bibliography/dhis2_bibliography.bib.bak
src/docbkx/en/dhis2_bibliography.xml
src/docbkx/en/dhis2_documentation_guide.xml
--
lp:~dhis2-documenters/dhis2/dhis2-docbook-docs
https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs
Your team DHIS 2 developers is subscribed to branch lp:~dhis2-documenters/dhis2/dhis2-docbook-docs.
To unsubscribe from this branch go to https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs/+edit-subscription
=== modified file 'src/bibliography/dhis2_bibliography.bib'
--- src/bibliography/dhis2_bibliography.bib 2011-06-08 18:36:47 +0000
+++ src/bibliography/dhis2_bibliography.bib 2011-06-09 08:50:51 +0000
@@ -1,4 +1,4 @@
-% This file was created with JabRef 2.6.
+% This file was created with JabRef 2.7b2.
% Encoding: UTF8
@MASTERSTHESIS{AlSaid2010,
@@ -51,6 +51,20 @@
url = {http://search.ebscohost.com/login.aspx?direct=true&db=aph&AN=6705438&site=ehost-live}
}
+@ARTICLE{BraaNetworksAction2004,
+ author = {Braa, Jørn; Monteiro, Eric; and Sahay, Sundeep},
+ title = {Networks of Action: Sustainable Health Information Systems Across
+ Developing Countries},
+ journal = {MIS Quarterly},
+ year = {2004},
+ volume = {28},
+ pages = {3},
+ number = {3},
+ owner = {jason},
+ timestamp = {2011.06.09},
+ url = {http://aisel.aisnet.org/misq/vol28/iss3/3/}
+}
+
@MASTERSTHESIS{Brucker2007,
author = {Brucker, Øyvind F},
title = {Internationalization and localization - A case study from HISP},
@@ -77,6 +91,18 @@
url = {http://urn.nb.no/URN:NBN:no-11506}
}
+@PHDTHESIS{Jacucci06exploringtensions,
+ author = {Edoardo Jacucci , Cover Inger S , Ved Anfinsen},
+ title = {EXPLORING TENSIONS IN INFORMATION SYSTEMS STANDARDIZATION Two Case
+ Studies from Healthcare in Norway and South Africa},
+ school = {University of Oslo},
+ year = {2006},
+ citeseerurl = {http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.105.1991},
+ owner = {jason},
+ timestamp = {2011.06.09},
+ url = {http://folk.uio.no/edoardo/MatNatAvh_Jacucci_rettet.pdf}
+}
+
@MASTERSTHESIS{Gjendem2008,
author = {Gjendem, Anders},
title = {Recruitment, training, communication and Open Source},
@@ -128,6 +154,20 @@
url = {http://urn.nb.no/URN:NBN:no-12659}
}
+@ARTICLE{BraaStandards2007,
+ author = {Jørn Braa, Ole Hanseth, Arthur Heywood, Woishet Mohammed, Vincent
+ Shaw},
+ title = {DEVELOPING HEALTH INFORMATION SYSTEMS IN DEVELOPING COUNTRIES: THE
+ FLEXIBLE STANDARDS STRATEGY},
+ journal = {MIS Q},
+ year = {2007},
+ volume = {31},
+ pages = {1},
+ owner = {jason},
+ timestamp = {2011.06.09},
+ url = {http://heim.ifi.uio.no/~vshaw/Files/Published%20Papers%20included%20in%20Kappa/4_Braa_Flexible%20standards.pdf}
+}
+
@MASTERSTHESIS{Lewis2005,
author = {Lewis, John},
title = {Design and development of spatial GIS application for primary healthcare
@@ -182,6 +222,39 @@
url = {http://urn.nb.no/URN:NBN:no-17859}
}
+@CONFERENCE{Saeb2009,
+ author = {Saeb, J. Kossi, E.K. Golly-Kobrissa, R.T. Titlestad, O. Braa, J.},
+ title = {Integrating health information systems in Sierra Leone},
+ booktitle = {Information and Communication Technologies and Development (ICTD),
+ 2009 International Conference on},
+ year = {2009},
+ pages = {379 - 391},
+ owner = {jason},
+ timestamp = {2011.06.09}
+}
+
+@PHDTHESIS{ShawComplexityInspried2009,
+ author = {Vincent Shaw},
+ title = {A complexity inspired approach to co-evolutionary hospital management
+ information systems development},
+ school = {University of Oslo},
+ year = {2009},
+ owner = {jason},
+ timestamp = {2011.06.09},
+ url = {http://heim.ifi.uio.no/~vshaw/Files/VShaw%20Kappa%20Final%20Version}
+}
+
+@CONFERENCE{Staring2008,
+ author = {Knut Staring and Ola Hodne Titlestad},
+ title = {Development as a Free Software: Extending Commons Based Peer Production
+ to the South},
+ booktitle = {ICIS 2008 PROCEEDINGS},
+ year = {2008},
+ owner = {jason},
+ timestamp = {2011.06.09},
+ url = {http://aisel.aisnet.org/icis2008/50}
+}
+
@MASTERSTHESIS{Store2007,
author = {Store, Margrethe},
title = {Explore the challenges of providing documentation in open source
@@ -209,6 +282,18 @@
url = {http://urn.nb.no/URN:NBN:no-25666}
}
+@CONFERENCE{ShawScaling2007,
+ author = {Vincent Shaw, Shegaw Anagaw Mengiste, Jorn Braa},
+ title = {Scaling of Health Information Systems in Nigeria and Ethiopia- Considering
+ the Options},
+ booktitle = {Proceedings of the 9th International Conference on Social Implications
+ of Computers in Developing Countries},
+ year = {2007},
+ owner = {jason},
+ timestamp = {2011.06.09},
+ url = {http://heim.ifi.uio.no/~vshaw/Files/Published%20Papers%20included%20in%20Kappa/6_Shaw_IFP9.4%20Scaling%20of%20HIS_Considering%20the%20Options.pdf}
+}
+
@MASTERSTHESIS{Vo2009,
author = {Vo, Kim Anh Thi},
title = {Challenges of Health Information Systems Programs in Developing Countries:
@@ -237,6 +322,17 @@
url = {http://urn.nb.no/URN:NBN:no-24751}
}
+@MASTERSTHESIS{Overland2006,
+ author = {Øverland,Lars Helge},
+ title = {Global Software Development and Local Capacity Building},
+ school = {University of Oslo},
+ year = {2006},
+ comment = {http://www.digbib.uio.no/publ/informatikk/2006/47609/Overland.pdf},
+ owner = {jason},
+ timestamp = {2011.06.09},
+ url = {http://urn.nb.no/URN:NBN:no-13609}
+}
+
@comment{jabref-meta: selector_publisher:}
@comment{jabref-meta: selector_author:}
=== modified file 'src/bibliography/dhis2_bibliography.bib.bak'
--- src/bibliography/dhis2_bibliography.bib.bak 2011-06-08 18:36:47 +0000
+++ src/bibliography/dhis2_bibliography.bib.bak 2011-06-09 08:50:51 +0000
@@ -1,7 +1,7 @@
-% This file was created with JabRef 2.6.
+% This file was created with JabRef 2.7b2.
% Encoding: UTF8
-@PHDTHESIS{AlSaid2010,
+@MASTERSTHESIS{AlSaid2010,
author = {Al Said, Said Salah Eldin},
title = {The health information system in Sudan},
school = {The University of Oslo},
@@ -14,7 +14,7 @@
url = {http://urn.nb.no/URN:NBN:no-27062}
}
-@PHDTHESIS{Berg2007,
+@MASTERSTHESIS{Berg2007,
author = {Berg, Eivind Anders},
title = {The challenges of implementing a health information system in Vietnam},
school = {The University of Oslo},
@@ -51,7 +51,21 @@
url = {http://search.ebscohost.com/login.aspx?direct=true&db=aph&AN=6705438&site=ehost-live}
}
-@PHDTHESIS{Brucker2007,
+@ARTICLE{BraaNetworksAction2004,
+ author = {Braa, Jørn; Monteiro, Eric; and Sahay, Sundeep},
+ title = {Networks of Action: Sustainable Health Information Systems Across
+ Developing Countries},
+ journal = {MIS Quarterly},
+ year = {2004},
+ volume = {28},
+ pages = {3},
+ number = {3},
+ owner = {jason},
+ timestamp = {2011.06.09},
+ url = {http://aisel.aisnet.org/misq/vol28/iss3/3/}
+}
+
+@MASTERSTHESIS{Brucker2007,
author = {Brucker, Øyvind F},
title = {Internationalization and localization - A case study from HISP},
school = {The University of Oslo},
@@ -64,7 +78,7 @@
url = {http://urn.nb.no/URN:NBN:no-15774}
}
-@PHDTHESIS{Damitew2005,
+@MASTERSTHESIS{Damitew2005,
author = {Damitew, Hirut Gebrekidan and Gebreyesus, Netsanet Haile},
title = {Sustainability and optimal use of Health Information Systems},
school = {The University of Oslo},
@@ -77,7 +91,19 @@
url = {http://urn.nb.no/URN:NBN:no-11506}
}
-@PHDTHESIS{Gjendem2008,
+@PHDTHESIS{Jacucci06exploringtensions,
+ author = {Edoardo Jacucci , Cover Inger S , Ved Anfinsen},
+ title = {EXPLORING TENSIONS IN INFORMATION SYSTEMS STANDARDIZATION Two Case
+ Studies from Healthcare in Norway and South Africa},
+ school = {University of Oslo},
+ year = {2006},
+ citeseerurl = {http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.105.1991},
+ owner = {jason},
+ timestamp = {2011.06.09},
+ url = {http://folk.uio.no/edoardo/MatNatAvh_Jacucci_rettet.pdf}
+}
+
+@MASTERSTHESIS{Gjendem2008,
author = {Gjendem, Anders},
title = {Recruitment, training, communication and Open Source},
school = {The University of Oslo},
@@ -90,7 +116,7 @@
url = {http://urn.nb.no/URN:NBN:no-19821}
}
-@PHDTHESIS{Gjerull2006,
+@MASTERSTHESIS{Gjerull2006,
author = {Gjerull, Nils Fredrik},
title = {Open Source Software Development in Developing Countries},
school = {The University of Oslo},
@@ -103,7 +129,7 @@
url = {http://urn.nb.no/URN:NBN:no-13117}
}
-@PHDTHESIS{Heldre2006,
+@MASTERSTHESIS{Heldre2006,
author = {Heldre, Thor Helge},
title = {Study of a Health Information System pilot project in Tanzania},
school = {The University of Oslo},
@@ -116,7 +142,7 @@
url = {http://urn.nb.no/URN:NBN:no-12362}
}
-@PHDTHESIS{Jacobsen2006,
+@MASTERSTHESIS{Jacobsen2006,
author = {Jacobsen, Petter},
title = {Design and development of a global reporting solution for DHIS},
school = {The University of Oslo},
@@ -128,7 +154,21 @@
url = {http://urn.nb.no/URN:NBN:no-12659}
}
-@PHDTHESIS{Lewis2005,
+@ARTICLE{BraaStandards2007,
+ author = {Jørn Braa, Ole Hanseth, Arthur Heywood, Woishet Mohammed, Vincent
+ Shaw},
+ title = {DEVELOPING HEALTH INFORMATION SYSTEMS IN DEVELOPING COUNTRIES: THE
+ FLEXIBLE STANDARDS STRATEGY},
+ journal = {MIS Q},
+ year = {2007},
+ volume = {31},
+ pages = {1},
+ owner = {jason},
+ timestamp = {2011.06.09},
+ url = {http://heim.ifi.uio.no/~vshaw/Files/Published%20Papers%20included%20in%20Kappa/4_Braa_Flexible%20standards.pdf}
+}
+
+@MASTERSTHESIS{Lewis2005,
author = {Lewis, John},
title = {Design and development of spatial GIS application for primary healthcare
sector},
@@ -143,7 +183,7 @@
url = {http://urn.nb.no/URN:NBN:no-11504}
}
-@PHDTHESIS{Mangset2005,
+@MASTERSTHESIS{Mangset2005,
author = {Mangset, Lars},
title = {DHIS-2 - A Globally Distributed Development Process},
school = {The University of Oslo},
@@ -155,7 +195,7 @@
url = {http://urn.nb.no/URN:NBN:no-10640}
}
-@PHDTHESIS{Ngoma2007,
+@MASTERSTHESIS{Ngoma2007,
author = {Ngoma, Caroline},
title = {Cultivation Strategies in the Implementation of Health Management
Information System in Zanzibar},
@@ -169,7 +209,7 @@
url = {http://urn.nb.no/URN:NBN:no-16911}
}
-@PHDTHESIS{Nguyen2007,
+@MASTERSTHESIS{Nguyen2007,
author = {Nguyen, Thanh Ngoc},
title = {OSS For Health Care in Developing Countries},
school = {The University of Oslo},
@@ -182,7 +222,40 @@
url = {http://urn.nb.no/URN:NBN:no-17859}
}
-@PHDTHESIS{Store2007,
+@CONFERENCE{Saeb2009,
+ author = {Saeb, J. Kossi, E.K. Golly-Kobrissa, R.T. Titlestad, O. Braa, J.},
+ title = {Integrating health information systems in Sierra Leone},
+ booktitle = {Information and Communication Technologies and Development (ICTD),
+ 2009 International Conference on},
+ year = {2009},
+ pages = {379 - 391},
+ owner = {jason},
+ timestamp = {2011.06.09}
+}
+
+@PHDTHESIS{ShawComplexityInspried2009,
+ author = {Vincent Shaw},
+ title = {A complexity inspired approach to co-evolutionary hospital management
+ information systems development},
+ school = {University of Oslo},
+ year = {2009},
+ owner = {jason},
+ timestamp = {2011.06.09},
+ url = {http://heim.ifi.uio.no/~vshaw/Files/VShaw%20Kappa%20Final%20Version}
+}
+
+@CONFERENCE{Staring2008,
+ author = {Knut Staring and Ola Hodne Titlestad},
+ title = {Development as a Free Software: Extending Commons Based Peer Production
+ to the South},
+ booktitle = {ICIS 2008 PROCEEDINGS},
+ year = {2008},
+ owner = {jason},
+ timestamp = {2011.06.09},
+ url = {http://aisel.aisnet.org/icis2008/50}
+}
+
+@MASTERSTHESIS{Store2007,
author = {Store, Margrethe},
title = {Explore the challenges of providing documentation in open source
projects},
@@ -196,7 +269,7 @@
url = {http://urn.nb.no/URN:NBN:no-15782}
}
-@PHDTHESIS{Storset2010,
+@MASTERSTHESIS{Storset2010,
author = {Storset, Leif Arne},
title = {Integration of Health Management Information Systems},
school = {The University of Oslo},
@@ -209,7 +282,19 @@
url = {http://urn.nb.no/URN:NBN:no-25666}
}
-@PHDTHESIS{Vo2009,
+@CONFERENCE{ShawScaling2007,
+ author = {Vincent Shaw, Shegaw Anagaw Mengiste, Jorn Braa},
+ title = {Scaling of Health Information Systems in Nigeria and Ethiopia- Considering
+ the Options},
+ booktitle = {Proceedings of the 9th International Conference on Social Implications
+ of Computers in Developing Countries},
+ year = {2007},
+ owner = {jason},
+ timestamp = {2011.06.09},
+ url = {http://heim.ifi.uio.no/~vshaw/Files/Published%20Papers%20included%20in%20Kappa/6_Shaw_IFP9.4%20Scaling%20of%20HIS_Considering%20the%20Options.pdf}
+}
+
+@MASTERSTHESIS{Vo2009,
author = {Vo, Kim Anh Thi},
title = {Challenges of Health Information Systems Programs in Developing Countries:
SUCCESS and FAILURE},
@@ -223,7 +308,7 @@
url = {http://urn.nb.no/URN:NBN:no-23652}
}
-@PHDTHESIS{Overland2010,
+@MASTERSTHESIS{Overland2010,
author = {Øverland, Jan Henrik},
title = {An Open Source Approach to Improving GIS Implementations in Developing
Countries},
=== modified file 'src/docbkx/en/dhis2_bibliography.xml'
--- src/docbkx/en/dhis2_bibliography.xml 2011-06-08 18:36:47 +0000
+++ src/docbkx/en/dhis2_bibliography.xml 2011-06-09 08:50:51 +0000
@@ -39,6 +39,22 @@
<bibliomisc><ulink url="http://search.ebscohost.com/login.aspx?direct=true&#x0026;db=aph&#x0026;AN=6705438&#x0026;site=ehost-live";>http://search.ebscohost.com/login.aspx?direct=true&#x0026;db=aph&#x0026;AN=6705438&#x0026;site=ehost-live</ulink></bibliomisc>
</biblioentry>
+<biblioentry xreflabel="BraaNetworksAction2004" id="BraaNetworksAction2004">
+ <authorgroup>
+ <author><firstname>Eric;</firstname><surname>Braa Jørn; Monteiro</surname></author>
+ <author><firstname>Sundeep</firstname><surname>Sahay</surname></author>
+
+ </authorgroup>
+ <citetitle pubwork="article">Networks of Action: Sustainable Health Information Systems Across Developing Countries</citetitle>
+ <citetitle pubwork="journal">MIS Quarterly</citetitle>
+
+ <volumenum>28</volumenum>
+
+ <artpagenums>3</artpagenums>
+ <pubdate>2004</pubdate>
+ <bibliomisc><ulink url="http://aisel.aisnet.org/misq/vol28/iss3/3/";>http://aisel.aisnet.org/misq/vol28/iss3/3/</ulink></bibliomisc>
+
+</biblioentry>
<biblioentry xreflabel="Brucker2007" id="Brucker2007">
<authorgroup>
<author><firstname>Øyvind F</firstname><surname>Brucker</surname></author>
@@ -62,6 +78,21 @@
<pubdate>2005</pubdate>
<bibliomisc><ulink url="http://urn.nb.no/URN:NBN:no-11506";>http://urn.nb.no/URN:NBN:no-11506</ulink></bibliomisc>
</biblioentry>
+<biblioentry xreflabel="Jacucci06exploringtensions" id="Jacucci06exploringtensions">
+ <authorgroup>
+ <author><firstname>Ved Anfinsen</firstname><surname>Edoardo Jacucci Cover Inger S</surname></author>
+
+ </authorgroup>
+ <citetitle pubwork="article">EXPLORING TENSIONS IN INFORMATION SYSTEMS STANDARDIZATION Two Case Studies from Healthcare in Norway and South Africa</citetitle>
+
+
+
+
+
+ <pubdate>2006</pubdate>
+ <bibliomisc><ulink url="http://folk.uio.no/edoardo/MatNatAvh_Jacucci_rettet.pdf";>http://folk.uio.no/edoardo/MatNatAvh_Jacucci_rettet.pdf</ulink></bibliomisc>
+
+</biblioentry>
<biblioentry xreflabel="Gjendem2008" id="Gjendem2008">
<authorgroup>
<author><firstname>Anders</firstname><surname>Gjendem</surname></author>
@@ -150,6 +181,52 @@
<pubdate>2007</pubdate>
<bibliomisc><ulink url="http://urn.nb.no/URN:NBN:no-17859";>http://urn.nb.no/URN:NBN:no-17859</ulink></bibliomisc>
</biblioentry>
+<biblioentry xreflabel="Saeb2009" id="Saeb2009">
+ <authorgroup>
+ <author><firstname>E.K. Golly-Kobrissa R.T. Titlestad O. Braa J.</firstname><surname>Saeb J. Kossi</surname></author>
+
+ </authorgroup>
+ <citetitle pubwork="article">Integrating health information systems in Sierra Leone</citetitle>
+
+
+
+
+ <artpagenums>379 - 391</artpagenums>
+ <pubdate>2009</pubdate>
+
+
+</biblioentry>
+<biblioentry xreflabel="ShawComplexityInspried2009" id="ShawComplexityInspried2009">
+ <authorgroup>
+ <author><firstname>Vincent</firstname><surname>Shaw</surname></author>
+
+ </authorgroup>
+ <citetitle pubwork="article">A complexity inspired approach to co-evolutionary hospital management information systems development</citetitle>
+
+
+
+
+
+ <pubdate>2009</pubdate>
+ <bibliomisc><ulink url="http://heim.ifi.uio.no/~vshaw/Files/VShaw%20Kappa%20Final%20Version";>http://heim.ifi.uio.no/~vshaw/Files/VShaw%20Kappa%20Final%20Version</ulink></bibliomisc>
+
+</biblioentry>
+<biblioentry xreflabel="Staring2008" id="Staring2008">
+ <authorgroup>
+ <author><firstname>Knut</firstname><surname>Staring</surname></author>
+ <author><firstname>Ola Hodne</firstname><surname>Titlestad</surname></author>
+
+ </authorgroup>
+ <citetitle pubwork="article">Development as a Free Software: Extending Commons Based Peer Production to the South</citetitle>
+
+
+
+
+
+ <pubdate>2008</pubdate>
+ <bibliomisc><ulink url="http://aisel.aisnet.org/icis2008/50";>http://aisel.aisnet.org/icis2008/50</ulink></bibliomisc>
+
+</biblioentry>
<biblioentry xreflabel="Store2007" id="Store2007">
<authorgroup>
<author><firstname>Margrethe</firstname><surname>Store</surname></author>
@@ -172,6 +249,21 @@
<pubdate>2010</pubdate>
<bibliomisc><ulink url="http://urn.nb.no/URN:NBN:no-25666";>http://urn.nb.no/URN:NBN:no-25666</ulink></bibliomisc>
</biblioentry>
+<biblioentry xreflabel="ShawScaling2007" id="ShawScaling2007">
+ <authorgroup>
+ <author><firstname>Jorn Braa</firstname><surname>Vincent Shaw Shegaw Anagaw Mengiste</surname></author>
+
+ </authorgroup>
+ <citetitle pubwork="article">Scaling of Health Information Systems in Nigeria and Ethiopia- Considering the Options</citetitle>
+
+
+
+
+
+ <pubdate>2007</pubdate>
+ <bibliomisc><ulink url="http://heim.ifi.uio.no/~vshaw/Files/Published%20Papers%20included%20in%20Kappa/6_Shaw_IFP9.4%20Scaling%20of%20HIS_Considering%20the%20Options.pdf";>http://heim.ifi.uio.no/~vshaw/Files/Published%20Papers%20included%20in%20Kappa/6_Shaw_IFP9.4%20Scaling%20of%20HIS_Considering%20the%20Options.pdf</ulink></bibliomisc>
+
+</biblioentry>
<biblioentry xreflabel="Vo2009" id="Vo2009">
<authorgroup>
<author><firstname>Kim Anh Thi</firstname><surname>Vo</surname></author>
=== modified file 'src/docbkx/en/dhis2_documentation_guide.xml'
--- src/docbkx/en/dhis2_documentation_guide.xml 2011-02-17 08:29:16 +0000
+++ src/docbkx/en/dhis2_documentation_guide.xml 2011-06-09 08:50:51 +0000
@@ -1,179 +1,183 @@
-<?xml version='1.0' encoding='UTF-8'?>
-<!-- This document was created with Syntext Serna Free. --><!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; [
-<!ENTITY br ''>]>
-<chapter>
- <chapterinfo>
- <title>DHIS 2 Documentation Guide</title>
- <author>
- <firstname>Jason</firstname>
- <surname>Pickering</surname>
- <affiliation>
- <orgname/>
- </affiliation>
- </author>
- <pubdate>14/09/09</pubdate>
- <keywordset>
- <keyword>DHIS2</keyword>
- <keyword>documentation</keyword>
- <keyword>DocBook</keyword>
- </keywordset>
- <revhistory>
- <revision>
- <revnumber>1</revnumber>
- <date>29/09/09</date>
- <revdescription>
- <para>Added more information on getting started with bzr and DocBook</para>
- </revdescription>
- </revision>
- <revision>
- <revnumber>2</revnumber>
- <date>28/10/09</date>
- <revdescription>
- <para> Added some more information on multilingual documents and editors.</para>
- </revdescription>
- </revision>
- <revision>
- <revnumber>3</revnumber>
- <date>17/02/11</date>
- <revdescription>
- <para>Edited the parts on getting and committing code with bazaar from using branch and push to checkout and commit.</para>
- </revdescription>
- </revision>
- </revhistory>
- </chapterinfo>
- <title>DHIS2 Documentation Guide</title>
- <section id="docs_1">
- <title>DHIS 2 Documentation System Overview</title>
- <para remap="">DHIS 2 is a web-based aggregate information management system under very active development.
-While primarily intended for management of aggregate, georeferenced health data, it should be possible to use the system for other purposes as well. Currently, there are a large number of disconnected pockets of documentation in various formats (e.g. MediaWiki, Word documents, Confluence). There is a need to consolidate the documentation process and bring it more in-line with the distributed nature of the development of the application itself. It has been suggested therefore to move the current documentation to the DocBook platform. This article will not discuss the relative merits of the DocBook platform, but rather will serve as a brief guide to its use by DHIS 2 implementers, users and developers. Readers are encouraged to make their own decision about whether to use DocBook or not for documentation purposes.</para>
- </section>
- <section id="docs_2">
- <title>Introduction</title>
- <para>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 <ulink url="http://wiki.docbook.org/topic/DocBookAuthoringTools";>here</ulink>. It is currently recommended to use <ulink url="http://www.syntext.com/products/serna-free/ ">Syntext Serna Free</ulink> 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. </para>
- <para>One of the key concepts to keep in mind when authoring documentation in DocBook, or other
-presentation neutral formats, is that the <emphasis role="bold">content </emphasis>of the document should be considered in the first instance. The <emphasis role="bold">presentation </emphasis>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.</para>
- <para>It is good practise 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 <productname>Microsoft Word</productname> 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.</para>
- </section>
- <section id="docs_3">
- <title>Getting started with Launchpad</title>
- <para>Currently, the documentation system is part of the source code housed at <ulink url="https://launchpad.net/";>Launchpad</ulink>. Launchpad is a collaborative platform that enables multiple people to work on software projects collaboratively. In order for this to be possible, a version control system is necessary in order to manage all the changes that multiple users may make. Launchpad uses the <emphasis>Bazaar</emphasis> source control system. While it is beyond the scope of this document to describe the functionality of <emphasis>Bazaar</emphasis>, users who wish to create documentation will need to gain at
-least a basic understanding of how the system works. A basic guide is provided in the next section. </para>
- <para> 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 Launchpad login id, you will need to get one. This can be done <ulink url="https://launchpad.net/+login";>here</ulink>. Once you register with Launchpad, you will need to request access to the<emphasis> dhis2-documenters</emphasis> group. Login to Launchpad, and then request access <ulink url="https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs";>here</ulink>. 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 emails on the groups' list. </para>
- </section>
- <section id="docs_4">
- <title>Getting the document source</title>
- <para>In order to edit the documentation, you will need to download the source pages of the
-documentation to your computer. Launchpad uses a version control system known as bzr . There are different methods for getting Bazaar working on your system, depending on which operating system you are using. A good step-by-step guide for <productname>Microsoft</productname> operating systems can be viewed <ulink url="http://wiki.showmedo.com/index.php/Using_Launchpad_and_Bazaar#Steps_to_download_a_project_on_Launchpad_that_uses_Bazaar_with_only_one_branch";>here</ulink>. If you are using Linux, you will need to install bzr on your system through your package manager, or from source code.</para>
- <para>Once you have installed bzr on your system, you will need to download the document source.
-Just follow this procedure:</para>
- <orderedlist>
- <listitem>
- <para>Make sure you have Bazaar installed.</para>
- </listitem>
- <listitem>
- <para>Start Bazaar by right-clicking a folder if you are using <productname>Windows</productname> and selecting <command>Bzr Here</command>. If you use Linux, you can just create a folder to hold the document sources. You can place the document source in any folder you like.</para>
- </listitem>
- <listitem>
- <para>To download the latest revision of the DHIS2 documents project type: <command>bzr checkout lp:~dhis2-documenters/dhis2/dhis2-docbook-docs</command> if you are using Linux, or alternatively if you are using <productname>Windows</productname> type the url to the source code repository "<ulink url="https://bazaar.launchpad.net/%7Edhis2-documenters/dhis2/dhis2-docbook-docs";>lp:~dhis2-documenters/dhis2/dhis2-docbook-docs</ulink>"</para>
- </listitem>
- <listitem>
- <para>The download process should start and all the documentation source files will be
-downloaded to the folder that you specified.</para>
- </listitem>
- </orderedlist>
- </section>
- <section id="docs_5">
- <title>Editing the documentation</title>
- <para>Once you have downloaded the source, you should have a series of folders inside of the
-dhis2-docbook-docs directory. All documents should be placed in the <filename>dhis2-docbook-docs/src/docbkx/XX</filename> folder. Note that the <filename>XX</filename> represents the ISO 639-1 (two-letter) language code of the documentation. If you are developing English language documentation, place it inside the <filename>/dhis2-docbook-docs/src/docbkx/en/</filename> folder. Place any image files that may be linked to your document in the <filename>/dhis2-docbook-docs/src/docbkx/XX/resources/images</filename> folder and link these inside your DocBook document using a relative file link. When the documentation is built, in a separate step, the images will be automatically copied over to the correct directory during the build process.</para>
- </section>
- <section id="docs_6">
- <title>Using images</title>
- <para>Screen shots are very useful for providing information to users on how particular actions
-should be performed. DocBook has no intrinsic mechanisms to know exactly how an image should be rendered in the final document. Therefore, it is necessary to provide instructions through element attributes. The following XML code fragment demonstrates how an 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. </para>
- <literallayout><screenshot>
-<screeninfo>DHIS2 Login screen</screeninfo> <mediaobject> <imageobject> <imagedata fileref="dhis2_login_screen.jpg" format="JPG" width="80%"/> </imageobject> </mediaobject> </screenshot></literallayout>
- <para>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. </para>
- </section>
- <section id="docs_7">
- <title>Linking documents together</title>
- <para>DocBook provides a modular framework where many separate documents can be linked together
-into a master document. Fragments from different documents can also be reused in different contexts. It is therefore important to consider whether your document should be constructed as an article or a chapter. Chapters are essentially portions of a book, and can therefore be linked together into a larger document very easily. Articles are essentially standalone documents, but they can also be assembled together into a larger document at the component level. </para>
- <para>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. </para>
- <para>
-<literallayout> <section id="mod2_1">
-<title>Getting started with DHIS2</title> ....</literallayout> </para>
- <para>In order to include an article into a book, an Xinclude statement must be used. The
-following example shows how. </para>
- <para>
-<literallayout> <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"/> </literallayout>
-</para>
- <para>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). </para>
- <para>Including chapters in a book is very simple. The example below illustrates how: </para>
- <para>
-<literallayout> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhis2_user_man_
-mod1.xml" encoding="UTF-8"/> </literallayout>
-</para>
- <para>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. </para>
- </section>
- <section id="docs_8">
- <title>Handling multilingual documentation</title>
- <para>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 <filename>dhis2-docbook-docs/src/docbkx/</filename> 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 <ulink url="http://en.wikipedia.org/wiki/ISO_639-1";>here</ulink>. 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. </para>
- </section>
- <section id="docs_9">
- <title>Building the documentation</title>
- <para>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. </para>
- <para>Latest builds of the documentation are available </para>
- <section>
- <title>Building the documentation with Apache maven</title>
- <para>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 <ulink url="http://maven.apache.org/download.html";>here</ulink> or by installing it through your package manager if you are using Linux. Just execute the command <command>mvn clean package</command> on Windows or on Linux from the <filename>/dhis2-docbook-docs </filename>directory. Maven will start to download the necessary components to transform the
-documents into HMTL and PDF. 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 /<filename>dhis2-docbook-docs/target/docbkx</filename> directory. HTML documents will be in the HTML directory, and PDF documents will be in the PDF directory.</para>
- </section>
- <section>
- <title>Building with xmlto</title>
- <para><command>xmlto</command> is a useful utility available on Linux platforms for
-transforming DocBook documents into many different formats. More information on the package can be found <ulink url="http://cyberelk.net/tim/software/xmlto/";>here</ulink>. If you do not want to use Apache Maven for some reason, you can install <command>xmlto</command> through your package manager. Once you have installed <command>xmlto</command> you can just execute <command>xmlto <parameter>html</parameter><parameter>file_to_transform</parameter></command> where the <parameter>file_to_transform</parameter> parameter is the name of the file you wish to transform. There are many other formats available, such as PDF, PS, JavaHelp and others. </para>
- </section>
- </section>
- <section id="docs_10">
- <title>Committing your changes back to Launchpad</title>
- <para>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 <command>bzr add</command> 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.</para>
- <blockquote>
- <para><command>bzr update</command></para>
- </blockquote>
- <para>If there are conflicts, bazaar will notify you of this. Your conflicts can also be listed by using the <command>bzr conflicts</command> command. If there are conflicts in a file, bazaar will create three versions of the file:</para>
- <itemizedlist>
- <listitem>
- <para><emphasis role="italic">filename.BASE</emphasis></para>
- </listitem>
- <listitem>
- <para><emphasis role="italic">filename.THIS</emphasis></para>
- </listitem>
- <listitem>
- <para><emphasis role="italic">filename.OTHER</emphasis></para>
- </listitem>
- </itemizedlist>
- <para>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 <command>bzr resolve</command>. This will tell bazaar that the conflict is resolved, and clean up the BASE, THIS, OTHER files.</para>
- <para>Once your source code is updated and any conflicts resolved, commit you changes with an informative message about the changes you have made: </para>
- <para><blockquote>
- <para><command>bzr commit -m "Created Amharic translation of documentation"</command><command/></para>
- </blockquote></para>
- <para>Never commit code using <command>bzr push</command>, as this will overwrite any changes in the repository, and revision history will be lost. </para>
- <para>If you have any questions, or cannot find that you can get started, just send an email
-with your problem to <email>dhis2-documenters@xxxxxxxxxxxxxxxxxxx</email>.</para>
- </section>
-</chapter>
+<?xml version='1.0' encoding='UTF-8'?>
+<!-- This document was created with Syntext Serna Free. --><!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; [
+<!ENTITY br ''>]>
+<chapter>
+ <chapterinfo>
+ <title>DHIS 2 Documentation Guide</title>
+ <author>
+ <firstname>Jason</firstname>
+ <surname>Pickering</surname>
+ <affiliation>
+ <orgname/>
+ </affiliation>
+ </author>
+ <pubdate>14/09/09</pubdate>
+ <keywordset>
+ <keyword>DHIS2</keyword>
+ <keyword>documentation</keyword>
+ <keyword>DocBook</keyword>
+ </keywordset>
+ <revhistory>
+ <revision>
+ <revnumber>1</revnumber>
+ <date>29/09/09</date>
+ <revdescription>
+ <para>Added more information on getting started with bzr and DocBook</para>
+ </revdescription>
+ </revision>
+ <revision>
+ <revnumber>2</revnumber>
+ <date>28/10/09</date>
+ <revdescription>
+ <para> Added some more information on multilingual documents and editors.</para>
+ </revdescription>
+ </revision>
+ <revision>
+ <revnumber>3</revnumber>
+ <date>17/02/11</date>
+ <revdescription>
+ <para>Edited the parts on getting and committing code with bazaar from using branch and push to checkout and commit.</para>
+ </revdescription>
+ </revision>
+ </revhistory>
+ </chapterinfo>
+ <title>DHIS2 Documentation Guide</title>
+ <section id="docs_1">
+ <title>DHIS 2 Documentation System Overview</title>
+ <para remap="">DHIS 2 is a web-based aggregate information management system under very active development. Given the modular nature of the system, its wide user base and distributed, global nature of development, a comprehensive documentation system is required. An in-depth discussion of the need for documentation of DHIS 2 has been considered previously.<citation>Store2007</citation> <ulink url="http://www.docbook.org";>DocBook</ulink> is a comprehensive XML based system for creation of books, papers and other technical documents maintained by <ulink url=" http://www.oasis-open.org/";>OASIS</ulink> . </para>
+ </section>
+ <section id="docs_2">
+ <title>Introduction</title>
+ <para>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 <ulink url="http://wiki.docbook.org/topic/DocBookAuthoringTools";>here</ulink>. It is currently recommended to use <ulink url="http://www.syntext.com/products/serna-free/ ">Syntext Serna Free</ulink> 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. </para>
+ <para>One of the key concepts to keep in mind when authoring documentation in DocBook, or other
+presentation neutral formats, is that the <emphasis role="bold">content </emphasis>of the document should be considered in the first instance. The <emphasis role="bold">presentation </emphasis>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.</para>
+ <para>It is good practise 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 <productname>Microsoft Word</productname> 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.</para>
+ </section>
+ <section id="docs_3">
+ <title>Getting started with Launchpad</title>
+ <para>Currently, the documentation system is part of the source code housed at <ulink url="https://launchpad.net/";>Launchpad</ulink>. Launchpad is a collaborative platform that enables multiple people to work on software projects collaboratively. In order for this to be possible, a version control system is necessary in order to manage all the changes that multiple users may make. Launchpad uses the <emphasis>Bazaar</emphasis> source control system. While it is beyond the scope of this document to describe the functionality of <emphasis>Bazaar</emphasis>, users who wish to create documentation will need to gain at
+least a basic understanding of how the system works. A basic guide is provided in the next section. </para>
+ <para> 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 Launchpad login id, you will need to get one. This can be done <ulink url="https://launchpad.net/+login";>here</ulink>. Once you register with Launchpad, you will need to request access to the<emphasis> dhis2-documenters</emphasis> group. Login to Launchpad, and then request access <ulink url="https://code.launchpad.net/~dhis2-documenters/dhis2/dhis2-docbook-docs";>here</ulink>. 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 emails on the groups' list. </para>
+ </section>
+ <section id="docs_4">
+ <title>Getting the document source</title>
+ <para>In order to edit the documentation, you will need to download the source pages of the
+documentation to your computer. Launchpad uses a version control system known as bzr . There are different methods for getting Bazaar working on your system, depending on which operating system you are using. A good step-by-step guide for <productname>Microsoft</productname> operating systems can be viewed <ulink url="http://wiki.showmedo.com/index.php/Using_Launchpad_and_Bazaar#Steps_to_download_a_project_on_Launchpad_that_uses_Bazaar_with_only_one_branch";>here</ulink>. If you are using Linux, you will need to install bzr on your system through your package manager, or from source code.</para>
+ <para>Once you have installed bzr on your system, you will need to download the document source.
+Just follow this procedure:</para>
+ <orderedlist>
+ <listitem>
+ <para>Make sure you have Bazaar installed.</para>
+ </listitem>
+ <listitem>
+ <para>Start Bazaar by right-clicking a folder if you are using <productname>Windows</productname> and selecting <command>Bzr Here</command>. If you use Linux, you can just create a folder to hold the document sources. You can place the document source in any folder you like.</para>
+ </listitem>
+ <listitem>
+ <para>To download the latest revision of the DHIS2 documents project type: <command>bzr checkout lp:~dhis2-documenters/dhis2/dhis2-docbook-docs</command> if you are using Linux, or alternatively if you are using <productname>Windows</productname> type the url to the source code repository "<ulink url="https://bazaar.launchpad.net/%7Edhis2-documenters/dhis2/dhis2-docbook-docs";>lp:~dhis2-documenters/dhis2/dhis2-docbook-docs</ulink>"</para>
+ </listitem>
+ <listitem>
+ <para>The download process should start and all the documentation source files will be
+downloaded to the folder that you specified.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+ <section id="docs_5">
+ <title>Editing the documentation</title>
+ <para>Once you have downloaded the source, you should have a series of folders inside of the
+dhis2-docbook-docs directory. All documents should be placed in the <filename>dhis2-docbook-docs/src/docbkx/XX</filename> folder. Note that the <filename>XX</filename> represents the ISO 639-1 (two-letter) language code of the documentation. If you are developing English language documentation, place it inside the <filename>/dhis2-docbook-docs/src/docbkx/en/</filename> folder. Place any image files that may be linked to your document in the <filename>/dhis2-docbook-docs/src/docbkx/XX/resources/images</filename> folder and link these inside your DocBook document using a relative file link. When the documentation is built, in a separate step, the images will be automatically copied over to the correct directory during the build process.</para>
+ </section>
+ <section>
+ <title>DHIS2 Bibliography</title>
+ <para>DHIS2 has a rich set of academic literature which can serve as invaluable resources during implementations, project proposals and more detailed reading than what is appropriate for a general user manual. A specialized bibliography has been added to the source code of the application. <ulink url="http://www.bibtex.org";>BibTeX</ulink> is a specialized language which is widely used in the academic world to handle bibliographic databases. A large number of free and open source tools are capable of working with BibTeX. Currently, the recommended tool of choice for manipulating the DHIS2 bibliography is <ulink url="http://jabref.sourceforge.net/";>JabRef</ulink>. </para>
+ <para>To get started with the bibliography, download a copy of JabRef and open the <filename>/src/bibliography/dhis2_bibliography.bib file</filename>. You will need to add the custom export filters available in <filename>/src/bibliography/docbook44.layout</filename>. Consult the JabRef documentation for more information on how to use the custom export filters. Add some new references, then export the bibliography back to the <filename>/src/docbkx/en/dhis2_bibliography.xml</filename> file. The updated bibliography will automatically be included in the documentation. </para>
+ </section>
+ <section id="docs_6">
+ <title>Using images</title>
+ <para>Screen shots are very useful for providing information to users on how particular actions
+should be performed. DocBook has no intrinsic mechanisms to know exactly how an image should be rendered in the final document. Therefore, it is necessary to provide instructions through element attributes. The following XML code fragment demonstrates how an 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. </para>
+ <literallayout><screenshot>
+<screeninfo>DHIS2 Login screen</screeninfo> <mediaobject> <imageobject> <imagedata fileref="dhis2_login_screen.jpg" format="JPG" width="80%"/> </imageobject> </mediaobject> </screenshot></literallayout>
+ <para>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. </para>
+ </section>
+ <section id="docs_7">
+ <title>Linking documents together</title>
+ <para>DocBook provides a modular framework where many separate documents can be linked together
+into a master document. Fragments from different documents can also be reused in different contexts. It is therefore important to consider whether your document should be constructed as an article or a chapter. Chapters are essentially portions of a book, and can therefore be linked together into a larger document very easily. Articles are essentially standalone documents, but they can also be assembled together into a larger document at the component level. </para>
+ <para>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. </para>
+ <para>
+<literallayout> <section id="mod2_1">
+<title>Getting started with DHIS2</title> ....</literallayout> </para>
+ <para>In order to include an article into a book, an Xinclude statement must be used. The
+following example shows how. </para>
+ <para>
+<literallayout> <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"/> </literallayout>
+</para>
+ <para>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). </para>
+ <para>Including chapters in a book is very simple. The example below illustrates how: </para>
+ <para>
+<literallayout> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhis2_user_man_
+mod1.xml" encoding="UTF-8"/> </literallayout>
+</para>
+ <para>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. </para>
+ </section>
+ <section id="docs_8">
+ <title>Handling multilingual documentation</title>
+ <para>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 <filename>dhis2-docbook-docs/src/docbkx/</filename> 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 <ulink url="http://en.wikipedia.org/wiki/ISO_639-1";>here</ulink>. 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. </para>
+ </section>
+ <section id="docs_9">
+ <title>Building the documentation</title>
+ <para>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. </para>
+ <para>Latest builds of the documentation are available </para>
+ <section>
+ <title>Building the documentation with Apache maven</title>
+ <para>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 <ulink url="http://maven.apache.org/download.html";>here</ulink> or by installing it through your package manager if you are using Linux. Just execute the command <command>mvn clean package</command> on Windows or on Linux from the <filename>/dhis2-docbook-docs </filename>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 /<filename>dhis2-docbook-docs/target/docbkx</filename> directory in respective sub-directories.</para>
+ </section>
+ <section>
+ <title>Building with xmlto</title>
+ <para><command>xmlto</command> is a useful utility available on Linux platforms for
+transforming DocBook documents into many different formats. More information on the package can be found <ulink url="http://cyberelk.net/tim/software/xmlto/";>here</ulink>. If you do not want to use Apache Maven for some reason, you can install <command>xmlto</command> through your package manager. Once you have installed <command>xmlto</command> you can just execute <command>xmlto <parameter>html</parameter><parameter>file_to_transform</parameter></command> where the <parameter>file_to_transform</parameter> parameter is the name of the file you wish to transform. There are many other formats available, such as PDF, PS, JavaHelp and others. </para>
+ </section>
+ </section>
+ <section id="docs_10">
+ <title>Committing your changes back to Launchpad</title>
+ <para>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 <command>bzr add</command> 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.</para>
+ <blockquote>
+ <para><command>bzr update</command></para>
+ </blockquote>
+ <para>If there are conflicts, bazaar will notify you of this. Your conflicts can also be listed by using the <command>bzr conflicts</command> command. If there are conflicts in a file, bazaar will create three versions of the file:</para>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis role="italic">filename.BASE</emphasis></para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="italic">filename.THIS</emphasis></para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="italic">filename.OTHER</emphasis></para>
+ </listitem>
+ </itemizedlist>
+ <para>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 <command>bzr resolve</command>. This will tell bazaar that the conflict is resolved, and clean up the BASE, THIS, OTHER files.</para>
+ <para>Once your source code is updated and any conflicts resolved, commit you changes with an informative message about the changes you have made: </para>
+ <para><blockquote>
+ <para><command>bzr commit -m "Created Amharic translation of documentation"</command></para>
+ </blockquote></para>
+ <para>Never commit code using <command>bzr push</command>, as this will overwrite any changes in the repository, and revision history will be lost. </para>
+ <para>If you have any questions, or cannot find that you can get started, just send an email
+with your problem to <email>dhis2-documenters@xxxxxxxxxxxxxxxxxxx</email>.</para>
+ </section>
+</chapter>
