dhis2-devs team mailing list archive

[noreply@xxxxxxxxxxxxx]

------------------------------------------------------------
revno: 47
committer: Jason Pickering <jason@jason-laptop>
branch nick: dhis2-docbook-docs
timestamp: Mon 2009-11-23 10:59:59 +0200
message:
  Added more details to the documentation guide on the use of images and Xinclude statements. 
modified:
  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/docbkx/en/dhis2_documentation_guide.xml'
--- src/docbkx/en/dhis2_documentation_guide.xml	2009-11-21 17:50:00 +0000
+++ src/docbkx/en/dhis2_documentation_guide.xml	2009-11-23 08:59:59 +0000
@@ -1,6 +1,6 @@
 <?xml version='1.0' encoding='UTF-8'?>
-<!-- This document was created with Syntext Serna Free. -->
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; []>
+<!-- This document was created with Syntext Serna Free. --><!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"; [
+<!ENTITY br ''>]>
 <article>
   <articleinfo>
     <title>DHIS 2 Documentation Guide</title>
@@ -143,6 +143,33 @@
     process.</para>
   </section>
   <section>
+    <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>
+    <literallayout>&lt;screenshot&gt;
+      &lt;screeninfo&gt;DHIS2 Login screen&lt;/screeninfo&gt;
+      &lt;mediaobject&gt;
+        &lt;imageobject&gt;
+          &lt;imagedata fileref=&quot;dhis2_login_screen.jpg&quot; format=&quot;JPG&quot; width=&quot;80%&quot;/&gt;
+        &lt;/imageobject&gt;
+      &lt;/mediaobject&gt;
+    &lt;/screenshot&gt;</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>
+    <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>  &lt;sect1 id=&quot;mod2_1&quot;&gt;
+    &lt;title&gt;Getting started with DHIS2&lt;/title&gt;
+</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>
+    <para><literallayout> &lt;chapter&gt;
+    &lt;title&gt;Getting started with DHIS2&lt;/title&gt;
+    &lt;xi:include xmlns:xi=&quot;http://www.w3.org/2001/XInclude&quot; href=&quot;dhis2_user_man_mod2.xml&quot; xpointer=&quot;mod2_1&quot; encoding=&quot;UTF-8&quot;/&gt;
+</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>
+  </section>
+  <section>
     <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>