<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN"
 "dtd/kdedbx45.dtd" [
  <!ENTITY kappname "&khangman;">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->
]>

<book id="khangman" lang="&language;">

<bookinfo>
<title>The &khangman; Handbook</title>

<authorgroup>
<author>
<firstname>Anne-Marie</firstname>
<surname>Mahfouf</surname>
<affiliation>
<address>&Anne-Marie.Mahfouf.mail;</address>
</affiliation>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>


<copyright>
<year>2001</year><year>2009</year>
<holder>&Anne-Marie.Mahfouf;</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>


<date>2016-04-25</date>
<releaseinfo>3.0 (Applications 16.04)</releaseinfo>

<abstract>
<para>
&khangman; is the classic hangman game for children.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdeedu</keyword>
<keyword>KHangMan</keyword>
<keyword>hangman</keyword>
<keyword>game</keyword>
<keyword>child</keyword>
<keyword>words</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>
&khangman; is a game based on the well-known hangman game. It is aimed at
children aged six and over. The game has several categories of words to play
with and among them: Animals, Clothing, Computers, Currencies, Easy and Fruits.
A word is picked at random, the letters are hidden, and you
must guess the word by trying one letter after another. Each time you guess a
wrong letter, part of a picture of a hangman is drawn. You must guess the word
before being hanged! You have 10 tries.
</para>

</chapter>

<chapter id="using-khangman">
<title>Using &khangman;</title>

<screenshot>
<screeninfo>Here's a screenshot of &khangman; when you start it for the first time
</screeninfo><mediaobject>
<imageobject>
<imagedata fileref="khangman-main.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>&khangman; screenshot</phrase>
</textobject>
</mediaobject>
</screenshot>

<para>
Here you can see &khangman; as it is the first time you run it. Category is
Animals, language is default (English here, the default is your current &kde;
language if the data exists), the theme is <quote>Notes</quote>. Any changes in category,
language or theme (background) are written in the configuration file and
restored in your next game.
</para>

<para>
Please note how easy it is to change the theme, just click on the button on
the bottom toolbar. Getting a new word and quitting the game are also easily done by
clicking on the corresponding buttons on the toolbars.
</para>

<sect1 id="general-usage">
<title>General usage</title>

<para>A word is chosen and its letters are displayed as an underscore (_)
symbol. You know how many letters there are in the word. You have to guess the
word by trying one letter after another. You type the letter on the keyboard 
or select them with the &LMB;. If the letter belongs to the word the background
color of the letter will change to green, otherwise to red.</para>

<para>The letter keys in the game window allow you to play &khangman; in foreign 
languages without changing your keyboard layout.</para>

<para>The word is picked at random and it is not the same as the previous word.
</para>

<important><para>All the words are nouns (there are no verbs or
adjectives, &etc;).</para></important>

<para>If you need help guessing the word, you can click on the <inlinemediaobject><imageobject> <imagedata
fileref="help-hint.png" format="PNG"/></imageobject></inlinemediaobject> icon in the
toolbar and a hint will be displayed to give you some clue about the word.
Clicking this icon again will hide the hint. 
</para>

<para>Hints are not displayed by default. 
</para>

<para> Usually, it is not important whether you type in lowercase or uppercase.
The program converts all input into an uppercase letter. The program does that 
automatically. </para>

<para> 
The current category, wins and losses are displayed in the window.
</para>

<para>
Each time you guess a letter that is not in the word, another part of the
hangman is drawn. You have 10 tries to guess the word. After that, the correct
answer is displayed.
</para>

<para>
There are several categories of words available, depending on the selected 
language. The program scans for all data files in all
languages and uses &kanagram; words files as well.
</para>
<!--FIXME no difficulty levels in KF5?
<para>
In the easy category, the words are quite simple and related to everyday life.
It
is suitable for children from 6 to 9.  The animals category contains only names
of
animals so they are easier to find. Some of them are easy, others are more
difficult. In the medium category, the words are longer and more difficult. It
is
suitable for ages 9+. The hard category is just that, hard, &ie; the words are
difficult to spell and not very well known. This category is challenging, even
for
adults.
</para>
-->
<para>After a word is guessed (or the hangman is completed), you are
congratulated and the next word is presented.
To quit the game click the <inlinemediaobject><imageobject><imagedata 
fileref="quit.png" format="PNG"/></imageobject></inlinemediaobject> icon in the top toolbar.
</para>

<para>You type the letter you want to try on the keyboard or select it
with the &LMB;. If the letter belongs to the word the key is highlighted in green
and the letter its place, as many times as it appears in the word. 
If the letter does not belong to the word, the key is highlighted red. You have ten
tries and after that you lose and the correct word is displayed.
</para>

<para>During the game, you can choose to start a new game by clicking on the 
<inlinemediaobject><imageobject><imagedata fileref="go-next.png" format="PNG"/></imageobject></inlinemediaobject>
on the bottom toolbar. You can also change the category of words clicking the current category.</para>

<para>The look can easily be changed with theme button on the bottom toolbar.</para>

<!--Not in kf5?
<para>You can also play the game with a local file installed on your machine
that you will open using the <guimenu>Game</guimenu> menu and choosing
<guimenuitem>Open</guimenuitem>.</para>
-->
</sect1>

<sect1 id="languages">
<title>Playing in different languages</title>
<para>
You can play &khangman; in many languages including: Brazilian Portuguese,
Bulgarian, Catalan, Czech, Danish, Dutch, English (US and GB), Finnish, French,
German, Hungarian, Irish (Gaelic), Italian, Norwegian (Bokm&#229;l), Norwegian
(Nynorsk), Polish, Portuguese, Romanian, Spanish, Serbian (Latin and Cyrillic),
Slovenian,
Tajik, Swedish, Russian and Turkish. You can even try Chinese if you install
the files from &kanagram;.
</para>

<para>
By default, after the first installation of &khangman;, only English and your
&kde; language if it is one of the above and if you have the corresponding
kde-i18n package will be installed. For example if you are a Danish user and if
you have &kde; in Danish, in Language you will see two
items: English and Danish and Danish will be the default. </para>

<para>
You can still play &khangman; in other languages. It is very easy to add new
data in &khangman;. All you need is a working Internet connection. You click on
<inlinemediaobject><imageobject><imagedata fileref="get-hot-new-stuff.png" format="PNG"/></imageobject></inlinemediaobject>
and a dialog appears, similar to this one:
</para>

<screenshot>
<screeninfo>The Get New Words dialog for &khangman;</screeninfo>
<mediaobject><imageobject>
<imagedata fileref="getnewstuff.png" format="PNG"/>
</imageobject><textobject>
<phrase>The Get New Words dialog for &khangman;</phrase>
</textobject>
</mediaobject>
</screenshot>

<para>
Click on the language name you want to install and then on the
<guibutton>Install</guibutton> button. If the language is successfully
installed, a green tick is displayed in front of the language name and the
<guibutton>Install</guibutton> turns to <guibutton>Uninstall</guibutton>. The
data is immediately installed and available in &khangman;. You click on the
<guibutton>Close</guibutton> button to close the Get New Words dialog (if you
want another data file, you can repeat these steps). </para>

<para>
You can then easily change the language by clicking the language button 
and choose the new language. </para>

<para>
Please note that the special characters in a language are displayed on the keyboard.
Here you see buttons with an icon of each special character per language like &eacute;
in French for example. Clicking on such a button will select the corresponding
letter. You can of course also use the keyboard layout corresponding to the language.
</para>

<!--FIXME still true in KF5? apparently khangman installs Dustismo_Roman + Domestic_Manners fonts
<important><para>
Please note that you need Arial and URW Bookman fonts in order to display the
special characters correctly in some languages. Provided you have those fonts
installed, &khangman; will automatically use them. If you see small squares
instead of letters, then you may not have one of these fonts installed. Type
<command>fonts:/</command> into the &konqueror; address bar to check which fonts
you have installed. </para></important> -->
</sect1>

<sect1 id="few-tips">
<title>A few tips</title>
<para>
In English, try to guess the vowels first. Then have a go with the most common
consonants:
l, t, r, n, s.
</para>
<para>When you see <quote>io</quote>, try n after that, in French and English.
</para>

<para>You have to either type the accented letters yourself or click on them. When you type <quote>a</quote>, only
<quote>a</quote> is displayed and you have to type for example
&atilde; for this letter to be displayed.
</para>
<para> Did you know? In English, the most common letter is e (12.7%), followed
by t (9.1%) then a (8.2%), i (7.0%) and n (6.7%). </para>
</sect1>

</chapter>

<chapter id="menus">
<title>Menubar and Toolbars</title>

<sect1 id="mainwindow">
<title>The Main &khangman; Window</title>

<screenshot>
<screeninfo>&khangman; Desert theme</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="khangman-desert.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>&khangman; Desert theme</phrase>
</textobject>
</mediaobject>
</screenshot>

<para> Here you have &khangman; with the Desert theme, French language and
category <quote>Animaux</quote>. The special characters for French are shown here.</para>

<para>The game has the main toolbar at the top of the window:</para>

<simplelist>
<member>
<inlinemediaobject><imageobject><imagedata fileref="play.png" format="PNG"/></imageobject></inlinemediaobject> or 
<inlinemediaobject><imageobject><imagedata fileref="pause.png" format="PNG"/></imageobject></inlinemediaobject> 
Start or stop a game
</member>
<member><inlinemediaobject><imageobject><imagedata fileref="settings_icon.png" format="PNG"/></imageobject></inlinemediaobject>
Open the settings dialog
</member>
<member><inlinemediaobject><imageobject><imagedata fileref="dialog-information.png" format="PNG"/></imageobject></inlinemediaobject>
About &khangman;
</member>
<member><inlinemediaobject><imageobject><imagedata fileref="about-kde.png" format="PNG"/></imageobject></inlinemediaobject>
About &kde;
</member>
<member><inlinemediaobject><imageobject><imagedata fileref="handbook.png" format="PNG"/></imageobject></inlinemediaobject>
View the &khangman; handbook
</member>
<member><inlinemediaobject><imageobject><imagedata fileref="get-hot-new-stuff.png" format="PNG"/></imageobject></inlinemediaobject>
Download new language files from the Internet
</member>
<member><inlinemediaobject><imageobject><imagedata fileref="quit.png" format="PNG"/></imageobject></inlinemediaobject>
Quit &khangman;
</member>
</simplelist>

<para>The bottom toolbar is displayed only when playing a game, if you pause the game this toolbar is hidden:</para>

<simplelist>
<member><inlinemediaobject><imageobject><imagedata fileref="help-hint.png" format="PNG"/></imageobject></inlinemediaobject>
- Display a hint about the word to guess
</member>
<member>A button to change the category</member>
<member>Language selection</member>
<member>Theme selection</member>
<member>Reveal the word to guess</member>
<member><inlinemediaobject><imageobject><imagedata fileref="go-next.png" format="PNG"/></imageobject></inlinemediaobject>
Load the next word and start a new game
</member>
</simplelist>

<para> All words are nouns. No verbs, no adjectives. The chosen category
 is then displayed on the statusbar.</para>
<para>Only letters are allowed to be typed in the text box.</para>
</sect1>

<sect1 id="settings">
<title>Settings</title>

<screenshot>
<screeninfo>&khangman; settings</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="settings.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>&khangman; settings</phrase>
</textobject>
</mediaobject>
</screenshot>

<!--FIXME Not displayed ?
Hint show duration
The duration for showing the hint for the actual word
-->
<para>The <guilabel>Word resolve time in seconds</guilabel> sets the
maximum allowed time for resolving the word in &khangman;. Default value is 120 seconds.
Young children will need more time to understand the game, for adults reduce 
the resolve time to keep the game exciting.
</para>

<para> <!--FIXME Can not edit this value - what is the usecase?-->
<guilabel>Score Multiplying Factor</guilabel> determines the factor by which 
the scores will be multiplied.
</para>

<para>
If you check <guilabel>Sounds</guilabel> then a sound will be played on new game 
and another sound will be played when you win a game.
</para>

</sect1>

</chapter>

<chapter id="developers">
<title>Developer's Guide to &khangman;</title>

<sect1 id="changing-words">
<title>How to translate words in a new language for the game</title>

<para>Please follow the procedure and then send the files tarred and gzipped
to the <ulink url="https://mail.kde.org/mailman/listinfo/kde-edu">kde-edu mailinglist</ulink>.
</para>
<para>
Please have a look in &khangman; <inlinemediaobject><imageobject><imagedata 
fileref="get-hot-new-stuff.png" format="PNG"/></imageobject></inlinemediaobject>
in the top toolbar to see if your language is available yet. 
If it is, then you can check if it contains <emphasis>hints</emphasis>.
</para>
<para>The standard list words are stored in 4 separate files, so to make
different categories. The files are in
<filename class="directory">/khangman/data/</filename>. The file
<filename>easy.kvtml</filename> is for category easy, the file
<filename>medium.kvtml</filename> is for category medium, the file
<filename>animals.kvtml</filename> is for category animals and the file
<filename>hard.kvtml</filename> is for category hard.</para>
<para>English is the default and thus the only language to be shipped with
&khangman;. All other languages data are put in the corresponding kde-l10n
module.
</para>
<procedure>
<step>
<para>The files use the kvtml format. The tag <sgmltag
class="starttag">text</sgmltag> is for the word and the tag <sgmltag
class="starttag">comment</sgmltag> is for the hint, those are within a <sgmltag
class="starttag">entry</sgmltag> tag. Please try to match the hint with the
category of difficulty. The category <guimenuitem>Easy</guimenuitem> will
require an easy hint but the category
<guimenuitem>Hard</guimenuitem> will require the definition in the dictionary.
Try not to use words of
the same family in the hint, that would give the word away too easily!</para>

<para> Note that you must use <emphasis role="bold">UTF-8 encoding</emphasis>
when editing the files. If your editor cannot do this, try using &kwrite; or
&kate;. When opening a file in &kwrite; or &kate; you can select utf8 encoding
with the combo box at the top of the file open dialog.</para>

<para>An example of a kvtml file is as follow:</para>
<programlisting><markup>
&lt;?xml version="1.0"?&gt; 
&lt;DOCTYPE kvtml PUBLIC "kvtml2.dtd"
"http://edu.kde.org/kanagram/kvtml2.dtd"&gt; 
&lt;kvtml version="2.0"&gt; 
&lt;information&gt;
    &lt;generator&gt;converter&lt;/generator&gt;
    &lt;title&gt;Animals&lt;/title&gt;&lt;!--Translate tag content--&gt;
    &lt;comment&gt;Animals from across the
planet&lt;/comment&gt;&lt;!--Translate tag content--&gt;
  &lt;/information&gt;
  &lt;identifiers&gt;
    &lt;identifier id="0" &gt;
      &lt;locale&gt;en&lt;/locale&gt;
    &lt;/identifier&gt;
  &lt;/identifiers&gt;
...
&lt;entry id="0" &gt;
      &lt;inactive&gt;false&lt;/inactive&gt;
      &lt;inquery&gt;false&lt;/inquery&gt;
      &lt;translation id="0" &gt;
        &lt;text&gt;bear&lt;/text&gt;&lt;!--Translate all text tags
content--&gt;
        &lt;comment&gt;Large heavy animal with thick
fur&lt;/comment&gt;&lt;!--Translate all comment tags content--&gt;
      &lt;/translation&gt;
    &lt;/entry&gt;
...
&lt;/kvtml&gt;
</markup></programlisting>
</step>
<step>
<para>At the beginning of the file, you should translate the content of the
<sgmltag class="starttag">title</sgmltag> and
the <sgmltag class="starttag">comment</sgmltag> tags which are within the
<sgmltag class="starttag">information</sgmltag> tag. The title will be the one
that will appear in the Category menu of the game (where the user chooses the
file to play with).
</para>
</step>
<step>
<para>Then within the <sgmltag class="starttag">identifier</sgmltag> tag, please
put your language code instead of en in
<sgmltag class="starttag">locale</sgmltag>.</para>

<para>Please don't translate the file name itself as filenames should never
contain any special characters. Thus please save your file with the same English
filename.</para>
</step>
<step>
<para>
Edit the kvtml files with a text editor (it will be easier if you use the &XML;
syntax highlighting) and replace each word inside the 
<sgmltag class="starttag">text</sgmltag> tag with a translated word and each
hint inside a <sgmltag class="starttag">comment</sgmltag> with a translated
hint. It is not really important that the exact meaning is preserved, but try to
keep the length and category of difficulty roughly the same.
</para> 

<para>You can include words with white space or - in them, in that case the
white space or the - will be shown instead of the _. Please contact the 
<ulink url="https://mail.kde.org/mailman/listinfo/kde-edu">kde-edu mailinglist</ulink> if
there is anything special related to your language so I can adapt the code to it
(especially the special and accented characters).
</para>
</step>	

<step>
<para>You can just translate the words but you can also adapt them
following the category and add new words if you want. For example,
<quote>table</quote> is in category easy in English but in your language,
it can be category medium. Feel free to adapt the files to your language
needs. The number of words in a file is not important, you can add
some if you want.</para>

<para>Remember that all words are nouns.</para>

</step>

<step>
<para>You can then commit your files in 
<emphasis>l10n-kf5/&lt;lang_code&gt;/data/kdeedu/kdeedu-data/</emphasis>. Do not
forget to update the CMakeLists.txt file as well. Please contact the 
<ulink url="https://mail.kde.org/mailman/listinfo/kde-edu">kde-edu mailinglist</ulink> if you need further
information. When you send the files, please do not forget to mention any
<emphasis role="bold">special characters</emphasis> used in your language (put
them in a text file, one per line and add this file in the tarball) and please
mention any other specificity.</para>
<para><emphasis>Please never commit files in a BRANCH as it might break the
game.</emphasis></para>
</step>
</procedure>
<para>Many thanks for your contribution!</para>
</sect1>

<sect1 id="internal">
<title>What is stored by &khangman; and where</title>
<para>
When you get a new language via <menuchoice><guimenu>Game</guimenu>
<guimenuitem>Get Words in New Language...</guimenuitem></menuchoice>, the new
language data is stored in <filename
class="directory">$XDG_DATA_HOME/share/apps/kvtml/</filename> in the language code
folder. The available language dir names are also stored in the &khangman;
config file in <filename>$XDG_DATA_HOME/share/config/khangmanrc</filename>.
</para>
<para>
The provider name (i.e. the address of the website where to download the new
languages) is stored in
<filename>$XDG_DATA_DIRS/share/apps/khangman/khangmanrc</filename>.
</para>
<para>
The English language (default) and the user language from his i18n package(s)
(if available) are stored in <filename
class="directory">$XDG_DATA_DIRS/share/apps/kvtml</filename>.
</para>
<para>
In the configuration file, stored for each user in
<filename>$XDG_DATA_HOME/share/config/khangmanrc</filename> are saved all the game
settings such as the background, last category played, ... plus the files that
were downloaded from the <guilabel>Get Hot New Stuff!</guilabel> dialog.
</para>
</sect1>
</chapter>

<chapter id="credits">

<title>Credits and License</title>

<para>
&khangman;
</para>
<para>
Program copyright 2001-2007 &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;
</para>
<para>
Contributors:
<itemizedlist>
<listitem><para>Hangman graphics: Renaud Blanchard
<email>kisukuma@chez.com</email></para> </listitem>
<listitem><para>Sounds: Ludovic Grossard
<email>ludovic.grossard@libertysurf.fr</email></para> </listitem>
<listitem><para>Former maintainer: &Primoz.Anzur;
&Primoz.Anzur.mail;</para> </listitem>
<listitem><para>Swedish data files, coding help, transparent pictures and i18n
fixes: Stefan Asserhäll 
<email>stefan.asserhall@telia.com
</email></para> </listitem>
<listitem><para>Spanish data files: eXParTaKus
<email>expartakus@expartakus.com
</email></para> </listitem>
<listitem><para>Spanish data hints: Rafael Beccar
<email>rafael.beccar@kdemail.net
</email></para> </listitem>
<listitem><para>Danish data files: Erik Kjaer Pedersen
<email>erik@mpim-bonn.mpg.de
</email></para> </listitem>
<listitem><para>Finnish data files: Niko Lewman
<email>niko.lewman@edu.hel.fi
</email></para> </listitem>
<listitem><para>Brazilian Portuguese data files: João Sebastião de Oliveira
Bueno
<email>gwidion@mpc.com.br
</email></para> </listitem>
<listitem><para>Catalan data files: Antoni Bella
<email>bella5@teleline.es
</email></para> </listitem>
<listitem><para>Italian data files: Giovanni Venturi
<email>jumpyj@tiscali.it
</email></para> </listitem>
<listitem><para>Dutch data files: Rinse
<email>rinse@kde.nl
</email></para> </listitem>
<listitem><para>Portuguese data files: Pedro Morais
<email>morais@kde.org
</email></para> </listitem>
<listitem><para>Serbian (Cyrillic and Latin) data files: Chusslove Illich
<email>chaslav@sezampro.yu
</email></para> </listitem>
<listitem><para>Slovenian data files: Jure Repinc
<email>jlp@holodeck1.com
</email></para> </listitem>
<listitem><para>Czech data files: Luk&aacute;&scaron; Tinkl
<email>lukas@kde.org
</email></para> </listitem>
<listitem><para>Tajik data files: Roger Kovacs
<email>rkovacs@khujand.org
</email></para> </listitem>
<listitem><para>Norwegian (Bokm&#229;l) data files: Torger &#197;ge Sinnes
<email>torg-a-s@online.no
</email></para> </listitem>
<listitem><para>Hungarian data files: Tamas Szanto
<email>tszanto@mol.hu
</email></para> </listitem>
<listitem><para>Norwegian (Nynorsk) data files: Gaute Hvoslef Kvalnes
<email>gaute@verdsveven.com
</email></para> </listitem>
<listitem><para>Turkish data files: Mehmet &Ouml;zel
<email>mehmet_ozel2003@hotmail.com
</email></para> </listitem>
<listitem><para>Bulgarian data files: Radostin Radnev
      <email>radnev@yahoo.com
</email></para> </listitem>
<listitem><para>Irish (Gaelic) data files: Kevin Patrick Scannell
    <email>scannell@slu.edu
</email></para> </listitem>
<listitem><para>Coding help: &Robert.Gogolok;
&Robert.Gogolok.mail;</para> </listitem>
<listitem><para>Coding help: Benjamin Meyer
<email>ben@meyerhome.net</email></para> </listitem>
<listitem><para>Code fixes: Lubos Lun&agrave;k
<email>l.lunak@kde.org</email></para> </listitem>
<listitem><para>Code fixes: Albert Astals Cid
&Albert.Astals.Cid.mail;</para> </listitem>
<listitem><para>Usability study: Celeste Paul
<email>seele@obso1337.org</email></para> </listitem>
</itemizedlist>
</para>

<para>
Documentation copyright 2001-2007 &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
&underFDL;               <!-- FDL: do not remove -->
&underGPL;        	 <!-- GPL License -->

</chapter>

&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes: nil
sgml-general-insert-case: lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->