Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdeedu@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 655 insertions, 0 deletions

diff --git a/doc/kgeography/index.docbook b/doc/kgeography/index.docbook
new file mode 100644
index 00000000..3e6b2af1
--- /dev/null
+++ b/doc/kgeography/index.docbook
@@ -0,0 +1,655 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kgeography "<application>KGeography</application>">
+  <!ENTITY kappname "&kgeography;">
+  <!ENTITY package "playground/edu">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE"> 
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The &kgeography; Handbook</title>
+
+<authorgroup>
+<author>
+<personname>
+<firstname>Anne-Marie</firstname>
+<surname>Mahfouf</surname>
+</personname>
+<email>&Anne-Marie.Mahfouf.mail;</email>
+</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+
+<copyright>
+<year>2005</year>
+<holder>&Anne-Marie.Mahfouf;</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2005-08-02</date>
+<releaseinfo>0.4</releaseinfo>
+
+<!-- Abstract about this handbook -->
+
+<abstract>
+<para>
+&kgeography; is a geography learning tool for &kde;. Right now it has six usage modes:
+<itemizedlist>
+<listitem>
+<para>Browse the maps clicking in a map division to see its name, capital and flag</para>
+</listitem>
+<listitem>
+<para>The game tells you a map division name and you have to click on it</para>
+</listitem>
+<listitem>
+<para>The game tells you a capital and you have to guess the division it belongs to</para>
+</listitem><listitem>
+<para>The game tells you a division and you have to guess its capital</para>
+</listitem><listitem>
+<para>The game shows you a map division flag and you have to guess its name</para>
+</listitem><listitem>
+<para>The game tells you a map division name and you have to guess its flag</para>
+</listitem>
+</itemizedlist>
+</para>
+
+</abstract>
+
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>kdeedu</keyword>
+<keyword>KGeography</keyword>
+<keyword>geography</keyword>
+<keyword>maps</keyword>
+<keyword>countries</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<!-- The introduction chapter contains a brief introduction for the
+application that explains what it does and where to report
+problems. Basically a long version of the abstract.  Don't include a
+revision history. (see installation appendix comment) -->
+
+<para>
+&kgeography; is a geography learning tool for &kde;. It allows you to learn about the political divisions of some countries (divisions, capitals of those divisions and their associated flags if there are some).
+</para>
+<para>
+Maps available in current release are: Africa, Asia, Austria, Brazil, Canada, China, Europe, France, Germany, Italy, Italy by provinces, North and Central America, Norway, Poland, South America, Spain, USA and the world.
+</para>
+</chapter>
+
+<chapter id="quick-start">
+<title>Quick Start to &kgeography;</title>
+<para>
+When you run &kgeography; for the first time, it first asks you to choose a map to start with.
+<screenshot>
+<screeninfo>Here's a screenshot of &kgeography; at first start</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="first-start1.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Here's a screenshot of &kgeography; at first start</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+<para>
+Here we choose Canada
+<screenshot>
+<screeninfo>Canada is choosen</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="first-start2.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Canada is choosen</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+<para>
+And &kgeography; main window appears with the map of Canada:
+<screenshot>
+<screeninfo>&kgeography; main window</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="first-start3.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&kgeography; main window</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+<para>
+You can then choose what type of learning or testing you want to do by looking at the menu on the left:
+<screenshot>
+<screeninfo>&kgeography; menu</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="first-start4.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&kgeography; menu</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+<para>
+Browse the map: a &LMB; click on an area of the map will display informations about that area:
+<screenshot>
+<screeninfo>Browse the map</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="first-start5.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Browse the map</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+<para>
+Click division in the map: you are first asked how many questions you want
+<screenshot>
+<screeninfo>How many questions</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="first-start6.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>How many questions</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+<para>
+Then you are asked to click on a specific province:
+<screenshot>
+<screeninfo>Click on a province</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="first-start7.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Click on a province</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+<para>
+When you finish all the questions, a result dialog is shown with your correct and uncorrect answers:
+<screenshot>
+<screeninfo>Your results</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="first-start8.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Your results</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+<para>
+Guess a division from its capital: you are asked to find the name of a province among a choice of 4 given its capital:
+<screenshot>
+<screeninfo>Guess a division from its capital</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="first-start9.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Guess a division from its capital</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+<para>
+And the results are displayed when the test is finished:
+<screenshot>
+<screeninfo>Your results</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="first-start10.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Your results</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+<para>
+Guess the capital from a division: you have a capital and four province names and you must choose the correct one. As before, at the end a result dialog is shown.
+</para>
+<para>
+Guess division from its flag: a flag is shown and you must find the province it belongs to.
+<screenshot>
+<screeninfo>the flag question</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="first-start11.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>the flag question</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+<para>
+Guess the flag of a division: a province name is given and you must find the correct flag among four.
+<screenshot>
+<screeninfo>match the flag with the province</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="first-start12.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>match the flag with the province</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+</chapter>
+
+<chapter id="using-kapp">
+<title>Using &kgeography;</title>
+
+<para>
+&kgeography; displays informations about some countries and tests you about those informations.
+
+
+<screenshot>
+<screeninfo>Here's a screenshot of &kgeography;</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="kgeography.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Screenshot</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+
+
+<sect1 id="kapp-features">
+<title>More &kgeography; features</title>
+
+<para>Another feature of &kgeography; is the possibility of zoom on a map.
+<screenshot>
+<screeninfo>Zoom</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="zoom.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Zoom</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+While in zoom mode, you can press &RMB; to go back to the original map size (the <guimenuitem>Original Size</guimenuitem> action has the same effect). Use the scroll bars to move around the zoomed map or use the <guimenuitem>Move</guimenuitem> action that will allow you to drag the map using &LMB;.
+</para>
+
+</sect1>
+</chapter>
+
+<!--<chapter id="teachers-parents">
+<title>Teachers/Parents guide to &kgeography; </title>
+ This chapter should emphasize the educational aims of your app and
+guide the parent/teacher on how to help the child using it.
+</chapter>-->
+
+<chapter id="how-to-maps">
+<title>How to make maps</title>
+<para>A map in &kgeography; is made by two files, one is the image of the map and the other one is its description. </para>
+<sect1 id="helper-tool">
+<title>Helper tool</title>
+<para>
+You can find <ulink url="http://kgeography.berlios.de/gen_map.pl">here</ulink> a tool (made by Yann Verley) which helped him with the map of France. To find out its usage, simply execute it and read the help message. It basically creates the <literal role="extension">.kgm</literal> file from a plain text file and creates a file with the colors it has assigned to each division, so you can fill the map according to them.</para>
+</sect1>
+<sect1 id="description-file">
+<title>Description file</title>
+<para>
+ The description file is needed and its file extension is <literal role="extension">.kgm</literal>. It should begin with <sgmltag class="starttag">map</sgmltag> and end with <sgmltag class="endtag">map</sgmltag>.
+</para>
+<para>
+ Inside of those tags there should be:
+<itemizedlist>
+<listitem>
+  <para><sgmltag class="starttag">mapFile</sgmltag> and <sgmltag class="endtag">mapFile</sgmltag>: the name of the file (without any path) containing the map image, &eg; <quote>europe.png</quote>.</para>
+</listitem>
+<listitem>
+  <para><sgmltag class="starttag">name</sgmltag> and <sgmltag class="endtag">name</sgmltag>: the name of map, &eg; <quote>Europe</quote>.</para>
+</listitem>
+<listitem>
+  <para>A <sgmltag class="starttag">division</sgmltag> and <sgmltag class="endtag">division</sgmltag> for each division in the map.</para>
+</listitem>
+</itemizedlist>
+ </para>
+<para>
+ Each division has these tags:
+<itemizedlist>
+<listitem>
+  <para><sgmltag class="starttag">name</sgmltag> and <sgmltag class="endtag">name</sgmltag>: the name of the division, &eg; <quote>Albania</quote>.</para>
+</listitem>
+<listitem>
+  <para><sgmltag class="starttag">capital</sgmltag> and <sgmltag class="endtag">capital</sgmltag>: the name of the capital of the division, &eg; <quote>Tirana</quote>.</para>
+</listitem>
+<listitem>
+  <para><sgmltag class="starttag">ignore</sgmltag> and <sgmltag class="endtag">ignore</sgmltag>: can be set to <userinput>yes</userinput>,  <userinput>allowClickMode</userinput> and <userinput>no</userinput>. If this tag is set to <userinput>yes</userinput> then the division will be ignored when asking for divisions in that map. It is then as if this division does not exist in &kgeography; quiz modes. If this tag is set to <userinput>allowClickMode</userinput> then &kgeography; will ask for the division in the <guibutton>Click Division in Map...</guibutton> mode but not in other quiz modes. Setting this tag to <userinput>no</userinput> means the division will appear in all modes (browse and quizzes). This tag is optional and when there is no <sgmltag class="starttag">ignore</sgmltag> tag that means as it is set to <userinput>no</userinput>. For example <quote>Algeria</quote> has this tag set to <userinput>yes</userinput> in the <quote>Europe</quote> map which means that <quote>Algeria</quote> will not be part of any quiz in the <quote>Europe</quote> map.</para>
+</listitem>
+<listitem>
+  <para><sgmltag class="starttag">flag</sgmltag> and <sgmltag class="endtag">flag</sgmltag>: the file (without any path) containing the flag of the division, &eg; <quote>albania.png</quote>. This tag is optional. Not needed for the divisions whose <sgmltag class="starttag">ignore</sgmltag> tag is set to <userinput>yes</userinput>.</para>
+</listitem>
+<listitem>
+  <para><sgmltag class="starttag">color</sgmltag> and <sgmltag class="endtag">color</sgmltag>: the color the division has in the map.</para>
+</listitem>
+</itemizedlist>
+ </para>
+<para>
+ The color is defined using three tags:
+<itemizedlist>
+<listitem>
+  <para><sgmltag class="starttag">red</sgmltag> and <sgmltag class="endtag">red</sgmltag>: red component of the color. Valid values are between 0 and 255.</para>
+</listitem>
+<listitem>
+  <para><sgmltag class="starttag">green</sgmltag> and <sgmltag class="endtag">green</sgmltag>: green component of the color. Valid values are between 0 and 255.</para>
+</listitem>
+<listitem>
+  <para><sgmltag class="starttag">blue</sgmltag> and <sgmltag class="endtag">blue</sgmltag>: blue component of the color. Valid values are between 0 and 255.</para>
+</listitem>
+</itemizedlist>
+</para>
+<tip>
+ <para>
+ It is convenient to create 2 or 3 false divisions like <quote>Water</quote>, <quote>Frontier</quote> and <quote>Coast</quote> and set them with the <sgmltag class="starttag">ignore</sgmltag> tag set to <userinput>yes</userinput>.
+ </para>
+</tip>
+ <important>
+   <para>All names (capitals and divisions) must be in English.</para>
+</important>
+</sect1>
+<sect1 id="map-file">
+<title>Map file</title>
+<para>
+ The map file is quite simple but laborious to create. It has to be in <acronym>PNG</acronym> format.
+ You can find some maps to transform at <ulink url="https://www.cia.gov/cia/publications/factbook/docs/refmaps.html">Cia Reference Maps</ulink>. If no map fits your needs you can download the <ulink url="https://www.cia.gov/cia/publications/factbook/reference_maps/pdf/political_world.pdf">political world map</ulink>, take a screenshot of it and work from it.
+ Each division in the map should have one and only one color. To achieve this you can use image processing programs like <application>The Gimp</application> and <application>Kolourpaint</application>.
+</para>
+</sect1>
+<sect1 id="flags">
+<title>Flags</title>
+<para>
+ If you have used the <sgmltag class="starttag">flag</sgmltag> tag you should provide the flag files. They have to be in <acronym>PNG</acronym> format and better if they are 300x200 pixels and you provide a <acronym>SVG</acronym> file for it. To obtain <acronym>SVG</acronym> flags of almost all countries in the world and some other divisions, you can consult the <ulink url="http://www.sodipodi.com/index.php3?section=clipart/flags">Sodipodi flags collection</ulink>.
+</para>
+</sect1>
+<sect1 id="how-to-test">
+<title>How to test</title>
+<para>
+ Before sending your map to Albert <email>tsdgeos@terra.es</email>, you should test it to see it has no errors. To achieve that, you have to do the following:
+<itemizedlist>
+<listitem>
+  <para>Put the map description and map image file in <filename class="directory">$<envar>KDEDIR</envar>/share/apps/kgeography/</filename></para>
+</listitem>
+<listitem>
+  <para>Put the flag <acronym>PNG</acronym> files (if any) in <filename class="directory">$<envar>KDEDIR</envar>/share/apps/kgeography/flags/</filename></para>
+</listitem>
+</itemizedlist>
+ Once that has been done you should be able of opening your map from inside &kgeography;.
+ </para>
+ <para>
+ If you don't know which is your <filename class="directory">$<envar>KDEDIR</envar></filename>, type <userinput><command>kde-config</command> <option>--prefix</option></userinput> in a shell.
+</para>
+</sect1>
+<sect1 id="non-political-maps">
+<title>Non political maps</title>
+<para> Is it possible to do non-political maps? Yes, it is!
+<screenshot>
+<screeninfo>Example of how to create a non political map</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="river.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Example of how to create a non political map</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+</para>
+<para>
+ Of course, the division concept can be extended to a river or a mountain. During the creation of the map, you should keep in mind that most times the river or mountain will be too small that you should provide an additional clicking area.
+ In this example the river would have the maroon area and color &lt;20,76,34&gt; as its identifier.
+</para>
+</sect1>
+</chapter>
+
+<chapter id="commands">
+<title>Command Reference</title>
+
+<!-- (OPTIONAL, BUT RECOMMENDED) This chapter should list all of the
+application windows and their menubar and toolbar commands for easy reference.
+Also include any keys that have a special function but have no equivalent in the
+menus or toolbars. This may not be necessary for small apps or apps with no tool
+or menu bars. -->
+
+<sect1 id="kapp-mainwindow">
+<title>The main &kgeography; window</title>
+
+<sect2>
+<title>The <guimenu>File</guimenu> Menu</title>
+<para>
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Open Map...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Open the choose map dialog</action></para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
+</shortcut>
+<guimenu>File</guimenu>
+<guimenuitem>Quit</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Quits</action> &kgeography;</para></listitem>
+</varlistentry>
+</variablelist>
+</para>
+
+</sect2>
+
+<sect2>
+<title>The <guimenu>View</guimenu> Menu</title>
+<para>
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<guimenu>View</guimenu>
+<guimenuitem>Zoom</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Goes in zoom mode</action></para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<guimenu>View</guimenu>
+<guimenuitem>Original Size</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Sets</action> the map back to its original size</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<guimenu>View</guimenu>
+<guimenuitem>Move</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Moves</action> the current map</para></listitem>
+</varlistentry>
+</variablelist>
+</para>
+
+</sect2>
+
+<sect2>
+<title>The <guimenu>Settings</guimenu> Menu</title>
+<para>
+<variablelist>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show/Hide Toolbar</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Show/Hide the &kgeography; toolbar.</action></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Shortcuts...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Configure key shortcuts for &kgeography;.</action></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Toolbars...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Configure the &kgeography; toolbar.</action></para></listitem>
+</varlistentry>
+
+</variablelist>
+</para>
+
+</sect2>
+<sect2>
+<title>The <guimenu>Help</guimenu> Menu</title>
+
+<!-- Assuming you have a standard help menu (help, what's this, about -->
+<!-- &kgeography;, about KDE) then the documentation is already written. -->
+<!-- The following entity is valid anywhere that a variablelist is -->
+<!-- valid.  -->
+
+&help.menu.documentation;
+
+</sect2>
+
+</sect1>
+</chapter>
+
+<!--<chapter id="faq">
+<title>Questions and Answers</title>
+
+
+&reporting.bugs;
+&updating.documentation;
+
+<qandaset id="faqlist">
+<qandaentry>
+<question>
+<para>My Mouse doesn't work. How do I quit &kgeography;?</para>
+</question>
+<answer>
+<para>You silly goose! Check out the <link linkend="commands">Commands
+Section</link> for the answer.</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>Why am I not able to twiddle my documents?</para>
+</question>
+<answer>
+<para>You can only twiddle your documents if you have the foobar.lib
+installed.</para>
+</answer>
+</qandaentry>
+</qandaset>
+</chapter>-->
+
+<chapter id="credits">
+
+<!-- Include credits for the programmers, documentation writers, and
+contributors here. The license for your software should then be included below
+the credits with a reference to the appropriate license file included in the KDE
+distribution. -->
+
+<title>Credits and License</title>
+
+<para>
+&kgeography;
+</para>
+<para>
+Program copyright 2004-2005 Albert Astals Cid <email>tsdgeos@terra.es</email>
+</para>
+
+
+<para>
+Documentation Copyright &copy; 2005 &Anne-Marie.Mahfouf; <email>&Anne-Marie.Mahfouf.mail;</email>
+</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+&underFDL;
+&underGPL;
+
+</chapter>
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="getting-kapp">
+<title>How to obtain &kgeography;</title>
+
+<!-- This first entity contains boiler plate for applications that are
+part of KDE CVS.  You should remove it if you are releasing your
+application -->
+
+&install.intro.documentation;
+
+</sect1>
+
+
+<sect1 id="compilation">
+<title>Compilation and Installation</title>
+
+<!-- This entity contains the boilerplate text for standard -->
+<!-- compilation instructions.  If your application requires any -->
+<!-- special handling, remove it, and replace with your own text. -->
+
+&install.compile.documentation;
+
+</sect1>
+
+
+</appendix>
+
+&documentation.index;
+</book>
+
+<!--
+Local Variables:
+mode: xml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+vim:tabstop=2:shiftwidth=2:expandtab 
+-->