<?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 "1.90.2">
  <!ENTITY manrevision "2.0">
  <!ENTITY date "27 April 2002">
  <!ENTITY app "<application>Same-Gnome</application>">
  <!-- Information about the entities
       The legal.xml file contains legal information, there is no need to
       edit the file. 
       Use the appversion entity to specify the version of the application.
       Use the manrevision entity to specify the revision number of this
       manual.
       Use the date entity to specify the release date of this manual.
       Use the app entity to specify the name of the application. -->
]>

<!-- 
      (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 Apr 11, 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 V&manrevision;</title>       

    <copyright> 
      <year>2002</year> 
      <holder>Nicholas Curran</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> 
		<firstname>Nicholas</firstname> 
		<surname>Curran</surname> 
		<affiliation> 
	  		<orgname>GNOME Documentation Project</orgname> 
	  		<address> <email>quasar@austar.net.au</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>


<!-- According to GNU FDL, revision history is mandatory if you are
     modifying/reusing someone else's document.  If not, you can omit it.
     Remember to remove the &manrevision; entity from the revision entries
     other than the current revision.  The revision numbering system for GNOME
     manuals is as follows:
       * the revision number consists of two components.
       * the first component of the revision number reflects the release
         version of the GNOME desktop.
       * the second component of the revision number is a decimal unit that
         is incremented with each revision of the manual.
     For example, if the GNOME desktop release is V2.x, the first version of
     the manual that is written in that desktop timeframe is V2.0, the second
     version of the manual is V2.1, etc.  When the desktop release version
     changes to V3.x, the revision number of the manual changes to V3.0, and
     so on. -->  
    <revhistory>
      <revision> 
	<revnumber>&app; Manual V&manrevision;</revnumber> 
	<date>&date;</date> 
	<revdescription> 
	<para role="author">Nicholas Curran
    	<email>quasar@austar.net.au</email>
  	  </para>
  	  <para role="publisher">GNOME Documentation Project</para>
	</revdescription> 
      </revision> 
    </revhistory> 

    <releaseinfo>This manual describes version &appversion; of &app;.
    </releaseinfo> 
    <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>SAME GNOME</primary> 
  </indexterm> 
  <indexterm zone="index"> 
    <primary>same gnome</primary> 
  </indexterm>

<!-- ============= Document Body ============================= -->
<!-- ============= Introduction ============================== -->

  <sect1 id="same-gnome-introduction"> 
    <title>Introduction</title> 
    <para>
      The objective of &app; is to remove as many balls from the playing area
      in as few moves as possible.
    </para>
    <para>
      The playing area contains three types of balls.  Each type is a
      different color.  Balls of the same type in squares that border each
      other are grouped together.  If you click on one ball in a group, you
      remove all of the balls in that group.  You cannot remove a ball that is
      not part of a group.
    </para>
    <para>
      You can tell which balls are in a group by moving your mouse over the
      playing area.  Balls which are in the same group as the ball your mouse
      is over rotate.
    </para>
    <para>
      The number of points you receive is based on how many balls you remove
      in one click.  All balls move down when the balls beneath them are
      removed.
    </para>
    <para>
      The game is over when you cannot remove any more balls.
    </para>
  </sect1>

<!-- =========== Getting Started ============================== -->

  <sect1 id="same-gnome-getting-started"> 
    <title>Getting Started</title> 

    <sect2 id="same-gnome-start">
    <title>To Start &app;</title>
    <para>You can start <application>&app;</application> in the following ways:
    </para> 
    <variablelist>
    	<varlistentry>
    		<term><guimenu>Applications</guimenu> menu</term>
    		<listitem>
    		<para>Choose 
    		<menuchoice>
    		<guisubmenu>Games</guisubmenu>
    		<guimenuitem>&app;</guimenuitem>
    		</menuchoice>. </para>
    		</listitem>
    	</varlistentry>
    	<varlistentry>
    		<term>Command line</term>
    		<listitem>
    		<para>To start <application>&app;</application> from a
		command line, type the following command, 
    		then press <keycap>Return</keycap>:</para>
    		<para> 
			<command>same-gnome</command> 
    		</para> 
    		</listitem>
    	</varlistentry>
    </variablelist>
    </sect2>

    <sect2 id="same-gnome-when-start">
    <title>When You Start &app;</title>
    <para>
      When you start <application>&app;</application>, the following
      window is displayed.
    </para>

    <!-- ==== Figure ==== -->
      <figure id="mainwindow-fig"> 
	<title>&app; Start Up Window</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
		fileref="figures/same-main-window.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->

    <para>The &app; window contains the following elements:
    </para>
      <variablelist>
	<varlistentry>
	<term>Menubar. </term>
	<listitem>
	<para>
	  The menus on the menubar contain all of the commands you need to
	  play <application>&app;</application>.
	</para>
	</listitem>
	</varlistentry>
	<varlistentry>
	<term>Statusbar. </term>
	<listitem>
	<para>The status bar displays the following information:
	  <itemizedlist>
	  <listitem><para>
	    The left penal shows information about menu items in &app;.
	  </para></listitem>
	  <listitem><para>
	    The center panel shows how many balls will be removed if you click
	    on the ball your mouse is currently over.
	  </para></listitem>
	  <listitem><para>
	    The right panel shows you your score.
	  </para></listitem>
	  </itemizedlist>
	</para>
	</listitem>
	</varlistentry>
	</variablelist>
    </sect2>
  </sect1>


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

  <sect1 id="playing-same-gnome"> 
    <title>Playing Same Gnome</title> 
    
    <para>
      A new game is started when you start &app;.  To start a new game
      manually, choose
      <menuchoice>
        <guimenu>Game</guimenu>
	<guimenuitem>New game</guimenuitem>
      </menuchoice>.
    </para>

    <para>
      To remove a group of balls, click on a ball that is in that group.  When
      your mouse is over a ball that is part of a group, the balls in that
      group rotate.
    </para>

    <para>
      The game is over when no groups of balls remain.  If there are no balls
      left, you receive a bonus 1000 points.  At the end of the game, &app;
      will display the <interface>Score</interface> dialog.  The
      <interface>Score dialog</interface> is shown in
      <xref linkend="score-dialog-fig"/>.

    <!-- ==== Figure ==== -->
      <figure id="score-dialog-fig"> 
	<title>Score Dialog</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
		fileref="figures/score-dialog.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->

    </para>
    <para>
      You can view the <interface>Score dialog</interface> at any time by
      choosing
      <menuchoice>
        <guimenu>Game</guimenu>
	<guimenuitem>Scores...</guimenuitem>
      </menuchoice>.
    </para>
  </sect1>


  <!-- ============= Customization ============================= -->

  <sect1 id="same-gnome-prefs"> 
    <title>Settings</title> 
    <para>
      The <interface>Preferences</interface> dialog allows you to change the
      scenario.  A scenario determines what the balls look like in &app;.
    </para>
    <para>
      To open the <interface>Preferences</interface> dialog, choose
      <menuchoice>
        <guimenu>Settings</guimenu>
	<guimenuitem>Preferences...</guimenuitem>
      </menuchoice>.
      The <interface>Preferences</interface> dialog is
      shown in <xref linkend="preferences-fig"/>.

    <!-- ==== Figure ==== -->
    <figure id="preferences-fig">
      <title>&app; Preferences Dialog</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
		fileref="figures/preferences.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->

    </para>
    <para>
      To change the current scenario, select an option from the
      <guilabel>Select scenario</guilabel> drop-down list box.  The balls in
      the playing area will change automatically.
      <xref linkend="same-planets-fig"/> shows the main window using the
      <guilabel>planets.png</guilabel> scenario.
     <figure id="same-planets-fig"> 
      <title>&app; Main Window Using planets.png Scenario</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
		fileref="figures/same-planets-fig.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
    </para>
  </sect1>

  <sect1 id="creating-scenarios">
  <title>Creating Scenarios</title>
  <para>
    Each scenario is a graphics file.  Each graphics file contains frames of
    animation which are shown when the mouse is moved over a group of balls.
  </para>
  <para>
    Every frame must measure 40 by 40 pixels.  There must be three rows of
    frames in each graphics file.  Each row represents one type of ball.  The
    number of columns of frames depends on how many frames of animation you
    need.
  </para>
  <para>
    The graphics files must be in
    <systemitem>Portable Network Graphics (PNG)</systemitem> format.
  </para>
  <para>
    For &app; to be able to use your scenario, the scenario must be placed in
    <filename class="directory">
      <replaceable>$prefix</replaceable>/share/pixmaps/same-gnome/
    </filename>.
    <replaceable>$prefix</replaceable> is the directory in which GNOME is
    installed.  <replaceable>$prefix</replaceable> is usually either
    <filename class="directory">/usr/include</filename> or
    <filename class="directory">/usr/local/include</filename>.
  </para>
  <para>
    <xref linkend="blink-sync-fig"/> shows the graphics file used for the
    <guilabel>blink-sync.png</guilabel> scenario.

    <!-- ==== Figure ==== -->
    <figure id="blink-sync-fig"> 
      <title>Grapics File for Blink-Sync.png Scenario</title>
      <screenshot> 
        <mediaobject> 
	  <imageobject><imagedata
	    fileref="figures/blink-sync.png" format="PNG"/> 
	  </imageobject>
	</mediaobject> 
      </screenshot> 
    </figure>
    <!-- ==== End of Figure ==== -->

  </para>
  </sect1>

<!-- ============= Bugs ================================== -->
<!-- This section is optional and is commented out by default. 
     You can use it to describe known bugs and limitations of the 
     program if there are any - please be frank and list all
     problems you know of.  -->
  
<!--  <sect1 id="same-gnome-bugs">
  <title>Known Bugs and Limitations</title>
  <para>
    If you switch from another scenario to <guilabel>blink-sync.png</guilabel>,
    some blocks of blink-sync remain in a mid-animation frame.  When the mouse
    is moved over the playing area, this is corrected.
  </para>
  <para>
    In some cases, if the scenarios are changed, some balls disappear until
    the mouse is placed over them.  It happens sometimes when the following is
    done:
    <orderedlist>
      <listitem><para>
      Some balls are removed.
      </para></listitem>
      <listitem><para>
      The theme is then changed.  The theme should have fewer frames in its animation.
      </para></listitem>
    </orderedlist>
  </para>
 </sect1> -->

<!-- ============= About ================================== -->
<!-- This section contains info about the program (not docs), such as
     author's name(s), web page, license, feedback address. This
     section is optional: primary place for this info is "About.." box of
     the program. However, if you do wish to include this info in the
     manual, this is the place to put it. Alternatively, you can put this
     information in the title page.-->
  <sect1 id="same-gnome-about"> 
    <title>About &app;</title> 
    <para> &app; was written by the following people:
      <itemizedlist>
      <listitem><para>
        Miguel de Icaza (<email>miguel@nuclecu.unam.mx</email>)
      </para></listitem>
      <listitem><para>
        Federico Mena (<email>federico@nuclecu.unam.mx</email>)
      </para></listitem>      
      <listitem><para>
        Horacio J. Pea&ntilde; (<email>horape@compendium.com.ar</email>)
      </para></listitem>
      </itemizedlist>
    </para>

    <para>
      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>

    <para> This program is distributed under the terms of the GNU
      General Public license as published by the Free Software
      Foundation; either version 2 of the License, or (at your option)
      any later version. A copy of this license can be found at this
      <ulink url="ghelp:gpl" type="help">link</ulink>, or in the file
      COPYING included with the source code of this program.
    </para>
  </sect1> 
</article>
