dhis2-devs team mailing list archive
-
dhis2-devs team
-
Mailing list archive
-
Message #03615
[Branch ~dhis2-documenters/dhis2/dhis2-docbook-docs] Rev 67: Added import-export draft document. Minor alterations to documentation guide. Added math and xsl ...
------------------------------------------------------------
revno: 67
committer: Jason Pickering <jason@jason-laptop>
branch nick: dhis2-docbook-docs
timestamp: Thu 2009-12-10 16:21:14 +0200
message:
Added import-export draft document. Minor alterations to documentation guide. Added math and xsl resources.
added:
src/docbkx/en/dhis2_user_man_mod7.xml
src/docbkx/en/resources/images/import_export/
src/docbkx/en/resources/images/import_export/Import_export_main.png
src/docbkx/en/resources/images/import_export/export_file_popup.png
src/docbkx/en/resources/images/import_export/export_to_dhis2.png
src/docbkx/en/resources/images/import_export/export_to_dhis2.xcf
src/docbkx/en/resources/images/import_export/metadata_detail.png
src/docbkx/en/resources/images/import_export/metadata_export.png/
src/docbkx/en/resources/images/import_export/metdata_export.png
src/docbkx/en/resources/images/indicator.png
src/docbkx/en/resources/math/
src/docbkx/en/resources/math/indicator.xml
src/docbkx/en/resources/xsl/
src/docbkx/en/resources/xsl/docbook-fo.xsl
modified:
readme.txt
src/docbkx/en/dhis2_documentation_guide.xml
src/docbkx/en/dhis2_user_manual_en.xml
src/docbkx/en/resources/glossary/glossary_en.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 'readme.txt'
--- readme.txt 2009-12-08 18:15:27 +0000
+++ readme.txt 2009-12-10 14:21:14 +0000
@@ -6,4 +6,5 @@
mvn package
-
+For further information, contact the groups mailing list at
+dhis2-documenters@xxxxxxxxxxxxxxxxxxx
=== modified file 'src/docbkx/en/dhis2_documentation_guide.xml'
--- src/docbkx/en/dhis2_documentation_guide.xml 2009-12-09 07:27:27 +0000
+++ src/docbkx/en/dhis2_documentation_guide.xml 2009-12-10 14:21:14 +0000
@@ -135,7 +135,7 @@
<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. Place any image files that may be linked to your document in the
+ 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
@@ -145,7 +145,7 @@
<section id="docs_6">
<title>Using images</title>
<para>Screenshots 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 screenshots in landscape format, this seems to be an appropriate amount. </para>
+ The following XML code fragment demonstrates how an image can be specified to occupy 80% of the available page width. For screenshots in landscape format, this seems to be an appropriate amount. You may need to experiment a bit to obtain a proper widht 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>
@@ -158,16 +158,22 @@
</section>
<section id="docs_7">
<title>Linking documents together</title>
- <para>DocBook provides a modular framework where many seperate documents can be linked together into a master document. Fragments from different documents can also be reused in different contexts. DocBook provides a mechanism to assign an id to a XML . In the example below, a section has been assigned an id. This id must be unique within the document. </para>
- <para><literallayout> <sect1 id="mod2_1">
+ <para>DocBook provides a modular framework where many seperate 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 ot resuse this section in a seperate document, an Xinclude statement must be used. The following example shows how. </para>
+ ....</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 filename 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 explicity 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>
@@ -175,14 +181,14 @@
</section>
<section id="docs_9">
<title>Building the documentation</title>
- <para/>
+ <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 stylesheets 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
- format, such as HTML or PDF, you will need to install the Apache Maven
+ 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. A sample build
- file has been included as part of the documentation source. Just execute
+ 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
@@ -196,7 +202,7 @@
</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 informtion 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> paramater is the name of the file you wish to transform. There are many other formats available, such as PDF, PS, JavaHelp and others. </para>
+ <para><command>xmlto</command> is a useful utility available on Linux platforms for transforming DocBook documents into many different formats. More informtion 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> paramater 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">
=== added file 'src/docbkx/en/dhis2_user_man_mod7.xml'
--- src/docbkx/en/dhis2_user_man_mod7.xml 1970-01-01 00:00:00 +0000
+++ src/docbkx/en/dhis2_user_man_mod7.xml 2009-12-10 14:21:14 +0000
@@ -0,0 +1,118 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "docbookV4.4/docbookx.dtd" []>
+<chapter>
+ <title>Import and export of data with DHIS2</title>
+ <highlights>
+ <para><emphasis>Learning objectives:</emphasis></para>
+ <para>
+After reading this module you will be able to understand:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+Why do we need functions of export and import data.</para>
+ </listitem>
+ <listitem>
+ <para>How to export data from DHIS2</para>
+ </listitem>
+ <listitem>
+ <para>
+How to import data into DHIS2</para>
+ </listitem>
+ </itemizedlist>
+ </highlights>
+ <section>
+ <title>What is import and export?</title>
+ <para>In a primary health system, the HMIS typically involves a distributed application, where the same application is running in different geographical locations (PHCs,CHCs, hospitals, districts, and state). Most of these physical locations do not have Internet connectivity, and hence they work offline. At some point (normally at the district level), the data needs to be synchronized in order to have a consolidated database for the a particular geographical region. For this, it is important to be able to export data from one location (which is working offline, say at the health facility level) to another one say at the district level where the data would need to be imported. This feature of exporting and importing is thus a crucial function of a HMIS. This feature also helps us overcome the dependency on Internet to some degree, as data updates can be transferred via USB key where there is no connectivity, or through email where there is limited Internet connectivity. DHIS 2 provides robust export-import functionality to fulfill these needs.
+</para>
+ <section>
+ <title>Online and offline export </title>
+ <para>In the case on online data entry, all data is saved into one database only. In an offline deployment, each deployment will have a separate database in their local system. So the data will be stored in their local database. In an offline deployment, after the data entry is finished, it will need to be manually sent to the next level of where the application is running. In an online application, however, that is not required, as all data is stored at a central location using the Internet.
+</para>
+ </section>
+ <section>
+ <title>Exporting from DHIS2</title>
+ <para>The export option can be made use of by selecting it as follows.
+The import or export is available only when the selected organization (source/destination) has defined datasets. This is because datasets help to define which data is to be or is being exported. Further, which specific data elements get exported is determined by the composition of the dataset being exported.
+If there are no datasets defined for an organization unit, it indicates that no data values are registered for this level of organization or lower.
+To access the main Import-Export module, choose <guimenu>Services->Import-Export</guimenu></para>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="resources/images/import_export/Import_export_main.png"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ <para>The exported data values are stored in an ‘xml file’. The file name is defined by the name of the source organization unit and the period to allow the receiving organization unit to identify the source and the period of the export file. The xml is placed in your home directory (On Windows this is normally <filename>C:\Documents and Settings\</filename> under the subdirectories <filename>/dhis / import-export</filename>.
+</para>
+ <section>
+ <title>Exporting data to other DHIS2 systems</title>
+ <para>Once the data export screen is displayed, select the Organisation unit, period and dataset for which data export should be selected.Finally click on the export option that will be available on the lower left side of displayed screen.
+If there are no datasets defined for an organization unit, it indicates that no data values are registered for this level of organization or lower.
+</para>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="resources/images/import_export/export_to_dhis2.png"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ <para>A popup save option will appear on the displayed screen (see picture below) prompting the saving of the exported data. You may save the export folder on your desktop or any other folder by selecting the ‘Save to Disk’ option from the popup prompt.
+</para>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="resources/images/import_export/export_file_popup.png"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ </section>
+ <section>
+ <title>Exporting metadata to other DHIS2 systems</title>
+ <para/>
+ <section>
+ <title>Metadata export</title>
+ <para>Metadata is "data about data". In the context of DHIS2, metadata consists of definitions of data elements, indicators, the structure and names contained in the organizational hierarchy, and other options. Click on the "Metadata export" link from the main "Data export" screen in order to access this. Just select the feature that you wish to export and click "Export". This metadata file can then be transmitted just like a data file, except it will contain information on the definitions of the various features, as opposed to the values of the data themselves. </para>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="resources/images/import_export/metdata_export.png"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ </section>
+ <section>
+ <title>Detailed metadata export</title>
+ <para>The "Detailed metadata" function will allow you to export specifc data element and indicator definitions. Just click "Detailed Metadata Export" and select the data elements and indicators that you wish to export. Click "Export" and save the file to a desired location. This file can then be transmitted via email or USB key to other DHIS2 installations. </para>
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="resources/images/import_export/metadata_detail.png"/>
+ </imageobject>
+ </mediaobject>
+ </screenshot>
+ </section>
+ </section>
+ <section>
+ <title>IXF data export</title>
+ <para>DHIS2 support export to the Indicator Exchange Format 2 developed by UNAIDS. The IXF data exchange standard has been implented ,with various levels of compatibility, between several information management systems including CRIS version 2, DevInfo version 5, KIDS developed by FAO, DHIS 1.4, DHIS2, and HealthMapper version 4 developed by WHO. A more detailed discussion on the use of the IXF data exchange format is discussed in depth <ulink url="http://data.unaids.org/pub/BaseDocument/2007/cris_de_web_final_en.pdf";>here</ulink>. </para>
+ <para>The IXF data export is essentially the same as a standard DHIS 2 DXF export, but results in a file format that is compatible with IXF 2. </para>
+ </section>
+ <section>
+ <title>IXF Metadata export</title>
+ <para>The IXF detailed metadata export provides the same functionality of the standard DHIS2 detailed metadata export, except that the resulting file is compatible with the IXF data exchange format. </para>
+ </section>
+ <section>
+ <title>DHIS 1.4 Metadata export</title>
+ <para>The DHIS 1.4 Metadata export functionality provides the same functionality as the standard DHIS2 metadata export, except that the resulting file can be used to transmit metadata information to DHIS 1.4 systems. </para>
+ </section>
+ <section>
+ <title>DHIS 1.4 Detailed Metadata Export</title>
+ <para>The DHIS 1.4 Metadata export functionality provides the same functionality as the detailed DHIS2 metadata export, except that the resulting file can be used to transmit metadata information to DHIS 1.4 systems. Simply select the data elements and indicators that you want and click "Export" to begin the export process.</para>
+ </section>
+ <section>
+ <title>PDF Metadata Export</title>
+ <para/>
+ </section>
+ </section>
+ </section>
+</chapter>
=== modified file 'src/docbkx/en/dhis2_user_manual_en.xml'
--- src/docbkx/en/dhis2_user_manual_en.xml 2009-12-09 08:02:26 +0000
+++ src/docbkx/en/dhis2_user_manual_en.xml 2009-12-10 14:21:14 +0000
@@ -5,6 +5,7 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_mod1.xml" encoding="UTF-8"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_mod2.xml" encoding="UTF-8"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_mod3.xml" encoding="UTF-8"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_mod7.xml" encoding="UTF-8"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_user_man_mod11.xml" encoding="UTF-8"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="dhis2_gis_user_manual_en.xml" encoding="UTF-8"/>
<appendix>
=== modified file 'src/docbkx/en/resources/glossary/glossary_en.xml'
--- src/docbkx/en/resources/glossary/glossary_en.xml 2009-12-09 08:49:34 +0000
+++ src/docbkx/en/resources/glossary/glossary_en.xml 2009-12-10 14:21:14 +0000
@@ -37,7 +37,13 @@
<glossentry>
<glossterm>Data element</glossterm>
<glossdef>
- <para>A data element is the fundemental building block of DHIS2. Essentially it is a data value that has been actually observed or recorded. As an example the data element "Number of fully immunized children" would refer to the number of children that received this particular service. Data elements are always linked to a period as as well as an organizational unit. They optionally may be linked to other dimensions. </para>
+ <para>A data element is the fundemental building block of DHIS2. It is an atomic unit of data with well-defined meaning. Essentially it is a data value that has been actually observed or recorded which is further characterized by a number of dimensions. As an example the data element "Number of fully immunized children" would refer to the number of children that received this particular service. Data elements are always linked to a period as as well as an organizational unit. They optionally may be linked to other dimensions. </para>
+ </glossdef>
+ </glossentry>
+ <glossentry>
+ <glossterm>Dimension</glossterm>
+ <glossdef>
+ <para>A dimension is used to categorize data elements during analysis. Dimensions provide a mechanism to group and filter data based on common characteristics. Typically, related data elements may be aggregated or filtered during analysis with the use of dimensions. Dimensions may be a member of a hierarchy. For instance the "Period" dimension may be broken down into "Day->Month->Quarter->Year". </para>
</glossdef>
</glossentry>
</glossdiv>
@@ -76,7 +82,14 @@
<glossentry>
<glossterm>Indicator</glossterm>
<glossdef>
- <para>The divisor of an indicator. Can be composed of multiple data elements with the use of an indicator formula.</para>
+ <para>The divisor of an indicator. Can be composed of multiple data elements with the use of an indicator formula.<equation>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="../images/indicator.png"/>
+ </imageobject>
+ </mediaobject>
+ </equation></para>
+ <para>This is obviously a very generalized example. The numerator and indicator themselves can be composed of various data elements, factors, and the four basic operands (addition, multiplication, division and subtraction). </para>
</glossdef>
</glossentry>
</glossdiv>
=== added directory 'src/docbkx/en/resources/images/import_export'
=== added file 'src/docbkx/en/resources/images/import_export/Import_export_main.png'
Binary files src/docbkx/en/resources/images/import_export/Import_export_main.png 1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/import_export/Import_export_main.png 2009-12-10 14:21:14 +0000 differ
=== added file 'src/docbkx/en/resources/images/import_export/export_file_popup.png'
Binary files src/docbkx/en/resources/images/import_export/export_file_popup.png 1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/import_export/export_file_popup.png 2009-12-10 14:21:14 +0000 differ
=== added file 'src/docbkx/en/resources/images/import_export/export_to_dhis2.png'
Binary files src/docbkx/en/resources/images/import_export/export_to_dhis2.png 1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/import_export/export_to_dhis2.png 2009-12-10 14:21:14 +0000 differ
=== added file 'src/docbkx/en/resources/images/import_export/export_to_dhis2.xcf'
Binary files src/docbkx/en/resources/images/import_export/export_to_dhis2.xcf 1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/import_export/export_to_dhis2.xcf 2009-12-10 14:21:14 +0000 differ
=== added file 'src/docbkx/en/resources/images/import_export/metadata_detail.png'
Binary files src/docbkx/en/resources/images/import_export/metadata_detail.png 1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/import_export/metadata_detail.png 2009-12-10 14:21:14 +0000 differ
=== added directory 'src/docbkx/en/resources/images/import_export/metadata_export.png'
=== added file 'src/docbkx/en/resources/images/import_export/metdata_export.png'
Binary files src/docbkx/en/resources/images/import_export/metdata_export.png 1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/import_export/metdata_export.png 2009-12-10 14:21:14 +0000 differ
=== added file 'src/docbkx/en/resources/images/indicator.png'
Binary files src/docbkx/en/resources/images/indicator.png 1970-01-01 00:00:00 +0000 and src/docbkx/en/resources/images/indicator.png 2009-12-10 14:21:14 +0000 differ
=== added directory 'src/docbkx/en/resources/math'
=== added file 'src/docbkx/en/resources/math/indicator.xml'
--- src/docbkx/en/resources/math/indicator.xml 1970-01-01 00:00:00 +0000
+++ src/docbkx/en/resources/math/indicator.xml 2009-12-10 14:21:14 +0000
@@ -0,0 +1,10 @@
+<mml:math display = 'block'>
+ <mml:mrow>
+ <mml:mi>indicator</mml:mi>
+ <mml:mo>=</mml:mo>
+ <mml:mfrac>
+ <mml:mi>numerator</mml:mi>
+ <mml:mi>denominator</mml:mi>
+ </mml:mfrac>
+ </mml:mrow>
+</mml:math>
=== added directory 'src/docbkx/en/resources/xsl'
=== added file 'src/docbkx/en/resources/xsl/docbook-fo.xsl'
--- src/docbkx/en/resources/xsl/docbook-fo.xsl 1970-01-01 00:00:00 +0000
+++ src/docbkx/en/resources/xsl/docbook-fo.xsl 2009-12-10 14:21:14 +0000
@@ -0,0 +1,7 @@
+<?xml version='1.0'?>
+<xsl:stylesheet
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; version="1.0">
+
+<xsl:import href="urn:docbkx:stylesheet" />
+<xsl:param name="html.stylesheet" select="'../css/docbook_bsd.css'"/>
+</xsl:stylesheet>
