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, 423 insertions, 0 deletions

diff --git a/doc/kshisen/index.docbook b/doc/kshisen/index.docbook
new file mode 100644
index 00000000..483c4eb7
--- /dev/null
+++ b/doc/kshisen/index.docbook
@@ -0,0 +1,423 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kappname "&kshisen;">
+  <!ENTITY package "kdegames">
+  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+  <!ENTITY % addindex "IGNORE">
+]>
+
+<book lang="&language;">
+<bookinfo>
+<title>The &kshisen; Handbook</title>
+
+<authorgroup>
+<author>
+<firstname>Dirk</firstname>
+<surname>Doerflinger</surname>
+<affiliation>
+<address>&Dirk.Doerflinger.mail;</address>
+</affiliation>
+</author>
+<othercredit role="reviewer">
+<firstname>Frerich</firstname><surname>Raabe</surname>
+<contrib>Reviewer</contrib>
+<affiliation><address>&Frerich.Raabe.mail;</address></affiliation>
+</othercredit>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+
+<date>2006-06-17</date>
+<releaseinfo>1.5.1</releaseinfo>
+
+<abstract>
+<para>&kshisen; is a game similar to Mahjongg for &kde;.</para>
+</abstract>
+
+<keywordset>
+      <keyword>KDE</keyword>
+      <keyword>kdegames</keyword>
+      <keyword>kshisen</keyword>
+      <keyword>game</keyword>
+      <keyword>shisen-sho</keyword>
+</keywordset>
+
+</bookinfo>
+
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>&kshisen; is a single-player-game similar to Mahjongg and uses the same
+set of tiles as Mahjongg.</para> 
+
+<para>The object of the game is to remove all tiles from the field.</para>
+
+</chapter>
+
+<chapter id="playing-kshisen">
+<title>Playing &kshisen;</title>
+
+<sect1 id="rules">
+<title>Rules</title>
+
+<para>The aim of the game is to remove all tiles from the board. Only two
+matching tiles can be removed at a time. Two tiles can only be removed if they
+can be connected with a maximum of three connected lines. Lines can be
+horizontal or vertical, but not diagonal. </para>
+
+<para>You don't have to draw the lines by yourself, the game does this for
+you. Just mark two matching tiles on the board, if they can be connected with a
+maximum of three lines, the lines will be drawn and the tiles are
+removed. </para>
+
+<para>Remember that lines only may cross the empty border. If you are stuck, you
+can use the Hint feature to find two tiles which may be removed.  Clicking a
+tile with the &RMB; will show you all corresponding tiles, no matter if they are
+removable at the moment or not.</para>
+
+<para>The game is over when no moves are possible. This could be due to 
+clearing all the tiles from the field or reaching a point in the game 
+where no two matching tiles can be connected by three lines.  
+Some games are unsolvable, if you would like to avoid unsolvable 
+games uncheck the option <guilabel>Allow unsolvable
+games</guilabel> in the configuration dialog.</para>
+
+<para>The resulting score <quote>S</quote> is calculated using the
+following formula, assuming that <quote>n</quote> represents the
+number of tiles present when the game started and <quote>t</quote>
+standing for the time (in seconds) it took to clear the
+field:</para>
+
+<mediaobject><imageobject>
+<imagedata fileref="score-formula.png" format="PNG"/>
+</imageobject><textobject>
+<phrase>S=(n/t)*sqrt(n/84)/0.0014</phrase>
+</textobject></mediaobject>
+
+<para>If you played with the <guilabel>Gravity</guilabel> setting enabled, this score
+will additionally get multiplied by two.</para>
+</sect1>
+</chapter>
+
+<chapter id="menu-reference">
+<title>Menu Reference</title>
+
+<sect1 id="game-menu">
+<title>The <guimenu>Game</guimenu> Menu</title>
+
+<para>The <guimenu>Game</guimenu> menu lets you control the status of the
+current game:</para>
+
+<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>Finish the actual game</action> set and start a new
+session with new tiles. </para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycombo><keycap>F5</keycap></keycombo></shortcut>
+<guimenu>Game</guimenu><guimenuitem>Restart
+Game</guimenuitem></menuchoice></term>
+<listitem><para><action>Restart the current game with the same
+tiles.</action></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycombo><keycap>P</keycap></keycombo></shortcut>
+<guimenu>Game</guimenu>
+<guimenuitem>Pause</guimenuitem></menuchoice></term>
+<listitem><para><action>Pauses the entire game</action>, especially the timer
+which affects the scoring. The menu entry is also used for resuming the
+game.</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>Shows the (local) Top-Ten charts of &kshisen;.</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>Quits</action> &kshisen;. </para></listitem>
+</varlistentry>
+
+</variablelist>
+
+<para>Some of the menu items can also be controlled by keykoard shortcuts. 
+See <xref linkend="key-bindings"/> for a list.</para> 
+
+</sect1>
+
+<sect1 id="move-menu">
+<title>The <guimenu>Move</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice> <shortcut><keycombo
+action="simul">&Ctrl;<keycap>Z</keycap></keycombo></shortcut>
+<guimenu>Move</guimenu>
+<guimenuitem>Undo</guimenuitem></menuchoice></term>
+<listitem><para><action>Undo the last step</action>. Same as the
+<guibutton>Undo</guibutton> button in the toolbar.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><shortcut><keycombo
+action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo></shortcut> 
+<guimenu>Move</guimenu>
+<guimenuitem>Redo</guimenuitem></menuchoice></term>
+<listitem><para><action>Redo the last step</action>. Same as the
+<guibutton>Redo</guibutton> button in the toolbar.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycombo><keycap>H</keycap></keycombo></shortcut>
+<guimenu>Move</guimenu>
+<guimenuitem>Hint</guimenuitem></menuchoice></term>
+<listitem><para><action>Show a tip</action>, which two tiles to remove
+next.</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 Toolbar</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>
+Toggle on and off the display of the toolbar.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show Statusbar</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>
+Toggle on and off the display of the status bar.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Shortcuts...</guimenuitem>
+</menuchoice></term>
+<listitem><para>
+<action>Open a dialog which lets you redefine all the keyboard shortcuts.</action>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Toolbars...</guimenuitem>
+</menuchoice></term>
+<listitem><para>Displays a &kde; standard dialog where you can configure the toolbar icons.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure &kshisen;...</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>Opens the <link linkend="configuration">configuration
+dialog</link> to change &kshisen; settings.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</sect1>
+
+<sect1 id="helpmenu">
+<title>The <guimenu>Help</guimenu> Menu</title>
+
+&help.menu.documentation;
+
+</sect1>
+
+<sect1 id="key-bindings">
+<title>Shortcuts</title>
+
+<para>Default shortcuts are:
+</para>
+
+<informaltable>
+<tgroup cols="2">
+<tbody>
+<row><entry>New</entry><entry><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo></entry></row>
+<row><entry>Restart Game</entry><entry><keycap>F5</keycap></entry></row>
+<row><entry>Pause</entry><entry><keycap>P</keycap></entry></row>
+<row><entry>Show Highscores</entry><entry><keycombo action="simul">&Ctrl;<keycap>H</keycap></keycombo></entry></row>
+<row><entry>Quit</entry><entry><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></entry></row>
+<row><entry>Undo</entry><entry><keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo></entry></row>
+<row><entry>Redo</entry><entry><keycombo action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo></entry></row>
+<row><entry>Hint</entry><entry><keycap>H</keycap></entry></row>
+<row><entry>&kshisen; Handbook</entry><entry><keycap>F1</keycap></entry></row>
+<row><entry>What's This</entry><entry><keycombo action="simul">&Ctrl;&Shift;<keycap>F1</keycap></keycombo></entry></row>
+</tbody>
+</tgroup>
+</informaltable>
+
+</sect1>
+</chapter>
+
+<chapter id="configuration">
+<title>Configuration</title>
+
+<para>Selecting the <menuchoice><guimenu>Settings</guimenu>
+<guimenuitem>Configure &kshisen;...</guimenuitem></menuchoice> menu item will
+open a configuration dialog which lets you alter the behavior of the game.</para>
+
+<screenshot>
+<screeninfo>&kshisen; configuration dialog</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="kshisen-configuration.png" format="PNG"/></imageobject>
+<textobject><phrase>&kshisen; configuration dialog</phrase></textobject>
+</mediaobject>
+</screenshot>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Gravity</guilabel></term>
+<listitem><para>Checking this makes the game even harder: If a tile is
+removed, all tiles lying above it will fall down one step.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Allow unsolvable games</guilabel></term>
+<listitem><para>If checked, only solvable games will be
+created when a new game is started. Note: You may still choose the wrong way and
+have to try again if you didn't solve the game, but if it's checked, the game
+<emphasis>will</emphasis> be solvable.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Board Difficulty</guilabel></term>
+<listitem><para>The slider controls the difficulty of the board. There are three
+options <guilabel>Easy</guilabel>, <guilabel>Medium</guilabel> and 
+<guilabel>Hard</guilabel>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Piece Removal Speed</guilabel></term>
+<listitem><para>Adjusting this slider alters the speed at which the pieces are 
+removed from the screen after a match has been made.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Prefer Unscaled Tiles</guilabel></term>
+<listitem><para>Resizing the window causes the tiles on the board to be scaled to
+match the window size. When this option is checked, the window is resized to fit
+the tiles' natural size. You can still adjust the size of the window. Doing so
+causes this mode to be disengaged.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Tile Size</guilabel></term>
+<listitem><para>This slider allows you to can change the number of tiles 
+on the board. The more tiles you have, the harder (and longer)
+the game will be.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guibutton>Help</guibutton></term>
+<listitem><para>Opens &kshisen; help pages. (this document).</para></listitem></varlistentry>
+
+<varlistentry>
+<term><guibutton>Defaults</guibutton></term>
+<listitem><para>Reverts all settings to defaults.</para></listitem></varlistentry>
+
+<varlistentry>
+<term><guibutton>OK</guibutton></term>
+<listitem><para>Saves your changes and closes the dialog.</para></listitem></varlistentry>
+
+<varlistentry>
+<term><guibutton>Apply</guibutton></term>
+<listitem><para>Saves your changes but doesn't close the dialog.</para></listitem></varlistentry>
+
+<varlistentry>
+<term><guibutton>Cancel</guibutton></term>
+<listitem><para>Cancels all your changes and closes the dialog.</para></listitem></varlistentry>
+
+</variablelist>
+</chapter>
+
+<chapter id="credits">
+<title>Credits and License</title>
+
+<para>
+&kshisen; Copyright 1999 &Mario.Weilguni;
+&Mario.Weilguni.mail;
+</para>
+
+
+<para>
+Documentation Copyright 2000 &Dirk.Doerflinger;
+<email>[email protected]</email>
+</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;
+&underGPL;
+
+</chapter>
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="getting-kshisen">
+<title>How to obtain &kshisen;</title>
+
+&install.intro.documentation;
+
+</sect1>
+
+<sect1 id="requirements">
+<title>Requirements</title>
+
+<para>
+In order to successfully compile &kshisen;, you need &kde; 3.x.
+All required libraries as well as &kshisen; itself can be found on
+&kde-ftp;.</para>
+</sect1>
+
+
+<sect1 id="compilation">
+<title>Compilation and Installation</title>
+
+&install.compile.documentation;
+
+</sect1>
+</appendix>
+
+</book>
+