diff options
Diffstat (limited to 'doc/kblackbox/index.docbook')
| -rw-r--r-- | doc/kblackbox/index.docbook | 491 |
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: +--> + |