<?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><email>ddoerflinger@web.de</email></address>
</affiliation>
</author>
<othercredit role="reviewer">
<firstname>Frerich</firstname><surname>Raabe</surname>
<contrib>Reviewer</contrib>
<affiliation><address><email>raabe@kde.org</email></address></affiliation>
</othercredit>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

<date>2003-09-17</date>
<releaseinfo>1.4.90</releaseinfo>

<abstract>
<para>This Handbook describes &kshisen; Version 1.4.90</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 if no moves are possible and some tiles are left on the
board (this should not happen if the option <guimenuitem>Disallow Unsolvable
Games</guimenuitem> in the <guimenu>Settings</guimenu> menu is checked, since for
these games there is at least one way to solve it, though it may happen that you
choose the wrong way).</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>

<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 then changes to
<guimenuitem>Resume Game</guimenuitem>, which is 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 hot-keys. 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>
</chapter>

<chapter id="configuration">
<title>Configuration</title>

<sect1 id="settings-menu">
<title>The <guimenu>Settings</guimenu> Menu</title>

<para>&kshisen; has several possibilities to change its behavior. All options
can be changed from the menu <guimenu>Settings</guimenu>.</para>

<para>The options will be saved automatically.</para>

<variablelist>
<varlistentry>
<term>
<menuchoice><guimenu>Settings</guimenu>
<guisubmenu>Size</guisubmenu></menuchoice></term>
<listitem><para>In the sub-menu <guisubmenu>Size</guisubmenu> you 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><menuchoice><guimenu>Settings</guimenu>
<guisubmenu>Speed</guisubmenu></menuchoice></term>
<listitem><para>The sub-menu <guisubmenu>Speed</guisubmenu> sets the time for
the tiles to disappear when connected correctly. </para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice><guimenu>Settings</guimenu>
<guisubmenu>Level</guisubmenu></menuchoice></term>
<listitem><para>Choose your game skill in the sub-menu
<guisubmenu>Level</guisubmenu>.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice><guimenu>Settings</guimenu>
<guimenuitem>Gravity</guimenuitem></menuchoice></term>
<listitem><para>Checking this item 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><menuchoice><guimenu>Settings</guimenu>
<guimenuitem>Disallow Unsolvable Games</guimenuitem></menuchoice></term>
<listitem><para>If this menu-item is 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><menuchoice><guimenu>Settings</guimenu>
<guimenuitem>Prefer Unscaled Tiles</guimenuitem></menuchoice></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>

</variablelist>

</sect1>

<sect1 id="key-bindings">
<title>Key Bindings</title>

<para>Default key bindings are:
</para>
<simplelist>
<member>New: <keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo></member>
<member>Restart Game: <keycombo><keycap>F5</keycap></keycombo></member>
<member>Pause: <keycombo><keycap>P</keycap></keycombo></member>
<member>Show Highscores: <keycombo action="simul">&Ctrl;<keycap>H</keycap></keycombo></member>
<member>Quit: <keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></member>

<member>Undo: <keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo></member>
<member>Redo: <keycombo action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo></member>
<member>Hint: <keycombo><keycap>H</keycap></keycombo></member>

<member>Prefer Unscaled Tiles: <keycombo><keycap>S</keycap></keycombo></member>

<member>What's This?: <keycombo action="simul">&Shift;<keycap>F1</keycap></keycombo></member>
</simplelist>
</sect1>
</chapter>


<chapter id="credits">
<title>Credits and License</title>

<para>
&kshisen; Copyright 1999 Mario Weilguni
<email>mweilguni@sime.com</email>
</para>


<para>
Documentation Copyright 2000 Dirk Doerflinger
<email>ddoerflinger@gmx.net</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>

