1 files changed, 617 insertions, 0 deletions
diff --git a/doc/kmines/index.docbook b/doc/kmines/index.docbook
new file mode 100644
index 00000000..423a60a8
--- /dev/null
+++ b/doc/kmines/index.docbook
@@ -0,0 +1,617 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kappname "&kmines;">
+  <!ENTITY package "kdegames">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The &kmines; Handbook</title>
+
+<authorgroup>
+<author>
+<firstname>Nicolas</firstname>
+<surname>Hadacek</surname>
+<affiliation>
+<address>&Nicolas.Hadacek.mail;</address>
+</affiliation>
+</author>
+<author>
+<firstname>Michael</firstname>
+<surname>McBride</surname>
+<affiliation><address><email>mmcbride@ematic.org</email></address></affiliation>
+</author>
+<othercredit role="developer">
+<firstname>Nicolas</firstname>
+<surname>Hadacek</surname>
+<affiliation>
+<address>&Nicolas.Hadacek.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>2000</year>
+<holder>&Nicolas.Hadacek;, Michael McBride</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2005-12-28</date>
+<releaseinfo>2.1.10</releaseinfo>
+
+<abstract><para>&kmines; is the &kde; version of the classic minesweeper
+game.</para></abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>game</keyword>
+<keyword>minesweeper</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>&kmines; is the classic Minesweeper game. You must uncover all the empty
+squares without blowing up a mine.</para>
+
+<para>When you uncover a square, a number appears: it indicates how many mines
+surround this square. If there is no number the neighboring squares are automatically
+uncovered. When you find a square that you are sure contains a mine, it is
+<emphasis>very</emphasis> useful to put a flag on it (by right-clicking).</para>
+
+</chapter>
+
+<chapter id="how-to-play">
+<title>How to Play</title>
+
+<para>You have to use the mouse and its three buttons to uncover or to flag the
+squares (with two-buttoned mice, clicking the
+<mousebutton>middle</mousebutton> button is generally achieved by
+simultaneously pressing the <mousebutton>left</mousebutton> and the
+<mousebutton>right</mousebutton> buttons). Here are the details:</para>
+
+<itemizedlist>
+<listitem><para>The <mousebutton>left</mousebutton> button will
+uncover a square. If there is a bomb below that square, the bomb will
+explode, and the game will be over.</para>
+<para>If there is not a bomb under the square, a number will appear.
+That is the number of neighboring squares that contain bombs.
+<quote>Which ones?</quote> you ask: That's the point of the game.</para>
+<para>For each square (excluding edge and corner squares), there are 8
+neighboring squares.</para>
+<para>If none of the neighboring squares has a bomb, then a blank will
+be shown under the square, and all neighboring squares will be
+automatically uncovered.</para>
+<note><para><mousebutton>Left</mousebutton> clicking a flagged square is
+safe and does nothing.</para></note></listitem>
+<listitem><para>The <mousebutton>right</mousebutton> button will mark
+a square as containing a mine (by drawing a red flag on it) or, if the option is
+set, as being uncertain (by drawing a question mark on it). The uncertain tag can
+be useful when you are puzzled about the positions of
+mines.</para></listitem>
+<listitem><para>The <mousebutton>middle</mousebutton> button will
+clear the surrounding squares if the right number of squares is
+already flagged. It is very useful since it is much quicker than
+uncovering all individual squares.</para>
+<warning><para>If your flags are not properly positioned, you will
+explode a bomb.</para></warning></listitem>
+<listitem><para>Pressing the <guiicon>yellow smiley</guiicon> will start a new
+game.</para></listitem>
+</itemizedlist>
+
+<note><para>These are the default settings.  The mouse buttons can be
+reprogrammed. For more information, see the section entitled <link
+linkend="prefs">Game Options</link>.</para></note>
+
+<sect1 id="screen"><title>The &kmines; Screen</title>
+
+<screenshot>
+<screeninfo>The &kmines; Screen</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="kmines1.png"
+	     format="PNG"/></imageobject>
+<textobject><phrase>The &kmines; Screen</phrase></textobject>
+</mediaobject>
+</screenshot>
+
+<para>The &kmines; screen consists of:</para>
+
+<itemizedlist>
+<listitem><para>A Box showing you the number of mines still left to be marked.
+Every time you flag a bomb site, this number will decrease by one.</para>
+<note><para>This box does not determine if you are right or wrong, but only how
+many mines you need to theoretically mark before you are done with this
+game.</para></note>
+<para>In this example, there are 40 mines to be marked.</para></listitem>
+<listitem><para>A Yellow Smiley Face.  Clicking this will start a new game.  If
+you lose the game, it will become a frown.</para></listitem>
+<listitem><para>The box on the right shows how much time this round has taken.
+The shortest time for each level is listed as the high
+score.</para></listitem>
+<listitem><para>The playing area. This will vary in size depending on the
+difficulty level of the game.  In this example, it consists of 256 squares. This is where you play the game.</para></listitem>
+<!-- This doesn't seem to be there any more.
+<listitem><para>A status line at the bottom of the window.  In this example, it
+simply says <guilabel>Game stopped</guilabel>.</para></listitem>
+-->
+</itemizedlist>
+</sect1>
+</chapter>
+
+<chapter id="prefs"><title>Game Options</title>
+<para>The options to &kmines; are set by selecting <menuchoice>
+<guimenu>Settings</guimenu> <guimenuitem>Configure &kmines;</guimenuitem>
+</menuchoice> from the menubar.  This will bring up a dialog box.</para>
+
+<screenshot>
+<screeninfo>&kmines; Preferences</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="kmines2.png" format="PNG"/></imageobject>
+<textobject><phrase>&kmines; Preferences</phrase></textobject>
+</mediaobject>
+</screenshot>
+
+<para>This dialog box is divided into three sections.</para>
+
+<variablelist>
+<varlistentry>
+<term><guilabel>Game</guilabel></term>
+<listitem>
+<para>The first option, labeled <guilabel>Enable ? mark</guilabel>,
+determines whether you can mark squares as
+<quote>questionable</quote>.  If this option is checked, then right clicking the mouse will first cause a square to be
+flagged. If you right click again on the same square, the flag will change to
+a <guiicon>?</guiicon>, to indicate you don't know if there is a bomb
+there or not.  If you click again, the square will change back to
+blank.</para>
+
+<para>If there is not a mark in front of this option, the first
+<mousebutton>right</mousebutton> mouse click will change the square to a
+red flag.  The second will make it blank again, thus skipping the <guiicon>?</guiicon>
+symbol.</para>
+
+<para>The next option down, labeled <guilabel>Enable
+keyboard</guilabel>, determines if the keyboard shortcuts will work
+while playing the game. The default keyboard shortcuts are given in <xref
+linkend="keys"/>, and can be changed by selecting
+<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Shortcuts...</guimenuitem></menuchoice>.</para>
+
+<note><para>The only keyboard shortcuts affected are those
+responsible for playing the game.  Keyboard commands such as
+<guimenuitem>New Game</guimenuitem> and
+<guimenuitem>Quit</guimenuitem>, still work, regardless of this
+option.</para></note>
+
+<para>The <guilabel>Pause if windows loses focus</guilabel> option will
+automatically pause the game if the &kmines; window loses focus. When the game
+is paused, the gameboard disappears, so you cannot use pausing the game as a way
+to cheat!</para>
+
+<para>The <guilabel>"Magic" reveal</guilabel> option switches on <quote>Magic
+reveal</quote> mode. In this mode, &kmines; does most of the gameplay for you:
+If you have uncovered enough squares to be able to tell with certainty that a
+square contains a mine, &kmines; will automatically mark it as a mine, and
+perform an autoreveal on squares for which it has marked the correct number of
+mines. Note that when you have this mode switched on, your scores do not count
+as highscores.</para>
+
+
+<para>The last section of this tab allows you to change the action of each of
+the three mouse buttons.  Your options are:</para>
+
+<variablelist>
+<varlistentry>
+<term>Reveal</term>
+<listitem><para>This will reveal the contents of the square.  If there is no bomb,
+then a number will appear.  If there is a bomb under that square, then the bomb
+will explode, and the game will be over.</para></listitem>
+</varlistentry>
+<!-- <varlistentry>
+<term>Toggle Mark</term>
+<listitem><para>Clicking with this button on a square will mark/unmark with a red flag.</para></listitem>
+</varlistentry> -->
+<varlistentry>
+<term>Autoreveal</term>
+<listitem><para>Clicking on a square with this button will automatically reveal
+all neighboring squares that are not marked with red flags.  If one of those
+neighboring squares has a bomb under it, the bomb will explode, and the game will
+be over.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Toggle Flag</term>
+<listitem><para>Clicking with this button on a square will cycle through blank,
+red flag, and question mark.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Toggle ? Flag</term>
+<listitem><para>Clicking with this button on a square will mark/unmark with a
+question mark.</para></listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Appearance</guilabel></term>
+<listitem>
+<para>The top three color buttons determine the 
+<guilabel>Flag Color</guilabel>, <guilabel>Explosion Color</guilabel> 
+and <guilabel>Error Color</guilabel>.</para>
+
+<para>The rest of this page is concerned with mines colors. To adjust,
+simply click the color button beside each description, and select the
+new color.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><guilabel>Custom Game</guilabel></term>
+<listitem>
+<para>Finally, if you are not finding the existing configurations
+challenging enough, you can set up a custom game here.  Use the
+sliders to change the <guilabel>Width</guilabel>,
+<guilabel>Height</guilabel>, and the percentage of the board covered
+with <guilabel>Mines</guilabel>.  The default game has 15 percent of
+the board covered, so there is plenty of room to make the game
+harder.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>Saving your changes</term>
+<listitem><para>Once your changes are complete, click
+<guibutton>OK</guibutton> to make them permanent.</para>
+
+<para>If you want to abandon your changes, click
+<guibutton>Cancel</guibutton> to abort the changes.</para>
+
+<para>If you click on <guilabel>Defaults</guilabel>, the default
+settings will be restored.  Click <guilabel>OK</guilabel> to make
+these default changes permanent, or edit the settings some
+more.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</chapter>
+
+<chapter id="command">
+<title>Commands/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 4 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>Starts a new game.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycap>P</keycap>
+</shortcut>
+<guimenu>Game</guimenu>
+<guimenuitem>Pause</guimenuitem> </menuchoice></term>
+<listitem><para>Pauses or resumes the game.  This will hide the board (no cheating), and
+give you a button to press when you want to continue this
+game.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>H</keycap></keycombo>
+</shortcut>
+<guimenu>Game</guimenu>
+<guimenuitem>Show Highscores</guimenuitem> </menuchoice></term>
+<listitem><para>This shows you the high score (the shortest time) for each
+difficulty level.</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> &kmines;</para></listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="move-menu"><title><guimenu>Move</guimenu> Menu</title>
+<variablelist>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycap>H</keycap>
+</shortcut>
+<guimenu>Move</guimenu>
+<guimenuitem>Hint</guimenuitem> </menuchoice></term>
+<listitem><para>If you use this item, you will get a hint about where
+you should click next. If you do that your score will not be added to the high-scores.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Move</guimenu>
+<guimenuitem>Solve</guimenuitem> </menuchoice></term>
+<listitem><para>This item tries to solve the current game.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Move</guimenu>
+<guimenuitem>Solving Rate...</guimenuitem> </menuchoice></term>
+<listitem><para>This item shows a dialog that calculates the solving rate for the current game type.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Move</guimenu>
+<guimenuitem>View Log</guimenuitem> </menuchoice></term>
+<listitem><para>This item shows a dialog with the log of the last game.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Move</guimenu>
+<guimenuitem>Replay Log</guimenuitem> </menuchoice></term>
+<listitem><para>This item replays the current log.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Move</guimenu>
+<guimenuitem>Save Log...</guimenuitem> </menuchoice></term>
+<listitem><para>This item shows a dialog to save the current log.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Move</guimenu>
+<guimenuitem>Load Log...</guimenuitem> </menuchoice></term>
+<listitem><para>This item shows a dialog to load a log.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</sect1>
+
+<sect1 id="view-menu"><title><guimenu>View</guimenu> Menu</title>
+<variablelist>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>+</keycap></keycombo>
+</shortcut>
+<guimenu>View</guimenu>
+<guimenuitem>Zoom In</guimenuitem></menuchoice></term>
+<listitem><para>Increase the size of the gameplay canvas.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>-</keycap></keycombo>
+</shortcut>
+<guimenu>View</guimenu>
+<guimenuitem>Zoom Out</guimenuitem></menuchoice></term>
+<listitem><para>Decrease the size of the gameplay canvas.</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</sect1>
+
+<sect1 id="settings-menu"><title><guimenu>Settings</guimenu> Menu</title>
+<variablelist>
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show Menubar</guimenuitem> </menuchoice></term>
+<listitem><para>If there is a check in front of this option, then the menubar
+will be visible.  Selecting this option, hides the menubar.</para>
+<note><para>To restore a hidden menubar, click outside the game play area, with
+the right mouse button.  This will bring up a small sub-menu.  Simply select
+<guimenuitem>Show Menubar</guimenuitem> from this sub-menu, and the menubar
+will be visible again.</para></note></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guisubmenu>Choose Game Type</guisubmenu>
+</menuchoice></term>
+<listitem>
+<para>Lets you set the difficulty level from a sub-menu.</para>
+<para>There are three default levels of difficulty:
+<guimenuitem>Easy</guimenuitem> (64 squares, 10 mines),
+<guimenuitem>Normal</guimenuitem> (256 squares, 40 mines), and
+<guimenuitem>Expert</guimenuitem> (480 squares, 99 mines).  There is also a
+<guimenuitem>Custom...</guimenuitem> level settings.</para>
+<para>If you select <guimenuitem>Custom...</guimenuitem>, then the
+settings you have configured in the <guimenuitem>Configure
+&kmines;</guimenuitem> dialog will be used.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
+Shortcuts...</guimenuitem></menuchoice></term>
+<listitem><para>This item lets you change the keyboard shortcuts used by &kmines;.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
+Notifications...</guimenuitem></menuchoice></term>
+<listitem><para>This item displays a standard &kde; notifications configuration
+dialog, where you can change the notifications (sounds, visible messages,
+&etc;) used by &kmines;.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
+Highscores...</guimenuitem></menuchoice></term>
+<listitem><para>On the <guilabel>Main</guilabel> tab you can change your 
+<guilabel>Nickname</guilabel> and add a
+cute <guilabel>Comment</guilabel> about yourself, to show in the high
+score table. You can also activate the <guilabel>World-wide highscores
+enabled</guilabel> checkbox, and share your skill at &kmines; across
+the world with an online highscore server. If you are connected to the 
+Internet, &kmines; will send your score automatically at the end of the 
+game to the highscore web server (kmines.sf.net).</para>
+<para>The <guilabel>Advanced</guilabel> tab displays your <guilabel>Registration Data</guilabel> 
+on kmines.sf.net: Your <guilabel>Nickname:</guilabel> from the <guilabel>Main</guilabel> 
+tab and the <guilabel>Key:</guilabel>. This key was generated when you registered on kmines.sf.net by 
+selecting <guilabel>World-wide highscores enabled</guilabel> the first time.
+The registration key is used in conjunction with the 
+nickname to identify uniquely users, but users cannot have the same nickname.
+Click on the <guibutton>Remove</guibutton> button to delete you from the world highscores
+list.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure &kmines;...</guimenuitem> </menuchoice></term>
+<listitem><para>Allows you to adjust game options.  For more detailed
+information, see the section entitled <link linkend="prefs">Game
+Options</link>.</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>
+<para>The following table shows you the default keyboard shortcuts.</para>
+
+
+<table>
+<title>Keyboard Shortcuts</title>
+<tgroup cols="2">
+<thead><row><entry>Key Combo</entry><entry>Action</entry></row></thead>
+<tbody>
+<row><entry><keycap>Arrows</keycap></entry><entry>Move cursor in playing area.</entry></row>
+<row><entry><keycap>PageDown</keycap></entry><entry>Move to bottom
+edge</entry></row>
+<row><entry><keycap>PageUp</keycap></entry><entry>Move to top
+edge</entry></row>
+<row><entry><keycap>Home</keycap></entry><entry>Move to left edge</entry></row>
+<row><entry><keycap>End</keycap></entry><entry>Move to right edge</entry></row>
+<row><entry><keycap>Space</keycap></entry><entry>Reveal square.</entry></row>
+<row><entry><keycap>W</keycap></entry><entry>Mark square as mine</entry></row>
+<row><entry><keycap>Return</keycap></entry><entry>Automatically reveal all
+surrounding squares not marked by a flag.</entry></row>
+<row><entry><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo></entry><entry>New Game</entry></row>
+<row><entry><keycap>P</keycap></entry><entry>Pause Game</entry></row>
+<row><entry><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></entry><entry>Quit &kmines;</entry></row>
+<row><entry><keycap>F1</keycap></entry><entry>&kmines; Handbook</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>H</keycap></keycombo></entry><entry>Show Highscores</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>+</keycap></keycombo></entry><entry>Zoom In</entry></row>
+<row><entry><keycombo action="simul">&Ctrl;<keycap>-</keycap></keycombo></entry><entry>Zoom Out</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>
+&kmines;
+</para>
+<para>
+Program copyright 1996-2000 &Nicolas.Hadacek; &Nicolas.Hadacek.mail;</para>
+<para>Documentation copyright 2000 &Nicolas.Hadacek; &Nicolas.Hadacek.mail;</para>
+<para>Documentation updated for &kde; 2.0 by &Mike.McBride;
+&Mike.McBride.mail;</para>
+<para>Some changes for &kde; 3.2 by &Philip.Rodrigues; &Philip.Rodrigues.mail;</para>
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+&underFDL;
+&underGPL;
+
+</chapter>
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="getting-kmines">
+<title>How to obtain &kmines;</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:
+-->
+
+