<!-- 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>
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.
<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, ⪚ <quote>europe.png</quote>.</para>
</listitem>
<listitem>
<para><sgmltag class="starttag">name</sgmltag> and <sgmltag class="endtag">name</sgmltag>: the name of map, ⪚ <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, ⪚ <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, ⪚ <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, ⪚ <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:
<para>Put the flag <acronym>PNG</acronym> files (if any) in <filename class="directory">$<envar>TDEDIR</envar>/share/apps/kgeography/flags/</filename></para>
If you don't know which is your <filename class="directory">$<envar>TDEDIR</envar></filename>, type <userinput><command>kde-config</command> <option>--prefix</option></userinput> in a shell.
<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 <20,76,34> 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
