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

2 files changed, 579 insertions, 0 deletions

diff --git a/doc/ktron/Makefile.am b/doc/ktron/Makefile.am
new file mode 100644
index 00000000..368fc0da
--- /dev/null
+++ b/doc/ktron/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_DOCS = AUTO
+KDE_LANG = en
+
diff --git a/doc/ktron/index.docbook b/doc/ktron/index.docbook
new file mode 100644
index 00000000..52a76da6
--- /dev/null
+++ b/doc/ktron/index.docbook
@@ -0,0 +1,575 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kappname "&ktron;">
+  <!ENTITY package "kdegames">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE">
+]>
+
+<book lang="&language;">
+<bookinfo>
+<title>The &ktron; Handbook</title>
+
+<authorgroup>
+<author>
+<firstname>Fabian</firstname>
+<surname>Dal Santo</surname>
+<affiliation>
+<address>&Fabian.DalSanto.mail;</address>
+</affiliation>
+</author>
+
+<othercredit role="developer">
+<firstname>Matthias</firstname>
+<surname>Kiefer</surname>
+<affiliation>
+<address>&Matthias.Kiefer.mail;</address>
+</affiliation>
+<contrib>Developer</contrib>
+</othercredit>
+
+<othercredit role="reviewer">
+<firstname>Lauri</firstname>
+<surname>Watts</surname>
+<affiliation>
+<address>&Lauri.Watts.mail;</address>
+</affiliation>
+<contrib>Reviewer</contrib>
+</othercredit>
+<!-- TRANS:ROLES_OF_TRANSLATORS-->
+</authorgroup>
+
+<copyright>
+<year>1999</year>
+<year>2000</year>
+<holder>&Matthias.Kiefer;</holder>
+</copyright>
+
+<copyright>
+<year>2001</year>
+<holder>&Fabian.Dal.Santo;</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2005-12-16</date>
+<releaseinfo>1.1</releaseinfo>
+
+<abstract>
+<para>
+&ktron; is a simple <quote>Tron</quote> clone for &kde;, which you can
+play alone or against a friend.
+</para>
+</abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>kdegames</keyword>
+<keyword>KTron</keyword>
+<keyword>game</keyword>
+<keyword>tron</keyword>
+</keywordset>
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>
+&ktron; is a simple Tron-Clone for the
+<ulink url="http://www.kde.org">K Desktop Environment</ulink>. You can play
+&ktron; against the computer or a friend.
+</para>
+
+<para>
+The aim of the game is to live longer than your opponent. To do that,
+avoid running into a wall, your own tail and that of your opponent.
+</para>
+
+</chapter>
+
+<chapter id="playing-ktron">
+<title>Playing &ktron;</title>
+
+<sect1 id="playing-ktron-rules">
+<title>Rules</title>
+
+<para>
+Once a round is started, the players do not stop moving forward (unless the game
+is paused).  All you have to do is avoid crashing by changing your players
+direction. Additionally you can try to hinder your opponent.  For this it is
+possible to increase the velocity by pressing your accelerator key.
+</para>
+
+<para>
+A round starts when all human players press a direction key.  The initial moving
+direction is then in this direction.
+</para>
+
+<para>
+If you want to interrupt playing, select
+<guimenuitem>Pause</guimenuitem> from the <guimenu>Game</guimenu> menu
+or hit the keyboard shortcut (see section <link linkend="keys">Default 
+Shortcuts</link>).  Additionally the game is paused when the game loses the
+keyboard focus, &eg; when switching to an other window.
+</para>
+
+<para>To continue the game, select the menu item
+<guimenuitem>Pause</guimenuitem> again, or the keyboard shortcut.  The
+game will also continue if the human players press one of their direction keys.
+But be careful, your player switches to this direction immediately.
+</para>
+
+
+<para>A game consists of several rounds, and ends if a player has at least
+nine points, and additionally two more points than the opponent.
+The current score is always displayed in the status bar.
+</para>
+
+</sect1>
+
+<sect1 id="computerplayer">
+<title>The Computer Player</title>
+
+<para>
+You can let the computer be Player One, Player Two or both players.
+There are three difficulty levels:  Beginner, Average and Expert.</para>
+
+<itemizedlist>
+<listitem>
+<para>If you choose Beginner, the computer doesn't care about
+the opponent and just moves around. This is the same algorithm as used by
+xtron-1.1.</para>
+</listitem>
+<listitem>
+<para>At skill levels Average and Expert, the computer tries to hinder the
+opponent when he comes near.</para>
+</listitem>
+</itemizedlist>
+
+<note><para>See the <link linkend="settings-menu"><guimenu>Settings</guimenu>
+Menu</link> section for information on how to configure the computer player.
+</para></note>
+
+</sect1>
+
+<sect1 id="using-keyboard">
+<title>Using the Keyboard</title>
+
+<para>
+Each player has five keys. Four keys for changing the direction and one to
+accelerate.
+</para>
+
+<para>
+The direction keys do not have to be held down. Simply press them once to change
+the direction of your player.
+</para>
+
+<para>
+Acceleration only occurs while the acceleration key remains depressed.  When you
+release the acceleration key, velocity returns to normal.
+</para>
+
+<note><para>
+See section <link linkend="settings-menu"><guimenu>Settings</guimenu>
+Menu</link> for information how to change the default keys.
+</para></note>
+</sect1>
+</chapter>
+
+<chapter id="command">
+<title>Command Reference</title>
+
+<para>The following sections briefly describe each menubar option.</para>
+
+<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.</action></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycap>P</keycap>
+</shortcut>
+<guimenu>Game</guimenu>
+<guimenuitem>Pause</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Toggles whether the game is paused.</action></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
+</shortcut>
+<guimenu>Game</guimenu>
+<guimenuitem>Exit</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Quits.</action></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 Statusbar</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Shows or hides the Statusbar.</action></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Shortcuts...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Displays a standard &kde; shortcuts configurator.</action></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure &kappname;...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Opens a <link linkend="configuration">comprehensive dialog</link>
+to configure various options.</action></para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="help">
+<title>The <guimenuitem>Help</guimenuitem> Menu</title>
+
+&help.menu.documentation;
+
+</sect1>
+
+<sect1 id="keys">
+<title>Default Shortcuts</title>
+
+<para>The following tables show you the default shortcuts.</para>
+
+
+<table>
+<title>Player 1 Shortcuts</title>
+<tgroup cols="2">
+<thead>
+<row>
+<entry>Key Combo</entry>
+<entry>Action</entry></row></thead>
+<tbody>
+<row>
+<entry><keycap>R</keycap></entry>
+<entry>Up</entry>
+</row>
+<row>
+<entry><keycap>F</keycap></entry>
+<entry>Down</entry>
+</row>
+<row>
+<entry><keycap>G</keycap></entry>
+<entry>Right</entry>
+</row>
+<row>
+<entry><keycap>D</keycap></entry>
+<entry>Left</entry>
+</row>
+<row>
+<entry><keycap>A</keycap></entry>
+<entry>Accelerate</entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+
+<table>
+<title>Player 2 Shortcuts</title>
+<tgroup cols="2">
+<thead>
+<row>
+<entry>Key Combo</entry>
+<entry>Action</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><keycap>Up Arrow</keycap></entry>
+<entry>Up</entry>
+</row>
+<row>
+<entry><keycap>Down Arrow</keycap></entry>
+<entry>Down</entry>
+</row>
+<row>
+<entry><keycap>Right Arrow</keycap></entry>
+<entry>Right</entry>
+</row>
+<row>
+<entry><keycap>Left Arrow</keycap></entry>
+<entry>Left</entry>
+</row>
+<row>
+<entry><keycap>0</keycap></entry>
+<entry>Accelerate</entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+
+<table>
+<title>General Shortcuts</title>
+<tgroup cols="2">
+<thead>
+<row>
+<entry>Key Combo</entry>
+<entry>Action</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><keycap>P</keycap></entry>
+<entry>Pause/Resume Game</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>Q</keycap></keycombo></entry>
+<entry>Quit &ktron;</entry>
+</row>
+<row>
+<entry><keycap>F1</keycap></entry>
+<entry>Help Contents</entry>
+</row>
+<row>
+<entry><keycombo
+action="simul"><keycap>Shift</keycap><keycap>F1</keycap></keycombo></entry>
+<entry>What's This Help</entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+These shortcuts can be changed by selecting <menuchoice>
+<guimenu>Settings</guimenu> <guimenuitem>Configure Shortcuts...</guimenuitem>
+</menuchoice> from the menubar.
+</para>
+
+</sect1>
+
+</chapter>
+
+<chapter id="configuration">
+
+<title>The Configuration Dialog</title>
+
+<para>Selecting the <guimenuitem>Configure &kappname;...</guimenuitem> option
+in the <guimenu>Settings</guimenu> menu will open a further dialog which lets
+you tweak &kappname;'s behavior.</para>
+
+<para>This dialog is divided into three pages.</para>
+
+<sect1 id="configuration-general">
+<title>General Configuration</title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Show winner by changing color</guilabel></term>
+<listitem><para>Enable this box to improve visualizing that the game is over
+by making &ktron; change the color of the loser's trail to the color of
+the winner.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Disable acceleration</guilabel></term>
+<listitem><para>Checking this box will disable the acceleration feature - 
+pressing the acceleration key will have no effect, both vehicles will always
+travel with constant velocity.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Crash when moving in the opposite direction</guilabel></term>
+<listitem><para>Enable this to make a vehicle crash into itself as soon as a
+player attempts to move into the opposite direction (&ie; a vehicle moves left,
+and the player tries to move to the right in one step). If this box is
+not checked, nothing happens when a player attempts to move into the opposite
+direction.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Player Names</guilabel></term>
+<listitem><para>Specify custom names to use for the players to override the use of default ones.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Speed</guilabel></term>
+<listitem><para>Use this slider to define how fast the vehicles move; moving the
+slider to the left will make the vehicles move slower, moving it to the right
+will make them move faster.</para></listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="configuration-ai">
+<title><acronym>AI</acronym> Configuration</title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Computer Controls</guilabel></term>
+<listitem><para>Use these two checkable boxes to define which players should
+be controlled by the computer.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Intelligence:</guilabel></term>
+<listitem><para>Selects the skill level of the computer player,
+<guimenuitem>Beginner</guimenuitem>, <guimenuitem>Average</guimenuitem> or
+<guimenuitem>Expert</guimenuitem></para>
+<para><guimenuitem>Beginner</guimenuitem> ignores the opponent, and just moves
+randomly. <guimenuitem>Average</guimenuitem> or
+<guimenuitem>Expert</guimenuitem> causes the computer to actively hinder the
+opponent.</para></listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="configuration-appearance">
+<title>Appearance Configuration</title>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Line style:</guilabel></term>
+<listitem><para>Here you can choose one of four different line styles to be
+used for drawing the vehicles. The names of the styles are self-explanatory:
+<guimenuitem>3D Line</guimenuitem>, <guimenuitem>3D Rectangles</guimenuitem>,
+<guimenuitem>Flat</guimenuitem> and <guimenuitem>Circles</guimenuitem>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Line Size</guilabel></term>
+<listitem><para>Use this slider to define how broad the trail of a vehicle should
+be. Moving the slider towards the left will make the trail more narrow, moving
+it to the right will result in a wider trail.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Background</guilabel></term>
+<listitem><para>Here you can define the appearance of the playground's
+background. If you prefer a simple solid color, select the
+<guilabel>Color:</guilabel> option and click on the button at the right of it
+to open a convenient color-selection dialog.</para>
+<para>You can also choose a background image for the playground. To do so,
+select the <guilabel>Image:</guilabel> option, and then provide the filename
+of a wallpaper image to use in the input field at the right. Alternatively you
+can click on the little button at the very right to open the well-known
+file-selection dialog.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Player 1 color:</guilabel></term>
+<listitem><para>Click on the colored rectangle to open a color-selection dialog
+which lets you define the color to be used for the vehicle of the first
+player.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Player 2 color:</guilabel></term>
+<listitem><para>Click on the colored rectangle to open a color-selection dialog
+which lets you define the color to be used for the vehicle of the second
+player.</para></listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+</chapter>
+
+<!-- credits chapter done --> 
+<chapter id="credits">
+<title>Credits and License</title>
+
+<para>
+&ktron; 
+</para>
+<para>Program Copyright 1999 &Matthias.Kiefer;
+&Matthias.Kiefer.mail;
+</para>
+
+<para>
+Parts of the code are from xtron-1.1 by Rhett D. Jacobs
+<email>[email protected]&gt;</email>
+</para>
+
+<para>
+Documentation Copyright 1999 &Matthias.Kiefer;
+&Matthias.Kiefer.mail;
+</para>
+
+<para>Documentation updated for &kde; 2.0 by &Fabian.Dal.Santo;
+&Fabian.DalSanto.mail;</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+&underFDL;
+&underGPL;
+</chapter>
+
+<!-- appendix finished -->
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="getting-ktron">
+<title>How to obtain &ktron;</title>
+
+&install.intro.documentation;
+
+</sect1>
+
+<sect1 id="requirements">
+<title>Requirements</title>
+
+<para>
+In order to successfully compile &ktron;, you need &kde; 3.0. All
+required libraries as well as &ktron; itself can be found on &kde-ftp;.</para>
+</sect1>
+
+<sect1 id="compilation">
+<title>Compilation and Installation</title>
+
+&install.compile.documentation;
+
+<para>Should you run into problems, please report them to the the
+author at <ulink url="mailto:[email protected]">&Matthias.Kiefer;</ulink>
+</para>
+
+</sect1>
+</appendix>
+
+</book>
+<!--
+Local Variables:
+mode: sgml
+sgml-omittag: nil
+sgml-shorttag: t
+End:
+-->
+