<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY ksirk '<application>KsirK</application>'>
  <!ENTITY kappname "&ksirk;"><!-- replace ksirk here -->
  <!ENTITY package "kdegames">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">
]>

<book id="ksirk" lang="&language;">

<bookinfo>
<title>The &kappname; Handbook</title>

<authorgroup>
<author>
<firstname>Gael</firstname>
<othername>Kleag</othername>
<surname>de Chalendar</surname>
<affiliation>
<address><email>Kleag@free.fr</email></address>
</affiliation>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>


<copyright>
<year>2002-2008</year>
<holder>Gael de Chalendar</holder>
</copyright>
<!-- Translators: put here the copyright notice of the translation -->
<!-- Put here the FDL notice.  Read the explanation in fdl-notice.docbook
     and in the FDL itself on how to use it. -->
<legalnotice>&FDLNotice;</legalnotice>

<!-- Date and version information of the documentation
Don't forget to include this last date and this last revision number, we
need them for translation coordination !
Please respect the format of the date (DD/MM/YYYY) and of the version
(V.MM.LL), it could be used by automation scripts.
Do NOT change these in the translation. -->

<date>18/09/2008</date>
<releaseinfo>4.1.2</releaseinfo>

<!-- Abstract about this handbook -->

<abstract>
<para>
&kappname; is a computerized version of a well known strategy game. Commercial
and other Free Software versions exist but I (Gaël de Chalendar) created this game
initially as a C++ learning exercise and so, I developed it up to this point (see README for details).
</para>
<para>
In the current version, &kappname; is a multi-player network-enabled game with an AI.
(see TODO for details)
</para>
<para>
This documentation gives the major information you need to start playing.
Please read the tooltips and the status bar messages to complete your information. A chapter explains how to create new skins for &kappname;
</para>
<para>
The goal of the game is simply to conquer the World... It is done by attacking your neighbors
with your armies. Peaceful, isn't it :-)
</para>
</abstract>

<!-- This is a set of Keywords for indexing by search engines.
Please at least include KDE, the KDE package it is in, the name
 of your application, and a few relevant keywords. -->

<keywordset>
<keyword>KDE</keyword>
<keyword>kdegames</keyword>
<keyword>game</keyword>
<keyword>strategy</keyword>
<keyword>Risk</keyword>
<keyword>free</keyword>
<keyword>GPL</keyword>
<keyword>Network</keyword>
<keyword>AI</keyword>
</keywordset>

</bookinfo>

<!-- The contents of the documentation begin here.  Label
each chapter so with the id attribute. This is necessary for two reasons: it
allows you to easily reference the chapter from other chapters of your
document, and if there is no ID, the name of the generated HTML files will vary
from time to time making it hard to manage for maintainers and for the CVS
system. Any chapter labeled (OPTIONAL) may be left out at the author's
discretion. Other chapters should not be left out in order to maintain a
consistent documentation style across all KDE apps. -->

<chapter id="introduction">
<title>Introduction</title>

<!-- The introduction chapter contains a brief introduction for the
application that explains what it does and where to report
problems. Basically a long version of the abstract.  Don't include a
revision history. (see installation appendix comment) -->
<para>
&kappname; is a computerized version of a well known strategy game. Commercial
and other Free Software versions exist but I (Gaël de Chalendar) created this game
initially as a C++ learning exercise and so, I developed it up to this point (see README for details).
</para>
<para>
<screenshot>
  <screeninfo>Here's a screenshot of &kappname;</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="firing-screenshot.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>Screenshot</phrase>
    </textobject>
  </mediaobject>
</screenshot>
</para>
<para>
In the current version, &kappname; is a multi-player network-enabled game with an AI.
(see TODO for details)
</para>
<para>
This documentation gives only the major information you need to start playing.
Please read the tooltips and the status bar messages to complete your information.
</para>
<para>
The goal of the game is simply to conquer the World... It is done by attacking your neighbors
with your armies. Peaceful, isn't it ? :-)
</para>
</chapter>

<chapter id="using-kapp">
<title>Using &kappname;</title>

<!-- This chapter should tell the user how to use your app. You should use as
many sections (Chapter, Sect1, Sect3, etc...) as is necessary to fully document
your application. -->



<sect1 id="playing-ksirk">
<title>Playing &kappname;</title>
<para>Preliminary note : the map can be scrolled by three methods:</para>
<itemizedlist><listitem><para>You can put your
mouse near a border of the window and the map will scroll in that direction</para></listitem>
<listitem><para>You can use your mouse wheel: with no modifier, it will scroll vertically; when pressing the &Alt;
key, it will scroll horizontally</para></listitem>
<listitem><para>You can use the keyboard arrows</para></listitem></itemizedlist>
<sect2 id="mainmenu" >
<title>Starting a game</title>
<para>
When &kappname; starts, you are presented with a main menu.
<screenshot>
  <screeninfo>The main menu of &kappname;</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="introscreen.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>Main menu</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<variablelist>
<varlistentry>
<term>
  <menuchoice>
    <guimenu>New Game</guimenu>
  </menuchoice>
</term>
<listitem>
  <para>
  <action>Starts a new game</action>
  </para>
</listitem>
</varlistentry>
<varlistentry>
  <term>
    <menuchoice>
      <guimenu>Join</guimenu>
    </menuchoice>
  </term>
  <listitem>
    <para>
      <action>Allow to join a network game as a client</action>
    </para>
  </listitem>
</varlistentry>
<varlistentry>
  <term>
    <menuchoice>
      <guimenu>Load</guimenu>
    </menuchoice>
  </term>
  <listitem>
    <para>
      <action>Use this to load a previously saved game</action>
    </para>
  </listitem>
</varlistentry>
<varlistentry>
  <term>
    <menuchoice>
      <guimenu>Quit</guimenu>
    </menuchoice>
  </term>
  <listitem>
    <para>
      <action>Maybe you finally don't want to play ?</action>
    </para>
  </listitem>
</varlistentry>
</variablelist>
</para>
<para>
If you hit <guibutton>New Game</guibutton> you will be presented with the <guilabel>New game properties</guilabel> dialog where you will be able to choose the number of players, the skin (or theme) to use, the game type (conquer the goal or have a specific goal) and finally if this game will be played with online players or if it is purely local.
<screenshot>
  <screeninfo>The New Game dialog</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="newgamedialog.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The New Game dialog</phrase>
    </textobject>
  </mediaobject>
</screenshot>
</para>
<para>
To start a network game, check the <guilabel>Network game</guilabel> check box on the right of the number of players spin box. After clicking <guibutton>OK</guibutton>, you will be able to choose the network parameters: number of network players and TCP port on which waiting for connections.
<screenshot>
  <screeninfo>Network game parameters dialog</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="numnetplayersdialog.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>Network game parameters dialog</phrase>
    </textobject>
  </mediaobject>
</screenshot>
</para>
<para>
Then, network players will be able to connect by choosing <guilabel>Join</guilabel> on the introduction screen and by indicating the IP or hostname of the host and the port number you just set.
<screenshot>
  <screeninfo>Joining network game dialog</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="joinnetgame.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>Joining network game dialog</phrase>
    </textobject>
  </mediaobject>
</screenshot>
</para>
<para>
Each connection is indicated by the message below in the status bar.
<screenshot>
  <screeninfo>Connection message</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="justjoined.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>Connection message</phrase>
    </textobject>
  </mediaobject>
</screenshot>

</para>
<para>
Let's suppose you keep all the default settings and hit <guibutton>OK</guibutton>. You will then setup two players, one after one. For each one, you'll choose a name, a nationality and, if you want, setup a password such that nobody else than you can reuse this player when reloading this saved game. Lastly, you will here specify if this player is played by the computer or by a human being.
<screenshot>
  <screeninfo>The Player Setup dialog</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="playersetupdialog.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The Player Setup dialog</phrase>
    </textobject>
  </mediaobject>
</screenshot>
</para>
<para>
Then, if you choose to play with goal, the goal of each local player is displayed, preceded by a warning such that other players looking at the same computer can discreetly turn away while the goal is being viewed.
<screenshot>
  <screeninfo>The Goal Display dialog</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="displaygoalmessage.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The Goal Display dialog</phrase>
    </textobject>
  </mediaobject>
</screenshot>
<screenshot>
  <screeninfo>The Goal Display warning message</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="displaygoalwarningmessage.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>The Goal Display warning message</phrase>
    </textobject>
  </mediaobject>
</screenshot>
</para>
</sect2>

<sect2 id="distribution" >
<title>Distribution</title>
<para>
At the beginning of the game, countries are distributed to all the players. Each country contains
one army (represented by an infantryman) at the start. Each player has some armies to
distribute to his countries at their turn (indicated by the presence of their name and their flag in
the status bar). Note that five armies are represented by a cavalryman and 10 by
a cannon.
</para>
<para>
To put an army on one of your countries, click on it with the left mouse button. To remove an
army, click with the right button. Note, as a general rule, that you will never be able to remove
more armies than the number you placed.
<screenshot>
  <screeninfo>Placing armies</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="placingarmies.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>Placing armies</phrase>
    </textobject>
  </mediaobject>
</screenshot>

</para>
<para>
When a player has distributed all there armies, the next player is automatically selected to do the
same task. When all players have finished to distributing their armies, there is two possibilities
that can be selected by two buttons showed in the right panel:
<variablelist>
<varlistentry>
<term>
      <inlinemediaobject>
        <imageobject>
          <imagedata fileref="recycling.png" format="PNG"/>
        </imageobject>
        <textobject>
          <phrase>Redistribution</phrase>
        </textobject>
      </inlinemediaobject>
    <guibutton>Recycle</guibutton>
</term>
<listitem>
  <para>
  <action>
  One player wants to change some of his choices. The first player can then remove an army he
  just put in a country with the right mouse button and put it in another one with the left mouse
  button. When he finishes, he gives control to next player with the <guibutton>Valid</guibutton> button. When all
  players have finished their redistribution, the two buttons are displayed again.
  </action>
  </para>
</listitem>
</varlistentry>
<varlistentry>
<term>
      <inlinemediaobject>
        <imageobject>
          <imagedata fileref="recyclingFinished.png" format="PNG"/>
        </imageobject>
        <textobject>
          <phrase>End of redistribution</phrase>
        </textobject>
      </inlinemediaobject>
    <guibutton>Done</guibutton>
</term>
<listitem><para><action>The redistribution is finished and the game can continue.
</action></para></listitem>
</varlistentry>
</variablelist>

</para>
</sect2>

<sect2 id="fight" >
<title>Fight</title>
<para>
After the redistribution, a turn starts. Each player plays at his turn. He has the choice to:
<variablelist>
  <varlistentry>
    <term>
          <inlinemediaobject>
            <imageobject>
              <imagedata fileref="joueurSuivant.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase>Next player</phrase>
            </textobject>
          </inlinemediaobject>
        <guibutton>Next Player</guibutton>
    </term>
    <listitem>
      <para>
        <action>
          The turn of the current player finishes and it's the turn of the next one.
        </action>
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
          <inlinemediaobject>
            <imageobject>
              <imagedata fileref="attackOne.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase>Attack 1</phrase>
            </textobject>
          </inlinemediaobject>
          &nbsp;<inlinemediaobject>
            <imageobject>
              <imagedata fileref="attackTwo.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase>Attack 2</phrase>
            </textobject>
          </inlinemediaobject>
          &nbsp;<inlinemediaobject>
            <imageobject>
              <imagedata fileref="attackThree.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase>Attack 3</phrase>
            </textobject>
          </inlinemediaobject><guibutton>Attack with one, two or three armies</guibutton>
          &nbsp;<inlinemediaobject>
            <imageobject>
              <imagedata fileref="autoattack.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase>Auto attack</phrase>
            </textobject>
          </inlinemediaobject>
          <guibutton>Auto attack</guibutton>
    </term>
    <listitem>
      <para>
          To attack, drag with the mouse from the attacking country and drop to the attacked one. You will then be presented with a contextual menu showing the above entries.
          <screenshot>
            <screeninfo>Attack menu</screeninfo>
            <mediaobject>
              <imageobject>
                <imagedata fileref="attackmenu.png" format="PNG"/>
              </imageobject>
              <textobject>
                <phrase>Attack menu</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
          For a country X to attack a country Y with x armies, 2 conditions must be fulfilled:</para>
          <itemizedlist><listitem><para> the two countries must be neighbors;</para></listitem>
          <listitem><para>country X must have at least x+1 armies before the attack.</para></listitem></itemizedlist>
        <para>
          If the attack is valid, a dialog is displayed if necessary for the defender to choose if he wants to defend with one or two armies or let the computer decide.
      </para>
      <para>
        When the defenders choice is done, the fight will occur and be completed. This will described below.
          <screenshot>
            <screeninfo>Defense dialog</screeninfo>
            <mediaobject>
              <imageobject>
                <imagedata fileref="defensedialog.png" format="PNG"/>
              </imageobject>
              <textobject>
                <phrase>Defense dialog</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
          <inlinemediaobject>
            <imageobject>
              <imagedata fileref="moveArmies.png" format="PNG"/>
            </imageobject>
            <textobject>
              <phrase>Move armies</phrase>
            </textobject>
          </inlinemediaobject>
          <guibutton>Move Armies from one country to another</guibutton>
    </term>
    <listitem>
      <para>
        <action>
          This is the last action of a player's turn. It gives the possibility to move some armies
          from one of his country to another, neighboring the first one. To choose the two
          countries, please drag and drop like you use during an attack. When both countries are selected,
          a slider is displayed on which you can choose how many armies there will be on each country afterwards.
        </action>
      </para>
    </listitem>
  </varlistentry>
</variablelist>
</para>
</sect2>
<sect2  id="fight-solution" >
  <title>Solution of the fight</title>
  <para>
    For each army in the fight there is a corresponding die cast. The player who rolls a higher number on the dice, whether being from the attacker or defender, wins and the one to roll a smaller number on the dice loses armies according to the number of dice thrown.
          <screenshot>
            <screeninfo>Attack result displayed</screeninfo>
            <mediaobject>
              <imageobject>
                <imagedata fileref="shownumberofarmies.png" format="PNG"/>
              </imageobject>
              <textobject>
                <phrase>Attack result displayed</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
  </para>
  <para>
    If the number of armies in the defender country reaches 0, the ownership of this country
    changes to the attacker: his flag is set up and one of his attacking armies is installed in his
    new country. The "Move armies" slider is displayed as for the moves of the end of the turn.
          <screenshot>
            <screeninfo>Invasion slider</screeninfo>
            <mediaobject>
              <imageobject>
                <imagedata fileref="invasionslider.png" format="PNG"/>
              </imageobject>
              <textobject>
                <phrase>Invasion slider</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
  </para>
</sect2>
<sect2  id="end_of_turn" >
  <title>End of the turn</title>
  <para>
    To finish your current turn, if you don't want to move armies, you can hit the <guibutton>Next Player</guibutton> button in the toolbar.
  </para>
  <para>
    When everybody has played, the turn is finished. Some armies are distributed to the
    players, in function of the countries they own: 1 for each group of three countries, with a
    minimum of 3. There is also a bonus for players that own a complete continent, different for
    each one. The values of the bonuses for the default skin are:
    <table>
      <title>Bonus due to the continents</title>
      <tgroup cols="2">
        <thead>
          <row><entry>Continent</entry><entry>Bonus</entry></row>
        </thead>
        <tbody>
          <row><entry>North America</entry><entry>5</entry></row>
          <row><entry>South America</entry><entry>2</entry></row>
          <row><entry>Europe</entry><entry>5</entry></row>
          <row><entry>Africa</entry><entry>3</entry></row>
          <row><entry>Asia</entry><entry>7</entry></row>
          <row><entry>Pacific Area</entry><entry>2</entry></row>
        </tbody>
      </tgroup>
    </table>
  </para>
  <para>
    When a player has finished distributing his armies, he clicks the <guibutton>Valid</guibutton> button to
    allow the next player to distribute his bonus armies. As for the initial distribution, when all player
    have placed their armies, they can start a new redistribution cycle or start a new turn...
  </para>
</sect2>
<sect2 id="sending-messages" >
<title>Sending messages to other players</title>
<para>
If you play a local game and want to communicate with the other players, well, let's speak (supposing you have no accessibility problems)... But if you are playing a network game, you can use the chat frame at the bottom of the window (it can be hidden or showed using the arrows). Just type in your message and hit &Enter;.
          <screenshot>
            <screeninfo>Sending messages</screeninfo>
            <mediaobject>
              <imageobject>
                <imagedata fileref="messagesent.png" format="PNG"/>
              </imageobject>
              <textobject>
                <phrase>Sending messages</phrase>
              </textobject>
            </mediaobject>
          </screenshot>

</para>
</sect2>
</sect1>
</chapter>

<chapter id="commands">
<title>Command Reference</title>

<sect1 id="kapp-mainwindow">
<title>The main &kappname; window</title>
<sect2>
<title>The buttons</title>
<para>
<variablelist>
<varlistentry>
<term>
      <inlinemediaobject>
        <imageobject>
          <imagedata fileref="quit.png" format="PNG"/>
        </imageobject>
        <textobject>
          <phrase>Quit Game</phrase>
        </textobject>
      </inlinemediaobject>
    <guibutton>Quit</guibutton>
</term>
<listitem><para><action>
Causes the program to quit.
</action></para></listitem>
</varlistentry>
<varlistentry>
<term>
      <inlinemediaobject>
        <imageobject>
          <imagedata fileref="newGame.png" format="PNG"/>
        </imageobject>
        <textobject>
          <phrase>New Game</phrase>
        </textobject>
      </inlinemediaobject>
    <guibutton>New Game</guibutton>
</term>
<listitem><para><action>Starts a new game. It will cause the displaying of a dialog asking
the number of players. After that, each player will be asked its name with another dialog.
</action></para></listitem>
</varlistentry>
</variablelist>
</para>

</sect2>

</sect1>
</chapter>

<chapter id="developers">
  <title>Developer's Guide to &kappname;</title>
  
  <para>
    Please refer to <ulink url="http://api.kde.org/">http://api.kde.org/</ulink> for the documentation of the API. It was quite complete but is currently a little bit outdated. There are no comments in the <filename>.cpp</filename> implementation files.
  </para>
  <para>
    Note that I originally developed this game under &Windows; with Borland C++ and WinG. I ported
    it to &Java; before converting back to C++ and &kde;. At the beginning I used French or a mix of
    French and English to name the identifiers (classnames, methods, members, &etc;). I also used French for the comments. When I decided to distribute this game, I decided to convert all to english... but I am clearly not a native English speaker: please suggest or make and submit corrections, to the code comments or to this documentation
  </para>
  
</chapter>

<chapter id="skins">
  <title>Creating new skins</title>
  <para>
    &kappname; comes with a skin editor, named ksirkskineditor(!), that allows to edit all skin data, as soon as graphics (map, sprites, etc.) are available in a SVG file. Please see the ksirkskineditor manual for further details.
  </para>
</chapter>

<chapter id="faq">
<title>Questions and Answers</title>

&reporting.bugs;
&updating.documentation;

<!-- commented out since it breaks compilation (endless loop due to empty answer tag) and looks unfinished anyway.
<qandaset id="faqlist">
<qandaentry>
<question>
<para>What will be the first question concerning &kappname;?</para>
</question>
<answer>
</answer>
</qandaentry>
</qandaset>
-->
</chapter>

<chapter id="credits">

<!-- Include credits for the programmers, documentation writers, and
contributors here. The license for your software should then be included below
the credits with a reference to the appropriate license file included in the KDE
distribution. -->

<title>Credits and License</title>

<para>
&kappname;
</para>
<para>
Program copyright 2002-2008 Gael de Chalendar <email>kleag@free.fr</email>
</para>
<para>
Contributors:
Robin Doer,
Albert Astals Cid,
Michal Golunski (Polish translation).
</para>

<para>
Documentation copyright 2002-2008 Gael de Chalendar <email>kleag@free.fr</email>
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;               <!-- FDL: do not remove. Commercial development should -->
<!-- replace this with their copyright and either remove it or re-set this.-->

<!-- Determine which license your application is licensed under,
     and delete all the remaining licenses below:

     (NOTE:  All documentation are licensed under the FDL,
     regardless of what license the application uses) -->

&underGPL;           <!-- GPL License -->

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-ksirk">
<title>How to obtain &kappname;</title>
&install.intro.documentation;
</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>
&install.compile.documentation;
</sect1>

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

<para>
  The settings menu entry opens a dialog that allows you to&nbsp;:
          <screenshot>
            <screeninfo>Preferences dialog</screeninfo>
            <mediaobject>
              <imageobject>
                <imagedata fileref="preferences.png" format="PNG"/>
              </imageobject>
              <textobject>
                <phrase>Preferences dialog</phrase>
              </textobject>
            </mediaobject>
          </screenshot>
</para>
      <itemizedlist>
        <listitem>
          <para>
      enable or disable the sounds&nbsp;;
          </para>
        </listitem>
        <listitem>
          <para>
      set the speed of the sprites (from slow to immediate)&nbsp;;
          </para>
        </listitem>
        <listitem>
          <para>
      enable or disable the contextual helps displayed in popups&nbsp;;
          </para>
        </listitem>
        <listitem>
          <para>
            show or hide the number of armies on each country. The following  snapshot shows the map when the number of armies are displayed.
            <screenshot>
              <screeninfo>Display of the number of armies</screeninfo>
              <mediaobject>
                <imageobject>
                  <imagedata fileref="shownumberofarmies.png" format="PNG"/>
                </imageobject>
                <textobject>
                  <phrase>Display of the number of armies</phrase>
                </textobject>
              </mediaobject>
            </screenshot>

          </para>
        </listitem>
      </itemizedlist>

</sect1>

</appendix>

&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->













