11 files changed, 994 insertions, 0 deletions
diff --git a/doc/ktouch/Makefile.am b/doc/ktouch/Makefile.am
new file mode 100644
index 00000000..bafa3f6c
--- /dev/null
+++ b/doc/ktouch/Makefile.am
@@ -0,0 +1,5 @@
+
+KDE_LANG = en
+KDE_DOCS = AUTO
+KDE_MANS = AUTO
+
diff --git a/doc/ktouch/color_options.png b/doc/ktouch/color_options.png
new file mode 100644
index 00000000..cb1998ae
--- /dev/null
+++ b/doc/ktouch/color_options.png
diff --git a/doc/ktouch/general_options.png b/doc/ktouch/general_options.png
new file mode 100644
index 00000000..d4a5638d
--- /dev/null
+++ b/doc/ktouch/general_options.png
diff --git a/doc/ktouch/index.docbook b/doc/ktouch/index.docbook
new file mode 100644
index 00000000..cdad9917
--- /dev/null
+++ b/doc/ktouch/index.docbook
@@ -0,0 +1,910 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+ <!ENTITY ktouch "<application>KTouch</application>">
+ <!ENTITY kappname "&ktouch;"><!-- replace kapp here -->
+ <!ENTITY package "kdeedu">
+ <!ENTITY % addindex "IGNORE">
+ <!ENTITY % English "INCLUDE"><!-- change language only here -->
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The &ktouch; Handbook</title>
+
+<authorgroup>
+<author>
+<firstname>Håvard</firstname><surname>Frøiland</surname>
+<affiliation>
+<address><email>&Haavard.Froeiland.mail;</email></address>
+</affiliation>
+</author>
+
+<author>
+<firstname>Andreas</firstname><surname>Nicolai</surname>
+<affiliation>
+<address><email>Andreas.nicolai@gmx.net</email></address>
+</affiliation>
+</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<copyright>
+<year>1999-2005</year>
+<holder>Håvard Frøiland, Andreas Nicolai</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2005-06-19</date>
+<releaseinfo>1.5</releaseinfo>
+
+<abstract>
+<para>&ktouch; is a program for learning to touch type.  &ktouch;
+provides you with text to train on and adjusts to different levels
+depending on how good you are. It displays which key to press next 
+and the correct finger to use.</para>
+
+</abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>touchwriting</keyword>
+<keyword>touchtyping</keyword>
+<keyword>typing</keyword>
+<keyword>typewriting</keyword>
+<keyword>education</keyword>
+<keyword>ktouch</keyword>
+<keyword>touch</keyword>
+<keyword>type</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="using_ktouch">
+<title>Using &ktouch;</title>
+
+<sect1 id="introduction">
+<title>Introduction</title>
+
+<sect2>
+<title>What is &ktouch;?</title>
+<para>&ktouch; is a program for learning to touch type.</para>
+<para>&ktouch; provides you with text to train on and adjusts to
+different levels depending on how good you are. It shows your keyboard 
+and indicates which key to press next and the correct finger to use.</para>
+
+<screenshot>
+<screeninfo>The main screen of &ktouch;</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="main_screen_default_color.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>The main screen of &ktouch;</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>&ktouch; is an excellent touch typing tutor. You learn typing 
+with all fingers, step by step, without having to look down 
+at the keyboard all the time to find your keys (which slows you down a lot). 
+It is convenient for all ages 
+and the perfect typing tutor for schools, universities and individuals. 
+It is free and licensed under the &GNU; Public License, so you will 
+never have to pay anything for the program or any update.
+</para>
+</sect2>
+
+<sect2>
+<title>Features </title>
+
+<para>In its current version, &ktouch; 1.5 has quite a number of helpful
+features, such as:</para>
+<itemizedlist>
+<listitem><simpara>Support for many different training lectures in many
+languages including language specific text fonts and a comfortable lecture
+editor</simpara></listitem>
+<listitem><simpara>Support for different keyboard layouts with the ability to
+use user-defined layouts</simpara></listitem>
+<listitem><simpara>During your training session comprehensive statistical
+information is obtained to help you (or your teacher) analyse your
+progress</simpara></listitem>
+</itemizedlist>
+<para>
+Many other features are included and will be discussed in the appropriate
+chapters of this manual.
+</para>
+
+</sect2>
+</sect1>
+
+
+<sect1 id="learning">
+<title>Learning touch typing with &ktouch;</title>
+
+<para>Here's another screenshot of &ktouch; in action, this time with a german
+keyboard and training lecture:</para>
+
+<screenshot>
+<screeninfo>Main screen of &ktouch;</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="main_window_german.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>Main screen of &ktouch;</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>Even though learning touch typing with &ktouch; and using the program
+should be very simple we will look a bit closer@&ktouch; in the following
+sections.</para>
+
+<sect2 id="getting_started">
+<title>Getting started</title>
+
+<para>When you start &ktouch; you can see the screen shown above. The main
+program window shows three main sections:
+</para>
+<orderedlist>
+<listitem><simpara>Some typing statistics in info boxes@the
+top</simpara></listitem>
+<listitem><simpara>The text you need to type (in the teacher's line) and the
+text that you have typed so far (in the student's line)</simpara></listitem>
+<listitem><simpara>The keyboard (that hopefully looks like
+yours)</simpara></listitem>
+</orderedlist>
+<para>We look@these sections later again.</para>
+<para>
+Ok, the first time you start &ktouch; it will open a default lecture and
+select a default keyboard layout.  Before you start typing you should adjust
+the keyboard layout so that it matches yours. Go to
+<menuchoice><guimenu>Settings</guimenu><guimenuitem>Keyboard
+Layouts...</guimenuitem></menuchoice> and select the country you're in (or
+some country which uses the same keyboard layout as you). If your keyboard is
+not included, you can always define your own keyboard (see <link
+linkend="create_keyboards">Creating your own keyboard</link>).
+</para>
+<para>
+Once you have your keyboard selected, choose your training lecture. The first
+line in your corrent lecture and level is shown in the teacher's line. You can
+select any of the default lectures via 
+<menuchoice><guimenu>Training</guimenu><guimenuitem>Default
+Lectures...</guimenuitem></menuchoice> or open a user defined lecture file
+(&eg; if your teacher gives you a special lecture to practice on) with
+<menuchoice><guimenu>File</guimenu><guimenuitem>Open
+Lecture...</guimenuitem></menuchoice>. You may even create your own lecture
+(see <link linkend="create_lectures">Creating your own lecture</link>). When
+you have selected keyboard and lecture you can start typing.
+</para>
+<para>
+Place your hand on the keyboard as indicated by the 8 marked finger keys
+(thumbs over the space bar) and start typing the text shown in the teacher's
+line. Each key you need to press is highlighted on the keyboard and if you
+need to move a finger from its resting position the target key and the
+appropriate finger key is highlighted. Try to move your hands as little as
+possible and after you typed a character always try to return your fingers to
+their resting positions.
+</para>
+<tip><para>The key colors indicate which finger needs to press which
+key.</para></tip>
+<para>
+While you type you may make mistakes and hit the wrong key. In that case the
+student's line will change its color (per default to red) and you have to hit
+Backspace to erase the wrong character (or characters) again.
+</para>
+<para>
+When you have successfully completed a line of text you need to press the
+Enter key to advance to the next line.
+</para>
+</sect2>
+
+<sect2 id="lectures_and_levels">
+<title>Lectures and levels</title>
+<para>
+As already mentioned above you need to select a training lecture which
+contains all the text you want to practice. Usually the difficulty of the text
+is gradually increasing and so most lectures contain various difficulty
+levels. However, some lectures may just contain a single level and text (&eg;
+a newspaper article to test your skills).
+</para>
+<para>
+In the info boxes@top of the &ktouch; main window you see the current
+level@the left. The small buttons to the right allow you to manually switch
+levels. Normally this happens automatically (more about this in the section
+<link linkend="training_options">Training Options</link>). The right info box
+shows a brief information text about the level. Usually it gives you a list of
+characters that are new in this level. The middle two info boxes show your
+current typing speed (in characters per minute) and your correctness. These
+values are Level Statistics and whenever you start a new level these values
+are resetted. However, the program still remembers your previous statistics
+(see section <link linkend="statistics">Statistics in &ktouch;</link>).
+</para>
+</sect2>
+
+<sect2 id="starting_stopping">
+<title>Starting and stopping a training session</title>
+<para>
+While you type the text of a training lecture you are in a practice session.
+You can start a new practice session using
+<menuchoice><guimenu>Training</guimenu><guimenuitem>Start New
+Session</guimenuitem></menuchoice> or the appropriate button in the toolbar.
+Level changes (automatic or manual) do not change your training session. You
+stay in this training session until you start a new training session, select a
+new lecture (which automatically starts a new training session) or quit the
+program.
+</para>
+<para>
+If you open any dialog in &ktouch; while you are in a training session the
+training is paused and the timer is stopped until you hit the next key. You
+can manually pause the session using
+<menuchoice><guimenu>Training</guimenu><guimenuitem>Pause
+Session</guimenuitem></menuchoice> or the appropriate button in the toolbar.
+</para>
+</sect2>
+
+</sect1>
+
+<sect1 id="statistics">
+<title>Statistics in &ktouch;</title>
+<para>&ktouch; remembers you! Basically whatever you type is recorded and some
+useful (and sometimes just interesting) statistics are created. &ktouch;
+stores statistical data based on the lecture file you use for training. For
+every lecture file a separate history is kept. &ktouch; also distinguishes
+between level and practice session statistics. This is important to prevent
+cheating :-).
+</para>
+
+<sect2>
+<title>Training Session Statistics</title>
+<screenshot>
+<screeninfo>Current Training Statistics</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="statistics_dialog.png"
+format="PNG"/></imageobject>
+<textobject><phrase>Current Training Statistics</phrase></textobject>
+</mediaobject>
+</screenshot>
+<para>Whenever you start a new training session a new statistics record is
+started. &ktouch; remembers several things to assess your skill and to help
+you identify problem keys:
+</para>
+<itemizedlist>
+<listitem><simpara>How many keys were pressed in total?</simpara></listitem>
+<listitem><simpara>How many were correctly pressed?</simpara></listitem>
+<listitem><simpara>Which keys where missed and how often?</simpara></listitem>
+<listitem><simpara>How many correct words did you type?</simpara></listitem>
+<listitem><simpara>How much time did you need?</simpara></listitem>
+</itemizedlist>
+<para>Using training session statistics you and &ktouch; can evaluate your
+overall performance and skill in a certain training lecture.</para>
+</sect2>
+
+<sect2>
+<title>Level Statistics</title>
+<para>For each level in your training session (&ie; all levels you typed text
+in) the same statistics as for the training session are obtained. Using level
+statistics data you can investigate your progress in each level of a training
+lecture (and you will notice how your skill increases level by level and you
+can concentrate on the levels which still cause problems).
+</para>
+</sect2>
+
+<sect2>
+<title>The Statistics Dialog</title>
+<para><menuchoice><guimenu>Training</guimenu><guimenuitem>Lecture
+Statistics</guimenuitem></menuchoice> or the statistics button in the toolbar
+opens the statistics dialog. It displays your current training and level
+statistics and shows a graphical history of previous training sessions.
+</para>
+<para>
+When you open the statistics dialog you can select a Session Statistics Page
+and a Level Statistics Page. The first page gives you a summary about
+everything you typed so far. The Level Statistics Page only contains the stats
+for the current level. This is useful to distinguish between overall
+performance and skill in certain levels.
+</para>
+<para>
+The third statistics page gives you a graphical overview of your typing skill
+by offering several choices. A note about the time scaling option. Whenever a
+session or level statistic is obtained, also the date is stored. So you can
+also see how your skill dropped in long training breaks and when you last
+practiced a certain lecture or level.
+</para>
+<screenshot>
+<screeninfo>Training Statistics Chart</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="statistics_dialog_chart.png"
+format="PNG"/></imageobject>
+<textobject><phrase>Training Statistics Chart</phrase></textobject>
+</mediaobject>
+</screenshot>
+
+</sect2>
+</sect1>
+</chapter>
+
+<chapter id="ui_guide">
+<title>The &ktouch; main menu and program dialogs</title>
+<para>In this chapter we look@some of the details in the program.
+<tip><para>You can use the <quote>What's this?</quote> feature (the little
+question mark besides the minimize/maximize window buttons) in many dialogs of
+the program.</para></tip>
+</para>
+
+<sect1 id="main_menu">
+<title>The menu of &ktouch;</title>
+<para>Pretty much everything in the &ktouch; menu should be self-explanatory.
+The file menu contains options to load a user defined lecture and edit
+lectures. The training menu contains training options and the settings menu
+contains options to setup the program. The various options in the
+configuration dialog are explained in the next section.</para>
+</sect1>
+
+<sect1 id="program_settings">
+<title>Configuration options for &ktouch;</title>
+<para>You can customize &ktouch; quite a bit. The settings are always stored
+for the current user of the program. Open the configuration dialog via
+<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &ktouch;
+...</guimenuitem></menuchoice>.</para>
+
+<sect2 id="general_options">
+<title>General Options</title>
+<para>In this dialog you can change general options that control the behaviour
+of &ktouch;.
+</para>
+<screenshot>
+<screeninfo>General options</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="general_options.png"
+format="PNG"/></imageobject>
+<textobject><phrase>General options</phrase></textobject>
+</mediaobject>
+</screenshot>
+<para>First of all you can switch the sound on or off (might be useful in
+class rooms). You can also set the sliding speed of the teacher's and
+student's line.
+</para>
+<para>Most important, however, might be the selection of the lecture font.
+When showing the teacher's text &ktouch; will normally use the font specified
+in the lecture file. But if this font doesn't exist on your system or none has
+been specified, &ktouch; uses a default system font. What if this font does
+not contain all characters needed for your lecture? In such cases you can
+override the choice of the font and specify any font you like.
+<note><para>&ktouch; distinguishes between lecture and keyboard fonts.
+Overriding the lecture font does not automatically adjust the keyboard font as
+well. Use the appropriate option in the Keyboard Options configuration
+page.</para></note>
+</para>
+</sect2>
+
+<sect2 id="training_options">
+<title>Training Options</title>
+<para>In this dialog you can select the options that control how &ktouch;
+changes difficulty levels based on the user's skill.</para>
+<screenshot>
+<screeninfo>Training options</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="training_options.png"
+format="PNG"/></imageobject>
+<textobject><phrase>Training options</phrase></textobject>
+</mediaobject>
+</screenshot>
+<para>If <guibutton>Automatic level adjustment</guibutton> is enabled,
+&ktouch; checks the given limits@the end of each level and decides whether to
+increase or decrease the level or stay in the level for another run. Level
+changes occur always@the end of a level (&ie; when the user has finished the
+last line of a level). If the typing speed (in characters per seconds) and
+accuracy (correctness) are <emphasis>both</emphasis> above or equal to the
+<quote>Limits to increase level</quote> &ktouch; will jump to the next higher
+level. If <emphasis>either</emphasis> typing speed or accuracy falls below the
+<quote>Limits to decrease level</quote> &ktouch; will jump back to the
+previous lower level.
+</para>
+<para>
+On this configuration page you can also select that the program remembers your
+current level when you quit the program and jumps back to it when you restart
+&ktouch;.
+</para>
+</sect2>
+
+<sect2 id="keyboard_options">
+<title>Keyboard Options</title>
+<para>In this dialog you can select keyboard specific options.</para>
+<screenshot>
+<screeninfo>Keyboard options</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="keyboard_options.png"
+format="PNG"/></imageobject>
+<textobject><phrase>Keyboard options</phrase></textobject>
+</mediaobject>
+</screenshot>
+<para>
+This dialog controls the appearance and functionality of the keyboard. Similar
+to the <quote>Override lecture font</quote> option in the general settings
+configuration page, you can here specify your own keyboard font. The option
+<quote>Highlight keys on keyboard</quote> can be used to increase the
+difficulty of the training. <tip><para>Once you are familiar with the keyboard
+you may want to turn keyboard highlighting off so it won't distract you when
+you concentrate on the teacher's text.</para></tip>
+</para>
+</sect2>
+
+
+<sect2 id="color_options">
+<title>Color Options</title>
+<para>In this dialog you can tweak the appearance of &ktouch;.</para>
+<screenshot>
+<screeninfo>Color options</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="color_options.png"
+format="PNG"/></imageobject>
+<textobject><phrase>Color options</phrase></textobject>
+</mediaobject>
+</screenshot>
+<para>
+This configuration page does not need much explaination. You can choose among
+four predefined color schemes for the keyboard. Alternatively you can switch
+the color schemes <quote>on the fly</quote> using the menu option
+<menuchoice><guimenu>Settings</guimenu><guimenuitem>Keyboard Color
+Schemes</guimenuitem></menuchoice>.
+</para>
+</sect2>
+
+</sect1>
+</chapter>
+
+
+<chapter id="extending">
+<title>Extending &ktouch;</title>
+
+<sect1 id="create_lectures">
+<title>Creating your own lecture</title>
+<para>You can easily create your own training lecture using the built-in
+&ktouch; lecture editor. When you select
+<menuchoice><guimenu>File</guimenu><guimenuitem>Edit
+Lecture...</guimenuitem></menuchoice> the <quote>Open Request Dialog</quote>
+will open and ask you to select a lecture. You can choose either edit the
+current lecture, any of the predefined lectures (if you have write access to
+the installation directoy) or create an empty lecture from scratch.</para>
+
+<sect2>
+<title>Creating a lecture</title>
+<para>
+Let's assume you want to create a new lecture. There are a few guidelines you
+may want to consider:
+</para>
+<itemizedlist>
+
+
+<listitem><para>
+For the first 20 keys or so, only add 2 keys@a time to a new level. Let the
+user practice the keys alone first in different combinations and then use the
+new keys in words and mixed with already known words.
+</para></listitem>
+
+<listitem><para>Add@least a few levels to the lecture in order to allow the
+user to see some progress while training</para></listitem>
+
+<listitem><para>
+Don't make the levels too long.
+</para></listitem>
+
+<listitem><para>
+Try to increase the difficulty of the text gradually and test your text
+yourself.
+</para></listitem>
+
+<listitem><para>
+After the first keys have been learned include a recap lecture.
+</para></listitem>
+</itemizedlist>
+
+</sect2>
+
+<sect2>
+<title>Things to know about lectures</title>
+<para>
+The lecture title is important for the quick-select menu entry in the training
+menu and for the statistics. The comment should be used to include information
+about the lecture author and source of lecture data if any.
+</para>
+<para>
+For each level you can specify the new characters/keys in the lecture. The
+text you enter there will be shown as level information text in the top right
+info box of the &ktouch; main window.
+</para>
+<para>You can also specify a default font for the lecture which will be used
+in the teacher's and student's line and of course in the edit lecture dialog
+using the <guibutton>Change Font...</guibutton> button.
+</para>
+</sect2>
+
+</sect1>
+
+<sect1 id="create_keyboards">
+<title>Creating your own keyboard</title>
+<para>You can create your own keyboards by creating keyboard files. Currently
+&ktouch; doesn't have a keyboard editor but it is still pretty easy to define
+your own keyboard. It doesn't require much more than a little math to work out
+the geometry and some time. Best is to start with an existing keyboard file,
+create a copy for your keyboard layout and simply adjust the lines.</para>
+<para>
+Currently keyboard files are plain UTF-8 encoded text files. In one of the
+next version of &ktouch; keyboard data will be stored in &XML; files, too.
+Therefore I'll only briefly explain the structure of a keyboard file.
+</para>
+<para>A keyboard file usually starts with a header including some information
+about the author and type of the keyboard.</para>
+<programlisting>
+####################################################
+#    KTouch
+#    Keybord layout file for german keybord layout
+#    Code=UTF-8
+####################################################
+</programlisting>
+<para>
+All lines starting with a hash character '#' are considered comments. After
+the header section a block of so called <quote>finger keys</quote> follows,
+indicating the resting positions for all 8 fingers.
+</para>
+<programlisting>
+#
+#          Unicode  KeyChar  x    y
+#
+FingerKey  97       A        18   20
+FingerKey  115      S        28   20
+FingerKey  100      D        38   20
+FingerKey  102      F        48   20
+FingerKey  106      J        78   20
+FingerKey  107      K        88   20
+FingerKey  108      L        98   20
+FingerKey  246      Ö        108  20
+</programlisting>
+<para>Keys have the default dimensions of 8 units, so using a grid of 10 units
+gives a normal looking keyboard. The first number is the unicode character
+code as decimal number. The KeyText is the text printed on the key encoded as
+UTF-8 (automatic under newer &Linux; versions, just make sure your editor saves
+files as UTF-8 format).</para>
+<para>The next section contains special keys, which are - apart from BackSpace
+and Enter - just decorative.</para>
+<programlisting>
+#
+#           Unicode  KeyText    x     y     Width Height
+#
+ControlKey  260      Tab        0     10    15    10
+ControlKey  13       Enter      138   20    12    10
+ControlKey  258      Shift      123   30    27    10
+ControlKey  264      AltGr      120   40    15    10
+ControlKey  265      Ctrl       135   40    15    10
+ControlKey  263      Alt        15    40    15    10
+ControlKey  262      Strg       0     40    15    10
+ControlKey  32       Leertaste  30    40    90    10
+ControlKey  257      Shift      0     30    13    10
+ControlKey  259      CapsLock   0     20    18    10
+ControlKey  8        BackSpace  130   0     20    10
+</programlisting>
+<para>
+ The text you specify for the key is printed completely on the keyboard.
+However, for the keytexts <quote>Shift</quote>, <quote>CapsLock</quote>,
+<quote>Tab</quote>, <quote>BackSpace</quote> and <quote>Enter</quote> &ktouch;
+draws the appropriate symbols. Hence you can use these keytexts regardless of
+the language. The other keytexts like Ctrl or Alt need to be translated
+though. The geometry of the control keys can be any rectangle, defined by
+upper left x and y coordinates and width and height.</para>
+<para>The next section contains all characters on the keyboard (except the
+already defined finger keys) that can be typed <emphasis>without</emphasis>
+pressing shift.</para>
+<programlisting>
+#
+#          Unicode  KeyChar   x    y      FingerKeyUnicode
+#
+NormalKey  94       ^         0    0      97
+NormalKey  49       1         10   0      97
+NormalKey  50       2         20   0      115
+NormalKey  51       3         30   0      100
+NormalKey  52       4         40   0      102
+NormalKey  53       5         50   0      102
+NormalKey  54       6         60   0      102
+.
+.
+.
+NormalKey  46       .         103  30     108
+NormalKey  45       -         113  30     246
+</programlisting>
+<para>The definition of these primary keys or chars is pretty much the same as
+for the finger keys, but they include an additional property. The last unicode
+character code identifies the associated finger key. Basically which finger
+has to be used to press this key.</para>
+<para>
+The next and last section in a keyboard layout defines all keys that are
+pressed by using a modifier key such as the shift key.
+</para>
+<programlisting>
+#
+#           Unicode   TargetUnicode   FingerUnicode   ControllUnicode    
+Comment
+#
+HiddenKey   65        97              97              258                 #A
+HiddenKey   66        98              102             258                 #B
+HiddenKey   67        99              100             258                 #C
+HiddenKey   68        100             100             258                 #D
+.
+.
+.
+HiddenKey   124       60              97              264                 #|
+HiddenKey   64        113             97              264                 #@
+</programlisting>
+<para>The <quote>hidden keys</quote> are really controlling what should happen
+on the keyboard when you type a certain character. The first unicode number is
+the character code of the character you define. The second number is the
+character code of the key on the keyboard (one of the already defined normal
+keys). The third number indicates a finger key (where does the finger rest
+that is needed to type the key) and the last number indicates the modifier key
+you need to press to get this character.
+</para>
+<para>Let's look@an example:</para>
+<para>You want to define the uppercase 'R' character. It has the unicode 82.
+The character obtained when the 'R' key is pressed without modifier is the
+small 'r' with the unicode 114. The finger for the 'R' rests over the 'f' key
+which has the unicode 102. And in order to get the 'R' you need to press the
+right (or left) shift key which has the code 264 (this is actually not a
+unicode but the code obtained from a keypress event of QT). Note that the
+identification of controll keys will likely change in the next version of
+&ktouch;.  But for now you can use the codes used in other keyboard files.
+</para>
+
+</sect1>
+</chapter>
+
+<chapter id="commands">
+<title>Command Reference</title>
+
+<sect1 id="ktouch-mainwindow">
+<title>Menus and shortcut keys</title>
+
+<sect2>
+<title>The <guimenu>File</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Open Lecture...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Open</action> a new training lecture
+file</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>File</guimenu>
+<guimenuitem>Edit Lecture...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Open</action> the lecture editor to allow you to
+change the current training file </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>Quit</action> &ktouch;</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+
+
+<sect2>
+<title>The <guimenu>Training</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<guimenu>Training</guimenu>
+<guimenuitem>Start New Session</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Start</action> a new typing session and ask you if you
+want to start@the same level</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Training</guimenu>
+<guimenuitem>Pause Session</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Pause</action> the current session: statistics are on
+hold</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Training</guimenu>
+<guimenuitem>Lecture Statistics</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Open</action> the current session statistics
+dialog</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Training</guimenu>
+<guisubmenu>Default Lectures</guisubmenu>
+<guimenuitem>English (auto-generated)</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Choose</action> what languagee you want to learn touch
+typing in</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect2>
+
+<sect2>
+<title>The <guimenu>Settings</guimenu> Menu</title>
+
+<variablelist>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show /HideToolbar</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Toggle</action> the  Toolbar</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guisubmenu>Keyboard Layouts</guisubmenu>
+<guimenuitem>number.keyboard</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Choose</action> the keyboard layout you want to use,
+here the number keyboard</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guisubmenu>Keyboard Color Schemes</guisubmenu>
+<guimenuitem>Black'n White</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Choose</action> the keyboard color layout in black in
+white: all keys are white and the one you should type is
+black</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guisubmenu>Keyboard Color Schemes</guisubmenu>
+<guimenuitem>Classic</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Choose</action> the classic keyboard color layout:
+each column of keys has a different color</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guisubmenu>Keyboard Color Schemes</guisubmenu>
+<guimenuitem>Deep Blue</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Choose</action> the deep blue keyboard color layout:
+each column of keys has a different color in a shade of blue</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guisubmenu>Keyboard Color Schemes</guisubmenu>
+<guimenuitem>Stripy</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Choose</action> the stripy keyboard color layout: in
+blue and grey</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Shortcuts...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Configure</action> the shortcuts you want to associate
+with some 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 &ktouch;...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Display</action> the &ktouch; settings dialog
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect2>
+
+<sect2>
+<title>The <guimenu>Help</guimenu> Menu</title>
+&help.menu.documentation;
+</sect2>
+</sect1>
+</chapter>
+
+<chapter id="credits">
+
+<title>Credits and License</title>
+<para>&ktouch;</para>
+<para>
+&ktouch;, Copyright 1999-2005 by</para>
+<itemizedlist>
+<listitem><simpara>Håvard Frøiland <email>haavard@users.sourceforge DOT
+net</email></simpara></listitem>
+<listitem><simpara>Andreas Nicolai <email>andreas.nicolai@gmx DOT
+net</email></simpara></listitem>
+</itemizedlist>
+
+<para> Contributors:</para>
+<itemizedlist>
+<listitem><simpara>Frank Quotschalla, German keyboard and german training file and
+ translation.</simpara></listitem>
+<listitem><simpara>Ernesto Hern&aacute;ndez-Novich, Latinamerican
+ keyboard</simpara></listitem>
+<listitem><simpara>Jo&atilde;o Miguel Neves, Portuguese keyboard</simpara></listitem>
+<listitem><simpara>Henri Girard, Frence keyboard</simpara></listitem>
+</itemizedlist>
+<para><emphasis>Special thanks to all the other (here not mentioned) contributors of keyboard and lecture files.</emphasis>
+</para>
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;           <!-- FDL: do not remove -->
+&underGPL;        	 <!-- GPL License -->
+
+</chapter>
+
+<appendix id="installation">
+<title>How to obtain and install &ktouch;</title>
+
+<para>&ktouch; has its own home page <ulink
+url="http://ktouch.sourceforge.net">http://ktouch.sourceforge.net</ulink>. Please refer to the instructions on the home page since they will contain up-to-date information about how to obtain &ktouch;.
+</para>
+<para>&ktouch; can also be found
+on <ulink url="http://edu.kde.org/ktouch">The &kde; Edutainment - &ktouch; home page</ulink>
+and is part of the &kde;-Edutainment project. </para>
+
+</appendix>
+
+&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:
+
+// vim:ts=2:sw=2:tw=78:noet
+-->
diff --git a/doc/ktouch/keyboard_options.png b/doc/ktouch/keyboard_options.png
new file mode 100644
index 00000000..27754a32
--- /dev/null
+++ b/doc/ktouch/keyboard_options.png
diff --git a/doc/ktouch/main_screen_default_color.png b/doc/ktouch/main_screen_default_color.png
new file mode 100644
index 00000000..3f2fce1f
--- /dev/null
+++ b/doc/ktouch/main_screen_default_color.png
diff --git a/doc/ktouch/main_window_german.png b/doc/ktouch/main_window_german.png
new file mode 100644
index 00000000..dfca3b03
--- /dev/null
+++ b/doc/ktouch/main_window_german.png
diff --git a/doc/ktouch/man-ktouch.1.docbook b/doc/ktouch/man-ktouch.1.docbook
new file mode 100644
index 00000000..a1bdc73d
--- /dev/null
+++ b/doc/ktouch/man-ktouch.1.docbook
@@ -0,0 +1,79 @@
+<?xml version="1.0" ?>
+<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+<!ENTITY % English "INCLUDE">
+]>
+
+<refentry lang="&language;">
+<refentryinfo>
+<title>KDE User's Manual</title>
+<author><personname>
+<firstname>Ben</firstname>
+<surname>Burton</surname>
+</personname>
+<email>bab@debian.org</email></author>
+<date>30 May, 2005</date>
+<productname>K Desktop Environment</productname>
+</refentryinfo>
+
+<refmeta>
+<refentrytitle><command>ktouch</command></refentrytitle>
+<manvolnum>1</manvolnum>
+</refmeta>
+
+<refnamediv>
+<refname><command>ktouch</command></refname>
+<refpurpose>a typing tutor for KDE</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>ktouch</command>
+<group choice="opt"><option>URL</option></group>
+<arg choice="opt">KDE Generic Options</arg>
+<arg choice="opt">Qt Generic Options</arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Description</title>
+<para>&ktouch; is a program for learning touch typing.  It helps you learn
+to type on a keyboard quickly and correctly.  Every finger has it's place on
+the keyboard with associated keys to press.</para> 
+<para>&ktouch; helps you learn to touch type by providing you with text to
+train on, and adjusts to different levels depending on how good you are.  It
+can display which key to press next, and correct finger to use.</para>
+<para>This application is part of the official &kde; edutainment
+module.</para>
+</refsect1>
+
+<refsect1>
+<title>Options</title>
+<variablelist>
+<varlistentry>
+<term><option>URL</option></term>
+<listitem><para>The training file to open</para></listitem>
+</varlistentry>
+</variablelist>
+
+</refsect1>
+
+<refsect1>
+<title>See Also</title>
+<para>More detailed user documentation is available from <ulink
+url="help:/ktouch">help:/ktouch</ulink>
+(either enter this <acronym>URL</acronym> into &konqueror;, or run
+<userinput><command>khelpcenter</command>
+<parameter>help:/ktouch</parameter></userinput>).</para>
+
+<para>There is also further information available at the <ulink
+url="http://edu.kde.org/ktouch/">&kde; edutainment website</ulink>.</para>
+</refsect1>
+
+<refsect1>
+<title>Authors</title>
+<para>KTouch was written by <personname><firstname>Haavard</firstname><surname>Froeiland</surname></personname> <email>haavard@users.sourceforge.net</email> and <personname><firstname>Andreas</firstname><surname>Nicolai</surname></personname> <email>Andreas.Nicolai@gmx.net</email>.This manual page based on the one prepared for Debian by <personname>
+<firstname>Ben</firstname><surname>Burton</surname></personname>
+</para>
+</refsect1>
+
+</refentry>
diff --git a/doc/ktouch/statistics_dialog.png b/doc/ktouch/statistics_dialog.png
new file mode 100644
index 00000000..1d56257f
--- /dev/null
+++ b/doc/ktouch/statistics_dialog.png
diff --git a/doc/ktouch/statistics_dialog_chart.png b/doc/ktouch/statistics_dialog_chart.png
new file mode 100644
index 00000000..0ed06c3e
--- /dev/null
+++ b/doc/ktouch/statistics_dialog_chart.png
diff --git a/doc/ktouch/training_options.png b/doc/ktouch/training_options.png
new file mode 100644
index 00000000..057a2a35
--- /dev/null
+++ b/doc/ktouch/training_options.png