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

3 files changed, 663 insertions, 0 deletions

diff --git a/doc/kspaceduel/Makefile.am b/doc/kspaceduel/Makefile.am
new file mode 100644
index 00000000..368fc0da
--- /dev/null
+++ b/doc/kspaceduel/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_DOCS = AUTO
+KDE_LANG = en
+
diff --git a/doc/kspaceduel/index.docbook b/doc/kspaceduel/index.docbook
new file mode 100644
index 00000000..2d3cc2b7
--- /dev/null
+++ b/doc/kspaceduel/index.docbook
@@ -0,0 +1,659 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kappname "&kspaceduel;">
+  <!ENTITY package "kdegames">
+  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+  <!ENTITY % addindex "IGNORE">
+]>
+
+<book lang="&language;">
+<bookinfo>
+<title>The &kspaceduel; Handbook</title>
+ 
+<authorgroup>
+<author>
+<firstname>Andreas </firstname>
+<surname>Zehender</surname>
+<affiliation>
+<address><email>az@azweb.de</email></address>
+</affiliation>
+</author>
+</authorgroup>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+ 
+<copyright>
+<year>1999</year><year>2000</year>
+<holder>Andreas Zehender</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+ 
+<date>2003-09-17</date>
+<releaseinfo>1.1</releaseinfo>
+
+<abstract>
+<para>&kspaceduel; is an space arcade game. </para>
+<para>Two ships fly around the sun and try to shoot eachother.</para>
+</abstract>
+
+
+<keywordset>
+<keyword>Space duel</keyword>
+<keyword>KDE</keyword>
+<keyword>game</keyword>
+<keyword>ships</keyword>
+<keyword>shooting</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>&kspaceduel; is an space arcade game for two players.</para> 
+
+<para>Each player controls a ship that flies around the sun and tries to shoot
+at the other ship. You can play &kspaceduel; with another person, against the
+computer, or you can have the computer control both ships and play each
+other.</para>
+
+</chapter>
+
+<chapter id="the-game">
+<title>The Game</title>
+<para>The idea of the game is simple (but addictive).  You try to destroy your opponent before he destroys you.</para>
+<para>Be careful not to hit the sun.</para>
+<sect1 id="rules-of-the-game">
+<title>Rules of the Game</title>
+<sect2 id="ship-movement">
+<title>Ship Movement</title>
+<para>Each player controls one ship. </para>
+<para>The ships can rotate, accelerate, shoot and lay mines.</para>
+</sect2>
+
+<sect2 id="energy">
+<title>Energy</title> 
+
+<para>Each ship has an amount of energy (refer to the game
+options for values). </para> 
+
+<para>Ships need energy for rotation, acceleration, shooting and laying mines. A
+ship gets energy from its solar panels. The amount of energy a ship gets depends
+on the distance from and direction to the sun. A ship gets more energy near the
+sun and less energy near the border. It gets the full amount of energy if the
+sun shines directly on the panels and less or even no energy if the sun shines
+at an angle to the panel or to the side of the panel.</para>
+
+<para>If a ship has no energy it can't navigate or shoot. </para>
+
+</sect2>
+
+<sect2 id="hit-points">
+<title>Hit points</title>
+
+<para>Collisions with own or other bullets or mines decrease the hit points of a
+ship.  If two ships collide, the weaker ship is destroyed and the hit points of
+the stronger ship are decreased by the hit points of the weaker ship plus an
+amount (Crash Damage). A ship is destroyed when it flies into the sun.</para>
+
+</sect2>
+
+<sect2 id="bullets-and-mines">
+<title>Bullets and Mines </title>
+
+<para>Bullets fly around the sun like a ship. </para>
+
+<para>Mines have an amount of energy to stay at the same position. When the
+energy is spent, the mine falls into the sun. Mines near the sun need more
+energy than those which are further away. </para>
+
+<para>Mines can be destroyed with bullets. </para>
+
+<para>By default a ship can have 5 bullets and 3 mines on the screen. </para>
+
+</sect2>
+
+<sect2 id="powerups">
+<title>Powerups</title>
+
+<para>From time to time powerups appear on the play field.</para>
+
+<para>There are four different powerups:</para>
+
+<variablelist>
+<varlistentry>
+<term>Mine</term>
+<listitem><para>The maximum number of mines is increased for the
+player.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Bullet</term>
+<listitem><para>The maximum number of bullets is increased for the
+player.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Energy (yellow sphere)</term>
+<listitem><para>The player gets energy.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>Shield (blue sphere)</term>
+<listitem><para>The player gets hit points</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2 id="screen">
+<title>The &kspaceduel; screen</title>
+
+<screenshot>
+<screeninfo>&kspaceduel; Main Screen</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="kspaceduel3.png" format="PNG"/></imageobject>
+<textobject><phrase>&kspaceduel; Main Screen</phrase></textobject>
+</mediaobject>
+</screenshot>   
+
+<para>You can see that the central part of the &kspaceduel; screen is the playing
+area.  To the left and the right are the Red Player's and the Blue Player's
+stats.</para>
+<para>The top box on the player stats, represents the <quote>Hit Points</quote> of the
+craft.</para>
+<para>The middle box on the player stats, represents the battery power.</para>
+<para>The bottom box on the player stats, shows the number of wins.</para>
+<para>The top of the playing area is occupied by the menubar and toolbar.</para>
+<para>The bottom of the playing area is the status bar.</para>
+
+</sect2>
+</sect1>
+
+<sect1 id="options">
+<title>Game Options</title>
+
+<para>&kspaceduel; has many, many options you can adjust to increase the enjoyment
+of this game.</para>
+
+<para>Configuration is divided into two sections:</para>
+
+<itemizedlist>
+<listitem><para><link linkend="options-keys">Player Keys</link></para></listitem>
+<listitem><para><link linkend="options-configurations">Game Settings</link></para></listitem>
+</itemizedlist>
+
+<sect2 id="options-keys">
+<title>Keys</title>
+
+<para>&kspaceduel; has a default set of keys to control the game.  For a list of
+default keys see the section entitled <link linkend="keys">Default key
+bindings</link>.</para>
+
+<para>Keys can be configured by:  </para>
+
+<para>Selecting <menuchoice> <guimenu>Settings</guimenu><guimenuitem>Configure
+Shortcuts...</guimenuitem> </menuchoice> from the menubar.</para>
+
+<para>This will bring up a dialog box which lets you configure all hotkeys,
+including the keys used for steering the space ships, for firing bullets, and
+for laying mines.</para>
+
+<para>You can see that each player (Red and Blue), have 5 keystrokes
+corresponding to Rotate Left, Rotate Right, Accelerate, Shot, and Mines.</para>
+
+<para>When you are finished configuring your keys, you should click on
+<guibutton>OK</guibutton> to apply your changes.</para>
+
+<para>If you want to restore the default keys, simply click on the
+<guibutton>Default</guibutton> button once. To make these changes permenant,
+press <guibutton>OK</guibutton>.</para> 
+
+<para>If you want to abandon the changes you made, and return to your previously
+selected keys, simply click <guibutton>Cancel</guibutton>, and your changes
+will be lost.</para>
+</sect2>
+
+<sect2 id="options-configurations">
+<title>Game Configuration</title>
+
+<para>All game settings of &kspaceduel; are configurable.</para>
+
+<para>If you want to change the game settings, simply select
+<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kspaceduel;...</guimenuitem> 
+</menuchoice> from the menubar.</para>
+
+<para>This will bring up a dialog box with two pages, labelled
+<guilabel>General</guilabel> and <guilabel>Game</guilabel>. The first page
+is rather simple, the second one has seven tabs across the top.</para>
+
+<para>Settings are collected in different configurations. You can choose from
+several pre-defined configurations.</para>
+
+<para>If you choose the <guilabel>Custom</guilabel> configuration, you can
+define all settings for yourself.</para> 
+
+<note><para>If you have not selected <guilabel>Custom</guilabel>, you will not
+be able to make any changes to these options.</para></note>
+
+<tip><para> If you have found an interesting configuration, mail it to the
+author of the game. It can be implemented in a future version (send the part
+[Game] in the file
+<filename>~/.kde/share/config/kspaceduelrc</filename>).</para></tip> 
+
+<para>When you are finished altering the options, you should click on
+<guibutton>OK</guibutton> to apply your changes.</para> 
+
+<para>If you want to restore the default, simply click on the
+<guibutton>Default</guibutton> button once. To make these changes permenant,
+press <guibutton>OK</guibutton>.</para> 
+
+<para>If you want to abandon the changes you made, and return to your previous
+options, simply click <guibutton>Cancel</guibutton>, and your changes will be
+lost.</para>
+
+<para>The settings are:</para>
+
+<sect3 id="general">
+<title><guilabel>General</guilabel></title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Hit Points</guilabel></term>
+<listitem><para>These two sliders allow you to define the hitpoints for each
+of the two players; you might want to decrease the hitpoints for a player
+to give that player a handycap.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Refresh time</guilabel></term>
+<listitem><para>Time between two screen refreshes in milliseconds.  All other
+settings are independent of the refresh time.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Red Player</guilabel></term>
+<listitem><para>Here you can define whether the red player gets controlled by
+the AI, and also choose the skill level of the AI for this player. Just
+experiment with the different skill level to find one which fits you.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Blue Player</guilabel></term>
+<listitem><para>This works the same as the options for the <guilabel>Red
+Player</guilabel> described above.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect3>
+
+<sect3 id="game">
+<title><guilabel>Game</guilabel></title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Game speed</guilabel></term>
+<listitem><para>Controls the speed of the whole game.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect3>
+
+<sect3 id="bullet">
+<title><guilabel>Bullet</guilabel></title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Shot speed</guilabel></term>
+<listitem><para>The speed of bullets</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Energy need</guilabel></term>
+<listitem><para>The amount of energy needed for one shot.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Max number</guilabel></term>
+<listitem><para>The maximum number of bullets a player can have on the
+screen.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Damage</guilabel></term>
+<listitem><para>The number of hit points damage done when a bullet hits a
+ship.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Life time</guilabel></term>
+<listitem><para>The maximum life time of a bullet.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Reload time</guilabel></term>
+<listitem><para>The time a ship needs to reload a bullet.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect3>
+<sect3 id="mine">
+<title>Mine</title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Mine fuel</guilabel></term>
+<listitem><para>The amount of fuel on a mine.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Energy need</guilabel></term>
+<listitem><para>The amount of energy needed for laying a mine.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Activate time</guilabel></term>
+<listitem><para>The time a mine is inactive.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Damage</guilabel></term>
+<listitem><para>The number of hit points of damage done when a ship hits a
+mine.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Max number</guilabel></term>
+<listitem><para>Maximum number of mines a player can have on the
+screen.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Reload time</guilabel></term>
+<listitem><para>The time a ship needs to reload a mine.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect3>
+
+<sect3 id="ship">
+<title><guilabel>Ship</guilabel></title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Acceleration</guilabel></term>
+<listitem><para>Acceleration of the ships</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Energy need</guilabel></term>
+<listitem><para>The energy needed to accelerate a ship.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Rotation speed</guilabel></term>
+<listitem><para>The speed at which a ship rotates.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Energy need</guilabel></term>
+<listitem><para>The energy needed to rotate a ship.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Crash damage</guilabel></term>
+<listitem><para>The number of hit points damage done when two ships
+collide.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect3>
+
+<sect3 id="sun">
+<title><guilabel>Sun</guilabel></title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Sun energy</guilabel></term>
+<listitem><para>The strength of the sun.  The higher the value, the quicker
+ships will be recharged.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Gravity</guilabel></term>
+<listitem><para>The strength of the gravitational pull of the
+sun.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect3>
+
+<sect3 id="start">
+<title><guilabel>Start</guilabel></title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Position X</guilabel> and <guilabel>Position Y</guilabel></term>
+<listitem><para>The ships position at the beginning of a new round.  The ships
+start at opposite sides of the sun.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Velocity X</guilabel> and <guilabel>Velocity Y</guilabel></term>
+<listitem><para>Velocity at the beginning of a new round.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect3>
+
+<sect3 id="powerup-options">
+<title><guilabel>Powerups</guilabel></title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Appearance time</guilabel></term>
+<listitem><para>Maximal time between the appearance of two
+powerups.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Life time</guilabel></term>
+<listitem><para>Maximal life time of a powerup.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Energy amount</guilabel></term>
+<listitem><para>Amount of energy a player gets from an energy
+powerup.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Shield amount</guilabel></term>
+<listitem><para>Amount of hit points a player gets from a shield
+powerup.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect3>
+</sect2>
+</sect1>
+</chapter>
+
+<chapter id="command">
+<title>Commands/Keyboard Shortcuts</title>
+
+<para>The following sections briefly describe each menubar option.</para>
+
+<sect1 id="game-menu">
+<title>The <guimenu>Game</guimenu> Menu</title>
+
+<para>The <guimenu>Game</guimenu> menu is used to start and pause the 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>Starts a new game of &kspaceduel;.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycombo action="simul">
+&Ctrl;<keycap>N</keycap></keycombo></shortcut>
+<guimenu>Game</guimenu><guimenuitem>New Round</guimenuitem> </menuchoice></term>
+<listitem><para>Starts a new round, at the current level.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycombo action="simul"><keycap>P</keycap></keycombo></shortcut>
+<guimenu>Game</guimenu><guimenuitem>Pause</guimenuitem> </menuchoice></term>
+<listitem><para>Pauses and unpauses the game.</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> &kspaceduel;</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="settings-menu">
+<title><guimenu>Settings</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Show Toolbar</guimenuitem> </menuchoice></term>
+<listitem><para>When selected, the toolbar will be visible.  When not selected,
+the toolbar will be hidden.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Show Statusbar</guimenuitem>
+</menuchoice></term>
+<listitem><para>When selected, the status bar (the bar along the bottom of the
+screen which gives textual information) will be visible.  When not selected, the
+status bar will be hidden.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Shortcuts...</guimenuitem>
+</menuchoice></term>
+<listitem><para>Allows you to change the keyboard shortcuts for &kspaceduel;,
+including the keys for steering the space ship, firing bullets &etc;.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice><guimenu>Settings</guimenu>
+<guimenuitem>Configure Toolbars...</guimenuitem>
+</menuchoice></term>
+<listitem><para>Display the standard KDE Toolbar Configuration Dialog.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure &kspaceduel;...</guimenuitem>
+</menuchoice></term>
+<listitem><para>Opens a configuration dialog which lets you define many
+settings of the game, refer to the chapter <link linkend="options">Game
+Options</link> for further information.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="help-menu">
+<title><guimenu>Help</guimenu> Menu</title>
+
+&help.menu.documentation;
+
+</sect1>
+
+<sect1 id="keys">
+<title>Default Key Bindings</title>
+
+<para>The following tables show you the default key bindings.</para>
+
+<para><emphasis>Menu bindings</emphasis></para>
+
+<informaltable frame="all">
+<tgroup cols="2">
+<thead><row><entry>Key Combo</entry><entry>Action</entry></row></thead>
+<tbody>
+<row><entry><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></entry><entry>Quit &kspaceduel;</entry></row>
+<row><entry><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo></entry><entry>New Game</entry></row>
+<row><entry><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo></entry><entry>New Round</entry></row>
+<row><entry><keycombo action="simul"><keycap>P</keycap></keycombo></entry><entry>Pause Game</entry></row>
+<row><entry><keycombo action="simul"><keycap>F1</keycap></keycombo></entry><entry>Help Contents</entry></row>
+<row><entry><keycombo action="simul">&Shift;<keycap>F1</keycap></keycombo></entry><entry>Whats This Help</entry></row>
+<row><entry><keycombo action="simul"><keycap>Space</keycap></keycombo></entry><entry>Start Game</entry></row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>The Menu Key Bindings can be changed by selecting <menuchoice>
+<guimenu>Settings</guimenu> <guimenuitem>Configure Key Bindings</guimenuitem>
+</menuchoice></para>
+
+<para><emphasis>Game Play</emphasis></para>
+
+<informaltable frame="all">
+<tgroup cols="3">
+<colspec colname="c1"/>
+<colspec colname="c2"/>
+<colspec colname="c3"/>
+<thead><row><entry>Action</entry><entry>Red Player</entry><entry>Blue Player</entry></row></thead>
+<tbody>
+<row><entry>Rotate Left</entry><entry>S</entry><entry>Left Arrow</entry></row>
+<row><entry>Rotate Right</entry><entry>F</entry><entry>Right Arrow</entry></row>
+<row><entry>Accelerate</entry><entry>E</entry><entry>Up Arrow</entry></row>
+<row><entry>Shot</entry><entry>D</entry><entry>Down Arrow</entry></row>
+<row><entry>Mines</entry><entry>A</entry><entry>Insert</entry></row>
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>To change these keys, refer to the section entitled <link
+linkend="options-keys">Player Keys...</link>.</para>
+
+</sect1>
+</chapter>
+
+<chapter id="credits">
+<title>Credits and License</title>
+ 
+<para>
+&kspaceduel;
+</para>
+<para>
+Program copyright 1999-2000 Andreas Zehender <email>az@azweb.de</email></para>
+<para>Documentation copyright 2000 Andreas Zehender <email>az@azweb.de</email></para>
+<para>Documentation updated for &kde; 2.0 by Mike McBride <email>mpmcbride7@yahoo.com</email></para>
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;
+&underGPL;
+
+</chapter>                  
+
+<appendix id="installation">
+<title>Installation</title>
+ 
+<sect1 id="getting-kspaceduel">
+<title>How to obtain &kspaceduel;</title>
+ 
+&install.intro.documentation;
+
+</sect1>
+
+<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:
+-->
+
diff --git a/doc/kspaceduel/kspaceduel3.png b/doc/kspaceduel/kspaceduel3.png
new file mode 100644
index 00000000..a23bc50e
--- /dev/null
+++ b/doc/kspaceduel/kspaceduel3.png