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

diff --git a/doc/kpat/index.docbook b/doc/kpat/index.docbook
new file mode 100644
index 00000000..3fcda113
--- /dev/null
+++ b/doc/kpat/index.docbook
@@ -0,0 +1,811 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kappname "&kpatience;">
+  <!ENTITY package "kdegames">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+ 
+<book lang="&language;">
+<bookinfo>
+<title>The &kpatience; Handbook</title>
+
+<authorgroup>
+<author>
+<firstname>Paul Olav</firstname>
+<surname>Tvete</surname>
+</author>
+<author>
+<firstname>Maren</firstname>
+<surname>Pakura</surname>
+</author>
+<author>
+<firstname>Stephan</firstname>
+<surname>Kulow</surname>
+</author>
+
+<othercredit role="reviewer">
+<firstname>Mike</firstname><surname>McBride</surname>
+<contrib>Reviewer</contrib>
+<affiliation><address><email>mpmcbride7@yahoo.com</email></address></affiliation>
+</othercredit>
+
+<othercredit role="developer">
+<firstname>Paul Olav</firstname>
+<surname>Tvete</surname>
+<contrib>Developer</contrib>
+</othercredit>
+
+<othercredit role="developer">
+<firstname>Stephan</firstname>
+<surname>Kulow</surname>
+<contrib>Developer</contrib>
+</othercredit>
+</authorgroup>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+
+<copyright>
+<year>2000</year>
+<holder>Paul Olav Tvete</holder>
+</copyright>
+<copyright>
+<year>2001</year><year>2004</year>
+<holder>Maren Pakura</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2004-02-07</date>
+<releaseinfo>3.2</releaseinfo>
+<abstract>
+
+<para>&kpatience; is a highly addictive card game for &kde;</para>
+
+</abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>game</keyword>
+<keyword>patience</keyword>
+<keyword>solitaire</keyword>
+</keywordset>
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>
+To play a patience you need, as the name suggests, patience.  For simple games,
+where the way the game goes depends only on how the cards fall, your patience is
+even the only thing you need.
+</para>
+
+<para>
+But there are also patience where you also need to plan your strategy and think
+ahead to win.
+</para>
+
+<para>
+All the games have in common that you have to put the cards in a special order
+in moving, turning and reordering them.
+</para>
+
+</chapter>
+
+<chapter id="rules">
+<title>Rules</title>
+
+<para><indexterm><primary>suits</primary></indexterm>
+A card game contains one or more card decks of 52 cards each. Each deck contains
+the four suits:
+</para>
+
+<informaltable pgwide="0" frame="none">
+<tgroup cols="2">
+<colspec/>
+<colspec/>
+<tbody>
+
+<row valign="middle">
+<entry>
+<inlinemediaobject>
+<imageobject>
+<imagedata fileref="clubs.png"/>
+</imageobject>
+</inlinemediaobject>
+</entry>
+<entry>
+Clubs
+</entry>
+</row>
+
+<row valign="middle">
+<entry>
+<inlinemediaobject>
+<imageobject>
+<imagedata fileref="spades.png"/>
+</imageobject>
+</inlinemediaobject>
+</entry>
+<entry>
+Spades
+</entry>
+</row>
+
+<row valign="middle">
+<entry>
+<inlinemediaobject>
+<imageobject>
+<imagedata fileref="hearts.png"/>
+</imageobject>
+</inlinemediaobject>
+</entry>
+<entry>
+Hearts
+</entry>
+</row>
+
+<row valign="middle">
+<entry>
+<inlinemediaobject>
+<imageobject>
+<imagedata fileref="diamonds.png"/>
+</imageobject>
+</inlinemediaobject>
+</entry>
+<entry>
+Diamonds
+</entry>
+</row>
+
+</tbody>
+</tgroup>
+</informaltable>
+
+<para>
+Each of these suits contains itself the following cards types: ace, two, three,
+four, five, six, seven, eight, nine, ten, jack, queen and king.
+</para>
+
+<para><indexterm><primary>family</primary></indexterm>
+This complete order of cards is called a family. There are real families and
+alternating ones. The real families are all of one suit (&eg; Hearts) while the
+alternating families the card color changes from one to another between a black
+color (Clubs and Spades) and a red color (Hearts and Diamonds).
+</para>
+
+<para>
+If the family is not complete, it's called a sequence.
+</para>
+
+<mediaobject>
+<imageobject><imagedata fileref="playfield.png" format="PNG"/></imageobject>
+<textobject>
+<phrase>The game field of &kpatience;</phrase>
+</textobject>
+</mediaobject>
+
+<para>
+There are only a few different elements in typical patience game.  These should
+be introduced in the following.
+</para>
+
+<variablelist>
+<varlistentry><term>1. Talon</term>
+<listitem>
+<para><indexterm><primary>talon</primary></indexterm>
+In the beginning of each game all cards are mixed in the deck. But not in every
+game all cards are dealt out, but some reside in the deck. These cards are put
+down on the so called talon, which you can find quite easy as it is in most
+games the only pile showing the reverse.
+</para>
+
+<para>
+If no card shows the reverse side, all cards are dealt out and there is no
+talon. These card games are the hardest as there is no randomness involved after
+the start of the game, so there is nothing to blame
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>2. Waste Pile</term>
+<listitem>
+<para><indexterm><primary>waste pile</primary></indexterm>
+Many games put cards from the talon first on a waste pile when you click on the
+reverse of the top card on the talon.
+</para>
+
+<para>
+From there you can take the card (which is then face up) and put
+it into the game. 
+</para>
+
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>3. Foundation</term>
+<listitem>
+<para><indexterm><primary>foundation</primary></indexterm>
+The foundation piles is where you want to have your cards in the end.  If all
+cards end up there in the right order, you've won.
+</para>
+
+<para>
+In most card games these piles are empty in the beginning, but &kpatience; drops
+cards there when it sees them fitting to save you this most often boring part.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>4. Playing Piles</term>
+<listitem>
+<para><indexterm><primary>playing piles</primary></indexterm>
+These piles are the ones where the actual reordering happens. The rules for
+these piles vary a lot between the games. Some show all cards on them, some
+not. Some allow only card to be removed, some allow every card to be removed,
+etc. See the following chapters for details.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<sect1 id="general-use">
+<title>General Use</title>
+
+<para>
+Use of the menu is too easy to be described now.
+</para>
+
+</sect1>
+
+<sect1 id="klondike">
+<title>Klondike</title>
+<anchor id="game_klondike" />
+
+<para><indexterm><primary>Klondike</primary></indexterm>
+Klondike is the most famous patience - most likely because an often used
+operating system comes with it. It is played with one deck.
+</para>
+
+<para>
+Goal of Klondike is to put all cards as real families ascending on the
+foundation. This works usually pretty well as soon as all cards are lying face
+up in the playing piles.
+</para>
+
+<para>
+The sequences on the playing piles have to be put there descending while the cards
+should alternate in colors (red and black). You can move whole sequences or
+parts of it if the first card fits on another pile.
+</para>
+
+<para>
+On a free pile you can put a king of any color or a sequence starting with a
+king.
+</para>
+
+<para>
+When you click on the talon, one card from will be moved to the waste pile,
+from where you can move it to the playing piles or the foundation.
+Is the talon empty, you can move the complete waste pile on the talon
+in clicking on the empty talon.
+</para>
+
+<para>
+You can look through the cards on the talon without any limit, but you should
+learn fast that you've lost if you can't find one card to move and that a new
+shift doesn't help you in finding new solutions.
+</para>
+</sect1>
+
+<sect1 id="grandfather">
+<title>Grandfather</title>
+<anchor id="game_grandfather"/>
+
+<para><indexterm><primary>Grandfather</primary></indexterm>
+This game has been introduced to Paul by his grandfather, so it got this
+name. There aren't any other patience games known implementing this patience
+game.
+</para>
+        
+<para>
+Grandfather deals one deck to seven playing piles while some cards on each pile
+are face down on initial deal.
+</para>
+
+<para>
+The goal is to put all cards as real families ascending on the foundations.
+</para>
+
+<para>
+You can move every card on every pile if it fits on another card to build a real
+sequence with descending order. For example you can move the five of spades on
+top of the six of spades, no matter how many cards on are on top of the five of
+spades. Just the six of spades has to be on top of its pile.
+</para>
+
+<para>
+On a free pile you can place a king (again no matter how many cards are on top of
+it)
+</para>
+
+<para>
+If no more cards can be moved, you can re-deal up to two times. All cards already
+in the foundations stay there, but the cards in the playing piles are reordered
+to give you a new chance to find a solution.
+</para>
+
+<para>
+Even though the rules are simple and allow quite some moves, the game is still
+hard to win, but is still a joy to play (or because of that).
+</para>
+</sect1>
+
+<sect1 id="aces-up">
+<title>Aces Up</title >
+<anchor id="game_aces_up"/>
+
+<para><indexterm><primary>Aces Up</primary></indexterm>
+This patience has very simple rules, but is still hard to win.  It is played
+with one deck and the goal is to put all cards beside the aces to the
+foundation. After that there should be an ace on every playing pile left.
+</para>
+
+<para>
+Each top card that is of the same suit (&eg; spades) and has a lower
+value than another top card (&eg; six of spades and four of spades) can be
+put on the foundation by clicking on it.
+</para>
+
+<para>
+If you can't move any more cards to the foundation, you can get a new card for
+each playing pile in clicking on the talon.
+</para>
+
+<para>
+On a free pile you can move every other card on top of a pile. You should choose
+these moves to free piles the way that new cards can be moved to the foundation
+after that.
+</para>
+
+<para>
+The auto drop feature is disabled for this patience.
+</para>
+
+</sect1>
+
+<sect1 id="freecell">
+<title>Freecell</title>
+<anchor id="game_freecell"/>
+
+<para><indexterm><primary>Freecell</primary></indexterm>
+Freecell is playing with one card deck. You have four free cells in the left top
+corner. Beside that there are the four foundation piles and below it there are
+eight playing piles.
+</para>
+
+<para>
+The goal of the game is to have all cards as real families ascending on the
+foundation. This works quite often if you know how to play as Freecell is
+solvable at a rate of 99.9% approximately (of the first 32000 deals there is only
+one unsolvable - 11982 if you want to know).
+</para>
+
+<para>
+In the playing piles you have to build descending sequences, where red and black
+cards alternate. In a free cell you can put any card.
+</para>
+
+<para>
+You can only move one single card that lays on top of a pile or a free cell.
+Sequences can only be moved if you have enough free room (free cells or free
+playing piles) to put the cards in between you move.
+</para>
+
+<para>
+The moving of sequences will be supported by &kpatience; if there is enough room. The
+maximum of cards you can move is calculated by:</para>
+
+<sidebar><para>
+(#{free cells} + 1) * 2<superscript>#{free piles}</superscript>
+</para></sidebar>
+
+<para>
+To solve this game it is recommended to grab the cards out of the playing
+sequences in the same order they have to be put into the foundation (first the
+aces, then the twos, &etc;)
+</para>
+
+<para>
+You should try to keep as many free cells and/or playing piles empty, so you can
+build as long sequences as possible.
+</para>
+
+</sect1>
+
+<sect1 id="napoleons-tomb">
+<title>Napoleon's Tomb</title>
+<anchor id="game_napoleons_tomb"/>
+<para><indexterm><primary>Napoleon's Tomb</primary></indexterm>
+Napoleon's Tomb is played with one deck. Goal is to put all cards on the
+foundations as ascending families without caring about the card colors or suits.
+</para>
+
+<para>
+The foundation is made out of five piles, that are put as an X. On the four
+corners of this X you have to build sequences starting with seven and ending
+with king.
+</para>
+
+<para>
+The pile in the middle takes four times the sequence from six down to ace. The
+color doesn't matter for all five piles.
+</para>
+
+<para>
+The other four piles on the sides of the pile in the middle (or in between the X
+- however you want to put it) can take one card each to place cards temporarily.
+You can go through the talon only once.
+</para>
+
+<para>
+[auto drop] is disabled for this patience.
+</para>
+</sect1>
+
+<sect1 id="mod3">
+<title>Mod3</title>
+<anchor id="game_mod3"/>
+
+<para><indexterm><primary>Mod3</primary></indexterm>
+Mod-3 is played with two card decks. Goal of the game is to put all
+cards on the top three rows. In those you have to build sequences of the same
+color. In the first row you have to create the sequence 2-5-8-B, in the second
+row the sequence 3-6-9-D and in the third row the sequence 4-7-10-K. The suit of
+the cards has to be the same in each sequence, so you can put a five of hearts
+only on top of a two of hearts.
+</para>
+
+<para>
+The fourth row is waste pile and playing pile at once. On an empty slot you can
+put any card from the first three rows or one of top of the fourth row.
+</para>
+
+<para>
+Aces you can put on the aces piles on top of the talon. They are in the game
+so you have a starting point for creating free slots.
+</para>
+
+<para>
+If you can't move any more cards, you can get new cards on the fourth row in
+clicking on the talon.
+</para>
+
+<para>
+[auto drop] is disabled for this patience.
+</para>
+</sect1>
+
+<sect1 id="calculation">
+<title>Calculation</title>
+<anchor id="game_calculation"/>
+
+<para><indexterm><primary>Calculation</primary></indexterm>
+Calculation is surely a patience you have to get used to. It is played with one
+card deck and the goal of the game is to put all cards in the four foundation
+piles as ascending families without caring the color of the cards.
+</para>
+
+<para>
+For the foundation you have to follow these orders:
+</para>
+
+<blockquote>
+<informaltable pgwide="0">
+<tgroup cols="2">
+<tbody>
+
+<row>
+<entry>1st pile</entry>
+<entry>A-2-3-4-5-6-7-8-9-10-J-Q-K</entry>
+</row>
+
+<row>
+<entry>2nd pile</entry>
+<entry>2-4-6-8-10-Q-A-3-5-7-9-J-K</entry>
+</row>
+
+<row>
+<entry>3rd pile</entry>
+<entry>3-6-9-Q-2-5-8-J-A-4-7-10-K</entry>
+</row>
+
+<row>
+<entry>4th pile</entry>
+<entry>4-8-Q-3-7-J-2-6-10-A-5-9-K</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+</blockquote>
+
+<para>
+The card on top of the talon can be put on any of the four playing piles.
+You should do this, so you can put following cards easier on the foundation.
+</para>
+</sect1>
+
+<sect1 id="gypsy">
+<title>Gypsy</title>
+<anchor id="game_gypsy"/>
+<para><indexterm><primary>Gypsy</primary></indexterm>
+Gypsy is played with two card decks. Goal of the game is to put all cards in
+real families ascending on the foundation.
+</para>
+
+<para>
+The playing piles have to be descending while red and black cards have to
+alternate. You can only move sequences or single cards. On a free slot you can
+put any card or sequence.
+</para>
+
+<para>
+If you can't move any more cards, you can click on the talon to get a new bunch
+of cards on each playing pile.
+</para>
+
+<para>
+In using the undo feature you can ease the game quite a lot as you have to take
+quite some decisions and some of them might turn out to be wrong after you
+clicked the talon.
+</para>
+
+</sect1>
+
+<sect1 id="forty-and-eight">
+<title>Forty And Eight</title>
+<anchor id="game_forty_and_eight"/>
+
+<para><indexterm><primary>Forty And Eight</primary></indexterm>
+Forty and Eight is played with two card decks. Goal of the game is to put all
+cards as real families on the foundation.
+</para>
+
+<para>
+The playing piles have to be descending while you have to care about colors.  So
+you can only put a five of hearts on a six of hearts.
+</para>
+
+<para>
+You can only move one single card on top of a pile. In a free slot you can put
+any card.
+</para>
+
+<para>
+In clicking on the talon you can put a card on the waste pile, from where you
+can put it on a playing pile or the foundation (this &kpatience; will do for you).
+Is the talon empty you can put all cards on the waste pile back on the talon.
+This works only once, after the second time the talon empties, the game is over.
+</para>
+
+<para>
+This patience isn't really easy to solve, but with some experience, you can
+solve many deals, especially if you use the undo feature from time to time to
+correct your decisions, and the decisions &kpatience; does in putting cards on the
+foundation.
+</para>
+</sect1>
+
+<sect1 id="simple-simon">
+<title>Simple Simon</title>
+<anchor id="game_simple_simon"/>
+
+<para><indexterm><primary>Simple Simon</primary></indexterm>
+Simple Simon is played with one card deck. Goal of the game is to put all cards
+as real families on the foundation.
+</para>
+
+<para>
+In the playing piles you can build sequences. In general you don't have to care
+about the suits of the cards, but sequences can only be moved if they are part
+of a real sequence. (&eg; you can move the six of spades only if on top of it is
+the five of spades and not move it if on top of it is the five of clubs).
+</para>
+
+<para>
+The cards can only be moved to the foundation if all 13 cards of one family lay
+on top of each other in the playing piles.
+</para>
+
+<tip>
+<title>Suggestion</title>
+<para>
+You should try as soon as possible to move away the cards on the right piles to
+get free piles to place cards temporarily as you can put on those any card.
+</para>
+
+<para>
+With enough free room you can build families on free slots independently of the
+color. If you have all cards in such families you can sort them after their
+color, so they can be moved to the foundation.
+</para>
+</tip>
+
+</sect1>
+
+<sect1 id="yukon">
+<title>Yukon</title>
+<anchor id="game_yukon"/>
+
+<para><indexterm><primary>Yukon</primary></indexterm>
+Yukon is played with one card deck. Goal of the game is to put all cards as real
+families ascending on the foundation.
+</para>
+
+<para>
+The sequences on the playing piles have to be descending with alternating red and
+black cards. You can move every face up card no matter how many cards are on top
+of it. So you can put a five of hearts on a six of spades if this one is on top
+of its pile.
+</para>
+
+<para>
+In a free slot you can put a king of any color (again, no matter how many cards are on top
+of it)
+</para>
+</sect1>
+
+<sect1 id="grandfathers-clock">
+<title>Grandfather's Clock</title>
+
+<anchor id="game_grandfathers_clock"/>
+<para><indexterm><primary>Grandfathers Clock</primary></indexterm>
+Grandfather's clock is a simple patience and after some experiments you should
+be able to solve most deals. It is played with one card deck and goal of the
+game is put the cards as real ascending sequences on the foundation.
+</para>
+
+<para>
+The foundation is on the right side and consists of 12 piles that form the shape
+of a clock. The ace is on one o'clock, jack is on 11 o'clock and queen on 12
+o'clock.
+</para>
+
+<para>
+There are 8 playing piles beside the clock and on each are 5 cards. On the
+playing piles you can build descending sequences without caring on the color of the
+cards. You can only move one single card at a time.
+</para>
+
+<para>[auto drop] is disabled for this patience.</para>
+
+</sect1>
+
+<sect1 id="kings">
+<title>Kings</title>
+
+<anchor id="game_kings"/>
+
+<para><indexterm><primary>Kings</primary></indexterm>
+The patience Kings is played with two card decks. The cards are dealt in a way
+that below each playing pile is a king. The cards between two kings are put on
+of them (the first cards are obviously put on the first king).  This way you can
+get piles with <emphasis>very</emphasis> different lengths.
+</para>
+
+<para>
+Goal of the game is to put all cards as real families ascending on the
+foundation (on the right side of the playing piles).
+</para>
+
+<para>
+The sequences on the playing piles have to be descending while red and black
+cards have to alternate. Several cards can only be moved when they are part of
+an alternating sequence.
+</para>
+
+<para>
+In the 8 free cells on the top of the playing field you can put a single card
+temporarily. On a free playing pile you can put any card or sequence.
+</para>
+
+</sect1>
+
+<sect1 id="spider">
+<title>Spider</title>
+
+<anchor id="game_spider"/>
+<para><indexterm><primary>Spider</primary></indexterm>
+Spider is played with two card decks. The cards are dealt out into 10 playing
+piles, 4 of 6 cards and 6 of 5 cards each. This leaves 50 cards that can be
+dealt out 10 at a time, one on each playing pile.
+</para>
+
+<para>
+In the playing piles, a card can be placed on another card of any suit and
+of one higher value.  A sequence of ascending cards of the same suit may be
+moved from one playing pile to another.
+</para>
+
+<para>
+The goal of spider is to put all cards as real families descending from
+Kings anywhere in the playing piles.  When such a family is built in a
+playing pile, it is removed to the lower-left corner of the window.
+</para>
+
+<para>
+The different levels determine how many suits are dealt - Easy uses 1 suit,
+Medium uses 2 suits, and Hard uses all 4 suits.  The game is fairly easy to
+win at Easy, and very difficult to win at Hard.
+</para>
+
+</sect1>
+
+<sect1 id="golf">
+<title>Golf</title>
+
+<para><indexterm><primary>Golf</primary></indexterm> 
+Golf is played with one card deck.  The goal of Golf is to move all the cards on the tableau to the foundation. </para>
+ 
+<para>The layout of golf solitare is straight forward.  At the beginning of the game you will see, the tableau, on it are seven columns each containing five cards.  Below that is the talon and the foundation. </para>
+
+<para>Playing golf solitare is simple, but does require strategy to win.  The cards at the base of each column on the tableau are available for play.  Available cards are built upon the top foundation card in ascending or descending sequence regardless of suit.  If there are no moves available a card may be dealt from the talon to the foundation.  A game is over when all the cards in the talon have been dealt and there are no more possible moves.</para>
+
+</sect1>
+
+</chapter>
+
+<chapter id="credits">
+<title>Credits and License</title>
+
+<para>
+&kpatience; Copyright 1995-2000 Paul Olav Tvete 
+</para>
+
+<para>
+&kpatience; Copyright 2001 Stephan Kulow
+<email>coolo@kde.org</email>
+</para>
+
+<para>
+Freecell Solver by Shlomi Fish
+<email>shlomif@vipe.technion.ac.il</email>
+</para>
+
+<para>
+Documentation Copyright 2000 Paul Olav Tvete 
+</para>
+
+<para>
+Documentation updated for KDE 2.0 by Michael McBride
+<email>mpmcbride7@yahoo.com</email>
+</para>
+
+<para>
+Documentation rewritten for &kpatience; 2.0 (KDE 2.1) by Maren Pakura
+<email>maren@kde.org</email>
+</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;
+&underX11License;
+
+</chapter>
+
+&documentation.index;
+
+</book>
+
+<!--
+Local Variables:
+mode: sgml
+sgml-omittag: nil
+sgml-shorttag: t
+End:
+-->
+