<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//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><email>hadacek@kde.org</email></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><email>hadacek@kde.org</email></address>
</affiliation>
<contrib>Developer</contrib>
</othercredit>
<othercredit role="reviewer">
<firstname>Lauri</firstname>
<surname>Watts</surname>
<affiliation><address><email>lauri@kde.org</email></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>2001-02-03</date>
<releaseinfo>2.00.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
cases without blowing on a mine.</para>

<para>When you uncover a case, a number appears: it indicates how many mines
surround this case. If there is no number the neighbour cases are automatically
uncovered.  In your process of uncovering secure cases, it is
<emphasis>very</emphasis> useful to put a flag on the cases which contain a
mine.</para>

</chapter>

<chapter id="how-to-play">
<title>How to play</title>

<para>You have to use the mouse and its three buttons (with
two-buttoned mouses, clicking the <mousebutton>middle</mousebutton>
button is generally achieved by simultaneously pressing the
<mousebutton>left</mousebutton> and the
<mousebutton>right</mousebutton> buttons) to uncover or to flag the
cases. Here are the details :</para>

<itemizedlist>
<listitem><para>The <mousebutton>left</mousebutton> button will
uncover a case. If there is a bomb below that case, the bomb will
explode, and the game will be over </para> 
<para>If there is not a bomb under the case, a number will appear.
That is the number of neighboring cases that do have bombs under them.
Which ones you ask? Thats the point of the game.</para>
<para>For each box (excluding edge and cornerboxes), there are 8
neighboring boxes.</para>
<para>If none of the neighboring boxes has a bomb, then a blank will
be shown under the case, and all neighboring boxes will be
automatically uncovered.</para>
<note><para><mousebutton>Left</mousebutton> clicking a flagged case is
secure and does nothing.</para></note></listitem>
<listitem><para>The <mousebutton>right</mousebutton> button will mark
a case as containing a mine (draw a red flag) or, if the option is
set, as being uncertain (draw a question mark). 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 cases if there is the right number of cases
already flagged. It is very useful since it is much quicker than
uncovering all individual cases. </para>
<warning><para>If your flags are not properly positionned, you will
explode on 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.
Everytime 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 10 mines to be marked.</para></listitem>
<listitem><para>A Yellow Smiley Face.  Clicking this will start a new game.  If
you loose 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, gets to list their name 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 64 boxes. This is where you play the game.</para></listitem>
<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 four sections.</para>

<variablelist>
<varlistentry>
<term><guilabel>Game</guilabel></term>
<listitem>
<para>The first option, labelled <guilabel>Enable ? Mark</guilabel>,
determines whether you can mark squares as
<quote>questionable</quote>.  If there is a mark in front of this
option, then right clicking the mouse will first cause a case to be
flaged. If you 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 case to a
red flag.  The second will make it blank again, thus skipping the ?
symbol.</para>

<para>The next option down, labelled <guilabel>Enable
keyboard</guilabel>, determins if the keyboard shortcuts will work
while playing the game.</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 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 case.  If there is no bomb,
then a number will appear.  If there is a bomb under that case, 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 case, will mark/unmark with a redflag.</para></listitem>
</varlistentry>
<varlistentry>
<term>Autoreveal</term>
<listitem><para>Clicking on a case with this button, will automatically reveal
all neighboring cases, that are not marked with red flags.  If one of those
neighboring cases 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 case, will flag/unflag with a
question mark.</para></listitem>
</varlistentry>

<varlistentry>
<term>Toggle ? mark</term>
<listitem><para>Clicking with this button on a case, will mark/unmark with a
question mark.</para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Appearance</guilabel></term>
<listitem>
<para>The top option, entitled <guilabel>case size</guilabel>,
determines the size of each of the squares in the playing area.  By default,
they are set small.  You can increase the size, if you are working on a very
high resolution monitor.</para> 

<para>The rest of this page is concerned with colors. To adjust,
simply click the color button beside each description, and select the
new color.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Highscores</guilabel></term>
<listitem>
<para>Here 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 enable the <guilabel>World-wide highscores
enabled</guilabel> checkbox, and share your skill at &kmines; across
the world with an online high score server.</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 20 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 permenant.</para>

<para>If you want to abandon your changes, click
<guibutton>Cancel</guibutton> to abort the changes.</para>

<para>If you click on <guilabel>Default</guilabel>, the default
settings will be restored.  Click <guilabel>OK</guilabel> to make
these default changes permenant, 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 5 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>
<guimenu>Game</guimenu>
<guisubmenu>Choose Level</guisubmenu>
</menuchoice></term>
<listitem>
<para>Lets you set the difficulty level from a submenu.</para>
<para>There are three default levels of difficulty:
<guimenuitem>Easy</guimenuitem> (64 boxes, 10 mines),
<guimenuitem>Normal</guimenuitem> (256 boxes, 40 mines), and
<guimenuitem>Expert</guimenuitem> (480 boxes, 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>Game</guimenu>
<guimenuitem>Pause</guimenuitem> </menuchoice></term>
<listitem><para>Pauses 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="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 submenu.  Simply select
<guimenuitem>Show Menubar</guimenuitem> from this submenu, and the menubar
will be visible again.</para></note></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure Shortcuts</guimenuitem> </menuchoice></term>
<listitem><para>Allows you to change the keyboard shortcuts for &kmines;</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 Key Bindings</title>
<para>The following tables show you the default key bindings.</para>


<table>
<title>Menu bindings</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>&Ctrl;</entry><entry>Automatically reveal all surrounding cases 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><keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo></entry><entry>Pause Game</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 &kmines;</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>Whats This Help</entry></row>
<row><entry><keycombo action="simul">&Shift;</keycombo></entry><entry>Reveal Mine.</entry></row>
<row><entry><keycap>Space</keycap></entry><entry>Mark Mine</entry></row>
</tbody>
</tgroup>
</table>

<para>These key bindings can be changed by selecting <menuchoice>
<guimenu>Settings</guimenu> <guimenuitem>Configure Key
Bindings</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 <email>hadacek@kde.org</email></para>
<para>Documentation copyright 2000 Nicolas Hadacek <email>hadacek@kde.org</email></para>
<para>Documentation updated for KDE 2.0 by Mike McBride <email>mpmcbride7@yahoo.com</email></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:
-->


