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

diff --git a/doc/kbackgammon/Makefile.am b/doc/kbackgammon/Makefile.am
new file mode 100644
index 00000000..368fc0da
--- /dev/null
+++ b/doc/kbackgammon/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_DOCS = AUTO
+KDE_LANG = en
+
diff --git a/doc/kbackgammon/board.png b/doc/kbackgammon/board.png
new file mode 100644
index 00000000..2556cbcd
--- /dev/null
+++ b/doc/kbackgammon/board.png
diff --git a/doc/kbackgammon/index.docbook b/doc/kbackgammon/index.docbook
new file mode 100644
index 00000000..d8dfe39d
--- /dev/null
+++ b/doc/kbackgammon/index.docbook
@@ -0,0 +1,622 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kappname "&kbackgammon;">
+  <!ENTITY package "kdegames">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The &kbackgammon; Handbook</title>
+    
+<authorgroup>
+<author>
+<firstname>Jens</firstname>
+<surname>Hoefkens</surname>
+<affiliation><address>&Jens.Hoefkens.mail;</address></affiliation>
+</author>
+      
+<othercredit role="developer">
+<firstname>Bo</firstname>
+<surname>Thorsen</surname>
+<affiliation><address>&Bo.Thorsen.mail;</address></affiliation>
+<contrib>Developer</contrib>
+</othercredit>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<copyright>
+<year>1999</year><year>2000</year>
+<holder>&Jens.Hoefkens;</holder>
+</copyright>
+    
+<legalnotice>&FDLNotice;</legalnotice>
+    
+<date>2005-12-22</date>
+<releaseinfo>2.6.0</releaseinfo>
+    
+<abstract>
+<para>&kbackgammon; is a graphical backgammon program for &kde;. It
+supports backgammon games with other players, games against computer
+engines like &GNU; <application>bg</application> and even on-line games
+on the <ulink url="http://www.fibs.com/">First Internet Backgammon
+Server</ulink>.</para>
+</abstract>
+    
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>game</keyword>
+<keyword>backgammon</keyword>
+<keyword>FIBS</keyword>
+<keyword>gnubg</keyword>
+</keywordset>
+    
+</bookinfo>
+  
+<chapter id="introduction">
+<title>Introduction</title>
+    
+<para>&kbackgammon; is a graphical backgammon program. The objective
+of backgammon is to move your checkers off the board before your
+opponent does. While the rules of backgammon are moderately difficult
+(the most difficult part apparently being the initial positioning of
+the checkers), this document does not try to teach these rules: please
+refer to the Web, a book, or (probably best) a friend for this.</para>
+
+<para>&kbackgammon; offers you a graphical backgammon board that can
+be used almost entirely by using the mouse (although textual commands
+are also available and it should be possible to play backgammon
+without the mouse, too). Therefore, &kbackgammon; is easy to use and
+allows you to concentrate on the important aspects of playing
+backgammon.</para>
+
+<para>In order to play backgammon, you usually need an
+opponent. &kbackgammon; offers you to play against hundreds of
+different opponents of various strength on the <ulink
+url="http://www.fibs.com/">First Internet Backgammon
+Server</ulink>. If you prefer, you may also use the <link
+linkend="engine-offline">Offline Engine</link> which allows you to
+play against yourself or friends that are with you at your
+computer.</para>
+
+<para>In the near future &kbackgammon; will allow you to play against
+<link linkend="engine-gnubg">&GNU; Backgammon</link>, which is a
+powerful backgammon program that usually runs without a graphical
+frontend. It plays on <acronym>FIBS</acronym> with a rating of about
+2000 (which is quite high).</para>
+
+<para>Additionally, plans are on the way that will allow games over
+the Internet between two &kbackgammon; programs (and their respective
+users). Finally, the architecture of &kbackgammon; is quite open and
+it is possible to include support for other engines easily (if you are
+interested in this, please contact the author).</para>
+
+</chapter>
+
+<chapter id="use-the-board">
+<title>How to use the Board</title>
+
+<para>&kbackgammon; is centered around a graphical backgammon
+board. This board consists of the checkers, the dice, and the
+cube. All these game elements can be conveniently manipulated with the
+mouse.</para>
+
+<para>The following image shows a typical game situation with the
+white player moving from 1 to 24 and the black player moving from 24
+to 1. Currently, the white player owns the cube and has just rolled 3
+and 4.</para>
+
+<screenshot>
+<screeninfo>The backgammon board</screeninfo>
+<mediaobject>
+<imageobject>
+<imagedata fileref="board.png" format="PNG"/>
+</imageobject>
+<textobject>
+<phrase>The Board</phrase>
+</textobject>
+</mediaobject>
+</screenshot>
+
+<para>If it is their turn, players can roll the dice by double
+clicking on the squares representing the dice or by using the
+corresponding menu entry or toolbar icon (if the toolbar is visible
+and rolling has been included in the toolbar).</para>
+
+<para>If they own the cube, players can double the cube by either
+double clicking on the square representing the cube or by using the
+corresponding menu entry or toolbar icon (if the toolbar is visible
+and the cube has been included in the toolbar).</para>
+
+<para>If it is their turn to move, players can move checkers by
+clicking on them and moving the mouse pointer to the desired location
+(while holding the mouse button continuously pressed). This is called
+dragging the checker. Depending on the selection made in the current
+<link linkend="engines">engine's</link> <link
+linkend="prefs">configuration</link>, the move will be finished once
+the maximum number of checkers has been moved (this may be anywhere
+between 1 and 4 checkers, although it will usually be 2
+checkers).</para>
+
+<para>In addition to dragging the checkers, the board offers a feature
+called <firstterm>short move feature</firstterm>. If this has been
+enabled in the board's configuration menu, checkers can be moved by
+simply clicking on them. The board will then automatically make the
+shortest move possible away from the current field. If the short move
+feature <link linkend="prefs">is enabled</link>, it may be set to
+single or double click. This option is very useful for users of
+touchpads that are sometimes difficult to use for dragging.</para>
+
+<para>Finally, the board has a certain smartness: it will only accept
+moves that are allowed (based on the current dice). While the <link
+linkend="engine-offline">offline engine</link> allows this to be
+switched off (for the <guilabel>Edit Mode</guilabel>), this is usually
+very helpful for unexperienced users (and advanced players will
+probably never notice this). This feature can also be used to cancel a
+move in progress: just drop it over an illegal field.</para>
+
+</chapter>
+
+<chapter id="engines">
+<title>Backgammon Engines</title>
+    
+<para>&kbackgammon; is built around the backgammon board, which
+doesn't know anything about how to play backgammon. The whole
+infrastructure (rolling the dice, &etc;) that allows backgammon games
+is handled by backgammon engines.</para>
+    
+<sect1 id="engine-offline">
+<title>The Offline Engine</title>
+      
+<para>The offline engine <guilabel>Open Board</guilabel> allows you to play against yourself, or
+probably more fun, another person sitting with you.</para>
+
+</sect1>
+
+<sect1 id="engine-FIBS">
+<title>The <acronym>FIBS</acronym> Engine</title>
+
+<para><acronym>FIBS</acronym> is the <quote>First Internet Backgammon
+Server</quote>, a 24-hour international online community of backgammon
+players of all ages and experience from Beginner to Experts.</para>
+
+<para>As well as playing the game, <acronym>FIBS</acronym> allows you
+to save games, chat with other players, and has a complex rating
+system.</para>
+
+<para>There is also a large <ulink
+url="http://www.fibs.com/">website</ulink> well worth some of your
+time, if you are a backgammon fan.</para>
+      
+</sect1>
+    
+<sect1 id="engine-gnubg">
+<title>The &GNU; Backgammon Engine</title>
+
+<para>The GNUbg engine does not yet exist (although it already has an
+entry in the <guilabel>Engine</guilabel> menu). Therefore, the
+remainder of this section should be taken with a grain of salt.</para>
+      
+<para>Use of the GNUbg engine requires a working installation of the
+actual GNUbg program. &kbackgammon; then starts GNUbg in the
+background and communicates with it. All this is transparent to the
+user (&ie; it is hidden from the user) and all interaction with GNUbg
+is through the &GUI; elements of &kbackgammon;.</para>
+
+<para>If there are other enhancements that can help using GNUbg from
+&kbackgammon;, please contact the author of &kbackgammon; (or better:
+send a patch). Some of the more advanced features will probably be
+position analysis and save/restore functions. However, playing is the
+most pressing issue.</para>
+
+<para>The one thing that will never happen is a combination of the
+GNUbg and the <acronym>FIBS</acronym> engine! Using computer programs
+to enhance user ratings is cheating!</para>
+
+</sect1>
+    
+</chapter>
+  
+<chapter id="prefs">
+<title>Game options</title>
+    
+<para>The options to &kbackgammon; are set by selecting <menuchoice>
+<guimenu>Settings</guimenu> <guimenuitem>Configure &kbackgammon;...</guimenuitem>
+</menuchoice> from the menubar. This will bring up a dialog
+box.</para>
+
+</chapter>
+  
+<chapter id="command">
+<title>Menu Reference/Keyboard Shortcuts</title>
+    
+<para>The following sections briefly describe each menubar option.</para>
+    
+<sect1 id="file-menu">
+<title><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>Start a new game</action>. This item opens a dialog to enter the nicknames of both players.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo>
+</shortcut>
+<guimenu>Game</guimenu>
+<guimenuitem>Print...</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Print a picture of the board.</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>Quit</action> and close &kbackgammon;</para>
+</listitem>
+</varlistentry>
+</variablelist>
+      
+</sect1>
+
+<sect1 id="move-menu">
+<title><guimenu>Move</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>Z</keycap>
+</keycombo>
+</shortcut>
+<guimenu>Move</guimenu>
+<guimenuitem>Undo</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para><action>Undo the last move you made.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo>
+</shortcut>
+<guimenu>Move</guimenu>
+<guimenuitem>Redo</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>If you have previously undone a move, you can redo it
+here.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Move</guimenu>
+<guimenuitem>Redisplay</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Redraw the board.</action></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>R</keycap>
+</keycombo>
+</shortcut>
+<guimenu>Move</guimenu>
+<guimenuitem>Roll Dice</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>As you may expect, roll the dice.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Move</guimenu>
+<guimenuitem>End Turn</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Let the other player know you have finished
+moving.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Move</guimenu>
+<guimenuitem>Double Cube</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Offer</action> the opponent player during the course of a game 
+(just before you roll the dice) to continue the game at twice the current stakes.
+If the opponent rejects this offer, you win the game.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Move</guimenu>
+<guisubmenu>Engine</guisubmenu>
+</menuchoice>
+</term>
+<listitem>
+<para>Choose from the various game engines (Open Board, FIBS, GNU Backgammon, Next Generation) here.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+    
+</sect1>
+
+<sect1 id="command-menu">
+<title><guimenu>Command</guimenu> Menu</title>
+
+<para>This menu has different items depending on the chosen game engine.</para>
+
+<para><guisubmenu>Open Board</guisubmenu> engine</para>
+
+<variablelist>
+<varlistentry><term>
+<menuchoice><guimenu>Command</guimenu>
+<guimenuitem>New Game</guimenuitem>
+</menuchoice></term>
+<listitem><para>
+<action>Start a new game</action>. This item opens a dialog to enter the nicknames of both players.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<menuchoice><guimenu>Command</guimenu>
+<guimenuitem>Edit Mode</guimenuitem></menuchoice>
+</term>
+<listitem>
+<para>
+In this mode the board accepts moves that are not allowed 
+(based on the current dice).
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Command</guimenu>
+<guimenuitem>Swap Colors</guimenuitem></menuchoice>
+</term>
+<listitem>
+<para>
+Swap the colors of the checkers between player 1 and player 2.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<!-- To Do : write the menuitems for the other game engines
+<para><guisubmenu>FIBS</guisubmenu> engine</para>
+<para><guisubmenu>GNU Backgammon</guisubmenu> engine</para>
+<para><guisubmenu>Next Generation</guisubmenu> engine</para>
+-->
+</sect1>
+    
+<sect1 id="settings-menu">
+<title><guimenu>Settings</guimenu> Menu</title>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>M</keycap>
+</keycombo>
+</shortcut>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show Menubar</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Toggle on and off the menubar</action>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guisubmenu>Toolbars</guisubmenu>
+<guimenuitem>Main (&kbackgammon;)</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Toggle</action> the <guilabel>Main Toolbar</guilabel></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guisubmenu>Toolbars</guisubmenu>
+<guimenuitem>Command Characters (&kbackgammon;)</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Toggle</action> the <guilabel>Command Toolbar</guilabel></para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show Statusbar</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Toggle on and off the statusbar</action>.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Save Settings</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>
+<action>Saves the current settings to become the default for &kbackgammon;.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Shortcuts...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Opens a dialog for changing the key bindings.</action>
+Using this option you can change the standard key shortcut for &kbackgammon;'s commands
+or create new ones.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Toolbars...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Opens a dialog for configuring the toolbar.</action> You
+can add and remove toolbuttons for &kbackgammon;'s commands with this
+option.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure &kbackgammon;...</guimenuitem>
+</menuchoice></term>
+<listitem><para><action>Opens a dialog for changing some options</action> for
+&kbackgammon;.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect1>
+    
+<sect1 id="help-menu">
+<title><guimenu>Help</guimenu> Menu</title>
+
+<para>&kbackgammon; has a standard &kde; <guimenu>Help</guimenu> as described
+below, with one addition:</para>
+
+<variablelist>
+<varlistentry>
+<term><menuchoice><guimenu>Help</guimenu>
+<guimenuitem>Backgammon on the Web</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>Opens the websites of FIBS Home, Backgammon Rules, or &kbackgammon; in &konqueror;.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<para>The standard &kde; <guimenu>Help</guimenu> entries are:</para>
+
+&help.menu.documentation;
+
+</sect1>
+
+<sect1 id="keys"><title>Default Shortcuts</title>
+
+<para>The following tables show you the default shortcuts of
+&kbackgammon;.</para>
+
+<table>
+<title>Key bindings</title>
+<tgroup cols="2">
+<thead><row><entry>Key Combo</entry><entry>Action</entry></row></thead>
+<tbody>
+<row><entry><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo></entry><entry>New Game</entry></row>
+<row><entry><keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo></entry><entry>Roll Dice</entry></row>
+<row><entry><keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo></entry><entry>Print Game</entry></row>
+<row><entry><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></entry><entry>Quit &kbackgammon;</entry></row>
+<row><entry><keycap>F1</keycap></entry><entry>Help Contents</entry></row>
+<row><entry><keycombo action="simul">&Shift;<keycap>F1</keycap></keycombo></entry><entry>What's This? Help</entry></row>
+<row><entry><keycombo action="simul">&Ctrl;<keycap>M</keycap></keycombo></entry><entry>Show Menubar</entry></row>
+<row><entry><keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo></entry><entry>Undo move</entry></row>
+<row><entry><keycombo action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo></entry><entry>Redo previously undone move</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="credits">
+<title>Credits and License</title>
+ 
+<para>&kbackgammon;</para>
+
+<para>Program copyright 1999-2000 &Jens.Hoefkens;
+&Jens.Hoefkens.mail;</para>
+
+<para>Documentation copyright 2000 &Jens.Hoefkens;
+&Jens.Hoefkens.mail;</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;
+&underGPL;
+
+</chapter>                  
+
+<appendix id="installation">
+<title>Installation</title>
+ 
+<sect1 id="getting-kbackgammon">
+<title>How to obtain &kbackgammon;</title>
+ 
+&install.intro.documentation;
+
+<para>The home page of &kbackgammon; is located at <ulink
+url="http://backgammon.sourceforge.net/">http://backgammon.sourceforge.net</ulink>.
+It will usually contain the most up-to-date information the program
+available.</para>
+
+</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:
+-->
+
+