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

diff --git a/doc/kbattleship/Makefile.am b/doc/kbattleship/Makefile.am
new file mode 100644
index 00000000..41691557
--- /dev/null
+++ b/doc/kbattleship/Makefile.am
@@ -0,0 +1,3 @@
+KDE_LANG = en
+KDE_DOCS = AUTO
+
diff --git a/doc/kbattleship/index.docbook b/doc/kbattleship/index.docbook
new file mode 100644
index 00000000..9e380d17
--- /dev/null
+++ b/doc/kbattleship/index.docbook
@@ -0,0 +1,485 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kappname "&kbattleship;">
+  <!ENTITY package "kdegames">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<book lang="&language;">
+<bookinfo>
+<title>The &kbattleship; Handbook</title>
+
+<authorgroup>
+<author>
+&Daniel.Molkentin; &Daniel.Molkentin.mail;
+</author>
+
+<author>
+&Nikolas.Zimmermann; &Nikolas.Zimmermann.mail;
+</author>
+
+<othercredit role="reviewer">
+&Frerich.Raabe;
+<!-- <contrib>Reviewer</contrib> -->
+&Frerich.Raabe.mail;
+</othercredit>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+
+</authorgroup>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<copyright>
+<year>2001</year>
+<holder>&Daniel.Molkentin;</holder>
+</copyright>
+<copyright>
+<year>2001</year>
+<holder>&Nikolas.Zimmermann;</holder>
+</copyright>
+<copyright>
+<year>2001</year>
+<holder>Kevin Krammer</holder>
+</copyright>
+
+
+<date>2005-12-14</date>
+<releaseinfo>1.1</releaseinfo>
+
+<abstract>
+<para>
+&kbattleship; is a network-enabled implementation of the famous <quote>Battle Ship</quote> game for &kde;.</para>
+</abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>kdegames</keyword>
+<keyword>kbattleship</keyword>
+<keyword>game</keyword>
+<keyword>battleship</keyword>
+<keyword>battle</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<sect1 id="features">
+<title>Features</title>
+<itemizedlist>
+<listitem><para>Network Gaming</para></listitem>
+<listitem><para>Computer Player (AI)</para></listitem>
+<listitem><para>Sounds</para></listitem>
+<listitem><para>Chat</para></listitem>
+<listitem><para>Statistics</para></listitem>
+<listitem><para>Highscore List</para></listitem>
+</itemizedlist>
+
+<tip>
+<para>
+&kbattleship; uses an &XML; based communication protocol so you can write
+clients for every platform and in any language.  If you want to write
+one in your favorite programming language or/and environment, contact
+us. We would really like to hear of it.
+</para>
+</tip>
+</sect1>
+
+</chapter>
+
+<chapter id="using-kbattleship">
+<title>Using &kbattleship;</title>
+
+<para>
+If you want to play &kbattleship;, you will need two players, either play
+against the computer or in a network against another player.</para>
+<para>
+In a network game one player has to open the game via
+<menuchoice><guimenu>Game</guimenu> <guimenuitem>Start
+Server</guimenuitem></menuchoice> or by pressing <keycap>F3</keycap>.
+</para>
+
+<para>
+A dialog box opens which will ask you for for a
+<guilabel>Nick name:</guilabel> and <guilabel>Port:</guilabel>. Normally,
+&kbattleship; will suggest your login name but you can enter any string
+you want. The predefined port should be OK. However, if you encounter
+problems, you can choose any other free ports above 1024.
+</para>
+
+<note>
+<para>You need to tell the other player in case you use a port other than
+the default as both players need to use the same port in order to be able
+to establish a connection.</para>
+</note>
+
+<para>
+The other player has to choose <menuchoice><guimenu>Game</guimenu>
+<guimenuitem>Connect to Server</guimenuitem></menuchoice>, or press
+<keycap>F2</keycap>. Again, a <guilabel>Nick name:</guilabel> is
+suggested, but you can choose any name you like.
+</para>
+
+<para>
+An important point is the field <guilabel>Server:</guilabel>. Here, you
+have to enter the host name of the server (the machine of the player
+that initiated the game).
+</para>
+
+<para>
+Another possibility is to play &kbattleship; against your
+computer. Select <guimenuitem>Single Player</guimenuitem> from the
+<guimenuitem>Game</guimenuitem> Menu, or press <keycap>F4</keycap>.
+</para>
+
+<para>
+When you are done, you can start the game. Simply follow the
+instructions in the statusbar. It will issue hints and suggest what to
+do next. When you now look at the screen, you will find two grid fields,
+the so-called <quote>battle areas</quote>. The left area belongs to
+you. This is where you place your ships and where you can follow the
+military actions of your enemy. The right area is where your enemy's
+fleet is located. When it's your turn to fire, you need to click on a
+certain sector (a field of the battle area) where you suppose the ships
+to be located.
+</para>
+
+<para>
+First, you need to place your ships. The game initiator starts. When
+he/she is done, player two sets his/her ships.
+</para>
+
+<para>
+Ship placement is very easy: Simply click on the field where you want to
+place your ship. The first one will have a length of four squares, the next
+will be three squares long &etc;. Click on the field where you want to start
+the placement. If you click with the &LMB; the ship will be placed horizontally,
+a &Shift; &LMB; click will cause it to be placed
+vertically. &Shift; itself will flip the ship placement preview.
+</para>
+
+<para>
+Now you can blindly fire with a &LMB; click on the enemy battle area. The status bar indicates
+who is about to shoot. 
+</para>
+
+<para>
+The first player destroying all their opponents ships wins the game!
+</para>
+
+</chapter>
+
+<chapter id="menu-reference">
+<title>The Menus</title>
+
+<sect1 id="game-menu">
+<title>The <guimenu>Game</guimenu> menu</title>
+
+<variablelist>
+<varlistentry>
+<term>
+<menuchoice>
+<shortcut><keycap>F2</keycap></shortcut>
+<guimenu>Game</guimenu>
+<guimenuitem>Connect to Server...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+<action>Initiate a connection to another player's server.</action>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<shortcut><keycap>F3</keycap></shortcut>
+<guimenu>Game</guimenu>
+<guimenuitem>Start Server...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+<action>Start the server so another player can connect to you.</action>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<shortcut><keycap>F4</keycap></shortcut>
+<guimenu>Game</guimenu>
+<guimenuitem>Single Player...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+<action>Start a game with your computer as the opponent.</action>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<shortcut action="simul">&Ctrl;<keycap>H</keycap></shortcut>
+<guimenu>Game</guimenu>
+<guimenuitem>Show Highscores</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+<action>Show the highest scores so far.</action>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycap>F11</keycap></shortcut>
+<guimenu>Game</guimenu>
+<guimenuitem>Enemy Info</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>Show the enemy's client (might also be &Mac;), the client
+version, a short description and the protocol version used.</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>Exit</action> &kbattleship;
+</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>Toggle on or off the display of the statusbar.</action> The
+default is on.
+</para>
+</listitem>
+</varlistentry>
+
+
+<varlistentry>
+<term>
+<menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show Grid</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+<action>Toggle on and off the display of a grid on the playing
+field.</action> The default is off.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Play Sounds</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+<action>Toggle whether sounds (played when shooting) should be played.</action>
+The default is on.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Shortcuts...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+<action>Configure the keyboard shortcuts used by &kbattleship;.</action>
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Notifications...</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>
+<action>Configure</action> the audio and visual notifications used by &kbattleship;.
+</para>
+</listitem>
+</varlistentry>
+
+
+</variablelist>
+</sect1>
+
+<sect1 id="help-menu">
+<title>The <guimenu>Help</guimenu> menu</title>
+
+&help.menu.documentation;
+
+</sect1>
+</chapter>
+
+<chapter id="questions-answers-and-tips">
+<title>Questions, Answers, and Tips</title>
+
+<qandaset id="faq">
+<title>Frequently asked questions</title>
+<qandaentry>
+<question>
+<para>I get the error: <errorname>Couldn't connect to &arts;
+Soundserver. Sound deactivated.</errorname></para>
+</question>
+<answer>
+<para>&kbattleship; relies on &arts;, &kde;'s soundserver, to play any
+sound. Enable &arts; in the &kcontrolcenter; by browsing to
+<menuchoice><guisubmenu>Sound &amp; Multimedia</guisubmenu>
+<guimenuitem>Sound System</guimenuitem></menuchoice> and making sure that
+the box labelled <guilabel>Enable the sound system</guilabel> is checked.</para>
+</answer>
+</qandaentry>
+
+<qandaentry>
+<question>
+<para>I have a question that is likely to become a &FAQ;. Who should I
+contact?</para>
+</question>
+<answer>
+<para>Contact the authors. They will most likely add it here.</para>
+</answer>
+</qandaentry>
+</qandaset>
+
+</chapter>
+
+<chapter id="credits">
+<title>Credits and Licenses</title>
+
+<para>&kbattleship; Copyright 2000, 2001</para>
+
+<itemizedlist>
+<title>Authors</title>
+<listitem>
+<para>
+&Nikolas.Zimmermann; &Nikolas.Zimmermann.mail;
+</para>
+</listitem>
+<listitem>
+<para>
+&Daniel.Molkentin; &Daniel.Molkentin.mail;
+</para>
+</listitem>
+<listitem>
+<para>
+Kevin Krammer <email>kevin.krammer@gmx.at</email>
+</para>
+</listitem>
+</itemizedlist>
+
+<itemizedlist>
+<title>Contributors</title>
+<listitem>
+<para>
+Benjamin Adler <email>benadler@bigfoot.de</email>
+</para>
+</listitem>
+<listitem>
+<para>
+Nils Trzebin <email>nils.trzebin@stud.uni-hannover.de</email>
+</para>
+</listitem>
+
+<listitem>
+<para>Elmar Hoefner <email>elmar.hoefner@uibk.ac.at</email></para>
+</listitem>
+
+</itemizedlist>
+
+<para>Documentation updated for &kde; 3.4 by
+<personname><firstname>Brian</firstname><surname>Beck</surname></personname>
+<email>brian.beck@mchsi.com</email></para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;
+&underGPL;
+
+</chapter>
+
+<appendix id="installation">
+<title>Installation</title>
+
+&install.intro.documentation;
+
+<sect1 id="requirements">
+<title>Requirements</title>
+
+<para><!-- This needs updating -->
+At the time of writing, &kbattleship; requires &kde; 3.x or greater and
+&Qt; 3.x or greater.
+</para>
+
+</sect1>
+
+<sect1 id="compiling">
+<title>Compiling</title>
+
+&install.compile.documentation;
+
+</sect1>
+
+</appendix>
+
+</book>
+<!--
+Local Variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+-->
+