tdegames/doc/kmines/index.docbook

<?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 "tdegames">
  <!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>