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

1 files changed, 582 insertions, 0 deletions

diff --git a/doc/kpoker/index.docbook b/doc/kpoker/index.docbook
new file mode 100644
index 00000000..d63af910
--- /dev/null
+++ b/doc/kpoker/index.docbook
@@ -0,0 +1,582 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kappname "&kpoker;">
+  <!ENTITY package "kdegames">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<book lang="&language;">
+<bookinfo>
+<title>&kpoker; Handbook</title>
+<authorgroup>
+<author>
+<firstname>Jochen</firstname>
+<surname>Tuchbreiter</surname>
+<affiliation>
+<address>&Jochen.Tuchbreiter.mail;</address>
+</affiliation>
+</author>
+<author>
+<firstname>Andreas</firstname>
+<surname>Beckermann</surname>
+<affiliation>
+<address>&Andreas.Beckermann.mail;</address>
+</affiliation>
+</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<copyright>
+<year>1997</year><year>2001</year>
+<holder>&Jochen.Tuchbreiter;, &Andreas.Beckermann;</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2005-12-14</date>
+<releaseinfo>1.1</releaseinfo>
+<abstract>
+
+<para>This is the helpfile of &kpoker;, a little poker game.</para>
+
+</abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>kpoker</keyword>
+<keyword>kdegames</keyword>
+<keyword>games</keyword>
+<keyword>game</keyword>
+<keyword>poker</keyword>
+<keyword>play cards</keyword>
+</keywordset>
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<sect1 id="what-is-kpoker">
+<title>What is &kpoker;?</title>
+
+<para>&kpoker; is a <ulink url="http://www.kde.org">&kde;</ulink> compliant clone
+of those highly addictive pocket video poker games which are sometimes called
+<quote>Videopoker</quote> as well.</para>
+</sect1>
+
+<sect1 id="where-do-i-get-the-latest-version-of-kpoker">
+<title>Where do I get the latest version of &kpoker;?</title>
+
+<para>The latest version of &kpoker; is always available at</para>
+<itemizedlist>
+<listitem>
+<para>The &kpoker; homepage: <ulink url="http://kpoker.sourceforge.net/">http://kpoker.sourceforge.net/</ulink></para>
+</listitem>
+<listitem>
+<para>The &kde; homepage: &kde-http;</para>
+</listitem>
+</itemizedlist>
+
+</sect1>
+</chapter>
+
+
+<chapter id="new-game">
+<title>Starting a new game</title>
+
+<para>You can start a new game two ways:</para>
+
+<orderedlist>
+
+<listitem><para>By selecting <menuchoice> <guimenu>Game</guimenu>
+<guimenuitem>New</guimenuitem></menuchoice> from the
+menubar.</para></listitem>
+
+<listitem><para>Selecting <keycombo
+action="simul">&Ctrl;<keycap>N</keycap></keycombo></para></listitem>
+</orderedlist>
+
+<para>Either way, you will be presented with a dialog box.</para>
+
+<screenshot>
+<screeninfo><acronym>AI</acronym> Configure Dialog</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="kpoker2.png" format="PNG"/></imageobject>
+<textobject><phrase><acronym>AI</acronym> Configure Dialog</phrase></textobject>
+</mediaobject>
+</screenshot>  
+
+<variablelist>
+<varlistentry>
+<term><guilabel>How many players do you want?</guilabel></term>
+<listitem><para>Will determine if you play a <link linkend="one-player-game">one
+player game</link> (against the house), or a <link linkend="two-player-game">two
+player game</link>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Your name:</guilabel></term>
+<listitem><para>Lets you personalize &kpoker; so that it calls you by name
+(instead of <guilabel>You</guilabel>you>).</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Player's starting money:</guilabel></term>
+<listitem><para>Lets you set the money you start each game
+with.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>The names of your opponents:</guilabel></term>
+<listitem><para> lets you set the name of the other player.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Show this dialog every time on
+startup</guilabel></term> 
+<listitem><para>If this is checked, the first game after you start
+&kpoker; will show this menu.  If this option is not checked, then the
+game will not show this menu for the first game.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>When you are satisfied with your settings, click
+<guibutton>OK</guibutton>, to start the game. Clicking
+<guibutton>Cancel</guibutton>, will cancel the start of a new
+game.</para>
+
+</chapter>
+
+<chapter id="one-player-game">
+<title>One player game</title>
+
+<sect1 id="how-do-i-play">
+<title>How do I play ?</title>
+
+<para>At the beginning of the game you get $100. You draw five cards
+and decide which ones you want to keep. You indicate which cards you
+want to keep by clicking on the face of the card. The word
+<guilabel>Held</guilabel> will appear above the card.</para>
+
+<para>After doing this you draw new cards for those you did not want
+to keep. This is accomplished by clicking on
+<guibutton>Draw New Cards</guibutton>.</para>
+
+<para> The game now looks if you have any <link linkend="hands">poker
+hand</link> and gives cash according to the kind of hand you got (see
+<link linkend="scoring">scoring</link>). </para>
+
+<para>Now you start over, drawing five cards, deciding which ones you want to
+keep ...</para>
+
+<para>The game ends if you can not pay for another round or if you close the
+&kpoker; window.</para>
+
+</sect1>
+
+<sect1 id="hands">
+<title>What are possible poker hands ?</title>
+
+<para>Possible poker hands are:</para>
+
+<variablelist>
+<varlistentry>
+<term>Jacks or higher</term>
+<listitem><para>Two cards of the same rank, both Jacks or
+higher</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Two pairs</term>
+<listitem><para>Two cards of one rank and two cards of another
+rank</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Three of a kind</term>
+<listitem><para>Three cards of the same rank</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Four of a kind</term>
+<listitem><para>Four cards of the same rank</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Full House</term>
+<listitem><para>Three cards of one rank and two cards of
+another</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Straight</term>
+<listitem><para>Five cards of consecutive rank including the combo
+ace-2-3-4-5</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Flush</term>
+<listitem><para>Five cards of the same suit</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Straight flush</term>
+<listitem><para>Five cards of the same suit and of consecutive
+rank</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Royal flush</term>
+<listitem><para>Ace, king, queen, jack, and ten of the same
+suit</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="scoring">
+
+<title>How many bucks do I get for what hand ? </title>
+
+<informaltable>
+<tgroup cols="2">
+<tbody>
+
+<row>
+<entry>A pair of Jacks or higher cards</entry><entry>$5</entry></row>
+<row><entry> Two Pairs</entry><entry> $10</entry></row>
+<row><entry> Three of a kind</entry><entry> $15</entry></row>
+<row><entry> Straight</entry><entry> $20</entry></row>
+<row><entry> Flush</entry><entry> $25</entry></row>
+<row><entry> Full House</entry><entry> $40</entry></row>
+<row><entry> Four of a kind</entry><entry> $125</entry></row>
+<row><entry> Straight Flush</entry><entry> $250</entry></row>
+<row><entry> Royal Flush</entry><entry>$2000</entry></row>
+</tbody>
+</tgroup>
+</informaltable>
+
+</sect1>
+</chapter>
+
+<chapter id="two-player-game">
+<title>Two player game</title>
+
+<para>The two player game is very different from a <link 
+linkend="one-player-game">one player game</link>.</para>
+
+<sect1 id="two-player">
+<title>Starting a two player game</title>
+
+<para>To start a two player game, select <menuchoice><guimenu>Game</guimenu>
+<guimenuitem>New</guimenuitem> </menuchoice> on the menubar.  This will
+bring up a dialog.  Simply select the number of players on the slider or 
+in the spinbox labeled <guilabel>How many players do you want?</guilabel>.
+Then click <guibutton>OK</guibutton>.</para>
+</sect1>
+
+<sect1 id="two-player-play">
+<title>Playing a two player game</title>
+
+<para>There are four phases to a two-player game:</para> 
+
+<procedure>
+<step><para>you begin to draw cards</para></step>
+<step><para>then you bet some money</para></step>
+<step><para>after that you exchange your cards</para></step>
+<step><para>then you raise and finally you will see the cards of the other
+player and the winner will get all the
+money.</para></step></procedure>
+
+<variablelist>
+<varlistentry>
+<term>Draw</term>
+<listitem><para>You will begin the game with $100. After clicking on the 
+<guibutton>Draw New Cards</guibutton>
+button you will get five cards. That's all, here.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Bet</term>
+<listitem><para>Now you decide if your cards are good or
+not. If they are, you bet some money - at least $5 and maximal $20. Just click
+on the <guibutton>+$5</guibutton> and similar buttons.</para></listitem>
+</varlistentry>
+
+<varlistentry><term>Exchange</term> 
+<listitem><para>Now you decide which cards you want to keep. Click on
+them. If you have a royal flush then don't exchange any cards! When
+you think you are ready then click again on the <guibutton>Draw New Cards</guibutton>
+button - you will probably get new cards.</para>
+
+<para>Perhaps you do not get new cards - then the computer player has
+quite good cards (or at least not very bad cards) and he has
+raised. You have to decide to adjust your bet or to get out of the
+round. By default you will adjust your bet. Click again on the
+<guibutton>Draw New Cards</guibutton> button when ready.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Raise</term> 
+
+<listitem> <para>After you got new cards you are allowed to raise a
+little bit. It is the same as the bet phase so I don't explain it
+again. Click on the draw button (which is now labeled with
+<guilabel>See!</guilabel>) when ready.  </para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>See / Draw</term>
+<listitem><para>I know I said there are four phases and this one is the
+fifth. But it is nearly the same as the draw phase. You will also see the cards
+of the computer player and the winning cards are blinking. The winner gets all
+money. Click on draw to begin a new round!</para>
+
+<note><para>The blinking cards are not necessarily the best cards of
+that player. Only the cards which caused the win are blinking. So if
+you have two pairs (&eg; 2 * 2 and 2 * 3) and an ace, but only the ace
+is blinking, then the computer player also has these two pairs (2 * 2
+and 2 * 3) but not an ace.</para></note></listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+</chapter>
+
+<chapter id="command">
+<title>Commands and Keyboard Shortcuts</title>
+
+<para>The following sections briefly describe each menubar option.</para>
+
+<sect1 id="game-menu">
+<title><guimenu>Game</guimenu> Menu</title>
+
+<para>The <guimenu>Game</guimenu> menu consists of three options.</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><action>Starts a new game</action> of &kpoker;. For more
+information, see the section entitled <link linkend="new-game">Starting a new
+game</link>.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo>
+</shortcut>
+<guimenu>Game</guimenu>
+<guimenuitem>Save</guimenuitem> </menuchoice></term>
+<listitem><para><action>Saves your current game</action> to disk.  This will
+replace any previously saved games.</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> &kpoker;</para></listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="settings-menu">
+<title><guimenu>Settings</guimenu> Menu</title>
+
+<para>The settings menu is used to adjust the sound, look and behavior of &kpoker;.</para>
+
+<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>This toggles the menubar on or off.  If it is off, and you need to use the menubar, you can right click in the playing area of &kpoker; and a menu will appear.  You can then select <guilabel>Show Menubar</guilabel> to turn it back on.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Show Statusbar</guimenuitem></menuchoice></term>
+<listitem><para>This option will <action>toggle the status bar on or
+off</action>.  The status bar is located at the bottom of the &kpoker; window, and contains instructions for play, and how much you won on the previous hand.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Sound</guimenuitem></menuchoice></term>
+<listitem><para>This option will <action>toggle the sound on or
+off</action>.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Blinking Cards</guimenuitem></menuchoice></term>
+<listitem><para>If this option has a check beside it, then when you win a hand,
+the <action>cards which won you the money will blink</action>.  If this option
+is not checked, no cards blink.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice> 
+<guimenu>Settings</guimenu><guimenuitem>Adjust Bet is
+Default.</guimenuitem></menuchoice></term>
+<listitem><para>If this option does not have a check in front of it, and you are
+playing a 2 person game, you will be responsible for clicking <guibutton>Adjust
+Bet</guibutton>, if your opponent raises the stakes, because the default action
+will be to <quote>fold</quote> your hand in defeat.</para>
+<para>If, on the other hand, the option does have a check in front of it, and
+you are in the same situation, the default action of the game, is to match your
+opponents bet, and you will be responsible for folding your
+hand.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Save
+Settings</guimenuitem></menuchoice></term>
+<listitem><para>This saves all your options to your hard drive.  These options
+will be restored automatically when you restart &kpoker;.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Shortcuts...</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>Customize the keyboard shortcuts.</action></para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Configure Carddecks...</guimenuitem></menuchoice></term>
+<listitem><para>This will open a new window where you can select the front and back of the cards for &kpoker;.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu><guimenuitem>Configure KPoker...</guimenuitem></menuchoice></term>
+<listitem><para>This opens a dialog box.</para>
+<screenshot>
+<screeninfo>AI Configure Dialog</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="kpoker1.png" format="PNG"/></imageobject>
+</mediaobject>
+</screenshot>  
+<para>There are either one or three options to adjust:</para>
+
+<para>The top text box determines in milliseconds how long to delay
+before showing the next card.  This can be used to speed up the deals,
+if you are not interested in the more realistic default speed.</para>
+
+<para>The text box labeled <guilabel>Maximal bet:</guilabel>,
+determines the maximum bet for each hand.</para>
+
+<para>The text box labeled <guilabel>Minimal bet:</guilabel> determines
+the smallest allowable bet for each hand.</para>
+
+<note><para>The <guilabel>Maximal bet:</guilabel> and <guilabel>Minimal
+bet:</guilabel> lines are not shown in one player mode.  In single
+player mode, only the card delay can be adjusted.</para></note>
+
+<para>As you can see, the changes will not go into effect until a new
+round is started.</para>
+
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="help-menu">
+<title><guimenu>Help</guimenu> Menu</title>
+
+&help.menu.documentation;
+
+</sect1>
+
+<sect1 id="keys">
+<title>Default Keyboard Shortcuts</title>
+
+<informaltable>
+<tgroup cols="2">
+<thead><row><entry>Key Combo</entry><entry>Action</entry></row></thead>
+<tbody>
+<row><entry><keycap>&Enter;</keycap></entry><entry>Draw</entry></row>
+<row><entry><keycap>1</keycap></entry><entry>Exchange Card 1</entry></row>
+<row><entry><keycap>2</keycap></entry><entry>Exchange Card 2</entry></row>
+<row><entry><keycap>3</keycap></entry><entry>Exchange Card 3</entry></row>
+<row><entry><keycap>4</keycap></entry><entry>Exchange Card 4</entry></row>
+<row><entry><keycap>5</keycap></entry><entry>Exchange Card 5</entry></row>
+<row><entry><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></entry><entry>Quit &kpoker;</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>S</keycap></keycombo></entry><entry>Save Game</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>F1</keycap></keycombo></entry><entry><quote>What's This</quote> Help</entry></row>
+<row><entry><keycombo action="simul"><keycap>F1</keycap></keycombo></entry><entry>Help Contents</entry></row>
+</tbody>
+</tgroup>
+</informaltable>
+</sect1>
+</chapter>
+<chapter id="credits"><title>Credits and License</title>
+ 
+<para>&kpoker;</para>
+
+<para>
+Program copyright 1997-2000 &Jochen.Tuchbreiter;&Jochen.Tuchbreiter.mail;, &Andreas.Beckermann; &Andreas.Beckermann.mail;</para>
+<para>Persons helping me:</para>
+<itemizedlist>
+<listitem><para>Chris Holmes - idea of writing this game and for parts of the
+visual appearance</para></listitem>
+<listitem><para>John Fitzgibbon - provided the card images</para></listitem>
+<listitem><para>Nico Schirwing - drew the backs of the cards</para></listitem>
+<listitem><para>&Andreas.Beckermann; - currently maintaining the game</para></listitem>
+</itemizedlist>
+
+<para>Documentation updated for &kde; 2.0 by &Mike.McBride;
+&Mike.McBride.mail;</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;
+&underGPL;
+
+</chapter>                  
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="getting-kpoker">
+<title>How to obtain &kpoker;</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:
+-->
+