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

1 files changed, 491 insertions, 0 deletions

diff --git a/doc/kblackbox/index.docbook b/doc/kblackbox/index.docbook
new file mode 100644
index 00000000..d45c2f76
--- /dev/null
+++ b/doc/kblackbox/index.docbook
@@ -0,0 +1,491 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+ <!ENTITY kappname "&kblackbox;">
+ <!ENTITY package "kdegames">
+ <!ENTITY % addindex "IGNORE">
+ <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+<title>&kblackbox; Game Manual</title>
+    
+<authorgroup>
+<author>
+&Robert.Cimrman; &Robert.Cimrman.mail;
+</author>
+
+<author>
+&Philip.Rodrigues; &Philip.Rodrigues.mail;
+</author>
+
+<othercredit role="developer">
+&Robert.Cimrman; &Robert.Cimrman.mail;
+<!-- Uncomment this when xslt bug is fixed!
+<contrib>Developer</contrib>
+-->
+</othercredit>
+
+<othercredit role="reviewer">
+&Lauri.Watts; &Lauri.Watts.mail;
+<!-- Uncomment this when xslt bug is fixed!
+<contrib>Reviewer</contrib>
+-->
+</othercredit>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+
+</authorgroup>
+
+<copyright>
+<year>1998</year><year>2000</year>
+<holder>&Robert.Cimrman;</holder>
+</copyright>
+
+<copyright>
+<year>2001-2003</year>
+<holder>&Philip.Rodrigues;</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2005-12-10</date>
+<releaseinfo>0.3.0</releaseinfo>
+
+<abstract><para>&kblackbox; is a superb graphical logical game, inspired
+by the <application>emacs</application> blackbox game.</para></abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>KBlackBox</keyword>
+<keyword>kdegames</keyword>
+<keyword>blackbox</keyword>
+<keyword>game</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="what-is-kblackbox">
+<title>What is &kblackbox;?</title>
+
+<para>&kblackbox; is a superb :-) graphical logical game, inspired by
+the <application>emacs</application> blackbox game. A major part of this help
+file is based on the original <application>emacs</application>
+help. </para>
+
+<para>&kblackbox; is a game of hide and seek played on a grid of
+boxes. Your opponent (the Random number generator, in this case) has
+hidden several balls within this box. By shooting rays into the box and
+observing where they emerge it is possible to deduce the positions of
+the hidden balls. The fewer rays you use to find the balls, the better
+(the lower) your score.</para>
+
+</chapter>
+
+<chapter id="game-description">
+<title>Game Description</title>
+
+<para>In the first part of this section a description of the game board
+will be given.  The second part deals with user interaction with the
+game board and finally in the third part the actual game rules are
+explained.</para>
+
+<sect1 id="game-board-descritpion">
+<title>Game Board Description</title>
+
+<para>The following types of field are found on the game board: </para>
+
+<variablelist>
+<varlistentry>
+<term><interface>Black squares</interface></term>
+<listitem><para>The black box.  Here you must mark the squares you think
+a ball is in.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><interface>Green squares</interface></term>
+<listitem><para>These are the lasers, shooting rays of light when
+switched on.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><interface>Light Gray squares</interface></term>
+<listitem><para>Nothing here of interest, this is just a
+border :-).</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><interface>Blue balls</interface></term>
+<listitem><para><quote>There must be one there!</quote> you think.  These mark
+where you suspect a ball is placed in the black box.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><interface>Cyan balls</interface></term>
+<listitem><para>Show where the balls actually are.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><interface>Red balls</interface></term>
+<listitem><para>Incorrectly positioned balls you have marked are
+indicated in red.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><interface>Brown squares</interface></term>
+<listitem><para>Marking color</para></listitem>
+</varlistentry>
+</variablelist>
+
+<note><para>The names of colors are used just for identifying the
+different types of the fields in this text. They <emphasis>might
+not</emphasis> be in any relation with the actual color of the
+fields. Simply said: the black box is in the center, around are the
+lasers and around them is the border. Remap the colors yourself
+:-). </para></note>
+
+</sect1>
+
+<sect1 id="user-interaction">
+<title>User Interaction</title>
+
+<para>The cursor can be moved around the box with the
+standard cursor movement keys or the mouse. Switching of lasers or
+marking of black boxes is done with the &LMB;, or by pressing the
+<keycap>Return</keycap> or &Enter; key.</para>
+
+<para>You can mark the fields where you think a ball cannot be, too. Just press
+the &RMB;. It often helps you to find an area where a ball could possibly
+be. To clear any marks (blue or brown) press the
+&LMB;. Brown marks cannot overwrite blue
+marks. This way you cannot erase the blue marks (guessed balls) by accident when
+playing with the &RMB;. </para>
+
+<para>When you think the configuration of balls you have placed is
+correct, press the &MMB;. You
+will be informed whether you are correct or not, and be given your
+score. Your score is the number of letters and numbers around the
+outside of the box plus five for each incorrectly placed ball. If you
+placed any balls incorrectly, they will be indicated with red fields,
+and their actual positions indicated with cyan fields.</para>
+
+</sect1>
+
+<sect1 id="game-rules">
+<title>Game Rules</title>
+
+<para>You have to find balls hidden in the black box. Your means are
+limited - you can just fire lasers which are around the box. There are
+three possible outcomes for each ray you send into the box: </para>
+
+<anchor id="detour"/>
+<variablelist>
+
+<varlistentry>
+<term>Detour</term> 
+<listitem><para>The ray is deflected and emerges somewhere other than
+where you sent it in. On the playfield, detours are denoted by matching
+pairs of numbers - one where the ray went in, and the other where it
+came out.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Reflection</term>
+<listitem><para>The ray is reflected and emerges in the same place it
+was sent in. On the playfield, reflections are denoted by the letter
+<guilabel>R</guilabel>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Hit</term>
+<listitem><para>The ray strikes a ball directly and is absorbed. It does not
+emerge from the box. On the playfield, hits are denoted by the letter
+<guilabel>H</guilabel>.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>The rules for how balls deflect rays are simple and are best shown by
+example.</para>
+
+<para>As a ray approaches a ball it is deflected ninety degrees. Rays
+can be deflected multiple times. In the diagrams below, the dashes
+represent empty box locations and the letter <guilabel>O</guilabel>
+represents a ball. The entrance and exit points of each ray are marked
+with numbers as described under <link linkend="detour">Detour</link>
+above. Note that the entrance and exit points are always
+interchangeable. <guilabel>*</guilabel> denotes the path taken by the
+ray.</para>
+
+<para>Note carefully the relative positions of the ball and the ninety
+degree deflection it causes.</para>
+
+<screen>
+    1                                            
+  - * - - - - - -         - - - - - - - -         - - - - - - - -       
+  - * - - - - - -         - - - - - - - -         - - - - - - - -       
+1 * * - - - - - -         - - - - - - - -         - O - - - - O -       
+  - - O - - - - -         - - O - - - - -         - - * * * * - -
+  - - - - - - - -         - - - * * * * * 2     3 * * * - - * - -
+  - - - - - - - -         - - - * - - - -         - - - O - * - -      
+  - - - - - - - -         - - - * - - - -         - - - - * * - -       
+  - - - - - - - -         - - - * - - - -         - - - - * - O -       
+                                2                         3
+</screen>
+
+<para>
+As mentioned above, a reflection occurs when a ray emerges from the same
+point it was sent in. This can happen in several ways:
+</para>
+
+<screen>
+  - - - - - - - -         - - - - - - - -          - - - - - - - -
+  - - - - O - - -         - - O - O - - -          - - - - - - - -
+R * * * * - - - -         - - - * - - - -          O - - - - - - -
+  - - - - O - - -         - - - * - - - -        R - - - - - - - -
+  - - - - - - - -         - - - * - - - -          - - - - - - - -
+  - - - - - - - -         - - - * - - - -          - - - - - - - -
+  - - - - - - - -       R * * * * - - - -          - - - - - - - -
+  - - - - - - - -         - - - - O - - -          - - - - - - - -
+
+</screen>
+
+<para>In the first example, the ray is deflected downwards by the upper
+ball, then left by the lower ball, and finally retraces its path to its
+point of origin. The second example is similar. The third example is a
+bit anomalous but can be rationalized by realizing the ray never gets a
+chance to get into the box. Alternatively, the ray can be thought of as
+being deflected downwards and immediately emerging from the box.</para>
+
+<para>A hit occurs when a ray runs straight into a ball:</para>
+
+<screen>
+  - - - - - - - -         - - - - - - - -          - - - - - - - -
+  - - - - - - - -         - - - - - - - -          - - - - O - - -
+  - - - - - - - -         - - - - O - - -        H * * * * - - - -
+  - - - - - - - -       H * * * * O - - -          - - - * - - - -
+  - - - - - - - -         - - - - O - - -          - - - O - - - -
+H * * * O - - - -         - - - - - - - -          - - - - - - - -
+  - - - - - - - -         - - - - - - - -          - - - - - - - -
+  - - - - - - - -         - - - - - - - -          - - - - - - - -
+
+</screen>
+
+<para>Be sure to compare the second example of a hit with the first
+example of a reflection.</para>
+
+</sect1>
+</chapter>
+<chapter id="gui-description">
+<title>&GUI; description</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>Starts a new game (and abandons the current, if
+any.)</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Game</guimenu>
+<guimenuitem>Give Up</guimenuitem></menuchoice></term>
+<listitem><para>Shows you positions of the balls.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Game</guimenu>
+<guimenuitem>Done</guimenuitem></menuchoice></term>
+<listitem><para>Checks whether all balls are placed. If yes, it terminates
+the current game, computes the final score and indicates real positions of
+the balls. The <mousebutton>middle</mousebutton> mouse button has the same
+function. </para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Game</guimenu>
+<guimenuitem>Resize</guimenuitem></menuchoice></term>
+<listitem><para>Resizes the main window, so that its contents fit perfectly. This is useful when you accidentally change the size of the
+window...</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>Quits &kblackbox;</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="settings-menu">
+<title>The <guimenu>Settings</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Show/Hide Toolbar</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Shows or hides the &kblackbox; toolbar.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Show/Hide Statusbar</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>Shows or hides the &kblackbox; status bar at the base of the screen.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Settings</guimenu>
+<guisubmenu>Size</guisubmenu></menuchoice></term>
+<listitem><para>Sets the size of the game field (black box).  You may choose
+between <guimenuitem>8 x 8</guimenuitem>, <guimenuitem>10 x 10</guimenuitem> and
+<guimenuitem>12 x 12</guimenuitem>.  The default is <guimenuitem>8 x
+8</guimenuitem>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Settings</guimenu>
+<guisubmenu>Balls</guisubmenu></menuchoice></term>
+<listitem><para>Sets the number of balls in the black box. You may choose
+between <guimenuitem>4</guimenuitem> (the default), <guimenuitem>6</guimenuitem>
+or <guimenuitem>8</guimenuitem>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Settings</guimenu>
+<guimenuitem>Tutorial</guimenuitem></menuchoice></term>
+<listitem><para>Switches the tutorial mode on or off.  In tutorial mode,
+you can see where the balls actually are. Note that you have to start a new
+game for this change to take effect.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Settings</guimenu>
+<guimenuitem>Configure Shortcuts...</guimenuitem></menuchoice></term>
+<listitem><para>Displays a standard &kde; shortcut configuration dialog, in
+which you can change the keyboard shortcuts used by &kblackbox;.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Configure Toolbars...</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>Brings up the standard &kde; toolbar configuration dialog to customize the &kblackbox; toolbar.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+
+<sect1 id="help">
+<title>The <guimenuitem>Help</guimenuitem> Menu</title>
+
+&help.menu.documentation;
+
+</sect1>
+
+<sect1 id="toolbar">
+<title>The Toolbar</title>
+
+<screenshot>
+<screeninfo>&kblackbox;'s toolbar</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="kblackboxtbar.png" format="PNG"/>
+</imageobject>
+</mediaobject>
+</screenshot>
+
+<para>The &kblackbox; toolbar offers quick access to the most commonly used
+&kblackbox; functions. From left to right, the icons are:</para>
+
+<variablelist>
+
+<varlistentry>
+<term><guiicon>New</guiicon></term>
+<listitem><para>Starts a new game.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guiicon>Give Up</guiicon></term>
+<listitem><para>Shows you positions of the balls.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guiicon>Done</guiicon></term>
+<listitem><para>Checks whether all balls are placed. If yes, it terminates
+the current game, computes the final score and indicates real positions of
+the balls. The <mousebutton>middle</mousebutton> mouse button has the same
+function. </para></listitem>
+</varlistentry>
+
+</variablelist>
+</sect1>
+</chapter>
+
+<chapter id="credits-and-license">
+<title>Credits and License</title>
+
+<para>&kblackbox;</para>
+
+<para>Program Copyright 1998-2000 &Robert.Cimrman; &Robert.Cimrman.mail;</para>
+
+<para>Documentation by &Robert.Cimrman;.  Updated and converted to Docbook
+for &kde; 2.0 by &Lauri.Watts; &Lauri.Watts.mail;</para>
+
+<para>
+Current maintainer &Philip.Rodrigues; &Philip.Rodrigues.mail;
+</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;
+&underGPL;
+
+</chapter>
+
+
+<appendix id="installation">
+<title>Installation</title>
+
+&install.intro.documentation;
+
+<sect1 id="compilation">
+<title>Compilation and Installation</title>
+
+&install.compile.documentation;
+
+</sect1>
+</appendix>
+
+</book>
+
+<!--
+Local Variables:
+mode: sgml
+sgml-omittag: nil
+sgml-shorttag: t
+End:
+-->
+