summaryrefslogtreecommitdiffstats
path: root/doc/khangman/index.docbook
blob: 1025b5d233c8ac62e3384068de485cbf1dc121cd (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
 "dtd/kdex.dtd" [
  <!ENTITY kappname "&khangman;">
  <!ENTITY package "tdeedu">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->
]>

<book 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>2005</year>
<holder>&Anne-Marie.Mahfouf;</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>


<date>2006-02-01</date>
<releaseinfo>1.6</releaseinfo>

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

<keywordset>
<keyword>KDE</keyword>
<keyword>tdeedu</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 four levels of difficulty: Animals (animals
words), Easy, Medium and Hard. 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="khangman1.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. Level is Animals,
language is default (English here, the default is your current &kde; language if
the data exists), the theme is "Sea". Any changes in level, 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 level and the theme, just
click on the combo boxes on the toolbar. Getting a new word and quitting the
game are also easily done by clicking on the corresponding buttons on the
toolbar.
</para>

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

<!-- FIXME: A word cannot really be displayed and hidden at the same time, -->
<!-- although I cannot think of a better way to phrase this -->
<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 enter the letter in the text box and you either press the Enter key or click on the Guess button to see if the letter belongs or not to the word. </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>
Usually, it is not important whether you type in lowercase or uppercase. The program
converts all input into lowercase (except for German words beginning with an uppercase letter). The program does that automatically.
</para>

<para> 
The current level and current language are displayed in the statusbar.
</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 4 levels: easy, medium, hard and animals, plus levels for other
topics in some languages. The program scans for all data files in all
languages.
 </para>
 
<para>
In the easy level, the words are quite simple and related to everyday life. It
is suitable for children from 6 to 9.  The animals level contains only names of
animals so they are easier to find. Some of them are easy, others are more
difficult. In the medium level, the words are longer and more difficult. It is
suitable for ages 9+. The hard level is just that, hard, &ie; the words are
difficult to spell and not very well known. This level is challenging, even for
adults.
</para>

<para>After a word is guessed (or the hangman is completed), you are
prompted for another word and you can either use the
<keycap>Y</keycap> or <keycap>N</keycap> keys or the mouse to answer
yes or no. If you say <guilabel>No</guilabel>, the game quits. If you
say <guilabel>Yes</guilabel>, another word is ready to be guessed.
</para>

<para>You type the letter you want to try in the text box (the mouse cursor is
ready in the text box) and you hit the &Enter; key. If the letter belongs to the
word, it takes its place, as many times as it appears in the word. If the
letter does not belong to the word, it goes in the Misses field and a further
part of the hangman is drawn on the right. 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 going in the
<guimenu>Game</guimenu> menu and choosing <guimenuitem>New</guimenuitem> or
clicking on the <guiicon>New</guiicon> icon on the toolbar. You can also change
the level with the level button on the toolbar (this will bring you a new word
for the new level).</para>

<para>
Future improvement (in &kde; 4) will allow you to create your own words file.
</para>
</sect1>

<sect1 id="languages">
<title>Playing in different languages</title>
<para>
You can play &khangman; in twenty-four languages: Brazilian Portuguese, Bulgarian, Catalan, Czech, Danish, Dutch, English,
Finnish, French, German, Hungarian, Irish (Gaelic), Italian, Norwegian (Bokm&#229;l), Norwegian (Nynorsk), Portuguese, Spanish, Serbian (Latin and Cyrillic), Slovenian, Tajik, Swedish, Russian and Turkish.
</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 tde-i18n package will be installed. For example if you are a Danish user and if you have &kde; in Danish, in <guimenu>Languages</guimenu> 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 the <guimenu>File</guimenu> menu and then on <guimenu>Get Words in New Language...</guimenu>. 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. You click on the <guibutton>Close</guibutton> button to close the Get New Words dialog (if you want another language, you get repeat these steps).
</para>

<para>
You can then easily change the language by going in the <guimenu>Languages</guimenu> and choose the new language.
</para>

<para>
Please note that you can now type the special characters in a language by displaying the <interface>Special Characters Toolbar</interface>.
This toolbar holds buttons with an icon of each special character per language like &eacute; in French for example. Clicking on such a
button will write the corresponding letter in the input line and you validate your choice with Enter. You can of course also use the keyboard layout corresponding to the language. This toolbar can be shown or hidden. The setting is restored next time you play &khangman;.
</para>

<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>
Try to guess the vowels first. Then have a go with the most common consonants:
l, t, r, n, s
</para>
<para>corresponding:
when you see <quote>io</quote>, try n after that, in French and English.
</para>
<para>
In Brazilian Portuguese, Catalan, Spanish and Portuguese, the accented
vowels can be discovered when you type the non accented corresponding
vowel. For example, all the accented <quote>a</quote> are displayed in
the word when you type <quote>a</quote>. This is when <guilabel>Type accented
letters</guilabel> on the <guilabel>Languages</guilabel> page of &khangman;'s
configuration dialog is not checked. When <guilabel>Type accented
letters</guilabel> is checked, then you have to type
the accented letters yourself. 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>

<para>The <guimenu>Game</guimenu> menu has 3 items:
<guimenuitem>New</guimenuitem>, <guimenuitem>Get Words in New Language...</guimenuitem> and
<guimenuitem>Quit</guimenuitem>.</para>

<para><guimenuitem>New</guimenuitem> brings you a new game, &ie; a new
word to guess, in the same level you already
are. <guimenuitem>Get Words in New Language...</guimenuitem> will display the Get New Stuff dialog to allow you to download data in a new language. <guimenuitem>Quit</guimenuitem> quits the game by closing the
main window and writing the actual settings in the configuration
file.</para>

<para>
The <guimenu>Level</guimenu> menu allows you to choose the level, &ie; the difficulty of the word to guess.
</para>

<para>
The <guimenu>Languages</guimenu> menu allows you to change the language the words are displayed in.
</para>

<para>
The <guimenu>Look</guimenu> menu proposes two themes: the <guimenuitem>Sea Theme</guimenuitem> and the <guimenuitem>Desert Theme</guimenuitem>. The background and the font colors changes for each theme.
</para>

<para>
The <guimenuitem>Settings</guimenuitem> menu allows you to configure
&khangman; easily.  First, <guimenuitem>Toolbars</guimenuitem> and
<guimenuitem>Show Statusbar</guimenuitem> give you the possibility to
hide/show the toolbars and statusbar.
</para>

<para>There are two toolbars: the main one which is the one on top
with the buttons and combo boxes and the
<guilabel>Special Characters</guilabel> toolbar which, when it is shown, is
on the bottom. This toolbar has buttons with the special characters
for each language: accented letters and other special characters. This
allows users to easily play in another language without having to configure
a new keyboard layout. You click on a special letter and it is
displayed as the letter to try. Pressing &Enter; will make the program
see if the letter is present in the word or not. The toolbar can be
hidden if you don't want it. This is saved in the configuration file
so if the toolbar is hidden, it will be hidden next time you run
&khangman;.
</para>
<tip>
<para>
It is of course possible to move the toolbars around. Put the mouse
cursor on the small handle on the left of the toolbar, press the &LMB;
and drag the toolbar to position it on the screen where you want
it. If you point the mouse on one of the toolbars and press the right
mouse button, a context menu appears to let you choose different
options for the toolbar.
</para>
</tip>
<para>
<guimenuitem>Configure Shortcuts...</guimenuitem> is a standard &kde; setting dialog that allows you to
choose different shortcut keys for different actions. For example,
<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> is the
standard shortcut for <guimenuitem>Quit</guimenuitem>.</para>
<para><guimenuitem>Configure Toolbars...</guimenuitem> is also a
standard &kde; menu item that allows you to add or suppress items from
the toolbar.</para>

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

<para> Here you have &khangman; with the Desert theme, Catalan language and level Easy. The
<interface>Characters</interface> toolbar is shown here.</para>

<para>The level is chosen with a combo box in the toolbar or via the <guimenu>Level</guimenu> menu in the menubar. The available levels are <guimenuitem>Easy</guimenuitem>, <guimenuitem>Medium</guimenuitem>, <guimenuitem>Animals</guimenuitem> and <guimenuitem>Hard</guimenuitem>. Easy is related to common objects a child aged six
or seven knows. Medium regards nouns a bit more challenging, hard is
quite difficult and animals is only animals nouns. </para>

<para> All words are nouns. No verbs, no adjectives. The chosen level
 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>Available Settings</title>
<para>
A toolbar is provided for quick access to some settings. You can click on a button to have a new game (i.e. a new word), or to quit the game. The level and the theme are easily changed via 2 combo boxes on the toolbar.
</para>
<para>
In <guimenu>Settings</guimenu>, <guimenu>Configure &khangman;...</guimenu> you will find tree pages. The first one is for <guilabel>General</guilabel> settings.
</para>

<sect2 id="general-settings">
<title>General Settings</title>

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

<para><guilabel>Require more guesses for duplicate letters</guilabel>: this is unchecked as default. When unchecked, if you try the letter "a" and the word has several as, they will be all displayed. For example if the word is "potato" and you try "o", both os will be diaplayed. If you check this option however, only the first "o" will be displayed and you will have to try it one more time to display the second "o" in "potato". This increases the difficulty.
</para>

<para><guilabel>Do not display the 'Congratulations! You won!' dialog</guilabel>: the default is unchecked, that means that when you win a game, a message box will be displayed to tell you that you won and ask you if you want to play again. If you check this option, this dialog is not displayed anymore, instead a new game starts directly after 3 seconds.
</para>

<para>
In the Sounds section, if you check <guilabel>Enable sounds</guilabel> then a sound will be played on new game and another sound will be played when you win a game.
</para>

</sect2>
<sect2 id="languages-settings">
<title>Languages Settings</title>
<para>The <guilabel>Languages</guilabel> Settings tab allows you to set some settings specific to some languages. If the settings are not available for the language you are playing in then those settings will be grayed and disabled so you cannot choose them.
</para>

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

<para>
Some languages also have hints to help you guess the word. The hint is shown by a right-click and gives a short definition of the word to guess. If this setting is enabled and if you check the option <guilabel>Show hints</guilabel>, you can &RMB; click anywhere on the game and get a hint shown for four seconds. This hint should help you to guess the word more easily.
</para>

<para><guilabel>Type accented letters</guilabel> is available for Brazilian Portuguese, Catalan, Portuguese and Spanish in &khangman;'s configuration dialog. If you check <guilabel>Type accented letters</guilabel>  then you will have to type all accented vowels (like &atilde;). If this remains unchecked, when you type any vowel, all accented vowels will be displayed as well.
</para>

</sect2>

<sect2 id="timers-settings">
<title>Timers Settings</title>
<para>The <guilabel>Timers</guilabel> Settings tab allows you to <guilabel>Set the time for displaying the hint</guilabel> and to <guilabel>Set the time for Already Guessed Letter</guilabel> tooltip.
</para>

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

<para>
<guilabel>Set the time for displaying the hint:</guilabel> allows you to set a greater time for showing the hint label. It is necessary to increase the time for younger children for example as they read more slowly than adults.
</para>

<para><guilabel>Set the time for displaying the Already Guessed Letter</guilabel> allows you to increase or decrease the time for displaying the Already Guessed Letter tooltip. This tooltip is a label which appears when you tried a letter that was already tried. Some people will want not to see it for long while children will need time to understand it and thus will need to set the display for a longer duration.
</para>

</sect2>

</sect1>

</chapter>

<chapter id="commands">
<title>Command Reference</title>

<sect1 id="khangman-mainwindow">
<title>Menus and Shortcut Keys</title>

<sect2>
<title>The <guimenu>Game</guimenu> Menu</title>

<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
</shortcut>
<guimenu>Game</guimenu>
<guimenuitem>New</guimenuitem>
</menuchoice></term>
<listitem><para><action>New</action> game (&ie; new word)</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo>
</shortcut>
<guimenu>Game</guimenu>
<guimenuitem>Get Words in New Language...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Display</action> the TDENewStuff dialog which lists all the data available in the different languages. </para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
</shortcut>
<guimenu>Game</guimenu>
<guimenuitem>Quit</guimenuitem>
</menuchoice></term>
<listitem><para><action>Quits</action> &khangman;</para></listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2>
<title>The <guimenu>Level</guimenu> Menu</title>

<variablelist>
<varlistentry>
<term><menuchoice>
<guimenu>Level</guimenu>
<guimenuitem>Animals</guimenuitem>
</menuchoice></term>
<listitem><para><action>Choose</action> the list of animals words to guess</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Level</guimenu>
<guimenuitem>Easy</guimenuitem>
</menuchoice></term>
<listitem><para><action>Choose</action> the list of easy words to guess</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Level</guimenu>
<guimenuitem>Medium</guimenuitem>
</menuchoice></term>
<listitem><para><action>Choose</action> the list of medium difficulty words to guess</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Level</guimenu>
<guimenuitem>Hard</guimenuitem>
</menuchoice></term>
<listitem><para><action>Choose</action> the list of difficult words to guess</para></listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2>
<title>The <guimenu>Language</guimenu> Menu</title>

<variablelist>
<varlistentry>
<term><menuchoice>
<guimenu>Language</guimenu>
<guimenuitem>English</guimenuitem>
</menuchoice></term>
<listitem><para><action>Choose</action> the English language for the words to guess.</para>
<para>All other installed languages are displayed as items in this menu as well.</para></listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2>
<title>The <guimenu>Look</guimenu> Menu</title>

<variablelist>
<varlistentry>
<term><menuchoice>
<guimenu>Look</guimenu>
<guimenuitem>Sea Theme</guimenuitem>
</menuchoice></term>
<listitem><para><action>Choose</action> the Sea background picture and associated font colors</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Look</guimenu>
<guimenuitem>Desert Theme</guimenuitem>
</menuchoice></term>
<listitem><para><action>Choose</action> the Desert background picture and associated font colors</para></listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2>
<title>The <guimenu>Settings</guimenu> Menu</title>

<variablelist>
<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guisubmenu>Toolbars</guisubmenu>
<guimenuitem>Main (&khangman;)</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggle</action> the Main Toolbar</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guisubmenu>Toolbars</guisubmenu>
<guimenuitem>Special Characters (&khangman;)</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggle</action> the Characters Toolbar</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>

<guimenu>Settings</guimenu>
<guimenuitem>Show Statusbar</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggle</action> the statusbar</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure Shortcuts...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Open</action> standard &kde; setting dialog that allows you to
choose different shortcut keys for different actions.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure Toolbars...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Configure</action> the items you want to put in the toolbar
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure &khangman;...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Display</action> the &khangman; settings dialog
</para></listitem>
</varlistentry>

</variablelist>

</sect2>

<sect2>
<title>The <guimenu>Help</guimenu> Menu</title>
&help.menu.documentation;
</sect2>
</sect1>
</chapter>

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

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

<para>Thanks to Stefan Asserhäll, it is very easy to add a new language
directly to the game. The procedure described here can also be
found in the <filename class="directory">khangman</filename> source folder
in the file <filename>README.languages</filename>. Please follow the procedure and then send me the files tarred and gzipped to [email protected].
</para>
<para>
The twenty four available languages so far by code are: bg ca cs da de en es fr fi ga hu it nb nl nn pt pt_BR ru sl sr sr@Ltn sv tg and tr. If your language code is not among those, you can proceed further. 
</para>
<para>Most of this data should be completed to include <emphasis>hints</emphasis>, please see below. Complete data: bg de fr en it only have hints so the other above languages must be updated as soon as possible.
</para>
<para>Be sure you are working with the latest svn trunk sources of &khangman; by
issuing a
<screen><userinput><command>
svn up khangman
</command></userinput></screen>
in the tdeedu module. Then 
<screen><userinput><command>
cd tdeedu/khangman
</command></userinput></screen>
</para>
<para>The words are stored in 4 separate files, one for each level. The files are in
<filename class="directory">/khangman/data/en</filename>. The file
<filename>easy.txt</filename> is for level easy, the file
<filename>medium.txt</filename> is for level medium, the file
<filename>animals.txt</filename> is for level animals and the file
<filename>hard.txt</filename> is for level 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 correct kde-l10n.
</para>
<procedure>
<step><para>Enter the following commands in a &konsole; to create the folder
   and files for the new language:</para>
<!-- Do not wrap or indent the next line, it's white space sensitive -->
<screen><userinput><command>./add_language <replaceable>language_code</replaceable></command></userinput></screen>
<para>Here you must replace <replaceable>language_code</replaceable>
with your language  code.</para>
</step>
<step>
<para>The files now use the kvtml format. The tag <sgmltag class="starttag">o</sgmltag> is for the word and the tag <sgmltag class="starttag">t</sgmltag> is for the hint. Try to match the hint with the level of difficulty. The level 'Easy' will require an easy hint but the level 'Hard' 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>An example of a kvtml file is as follow:</para>
<programlisting><markup>
	&lt;?xml version="1.0"?&gt; 
	&lt;!DOCTYPE kvtml SYSTEM "kvoctrain.dtd"&gt; 
	&lt;kvtml&gt; 
	&lt;e&gt; 
	&lt;o&gt;cane&lt;/o&gt; 
	&lt;t&gt;&egrave; il tuo animale domestico preferito&lt;/t&gt; 
	&lt;/e&gt; 
	...
	...
	&lt;/kvtml&gt;
</markup></programlisting>
</step>
<step>
<para>Edit all indicated text files in the new folder with a text editor,
and replace each word inside the <sgmltag class="starttag">o</sgmltag> tag with a translated word and each hint inside a <sgmltag class="starttag">t</sgmltag> with a translated hint. It is not really important
that the exact meaning is preserved, but try to keep the length and
level of difficulty roughly the same.
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 &Anne-Marie.Mahfouf; <email>[email protected]</email> if there is anything special related to your language so I can adapt the code to it (especially the special and accented characters).</para> 
	
<para>You can just translate the words but you can also adapt them
following the level and add new words if you want. For example,
<quote>table</quote> is in level easy in English but in your language,
it can be level 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>

<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>Please keep the actual English filenames in your
<replaceable>language_code</replaceable> dir.</para>
</step>

<step>
<para>Enter the following command to install the new data files:</para>
<screen><userinput><command>make</command></userinput>
<userinput><command>make install</command></userinput></screen>

<para>You may have to become <systemitem
class="username">root</systemitem> to run <command>make
install</command>, depending on your installation.</para>
</step>
<step>
<para>Run the game and check that your language has been added:</para>
<screen><userinput><command>khangman</command></userinput></screen>
</step>
<step><para>Instead of committing your files, please sent them to
&Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail; tarred and gzipped. As there are
now twenty three languages, a wizard (TDENewStuff) is now included in &khangman;
to easily download and install new languages that are placed on the website.
This is done to reduce the size of the tdeedu module and it will also be done in
&klettres;, &kstars; and maybe &ktouch;.
Please contact Anne-Marie by email if you need further information.</para>
<para>When you send me the files, please don't 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">$~/.trinity/share/apps/khangman/data</filename> in the language code folder. The available language dir names are also stored in the &khangman; config file in <filename>~/.trinity/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>$TDEDIR/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">$TDEDIR/share/apps/khangman</filename>.
</para>
<para>
In the configuration file, stored for each user in his <filename>~/.trinity/share/config/khangmanrc</filename> are saved all the game settings such as the background, last level played, ... plus the files that were downloaded from the TDENewStuff dialog.
</para>
</sect1>
<sect1 id="planned-features">
<title>Planned Features for &khangman;</title>
<para>
A planned feature is of course to have more language data and also hints in every language. You can help for this in your own language if it is not done yet. Please contact me if you want to help with this, it's just a matter of translating the English words to your language (see <link linkend="changing-words">How to add words in a new language for the game</link>).
</para>
<para>
What can also be done is to use other kvtml files like the ones that are on the
&kde;-Edu website to play &khangman;. For example, imagine you can play the
capitals of the world, the hint will tell you the country and you have to guess
the capital. Or learn words in another language, the hint is the word in your
language, the word to guess is the translation in the new language.
</para>
</sect1>
</chapter>

<chapter id="faq">
<title>Questions and Answers</title>

&reporting.bugs;
&updating.documentation;

<qandaset id="faqlist">
<qandaentry>
<question>
<para>I have an error message telling me the pictures cannot be found.</para>
</question>
<answer>
<para>The game installs by default in <filename
class="directory">/usr/local/kde</filename> so add <filename
class="directory">/usr/local/kde/bin</filename> to your path and set
the <envar>TDEDIR</envar> variable to <filename
class="directory">/usr/local/kde</filename> before running the
game. An easy way is to configure &khangman; with the option
<option>--prefix</option>=$<envar>TDEDIR</envar> where
$<envar>TDEDIR</envar> is where the rest of &kde; is installed.  This
could vary widely, depending on the distribution and operating system
you.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>&khangman; does not start correctly after I upgraded from an earlier version to the &kde; 3.5 version</para>
</question>
<answer>
<para>
There might be a problem due to the change of the configuration file. Please remove the <filename>khangmanrc</filename> file in your <filename class="directory">$HOME/.trinity/share/config</filename> folder.
</para>
</answer>
</qandaentry>
</qandaset>
</chapter>

<chapter id="credits">

<title>Credits and License</title>

<para>
&khangman;
</para>
<para>
Program copyright 2001-2006 &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;
</para>
<para>
Contributors:
<itemizedlist>
<listitem><para>Hangman graphics: Renaud Blanchard
<email>[email protected]</email></para> </listitem>
<listitem><para>Sounds: Ludovic Grossard
<email>[email protected]</email></para> </listitem>
<listitem><para>Blue theme, icons and code: &Primoz.Anzur;
&Primoz.Anzur.mail;</para> </listitem>
<listitem><para>Swedish data files, coding help, transparent pictures and i18n fixes: Stefan Asserhäll
<email>[email protected]
</email></para> </listitem>
<listitem><para>Nature theme: Joe Bolin
<email>[email protected]</email></para> </listitem>
<listitem><para>Softer Hangman Pictures: Matt Howe
<email>[email protected]</email></para> </listitem>
<listitem><para>Spanish data files: eXParTaKus
<email>[email protected]
</email></para> </listitem>
<listitem><para>Spanish data hints: Rafael Beccar
<email>[email protected]
</email></para> </listitem>
<listitem><para>Danish data files: Erik Kjaer Pedersen
<email>[email protected]
</email></para> </listitem>
<listitem><para>Finnish data files: Niko Lewman
<email>[email protected]
</email></para> </listitem>
<listitem><para>Brazilian Portuguese data files: João Sebastião de Oliveira Bueno
<email>[email protected]
</email></para> </listitem>
<listitem><para>Catalan data files: Antoni Bella
<email>[email protected]
</email></para> </listitem>
<listitem><para>Italian data files: Giovanni Venturi
<email>[email protected]
</email></para> </listitem>
<listitem><para>Dutch data files: Rinse
<email>[email protected]
</email></para> </listitem>
<listitem><para>Portuguese data files: Pedro Morais
<email>[email protected]
</email></para> </listitem>
<listitem><para>Serbian (Cyrillic and Latin) data files: Chusslove Illich
<email>[email protected]
</email></para> </listitem>
<listitem><para>Slovenian data files: Jure Repinc
<email>[email protected]
</email></para> </listitem>
<listitem><para>Czech data files: Luk&aacute;&scaron; Tinkl
<email>[email protected]
</email></para> </listitem>
<listitem><para>Tajik data files: Roger Kovacs
<email>[email protected]
</email></para> </listitem>
<listitem><para>Norwegian (Bokm&#229;l) data files: Torger &#197;ge Sinnes
<email>[email protected]
</email></para> </listitem>
<listitem><para>Hungarian data files: Tamas Szanto
<email>[email protected]
</email></para> </listitem>
<listitem><para>Norwegian (Nynorsk) data files: Gaute Hvoslef Kvalnes
<email>[email protected]
</email></para> </listitem>
<listitem><para>Turkish data files: Mehmet &Ouml;zel
<email>[email protected]
</email></para> </listitem>
<listitem><para>Bulgarian data files: Radostin Radnev
      <email>[email protected]
</email></para> </listitem>
<listitem><para>Irish (Gaelic) data files: Kevin Patrick Scannell
    <email>[email protected]
</email></para> </listitem>
<listitem><para>Coding help: &Robert.Gogolok;
&Robert.Gogolok.mail;</para> </listitem>
<listitem><para>Coding help: Benjamin Meyer
<email>[email protected]</email></para> </listitem>
<listitem><para>Code fixes: Lubos Lun&agrave;k
<email>[email protected]</email></para> </listitem>
<listitem><para>Code fixes: Albert Astals Cid
<email>[email protected]</email></para> </listitem>
<listitem><para>Usability study: Celeste Paul
<email>[email protected]</email></para> </listitem>
</itemizedlist>
</para>

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

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

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-khangman">
<title>How to obtain &khangman;</title>

&install.intro.documentation;

</sect1>

<sect1 id="compilation">
<title>Compilation and installation</title>

&install.compile.documentation;

</sect1>
</appendix>

&documentation.index;
</book>