<?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.12">
  <!ENTITY manrevision "2.10">
  <!ENTITY date "June 2005">
  <!ENTITY app "<application>Mahjongg</application>">
  <!ENTITY appname "Mahjongg">
]>

<!-- 
      (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>
	Mahjongg is a solitaire version of the classic Eastern tile game. 
	It involves clearing as much of the board as possible by matching 
	corresponding tiles and taking them out of play.
      </para>
    </abstract>
    <copyright>
      <year>1998</year>
      <holder>Free Software Foundation</holder>
    </copyright>
    <copyright>
      <year>2000</year>
      <holder>Eric Baudais (Documentation Author)</holder>
    </copyright>  
    
    <!-- translators: uncomment this:
    
  <copyright>
  <year>2000</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>Eric</firstname> 
	<surname>Baudais</surname> 
	<affiliation> 
	  <address> <email>baudais@okstate.edu</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">Eric Baudais
	    <email>baudais@okstate.edu</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 appliactions
    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="ghelp:gnome-feedback"
	  type="help">GNOME Feedback Page</ulink>. 
      </para>
<!-- Translators may also add here feedback address for translations -->
    </legalnotice>
  </articleinfo>

  <indexterm zone="index"> 
    <primary>GNOME Mahjongg</primary> 
  </indexterm>

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

    <para>
      <application>GNOME Mahjongg</application>, or Mahjongg for short,
      is a solitaire (one player) version of the classic Eastern tile game, 
      Mahjongg.  It has all the functionality you expect from a tile or 
      card game.  You can change the type of tiles, the background, and 
      the difficulty level, among other things, in the 
      <link linkend="prefs">Preferences</link> dialog.  
      Other features, like the <link linkend="pause"><guibutton>Pause
      </guibutton> button</link>, make the game more 
      competitive when you play against the clock. This document describes 
      <application>Mahjongg</application>.
    </para>

    <sect2 id="history">
      <title>A Brief History of Mahjongg</title>

      <!-- FIXME: Explain more about solitaire version.-->
      <para>
	Mahjongg tile sets are used to play many variations of the original 
	game.  The version of Mahjongg you play is the solitaire one.  Each 
	tile also has a <ulink type="http" 
        url="http://www.xs4all.nl/~korntner/mahjong/fortune/index.html">
        meaning</ulink> associated with it.
      </para>

      <para>
	Mahjongg's origins are not fully known, but many theories have been put 
	forth.  One such theory says that Noah played Mahjongg on the ark because 
	the East hand is dominant, presumably the direction the rains came, in the 
	flood.  Another theory says that the Chinese philosopher, Confucius, made 
	the game.  The three <quote>Cardinal</quote> tiles have the same names as 
	his three Cardinal virtues, Chung (middle) the Red, Fa (prosperity) the 
	Green, and Po (white) the White, cooresponding with Benevolence, Sincerity, 
	and Filial Piety.  Still another theory says that Mahjongg is derived from 
	other Chinese games.  <quote>Ya Pei</quote> is played with 32 cards made of 
	wood or ivory and have the same oblong shape as present day Mahjongg tiles.  
	<quote>Ma Tiae</quote> is played with 40 paper cards, similar in appearance, 
	numbering 1 to 9 in four different suits along with the flower cards.  It has 
	been suggested that two brothers made the game, around 1850 A.D., from a 
	combination of these two games.
      </para>

      <para>
	In the early 1900's Mahjongg was introduced into English clubs in Shanghai.  
	Mr. Babcock started the importation of Mahjongg tiles to the Western world.  
	He stripped down the rules to the very basics and even put Arabic numerals 
	on the tiles.  1923 was the height of the Mahjongg craze with major gaming 
	companies, like Parker Bros., Milton Bradley, and United States Playing Card, 
	importing Mahjongg tile sets by the thousands.
      </para>

      <para>
	Many different rules sprang up and in 1924 the Standardization Committee of 
	the American Official Laws of Mah-Jongg was formed to write a rule book.  
	Still today many clubs play by different rules and sometimes even add flower 
	or joker tiles.  Players of the computer version are becoming intrigued with the
	beauty and detail of the hand crafted sets of the 1920's and 1930's and are
	searching antique shops and flea markets for sets of their own. Many new
	players are being introduced to the game solely through the solitaire
	version and are slowly realizing the intrigue and challenge that the
	traditional game offers.
	<footnote>
	  <para>
	    Portions of this text were adapted from the <ulink type="http"
            url="http://www.mahjongmuseum.com/">Mah Jong Museum.</ulink>
	  </para>
	</footnote>
      </para>
    </sect2>
  </sect1>

  <sect1 id="usage">
    <title>Playing Mahjongg</title>

    <para>
      You start with five levels of tiles which are stacked so some are 
      covered up by the tiles on top.  The harder the level you set in the 
      <link linkend="prefs"><interface>Preferences</interface> dialog</link>, 
      the more tiles are covered when the game starts.  The object of 
      <application>GNOME Mahjongg</application> is to remove all the tiles 
      from the game.  To remove tiles you have to find matching pairs which 
      look alike.  A matching tile will usually have the same number of buttons 
      or markings on it or will look similar to each other.
    </para>

    <para>
      As an example, the highlighted tile, in the <link linkend="mahjongg-fig">
      figure below</link>, has six buttons.  The matching tile is the one which 
      also has six buttons.  The tile is on the right-hand end of the third row from the bottom and there is another near the top of the fourth row from the bottom.
      If you want to match the tile on the top level, you need to look for the 
      tile with the same green bamboo symbols.  Do you see a matching tile yet?  
      There are three tiles, which are visible, that match the tile on the top 
      level.  Two are to the left and the lower right. The thrid one is on the top row, but you can't
      remove that tile yet because the tile isn't 
      on the outside of the stack of tiles.  Later I'll explain more fully which 
      tiles can be removed and which tiles can't be removed even though they match.
      I'll let you find the other two matching tiles, which are visible, on your own.
    </para>

    <figure id="mahjongg-fig">
      <title>Mahjongg's Main Window</title>
      <screenshot>
	 <mediaobject> 
    <imageobject>
  <imagedata fileref="figures/mahjongg.png" format="PNG"
	       srccredit="Eric Baudais"/>
	</imageobject>
    <textobject> 
      <phrase>Main window.</phrase> 
    </textobject> 
  </mediaobject>
      </screenshot>
    </figure>

    <para>
      <application>Mahongg</application> is played by 
      clicking on two matching tiles that are then removed. Play
      continues until all the tiles are removed or there are no
      available pairs.
    </para>

    <para>
      Only tiles at the far left and right edges on each level 
      can be selected.  This is because you can't remove any tiles which 
      aren't at the far left and far right sides.  If the tiles are on 
      a different level and at the left or right sides, those can be removed 
      when you find another matching tile.
    </para>

    <para>
      If you can't match any more tiles, a 
      dialog will appear telling you no more tiles can be matched and giving you the option of shuffling the tiles or undoing your last move (although you may have to undo many more moves to find your mistake).
    </para>

    <figure id="info-fig1">
      <title>Information Dialog</title>
      <screenshot>
	 <mediaobject> 
    <imageobject>
  <imagedata fileref="figures/no-move.png" format="PNG"
	       srccredit="Eric Baudais"/>
	</imageobject>
    <textobject> 
      <phrase>Information Dialog.</phrase> 
    </textobject> 
  </mediaobject>
      </screenshot>
    </figure>
    
    <sect2 id="toolbar">
      <title>Toolbar</title>
      <para>
	The <interface>toolbar</interface> can be moved around the 
	<interface>desktop</interface>.  If you click on the far 
	left side of it, you will be able to drag it any place 
	on the <interface>desktop</interface> you wish.  The 
	<interface>toolbar</interface> also snaps into place 
	at the top and left side of the <interface>Main Window
	</interface> in <application>GNOME Mahjongg</application>, 
	but the default place the toolbar is located, and the best 
	in my opinion, is under the <interface>menubar</interface>.
      </para>

      <para>
	The <interface>toolbar</interface> contains the following buttons:
      </para>
      
      <variablelist>
	<varlistentry>
	  <term><guibutton>New</guibutton></term>
	  <listitem>
	    <para>
	      This button starts a new game with the current settings.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><guibutton>Restart</guibutton></term>
	  <listitem>
	    <para>
	      This button restarts the current game to the beginning without 
	      shuffling the tiles.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="pause">
	  <term><guibutton>Pause</guibutton></term>
	  <listitem>
	    <para>
	      This button pauses the game.  When the game is paused, the clock, 
	      at the bottom right corner of the <interface>Main Window</interface>, 
	      stops and you cannot see any of the tile's faces.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><guibutton>Undo</guibutton></term>
	  <listitem>
	    <para>
	      This button replaces two tiles you removed until 
	      you reach the beginning of the game.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><guibutton>Redo</guibutton></term>
	  <listitem>
	    <para>
	      This button replays your previous move, the <guibutton>Undo</guibutton> 
	      button took back.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><guibutton>Hint</guibutton></term>
	  <listitem>
	    <para>
	      This button gives you a pair of matching tiles to remove.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
      <para>
      The status bar at the bottom of the window gives you
      information on the current state of the game:
      </para>
      <variablelist>
	<varlistentry>
	  <term><guilabel>Tiles Left:</guilabel></term>
	  <listitem>
	    <para>
	      This shows the number 
	      of tiles remaining to be matched.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><guilabel>Moves Left:</guilabel></term>
	  <listitem>
	    <para>
	      This number 
	      of possible matches you can make.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
      
      <figure id="toolbar-fig">
	<title>Mahjongg's Toolbar</title>
	<screenshot>
	   <mediaobject> 
    <imageobject>
  <imagedata fileref="figures/toolbar.png" format="PNG"
		 srccredit="Eric Baudais"/>
	  </imageobject>
    <textobject> 
      <phrase>Toolbar.</phrase> 
    </textobject> 
  </mediaobject>
	</screenshot>
      </figure>
      
    </sect2>
    
    <sect2 id="menubar">
      <title>Menus</title>
      <para>
	The menu bar, located at the top of the <interface>Main
	Window</interface>, contains the following menus:
      </para>

      <variablelist>
	<varlistentry>
	  <term><guimenu>Game</guimenu></term>
	  <listitem>
	    <para>
	      The menu contains:
	      <itemizedlist mark="opencircle">
		<listitem>
		  <para>
		    <menuchoice>
		      <shortcut>
			<keysym>Ctrl-N</keysym>
		      </shortcut>
		      <guimenuitem>New</guimenuitem>
		    </menuchoice> &mdash; 
		    This item starts a new game.
		  </para>
		</listitem>
		<listitem>
		  <para>
		    <menuchoice>
		      <guimenuitem>Restart</guimenuitem>
		    </menuchoice> &mdash; 
		    This item resets the current game to the start.
		  </para>
		</listitem>
		<listitem>
		  <para>
		    <menuchoice>
		      <guimenuitem>Pause</guimenuitem>
		    </menuchoice> &mdash; 
                    This pauses the game, stopping the clock and
		    hiding the tiles.
		  </para>
		</listitem>
		<listitem>
		  <para>
		    <menuchoice>
		      <shortcut>
			<keysym>Ctrl-Z</keysym>
		      </shortcut>
		      <guimenuitem>Undo move</guimenuitem>
		    </menuchoice> &mdash; 
		    This item takes back two tiles you removed until 
		    you reach the beginning of the game.
		  </para>
		</listitem>
		<listitem>
		  <para>
		    <menuchoice>
		      <shortcut>
			<keysym>Ctrl-R</keysym>
		      </shortcut>
		      <guimenuitem>Redo move</guimenuitem>
		    </menuchoice> &mdash; 
		    This item replays your previous move the <guibutton>Undo</guibutton> 
		    button took back.  When you reach the state you started undoing the 
		    message <quote>No more redo!</quote> appears at the bottom left corner 
		    of the <interface>Main Window</interface>.
		  </para>
		</listitem>
		<listitem>
		  <para>
		    <menuchoice>
		      <guimenuitem>Hint</guimenuitem>
		    </menuchoice> &mdash; 
		    This item gives you a pair of matching tiles to remove.
		  </para>
		</listitem>
		<listitem>
		  <para>
		    <menuchoice>
		      <guimenuitem>Scores</guimenuitem>
		    </menuchoice> &mdash; 
		    This item brings up a dialog showing you the ten best scores.  The 
		    dialog has the scores identified by user name, score, the 
		    time it took to complete the game, and the date the game was 
		    completed.

		  </para>
		</listitem>
		<listitem>
		  <para id="quit">
		    <menuchoice>
		      <shortcut>
			<keysym>Ctrl-Q</keysym>
		      </shortcut>
		      <guimenuitem>Exit</guimenuitem>
		    </menuchoice> &mdash; 
		    This item allows you to quit the game.
		  </para>
		</listitem>
	      </itemizedlist>
	    </para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term><guimenu>Settings</guimenu></term>
	  <listitem>
	    <para>
	      The menu contains:
	      <itemizedlist mark="opencircle">
		<listitem>
		  <para>
		    <menuchoice>
		      <guimenuitem>Toolbar</guimenuitem>
		    </menuchoice> &mdash; 
		    This item determines whether the <link linkend="toolbar">
		    <interface>toolbar</interface></link> 
		    is shown or not.  If the item is checked, the 
		    <interface>toolbar</interface> is shown in the 
		    last place you put it.  If the item is unchecked, the 
		    <interface>toolbar</interface> is not shown.
		  </para>
		</listitem>
		<listitem>
		  <para>
		    <menuchoice>
		      <guimenuitem>Preferences</guimenuitem>
		    </menuchoice> &mdash; 
		    This item brings up the <link linkend="prefs">Preferences
		    </link> dialog.
		  </para>
		</listitem>
	      </itemizedlist>
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><guimenu>Help</guimenu></term>
	  <listitem>
	    <para>
	      The menu contains: 
	      <itemizedlist mark="opencircle">
		<listitem>
		  <para>
		    <menuchoice>
                      <shortcut>
			<keysym>F1</keysym>
		      </shortcut>
		      <guimenuitem>Contents</guimenuitem>
		    </menuchoice> &mdash; 
		    This item shows this manual.
		  </para>
		</listitem>
		<listitem>
		  <para>
		    <menuchoice>
		      <guimenuitem>About</guimenuitem>
		    </menuchoice> &mdash; 
		    This item gives you some basic information about 
		    <application>GNOME Mahjongg</application>, such as 
		    the author's names and the application version number.
		  </para>
		</listitem>
	      </itemizedlist>
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>

    </sect2>
  </sect1>

  <sect1 id="prefs">
    <title>Customization</title>
    <para>
      To change the application's settings, select
      <guimenuitem>Preferences</guimenuitem> from the
      <guimenu>Settings</guimenu> menu. This opens the 
      <link linkend="preferences-fig"><interface>Preferences
      </interface> dialog</link>.
    </para>
    
    <figure id="preferences-fig">
<!-- FIXME: This dialog is the old one. -->
<!-- ALAN: looks correct like version 2.10 to me -->
      <title>Preferences Dialog</title>
      <screenshot>
	 <mediaobject> 
    <imageobject>
  <imagedata fileref="figures/preferences.png" format="PNG"
		 srccredit="Eric Baudais"/>
	</imageobject>
    <textobject> 
      <phrase>Preferences dialog.</phrase> 
    </textobject> 
  </mediaobject>
      </screenshot>
    </figure>

    <para>
      All the options are applied and saved immediately.
    </para>
    
    <para>
      The properties in the <interface>Preferences</interface> dialog are:
    </para>
      
      <itemizedlist mark="opencircle">
	<listitem>
	  <para>
	    <guilabel>Tile Set:</guilabel> &mdash; 
	    Select the look of the tiles from this list.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <guilabel>Select Map:</guilabel> &mdash; 
	    Change the difficulty of the game by altering how 
	    the tiles are stacked.  The more spread out (easy) version 
	    lets you see more of the tiles while the more compact (hard) 
	    version does not let you see many tiles.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    <guilabel>Background Color:</guilabel> &mdash; 
	    Change the color of the background 
	    by bringing up a <interface>
	    color picker</interface> to let you select a new color.
	  </para>
	</listitem>
      </itemizedlist>

    <para>To alter the size of the tiles simply resize the window in
    the normal way. The tiles will expand to fill it.</para>

  </sect1>
  
<!-- ALAN: Better to leave this section out than to say something unhelpful 
and risk annoying the user.  
 <sect1 id="bugs">
  <title>Known Bugs and Limitations</title>
  <para>
   This application has no known bugs.
  </para>
 </sect1>
-->

 <sect1 id="authors">
  <title>Authors</title>
  <para>
   <application>GNOME Mahjongg</application> was written by Francisco 
   Bustamante (<email>pancho@nuclecu.unam.mx</email>), Michael Meeks 
   (<email>mmeeks@gnu.org</email>), Max Watson, Heinz Hempe, and 
   Philippe Chavin.  Tiles for <application>GNOME Mahjongg</application>
   were made by Jonathan Buzzard and Max Watson.    This manual was written by Eric Baudais
   (<email>baudais@okstate.edu</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>

  <!-- For translations: uncomment this:

  <para>
   Latin translation was done by ME
   (<email>MYNAME@MYADDRESS</email>). Please send all  comments  and
   suggestions regarding this translation to SOMEWHERE.
  </para>

  -->

 </sect1>


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

 <sect1 id="license">
  <title>License</title>
  <para>
   This program and tile artwork is free software; you can redistribute it and/or
   modify it under the terms of the <citetitle>GNU General Public
   License</citetitle> as published by the Free Software Foundation;
   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>GNU General Public License</citetitle> for more details.
  </para>
  <para>
   A copy of the <citetitle>GNU General Public License</citetitle> is
   included as an appendix to the <citetitle>GNOME Users
   Guide</citetitle>.  You may also obtain a copy of the
   <citetitle>GNU General Public License</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>51 Franklin Street, Fifth Floor</street>
    <city>Boston</city>, <state>MA</state> <postcode>02110-1301</postcode>
    <country>USA</country>
   </address>
  </para>
 </sect1>
</article>







