diff options
Diffstat (limited to 'doc/kgeography/index.docbook')
| -rw-r--r-- | doc/kgeography/index.docbook | 655 |
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, ⪚ <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: +<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 <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 +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 © 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 +--> |