<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY legal SYSTEM "legal.xml">
  <!ENTITY appversion "2.14">
  <!ENTITY manrevision "2.9">
  <!ENTITY date "January 2006">
  <!ENTITY app "<application>Mines</application>">
  <!ENTITY appname "Mines">
  <!ENTITY version "2.14">
]>

<!-- 
      (Do not remove this comment block.)
  Maintained by the GNOME Documentation Project
  http://developer.gnome.org/projects/gdp
  Template version: 2.0 beta
  Template last modified Feb 12, 2002
-->

<!-- =============Document Header ============================= -->

<article id="index" lang="en">
<!-- please do not change the id; for translations, change lang to -->
<!-- appropriate code -->
  <articleinfo>
    <title>&app; Manual</title>
    <abstract role="description">
      <para>
	Mines is GNOME's take on the popular logic puzzle minesweeper, 
	which includes avoiding mines while receiving clues for 
	the location of the mines.
      </para>
    </abstract>
    <copyright>
      <year>2006</year>
      <holder>Callum McKenzie</holder>
<!--   Based on an earlier manual by   <holder>Tim Riehle</holder> -->
    </copyright>
<!-- translators: uncomment this:

  <copyright>
   <year>2002</year>
   <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
  </copyright>

   -->
<!-- An address can be added to the publisher information.  If a role is 
     not specified, the publisher/author is the same for all versions of the 
     document.  -->
    <publisher> 
      <publishername> GNOME Documentation Project </publishername> 
    </publisher> 

   &legal;
   <!-- This file  contains link to license for the documentation (GNU FDL), and 
        other legal stuff such as "NO WARRANTY" statement. Please do not change 
	any of this. -->

    <authorgroup> 
      <author role="maintainer"> 
	<firstname>Callum</firstname> 
	<surname>McKenzie</surname> 
	<affiliation> 
	  <address> <email>callum@spooky-possum.org</email> </address> 
	</affiliation> 
      </author> 
<!-- This is appropriate place for other contributors: translators,
      maintainers,  etc. Commented out by default.
       <othercredit role="translator">
	<firstname>Latin</firstname> 
	<surname>Translator 1</surname> 
	<affiliation> 
	  <orgname>Latin Translation Team</orgname> 
	  <address> <email>translator@gnome.org</email> </address> 
	</affiliation>
	<contrib>Latin translation</contrib>
      </othercredit>
-->
    </authorgroup>
    <revhistory>
      <revision> 
	<revnumber>&appname; Manual V&manrevision;</revnumber> 
	<date>&date;</date> 
	<revdescription> 
	  <para role="author">Callum McKenzie
	    <email>callum@spooky-possum.org</email>
	  </para>
	  <para role="publisher">GNOME Documentation Project</para>
	</revdescription> 
      </revision> 
    </revhistory> 

    <releaseinfo>This manual describes version &appversion; of &appname;.
    </releaseinfo>
    <!-- The following feedback information only applies to applications
    listed in bugzilla.gnome.org and bugzilla.ximian.com. For other
    applications, please provide your own feedback info or remove thsi
    section altogether -->
    <legalnotice> 
      <title>Feedback</title> 
      <para>To report a bug or make a suggestion regarding the &app; application or
	this manual, follow the directions in the 
	<ulink url="http://bugzilla.gnome.org">GNOME bug reporting database.</ulink>. 
      </para>
<!-- Translators may also add here feedback address for translations -->
    </legalnotice>
  </articleinfo>

  <indexterm zone="index"> 
    <primary>GNOME Mines</primary> 
  </indexterm>
  
 <!-- ============= Document Body ============================= -->

 <!-- ============= Introduction ============================== -->
  <sect1 id="intro">
    <title>Introduction</title>

    <para>
     <application>&app;</application> is a puzzle game where you
     locate mines floating in an ocean using only your brain and a
     little bit of luck.  
    </para>

    <para>
      You start the game with a grid of covered squares and no idea what is in them. Clicking on a square reveals
      what is in it: either empty ocean or a mine. If you
      find a mine bad things happen and the game is over. If you
      uncover an empty square, you survive and get to try again. We do
      give you a bit of help; if you find an empty piece of ocean
      a number is printed there telling you how many mines are in the 
      adjacent squares (or no number if there are no nearby
      mines). Once you find a few clear squares you can start to
      deduce which squares have mines in them and which don't. You win
      the game once you have revealed all the un-mined squares and
      marked all the mined squares.
    </para>

    <figure id="main-window">
      <title>The stages of the game: the start, playing, losing,
	    and winning.</title>
    	    <mediaobject><imageobject>
    	      <imagedata fileref="figures/main-window.png"
	    format="PNG"/>
	    </imageobject></mediaobject>
    </figure>

    <para>
      To mark a square as having a mine you right-click on it and a
      flag is placed there. If you click on a square with a number and
      you have placed precisely that number of flags on adjacent
      squares then the remaining squares are revealed. If you didn't
      mark the mines correctly then an explosion will occur and the game
      is over. Squares with no adjacent mines (i.e. blank squares)
      have their adjacent squares automatically cleared.  
    </para>

    <figure id="status-bar">
      <title>Important information.</title>
    	    <mediaobject><imageobject>
	    <imagedata fileref="figures/statusbar.png"
	    format="PNG"/>
	    </imageobject></mediaobject>
    </figure>

    <para>
      You are being timed. To be good at this game you have to work
      both quickly and correctly. Once you have found all the mines
      and revealed all the un-mined squares the clock is stopped. Your
      score is the time you took; the shorter the better.
    </para>

    <para>
      The time you have taken is displayed on the bottom right of the
      window. Beside it, on the left, is a count of the number of mines 
      you have cleared and the total number hidden on the board.
    </para>

    <figure id="faces">
      <title>The yellow face shows you how well you are going.</title>
    	    <mediaobject><imageobject>
	    <imagedata fileref="figures/faces.png"
	    format="PNG"/>
	    </imageobject></mediaobject>
    </figure>

    <!-- Face graphics image. -->

  </sect1>


  <sect1 id="details">
    <title>The Details</title>

    <para>
      This section provides information on the controls and the
    important menu items. If you need help figuring where the
    mines are, see the <link linkend="strategy">strategy section</link>.
    </para>

    <sect2>
      <title>The Goal</title>

      <para>
        Starting from an ocean of squares with unknown contents
	you must mark all the squares with mines and reveal all the
	clear squares. You don't actually have to mark the squares with mines,
	but it is a lot easier if you do. Once you have cleared all
	the un-mined squares, any remaining mined squares will be
	marked for you.
      </para>

      <para>
	If you left click on a mine, or auto-clear a square with a mine
        in it you lose. To help prevent accidents, you aren't allowed
        to auto-clear around a square unless the number of marked
        mines equals the number given in the square.
      </para>

    </sect2>

    <sect2>
      <title>Using the Mouse</title>
      
      <informaltable>
        <tgroup cols="2">
	<!-- FIXME: proper headers. -->
	  <thead>
	    <row>
	      <entry>Action</entry><entry>Result</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry>Left click on an un-revealed square.</entry>
	      <entry>Reveals the contents of that square. For better or for
	      worse.</entry>
	    </row>
	    <row>
	      <entry>Left click in a revealed square.</entry>
	      <entry>Auto-clear. Reveals the unmarked squares around
              the clicked square,
	      but only if enough squares have been marked to match the
	      number in the square.</entry>
	    </row>
	    <row>
	      <entry>Right click on an un-revealed square.</entry>
	      <entry>Marks the square as a mine. If it is already
	      marked, the mark will be removed.</entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <tip><para>If you are used to the more traditional mouse controls,
           don't worry, they still work.</para></tip>
    </sect2>

    <sect2>
      <title>Game Size and Difficulty</title>

      <para>
        By choosing <menuchoice><guimenu>Settings</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice> from the 
	 menu you can
        change the size of the games. Larger sizes obviously take longer
        and require more concentration. Smaller games are more
        frantic. We provide Small, Medium, Large and Custom
        sizes.
      </para> 

    <figure id="preferences-img">
      <title>The preferences dialog.</title>
    	    <mediaobject><imageobject>
	      <imagedata fileref="figures/preferences.png"
	    format="PNG"/>
	    </imageobject></mediaobject>
    </figure>

      <para>
        On the right hand side of the dialog there are three
        parameters for controlling the custom size. Horizontal and
        Vertical are the width and height of the desired grid in
        squares. The number of mines is - obviously - the number of
        mines you need to find. If this number is set too high or too
        low then the game becomes very easy. The number of mines is
        limited to slightly less than the total number of squares.
      </para>

    </sect2>
    
    <sect2>
      <title>"I'm not sure" Flags</title>

      <informalfigure id="imnotsureflagsimg">
    	    <mediaobject><imageobject>
  	      <imagedata fileref="figures/imnotsureflagscheckbox.png"
  	        format="PNG"/>
	    </imageobject></mediaobject>
      </informalfigure>

      <para>
        There is a check-box in the properties dialog entitled
        Use "I'm not sure" flags. If you enable this then, when
        right-clicking on a square, it cycles between the normal flags
        used to mark the square as mined, a flag with a question mark
        on it and no flag. This new flag is to help you with your
        reasoning, to mark mines you think might be a mine but aren't
        sure about. These
        flags have no effect on the game; you still have to use the 
	appropriate  number of red marker flags to be able to clear
        around a numbered square.
      </para>

      <figure id="flags-img">
	<title>The sequence of flags when "I'm not sure" flags are enabled.</title>
    	    <mediaobject><imageobject>
  	      <imagedata fileref="figures/flags.png"
  	        format="PNG"/>
	    </imageobject></mediaobject>
      </figure>

    </sect2>

    <sect2>
      <title>Use "Too many flags" warning</title>

      <para>
        The other check-box in the properties dialog is entitled
        Use "Too many flags" warning. This feature will show you a
        warning when you have placed too many flags. This is disabled
        by default, as it provides so much hint that it could be
        considered "cheating".
      </para>

    </sect2>

    <sect2>
      <title>Hints</title>
    
      <para>
        If you get stuck - it is reasonably common to end up with two
        options that you can't logically resolve - then you can either
        guess, or ask for a hint. When you choose 
	<guimenuitem>Hint</guimenuitem> from the <guimenu>Game</guimenu>
        menu a single square is revealed (plus surrounding
        squares if it is blank). The choice of square is random, but
        should be helpful. There is 10 second penalty added to your
        time whenever you use a hint.
      </para>

    </sect2>

    <sect2>
      <title>High Scores</title>

      <para>
        If your score is in the top ten you will be shown the list of top scores and have an
        opportunity to change the name recorded in the high score table. You can
        also review the scores later by choosing 
	<guimenuitem>Scores</guimenuitem> from the <guimenu>Game</guimenu>
        menu. The drop-down menu at the top of the dialog lets you
        look at the scores for other board sizes.
      </para>

    <figure id="high-score-img">
      <title>The high scores dialog.</title>
    	    <mediaobject><imageobject>
	    <imagedata fileref="figures/highscores.png"
	    format="PNG"/>
	    </imageobject></mediaobject>
    </figure>

      <tip>
        <para>The high score for the custom size is usually meaningless. Any
	other player can make the game size smaller and get a better time. If
        you only ever play one custom size then it will tell you how
	well you are doing. This is the only reason it is still recorded.</para>
      </tip>
    </sect2>

    <sect2>
      <title>Window Size</title>
      
      <para>Resizing the window makes the squares bigger or smaller to
    suit. If you want to make maximum use of the screen then there is a
    <guimenuitem>Fullscreen</guimenuitem> option under the
    <guimenu>Settings</guimenu> menu. You can
    also use the <keycap>F11</keycap> key to toggle full-screen mode.
      </para>
    </sect2>

    <sect2>
      <title>Pausing the Game</title>

      <para>
        The game can be paused automatically when you start using another
        window, or paused by choosing <guimenuitem>Pause</guimenuitem> 
	from the <guimenu>Game</guimenu> menu. The playing area is 
	blanked so you can't think ahead while the clock is stopped. To
        start playing again press the button labelled "Press to Resume".
      </para>
    </sect2>

  </sect1>

 <!-- ================ Usage ================================ -->

  <sect1 id="strategy">
    <title>Strategy</title>

    <para>
      The first half of this section explains the very basics of
    deducing where mines are. If you are familiar with how to play the
    game skip down to the <link linkend="advanced">Advanced Situations</link> subsection.
    </para>

    <sect2>
      <title>The Basics</title>
      <para>
        These are a few basic situations which should be incredibly
      obvious, but if you're struggling with how to play the game,
      they should be useful. The first case is where you have an
      isolated covered square and most of the squares around it read
      1. That covered square is a mine. 
      </para>

      <figure>
        <title>The simplest case.</title>
    	    <mediaobject><imageobject>
            <imagedata  format="PNG" fileref="figures/easy-hints-1.png"/>
	    </imageobject></mediaobject>
      </figure>

      <para>
        The next simplest case is where you have two covered squares
        adjacent to each other and both squares on one side are marked
        with a 2. If they have no other uncleared neighbors, then
        both squares are mines.
      </para>

      <figure>
        <title>The two mine case.</title>
    	    <mediaobject><imageobject>
            <imagedata  format="PNG" fileref="figures/easy-hints-2.png"/>
	    </imageobject></mediaobject>
      </figure>

      <para>
        Finally, when there are three uncovered squares in a row and
        the clear square beside the middle one is a 3 (once again this
        square should have no other neighbors) then all three are mines.
      </para>

      <figure>
        <title>The three mine case.</title>
    	    <mediaobject><imageobject>
            <imagedata  format="PNG" fileref="figures/easy-hints-3.png"/>
	    </imageobject></mediaobject>
      </figure>

      <para>
        These are the simplest cases. Other permutations on these
        simple situations are possible, for example the three squares
        in the previous example could be in an L shape. 
      </para>
      <para>
        Simple analysis will solve most of the
        puzzle, but not all. Before going on to the next sections,
        where we give you more advanced hints, you should play
        for a bit and see what you can work out for yourself.
      </para>
    </sect2>

    <sect2 id="advanced">
      <title>Advanced Situations</title>
      
      <para>
        These are some more complicated situations. They are a bit of
        a step up from the last section, so we hope you took our
        advice and played for a bit first.
      </para>

      <para>
      In the example below the mines are to the left of
      the ones. We figure this out by a process of elimination. If the
      square to the left of the 2 was a mine then the 1s
      would both have their maximum number of mines leaving no free square for
      the second mine adjacent to the 2 (since they would also be
      adjacent to the 1s). Having eliminated the middle square we are
      left with two squares we require for the 2 so they are both mined.
      </para>

      <figure>
        <title>A not-so-obvious pattern.</title>
    	    <mediaobject><imageobject>
            <imagedata  format="PNG" fileref="figures/hard-hints-1.png"/>
	    </imageobject></mediaobject>
      </figure>

      <para>
      This situation can be disguised, for example consider the figure
      below. It is the same situation, but the extra mined square on
      the right has increased all the numbers by 1.
      </para>

      <figure>
        <title>The extra mine disguises a copy of the previous example.</title>
    	    <mediaobject><imageobject>
            <imagedata  format="PNG" fileref="figures/hard-hints-2.png"/>
	    </imageobject></mediaobject>
      </figure>

<para>
Now we're going to try a complicated example. It illustrates two
points. The first is that even if you aren't sure which squares are
mined, restricting the possibilities is helpful. The second is that
knowing which squares aren't mined is nearly as good as knowing which
are mined.
</para>

<para>
Assume that, in the figure below, we start off knowing that the top
left square is mined and so the two squares marked 2 on the left only
require one more mine. Next observe that the left-most 2 implies that
one of the covered squares beneath it is mined, but we don't yet know
which one. Since at least one of these squares is mined and they are
both neighbors of the second 2 then we know that that 2 is also
satisfied by one of these two squares (we still don't know which
one). This means that the square beneath the 4 is clear because it is
also a neighbor of the second 2 and not one of the two squares we
identified previously. 
This one blank square now leaves the 4 with only four neighbors - all
of which must be mines. Not only does it tell us which mines surround
the 4, it now tells us which of the squares beside the 2 is mined!
</para>

      <figure>
        <title>As tricky as it gets.</title>
    	    <mediaobject><imageobject>
            <imagedata  format="PNG" fileref="figures/hard-hints-3.png"/>
	    </imageobject></mediaobject>
      </figure>


<para>
This sort of situation is tricky. In all the other examples you can
learn to look for patterns and avoid thinking hard. Situations like
the one in the figure don't crop up easily or in easily recognisable
places. Often it is easier to just ignore them and keep playing
elsewhere in the hope that you can start clearing the squares from the
other side.
</para>

</sect2>
<sect2>

    <title>Tips</title>

    <para>
      Remember, the edge of the board is just the same as a large
      cleared area (but without the numbers). Often working
      at the edge of the board is the easiest way forward. 
    </para>

    <para>
      Sometimes you end up in a situation where there is no way to
      deduce what the configuration is. In these cases you either have
      to guess or use the hint function
      (<menuchoice><guimenu>Game</guimenu><guimenuitem>Hint</guimenuitem></menuchoice>).
      Sometimes it isn't a 50/50 situation and instead of taking a hint
      you might like to gamble on the most likely outcome.
    </para>

    <para>
      One final hint: remember the counter on the bottom left of the window
      that tells you how many mines you have left? Often, near the end
      of the game, this number can help you figure out what possible
      places mines can be. How to do this is  up
      to you to figure out.
    </para>

    </sect2>
 </sect1>

 <sect1 id="authors">
  <title>Authors</title>
  <para>
   <application>GNOME Mines</application> was written by Pista
   (<email>szekeres@cyberspace.mht.bme.hu</email>). This manual was written by Callum McKenzie
  (<email>callum@spooky-possum.org</email>) with help from Vincent
  Povirk and based on an earlier manual by Tim Riehle
   (<email>tkriehle@citilink.com</email>).
   To report a bug or make a suggestion regarding this application or
   this manual, follow the directions in this 
   <ulink url="ghelp:gnome-feedback" type="help">document</ulink>.
  </para>
 </sect1>


 <!-- ============= Application License ============================= -->

 <sect1 id="license">
  <title>License</title>
  <para>
   This program is free software; you can redistribute it and/or
   modify it under the terms of the <citetitle><ulink type="help" url="gnome-help:gpl">GNU General Public License</ulink></citetitle> as
   published by the <ulink type="http"
   url="http://www.fsf.org">Free Software Foundation</ulink>;
   either version 2 of the License, or (at your option) any later
   version.
  </para>
  <para>
   This program is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   <citetitle><ulink type="help" url="gnome-help:gpl">GNU General Public License</ulink></citetitle> for more details.
  </para>
  <para>
   A copy of the <citetitle><ulink type="help" url="gnome-help:gpl">GNU General Public License</ulink></citetitle> is
   included as an appendix to the <citetitle>GNOME Users
   Guide</citetitle>.  You may also obtain a copy of the
   <citetitle><ulink type="help" url="gnome-help:gpl">GNU General Public License</ulink></citetitle> from the Free
   Software Foundation by visiting <ulink type="http"
   url="http://www.fsf.org">their Web site</ulink> or by writing to
   <address>
    Free Software Foundation, Inc.
    <street>59 Temple Place</street> - Suite 330
    <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
    <country>USA</country>
   </address>
  </para>
 </sect1>
</article>
