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

5 files changed, 387 insertions, 0 deletions

diff --git a/doc/kbounce/Makefile.am b/doc/kbounce/Makefile.am
new file mode 100644
index 00000000..085981d9
--- /dev/null
+++ b/doc/kbounce/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_LANG = en
+KDE_DOCS = AUTO
+
diff --git a/doc/kbounce/index.docbook b/doc/kbounce/index.docbook
new file mode 100644
index 00000000..8e4896d1
--- /dev/null
+++ b/doc/kbounce/index.docbook
@@ -0,0 +1,383 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kappname "&kbounce;">
+  <!ENTITY package "kdegames">
+  <!ENTITY % English "INCLUDE" > 
+  <!ENTITY % addindex "IGNORE">
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The &kbounce; Handbook</title>
+
+<authorgroup>
+<author>
+&Aaron.J.Seigo; &Aaron.J.Seigo.mail;
+</author>
+
+<othercredit role="reviewer">
+&Lauri.Watts; &Lauri.Watts.mail;
+<!-- <contrib>Reviewer</contrib> -->
+</othercredit>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2005-12-10</date>
+<releaseinfo>0.5</releaseinfo>
+
+<!-- Abstract about this handbook -->
+
+<abstract>
+<para>
+&kbounce; is a ball game for &kde;.
+</para>
+</abstract>
+
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>kdegames</keyword>
+<keyword>jezzball</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="how-to-play">
+<title>How To Play</title>
+
+<para>&kbounce; is played on a field, surrounded by a wall, with two or
+more balls that move about in the field bouncing off of the
+walls.</para>
+
+<para>Walls are a darker color while the active areas of the field are
+a lighter color.</para>
+
+<para>The size of the active area of the field is decreased by making
+new walls that enclose areas without balls in them.  To complete a
+level, the player must decrease the size of the active field by at
+least 75&percnt; within the time allowed.</para>
+
+<para>With each new level, another ball is added to the field, and the
+player is given one more life than in the level before.  The time
+allotted to complete the level is also increased.</para>
+
+<para>Scoring is based on how much of the field is cleared.</para>
+
+<para>New walls are built by clicking the
+<mousebutton>left</mousebutton> mouse button in an active area of the
+field, at which point two walls will begin to grow in opposite
+directions from the square the mouse was clicked in.  Only two walls
+may be growing on the screen at any given time.</para>
+
+<screenshot>
+<screeninfo>A new wall growing</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="jezball_newWall.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>A new wall growing</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>When the mouse is on the field, the cursor is shown as a pair of
+arrows pointing in opposite directions, either horizontally or
+vertically.  The arrows point in the direction the walls will grow
+when the <mousebutton>left</mousebutton> is clicked.  This direction
+can be changed by clicking the <mousebutton>right</mousebutton> mouse
+button.</para>
+
+<para>A new wall has a <quote>head</quote> which moves away from the
+point where the mouse was clicked.  A wall is not permanent until this
+<quote>head</quote> runs into another wall.  If a ball collides with
+any part of the wall except the head, before the head has run into
+another wall, the new wall will disappear completely and one life will
+be lost.  If a ball collides with the head in the direction of the
+wall's growth, the wall will stop growing there, and become permanent,
+with no loss of life.  If a ball collides with the head from any other
+side, the ball will bounce off and the wall will continue to grow
+normally.</para>
+
+</chapter>
+
+<chapter id="strategy">
+<title>Strategy</title>
+
+<para>Many players find the game becomes quite difficult by only the
+third or fourth level, given the number of balls on the field at
+once.</para>
+
+<para>The trick to playing &kbounce; successfully is to build
+<quote>corridors</quote>.  To build a corridor, start a pair of walls
+growing close to another wall, and time it such that one of the walls
+will be hit by a ball and one of the walls will not, and thus become
+permanent.</para>
+
+<screenshot>
+<screeninfo>Building a corridor</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="jezball_corridor1.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>Building a corridor</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>This will leave a narrow corridor only a few squares high on the
+field, surrounded on three sides by walls.  Wait for the balls to
+bounce into the open end of the corridor, and close the corridor
+behind the ball with a new wall.  Although you will most likely lose a
+life for each corridor created, you can trap several balls in a single
+corridor.</para>
+
+<screenshot>
+<screeninfo>Capturing balls in a corridor</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="jezball_corridor2.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>Capturing balls in a corridor</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>A final tip &mdash; take your time!  There is plenty of time, as
+shown in the <guilabel>Time</guilabel> display on the right hand side
+of the screen.  Rushing will just get you in trouble!</para>
+
+</chapter>
+
+<chapter id="menu-reference">
+<title>Menu Reference</title>
+
+<sect1 id="game-menu">
+<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>Start a new game.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice><shortcut>
+<keycombo action="simul">&Ctrl;<keycap>End</keycap>
+</keycombo>
+</shortcut>
+<guimenu>Game</guimenu>
+<guimenuitem>End Game</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>End the current game.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice><shortcut>
+<keycap>P</keycap></shortcut>
+<guimenu>Game</guimenu>
+<guimenuitem>Pause</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Pause or resume the game.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice><shortcut>
+<keycombo action="simul">&Ctrl;<keycap>H</keycap></keycombo>
+</shortcut>
+<guimenu>Game</guimenu>
+<guimenuitem>Show Highscores</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>Opens a dialog that displays different high score tables. 
+<guibutton>Export</guibutton> the high scores into a file or click on 
+<guibutton>Configure</guibutton> to open a dialog to customize your Nickname 
+and add a Comment.</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>Quit</action> and close &kbounce;.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="settings-menu">
+<title>The <guimenu>Settings</guimenu> Menu</title>
+<variablelist>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Select Background Folder...</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Opens a dialog to select a folder for the background images.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show Backgrounds</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Shows the background images in the selected folder. Only enabled, if a background folder is already selected</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show/Hide Toolbar</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Shows/hides the &kbounce; toolbar.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show/Hide Statusbar</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Shows/hides the &kbounce; statusbar.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Play Sounds</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>If checked, &kbounce; game sounds are played.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Shortcuts...</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Opens a standard &kde; shortcut configuration dialog, in which
+you can change the keyboard shortcuts used by &kbounce;.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Toolbars...</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Opens the standard &kde; toolbar configuration dialog to customize the &kbounce; toolbar.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Highscores...</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Opens a dialog to customize your <guilabel>Nickname</guilabel> and 
+add a <guilabel>Comment</guilabel>.</action></para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</sect1>
+
+
+<sect1 id="help-menu">
+<title>The <guimenu>Help</guimenu> Menu</title>
+
+&help.menu.documentation;
+
+</sect1>
+
+</chapter>
+
+<chapter id="credits-and-licenses">
+<title>Credits and Licenses</title>
+
+
+<para>&kbounce;</para>
+
+<para>Copyright 2000, Stefan Schimanski</para>
+
+<itemizedlist>
+<title>Developers</title>
+<listitem>
+<para>Stefan Schimanski <email>[email protected]</email></para>
+</listitem>
+<listitem>
+<para>Sandro Sigala <email>[email protected]</email> -
+Highscore</para>
+</listitem>
+</itemizedlist>
+
+<para>Documentation copyright 2002, &Aaron.J.Seigo;
+&Aaron.J.Seigo.mail;</para>
+
+<para>This handbook is dedicated to Dennis E. Powell.</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+ 
+&underFDL; 
+
+&underGPL;
+
+</chapter>
+
+<appendix id="installation">
+<title>Installation</title>
+
+&install.intro.documentation;
+
+&install.compile.documentation;
+
+</appendix>
+
+&documentation.index; 
+</book>
+<!--
+Local Variables:
+mode: sgml
+sgml-minimize-attributes: nil
+sgml-general-insert-case: lower
+End:
+-->
+
diff --git a/doc/kbounce/jezball_corridor1.png b/doc/kbounce/jezball_corridor1.png
new file mode 100644
index 00000000..42df31c8
--- /dev/null
+++ b/doc/kbounce/jezball_corridor1.png
diff --git a/doc/kbounce/jezball_corridor2.png b/doc/kbounce/jezball_corridor2.png
new file mode 100644
index 00000000..38c84169
--- /dev/null
+++ b/doc/kbounce/jezball_corridor2.png
diff --git a/doc/kbounce/jezball_newWall.png b/doc/kbounce/jezball_newWall.png
new file mode 100644
index 00000000..4700df3e
--- /dev/null
+++ b/doc/kbounce/jezball_newWall.png