tdegames/doc/kshisen/index.docbook

<?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 "tdegames">
  <!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>tdegames</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>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>