Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdegames@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

3 files changed, 429 insertions, 0 deletions

diff --git a/doc/klickety/Makefile.am b/doc/klickety/Makefile.am
new file mode 100644
index 00000000..085981d9
--- /dev/null
+++ b/doc/klickety/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_LANG = en
+KDE_DOCS = AUTO
+
diff --git a/doc/klickety/index.docbook b/doc/klickety/index.docbook
new file mode 100644
index 00000000..b38f81c6
--- /dev/null
+++ b/doc/klickety/index.docbook
@@ -0,0 +1,425 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+<!ENTITY % imageobjectco.module "INCLUDE">
+  <!ENTITY klickety "<application>Klickety</application>">
+  <!ENTITY kappname "&klickety;">
+  <!ENTITY package "kdegames">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE">
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The &klickety; Handbook</title>
+
+<authorgroup>
+<author>
+<personname>
+<firstname>Thomas</firstname>
+<surname>Davey</surname>
+</personname>
+<email>thomas.davey@gmail.com</email>
+</author>
+<othercredit role="reviewer">
+&Philip.Rodrigues;
+&Philip.Rodrigues.mail;
+</othercredit>
+</authorgroup>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+
+<copyright>
+<year>2005</year>
+<holder>Thomas Davey</holder>
+</copyright>
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2006-01-21</date>
+<releaseinfo>3.5</releaseinfo>
+
+<abstract>
+<para>
+&klickety; is a strategy game for &kde;, an adaption of the <application>Clickomania</application> game.
+</para>
+</abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>kdegames</keyword>
+</keywordset>
+
+</bookinfo>
+
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>The objective of &klickety; is to clear the game board of all
+the colored blocks in the least possible time (although having a short time is
+only a secondary objective). The overall aim is to get the lowest score
+possible. It will provide entertainment for all abilities, but a
+challenge in logical thought if you want to get a really low score.</para>
+
+</chapter>
+
+<chapter id="the-game-screen">
+<title>The Game Screen</title>
+
+<screenshot>
+<mediaobjectco>
+<imageobjectco>
+<areaspec units="calspair">
+<area id="play-game" coords="1 1"/>
+<area id="game-board" coords="1 1"/>
+<area id="game-timer" coords="1 1"/>
+<area id="block-counter" coords="1 1"/>
+</areaspec>
+<imageobject>
+<imagedata fileref="screenshot.png" format="PNG"/>
+</imageobject>
+</imageobjectco>
+</mediaobjectco>
+</screenshot>
+
+<calloutlist>
+<callout arearefs="play-game">
+<para>This is a colored block, you click on these to play the game.</para>
+</callout>
+
+<callout arearefs="game-board">
+<para>This is what was referred to in the introduction as the <quote>game
+board</quote>, this is where the game actually takes place.</para>
+</callout>
+
+<callout arearefs="game-timer">
+
+<para>This is the game timer, it starts the first time that you click on a
+removable block.</para>
+</callout>
+
+<callout arearefs="block-counter">
+
+<para>This the remaining block counter, which also doubles up the score
+counter. It is usually black at the start of a game, it changes to
+blue if the score is good enough to get onto your local highscore
+table, and red if it would make the top spot.
+</para>
+</callout>
+</calloutlist>
+</chapter>
+
+<chapter id="playing-the-game">
+<title>Playing the game</title>
+
+<para>When you start the program you will get a screen that looks
+something like the screenshot in the previous section. The idea of the
+game is to remove blocks, which you do by clicking on them.</para>
+
+<para>However, you can only remove a block if it is adjacent to one or
+more other blocks of the same color on one or more of its
+sides. Diagonal connections do not count. You get a random board every
+time you start a new game.</para>
+
+<para>If you click on a block which is connected as described, it will
+disappear. Any adjacent blocks of the same color will also disappear,
+along with all of the same color adjacent to <emphasis>them</emphasis>, and so
+on. Any blocks above them drop down to fill the gaps left by the
+disappeared pieces. If you clear an entire column, all the columns to
+the right move across to fill the gap.</para>
+
+
+<para>The game ends when there are no blocks adjacent to other blocks
+of the same colour</para>
+</chapter>
+
+<chapter id="scoring">
+<title>Scoring</title>
+
+<para>Scoring is very simple. Your score is the number of remaining
+blocks when the game ends. In the case of having two high scores of
+the same score, the one completed in the shortest time is listed in
+the higher position.</para>
+</chapter>
+
+
+<chapter id="menu-reference">
+<title>Menu Reference</title>
+
+<sect1 id="the-game-menu">
+<title>The <guimenu>Game</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice><guimenu>Game</guimenu><guimenuitem>New Game</guimenuitem>
+</menuchoice> (<keycombo action="simul">&Ctrl;<keycap>N</keycap>
+</keycombo>)</term>
+<listitem><para>Starts a new game before the previous one has finished
+(once you end a game, a button appears on the game board labeled
+'start' which does the same thing).</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term><menuchoice><guimenu>Game</guimenu><guimenuitem>Pause</guimenuitem>
+</menuchoice> (<keycombo><keycap>P</keycap>
+</keycombo>)</term>
+<listitem><para>Not yet implemented.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Game</guimenu><guimenuitem>Show
+Highscores</guimenuitem> </menuchoice> (<keycombo
+action="simul">&Ctrl;<keycap>H</keycap> </keycombo>)</term>
+
+<listitem><para>Shows the Highscore Table for checking a target or for
+bragging purposes. (This is the same highscore table as is displayed
+if you get a new highscore at the end of a game.) There are also tabs
+for seeing all the players who have turned in scores and for looking
+at some statistical analysis of the performance of individual
+players. There are also links to the worldwide highscore and player
+lists on the web.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Game</guimenu><guimenuitem>Quit</guimenuitem> </menuchoice> (<keycombo
+action="simul">&Ctrl;<keycap>Q</keycap> </keycombo>)</term>
+
+<listitem><para>Ends the program.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</sect1>
+
+<sect1 id="the-view-menu">
+<title>The <guimenu>View</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice><guimenu>View</guimenu><guimenuitem>Zoom In</guimenuitem>
+</menuchoice> (<keycombo action="simul">&Ctrl;<keycap>+</keycap>
+</keycombo>)</term>
+
+<listitem><para>Zooms the game board in, increases the window size as
+necessary.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>View</guimenu><guimenuitem>Zoom Out</guimenuitem>
+</menuchoice> (<keycombo action="simul">&Ctrl;<keycap>-</keycap>
+</keycombo>)</term>
+<listitem><para>Zooms the game board out. Window size will decrease around it.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="the-settings-menu">
+<title>The <guimenu>Settings</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Hide Menu Bar</guimenuitem>
+</menuchoice> (<keycombo action="simul">&Ctrl;<keycap>M</keycap>
+</keycombo>)</term>
+
+<listitem><para>Hides the menu bar. It can be brought back with the
+right-click menu or by pressing <keycombo
+action="simul">&Ctrl;<keycap>M</keycap> </keycombo>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Shortcuts...</guimenuitem>
+</menuchoice></term>
+<listitem><para>Allows you to change the shortcut keys listed above.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Notifications...</guimenuitem>
+</menuchoice></term>
+
+<listitem><para>Allows you to change the notifications for <guilabel>Game
+over</guilabel> and the removal of a column (listed as <guilabel>Line
+removed</guilabel>), such as playing a sound when you remove a column, or
+starting your favorite IRC client when you finish the game so that you
+can tell all your friends about your &klickety; skills.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Highscores...</guimenuitem>
+</menuchoice></term>
+<listitem><para>
+Displays the highscores configuration dialog, which has two
+tabs:</para>
+
+<para>On the <guilabel>Main</guilabel> tab, you can change the default
+nickname that is entered onto the highscore table if you get a
+highscore, add a comment to go with your entry on the players tab of
+the highscore table.  You can also activate the <guilabel>World-wide highscores
+enabled</guilabel> feature so that you can compare scores with players 
+from around the globe. If you are connected to the 
+Internet, &klickety; will send your score automatically at the end of the 
+game to the highscore web server (klickety.sf.net).</para>
+
+<para>The <guilabel>Advanced</guilabel> tab displays your <guilabel>Registration Data</guilabel>
+on klickety.sf.net. If worldwide highscores have been activated, 
+this tab shows the <guilabel>Nickname:</guilabel> from the <guilabel>Main</guilabel> 
+tab with which you are registered and the cryptographic <guilabel>Key:</guilabel> 
+used to prevent any attempts at cheating. This key was generated when you 
+registered on klickety.sf.net by selecting 
+<guilabel>World-wide highscores enabled</guilabel> the first time.
+The registration key is used in conjunction with the 
+nickname to identify uniquely users, but users cannot have the same nickname.
+Click on the <guibutton>Remove</guibutton> button to delete you from the world highscores
+list.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &klickety;...</guimenuitem>
+</menuchoice></term>
+
+<listitem><para>Brings up the main configuration dialog, this will be
+dealt with in the next chapter.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+<sect1 id="the-help-menu">
+<title>The <guimenu>Help</guimenu> Menu</title>
+
+&help.menu.documentation;
+
+</sect1>
+</chapter>
+
+<chapter id="configuring-klickety">
+<title>Configuring &klickety;</title>
+
+<para>Each page of the &klickety; configuration dialog has buttons
+labeled <guibutton>Help</guibutton> and
+<guibutton>Defaults</guibutton>.The <guibutton>Help</guibutton> button
+brings up this handbook, and the <guibutton>Defaults</guibutton>
+button restores all the settings to their default values.</para>
+
+<para>The individual options are as follows:</para>
+
+<sect1 id="the-appearance-tab">
+<title>The <guilabel>Appearance</guilabel> tab</title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Enable Animations</guilabel></term>
+<listitem><para>If checked, pieces are shown with an
+animation (a small rebound effect), when they touch the bottom.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Background</guilabel></term>
+
+<listitem><para>Allows you to change the background color and change
+its opacity. Trivia: if it has some transparency it doesn't actually
+show what's directly beneath &klickety;, but rather it shows the
+desktop wallpaper.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+<sect1 id="the-colors-tab">
+<title>The <guimenu>Colors</guimenu> tab</title>
+
+<para>Colors #1 through #5 Allow you to change the colors of the
+colored blocks. For an extra challenge, make them all the same
+color. N.B. You must restart &klickety; for these changes to take
+effect.</para>
+
+</sect1>
+</chapter>
+
+<chapter id="tips">
+<title>Tips</title>
+
+<itemizedlist>
+<listitem><para>Try to remove sets of two blocks to allow single blocks to join
+up with other ones of the same color, it's your only way to get rid of
+them.</para></listitem>
+
+<listitem><para>Spend time thinking about your move: you primarily get higher places on the highscore table by getting rid of more pieces than doing it quickly.</para></listitem>
+
+</itemizedlist>
+</chapter>
+
+
+<chapter id="credits">
+
+<title>Credits and License</title>
+
+<para>&klickety; Program Copyright 1995 Eirik Eng and 1996-2004 Nicolas Hadacek</para>
+
+<para>&klickety; is based on clickomania.</para>
+
+<para>The &klickety; website can be found at <ulink
+url="http://klickety.sourceforge.net">http://klickety.sourceforge.net</ulink>.</para>
+
+<para>First version of documentation by Thomas Davey, Copyright 2005.</para>
+
+<para>Reviewed by &Philip.Rodrigues; &Philip.Rodrigues.mail;.</para>
+
+<para>Further markup and reviewing by &Francis.Giannaros;
+&Francis.Giannaros.mail;.</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;
+
+&underGPL;
+
+</chapter>
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="getting-kapp">
+<title>How to obtain &klickety;</title>
+
+&install.intro.documentation;
+
+</sect1>
+
+<sect1 id="compilation">
+<title>Compilation and Installation</title>
+
+&install.compile.documentation;
+
+</sect1>
+
+</appendix>
+
+&documentation.index;
+</book>
+
+<!--
+Local Variables:
+mode: xml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+-->
diff --git a/doc/klickety/screenshot.png b/doc/klickety/screenshot.png
new file mode 100644
index 00000000..c59d09f9
--- /dev/null
+++ b/doc/klickety/screenshot.png