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

diff --git a/doc/kasteroids/Makefile.am b/doc/kasteroids/Makefile.am
new file mode 100644
index 00000000..368fc0da
--- /dev/null
+++ b/doc/kasteroids/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_DOCS = AUTO
+KDE_LANG = en
+
diff --git a/doc/kasteroids/fuel.png b/doc/kasteroids/fuel.png
new file mode 100644
index 00000000..7ee0ff73
--- /dev/null
+++ b/doc/kasteroids/fuel.png
diff --git a/doc/kasteroids/index.docbook b/doc/kasteroids/index.docbook
new file mode 100644
index 00000000..61563db0
--- /dev/null
+++ b/doc/kasteroids/index.docbook
@@ -0,0 +1,328 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+<!ENTITY kappname "&kasteroids;">
+<!ENTITY package "kdegames">
+<!ENTITY % addindex "IGNORE">
+<!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+
+<title>The &kasteroids; Handbook</title>
+
+<authorgroup>
+<author>
+&Martin.R.Jones; &Martin.R.Jones.mail;
+</author>
+
+<author>
+&Philip.Rodrigues; &Philip.Rodrigues.mail;
+</author>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<copyright>
+<year>2000</year>
+<holder>Martin R. Jones</holder>
+</copyright>
+
+<copyright>
+<year>2001-2005</year>
+<holder>Philip Rodrigues</holder>
+</copyright>
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2005-01-18</date>
+<releaseinfo>2.3</releaseinfo>
+
+<abstract><para>&kasteroids; is, as you would expect, the &kde; clone of the
+popular <application>Asteroids</application> game.</para></abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>games</keyword>
+<keyword>linux</keyword>
+<keyword>asteroids</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>The objective of &kasteroids; is to destroy all the asteroids on the
+screen to advance to the next level. Your ship is destroyed if it makes contact
+with an asteroid.</para>
+
+</chapter>
+
+<chapter id="ship">
+<title>Your Ship</title>
+
+<para>When your ship is first launched, it has only basic abilities: Turning,
+Thrusting and Shooting</para>
+
+<para>In order to move your ship, rotate it to face the direction you wish to
+travel and press the thrust key. Of course the ship has momentum, so you will
+have to compensate when you select the angle of the ship. Thrusting uses fuel,
+so you should not use your thrusters more than necessary.</para>
+
+<para>You have an unlimited amount of ammunition, so shoot away. Only a limited
+number of shots can be active at once, though. If you repeatedly shoot and
+miss, you will find that you are unable to shoot until some of the shots have
+expired.</para>
+
+<para>Your ship has a limited amount of fuel. When all the ship's fuel has been
+consumed it is unable to thrust anymore. This leaves you immobile, but not
+defenseless &dash; you can still rotate and shoot.</para>
+
+<para>Fortunately the asteroids occasionally release fuel when they are shot.
+Fly your ship into the fuel symbol to collect it.</para>
+
+<screenshot>
+<screeninfo>Fuel Upgrade</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="fuel.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>Fuel Upgrade</phrase>
+</textobject>
+<caption><para>Fuel Upgrade</para></caption>
+</mediaobject>
+</screenshot>
+
+</chapter>
+
+<chapter id="upgrades">
+<title>Ship Upgrades</title>
+
+<para>Occasionally when you shoot an asteroid a symbol will be produced. These
+symbols represent upgrades to your ship. Fly over the symbol to install it in
+your ship. The upgrades have a cumulative effect, up to a maximum of 5.</para>
+
+<para>The improvements available are:</para>
+
+<variablelist>
+<varlistentry>
+<term>>Brakes</term>
+<listitem><para>Brakes stop your ship as quickly as possible. The more brake
+upgrades you have the faster you can stop, with lower fuel
+usage.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Shields</term>
+<listitem><para>Shields absorb the collision with asteroids, but use a lot of
+fuel. You need at least two shield upgrades to survive a hit from a medium
+sized rock, and 3 to survive a large rock. You will also need to have enough
+fuel to maintain the shield during the strike.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</chapter>
+
+<chapter id="controls">
+<title>Controls</title>
+
+<para>The key bindings are configurable via the
+<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
+Shortcuts...</guimenuitem></menuchoice> menu item.</para>
+
+<para>The defaults are:</para>
+
+<itemizedlist>
+<listitem><para><action>Rotate Anti-Clockwise</action> - <keysym>Left
+Arrow</keysym></para></listitem>
+<listitem><para><action>Rotate Clockwise</action> - <keysym>Right
+Arrow</keysym></para></listitem>
+<listitem><para><action>Thrust</action> - <keysym>Up
+Arrow</keysym></para></listitem>
+<listitem><para><action>Shoot</action> - <keysym>Space
+Bar</keysym></para></listitem>
+<listitem><para><action>Shields</action> - <keycap>S</keycap></para></listitem>
+<listitem><para><action>Pause</action> - <keycap>P</keycap></para></listitem>
+<listitem><para><action>Brake</action> - <keycap>X</keycap></para></listitem>
+</itemizedlist>
+
+</chapter>
+
+<chapter id="config">
+<title>Configuring &kasteroids;</title>
+<para>&kasteroids; only has a few options, which can be reached from
+<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
+KAsteroids...</guimenuitem></menuchoice>.</para>
+
+<variablelist>
+<varlistentry><term>Start new game with <replaceable>n</replaceable>
+ships</term>
+<listitem><para>When you start a new game, you have ships in
+reserve, in case of an accident ;-). This specifies how many ships you have
+<emphasis>in total</emphasis> when the game starts.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>Show Highscores on Game Over</term>
+<listitem><para>If selected, shows all of the highscores each time you finish a
+game, regardless of whether or not you achieve a highscore.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry><term>Player can destroy Powerups</term>
+<listitem><para>If selected, shooting a powerup destroys it. If unselected, the
+powerup remains, allowing you to still pick it up.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</chapter>
+
+<chapter id="tips">
+<title>Tips</title>
+
+<para>Here are some tips that may help:</para>
+
+<tip><para>If you want to stop your ship, use the brakes rather than stopping
+manually. The brakes stop you faster, with less fuel usage.</para></tip>
+
+<tip><para>Shields are expensive. They should be used as a last resort. Try to
+use your thrusters to avoid collisions when practical.</para></tip>
+
+<tip><para>Avoid the edges of the playing field. It's more difficult to see
+asteroids approaching from the opposite side of the field.</para></tip>
+</chapter>
+
+<chapter id="menu-reference">
+<title>Menu Reference</title>
+<sect1 id="game-menu">
+<title>The <guimenu>Game</guimenu> Menu</title>
+
+<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>Starts a new game of
+&kasteroids;</action></para></listitem> </varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut><keycap>P</keycap></shortcut>
+<guimenu>Game</guimenu>
+<guimenuitem>Pause</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Pauses the game</action></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><action>Shows the High Scores for
+&kasteroids;</action></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> &kasteroids;</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="settings-menu">
+<title>The <guimenu>Settings</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry><term><menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Configure Shortcuts...</guimenuitem></menuchoice></term>
+<listitem><para>Brings up the Shortcuts Configuration dialog. This is
+a standard &kde; shortcuts configuration dialog, which you are
+probably familiar with. See <xref linkend="controls"/> for details of the
+default controls.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure KAsteroids...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Brings up the configuration dialog</action> for
+&kasteroids;. See <xref linkend="config"/>.
+</para></listitem> </varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="help">
+<title>The <guimenuitem>Help</guimenuitem> Menu</title>
+
+&help.menu.documentation;
+
+</sect1>
+
+</chapter>
+
+
+<chapter id="credits">
+<title>Credits</title>
+
+<para>&kasteroids;</para>
+
+<para>Program Copyright 1997 &Martin.R.Jones; &Martin.R.Jones.mail;</para>
+
+<para>Documentation based on the original by &Martin.R.Jones;, currently
+maintained by &Philip.Rodrigues; &Philip.Rodrigues.mail;.</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;
+&underGPL;
+
+</chapter>
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="getting-kasteroids">
+<title>How to obtain &kasteroids;</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
+sgml-indent-step: nil
+End:
+-->
+
+