<!DOCTYPE article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
<!ENTITY version "1.0pre2">
]>

<article id="index"> 

  <artheader>
    <title>GnomerMind Manual</title>
    <copyright>
      <year>2001</year>
      <holder>Germano Rizzo</holder>
    </copyright>
    <copyright>
      <year>2001</year>
      <holder>Marco Cova (Documentation)</holder>
    </copyright>

  <!-- translators: uncomment this:

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

   -->


  <legalnotice id="legalnotice">
   <para>
    Permission is granted to copy, distribute and/or modify this document
    under the terms of the <ulink type="help" 
    url="gnome-help:fdl"><citetitle>GNU Free Documentation
    License</citetitle></ulink>, Version 1.1 or any later version 
    published by the Free Software Foundation with no Invariant Sections, 
    no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
    can be found <ulink type="help" url="gnome-help:fdl">here</ulink>.
   </para>
   <para>
    Many of the names used by companies to distinguish their products and
    services are claimed as trademarks. Where those names appear in any
    GNOME documentation, and those trademarks are made aware to the members
    of the GNOME Documentation Project, the names have been printed in caps
    or initial caps.
   </para>
  </legalnotice>

    <releaseinfo>
       This is version &version; of GnomerMind manual.
    </releaseinfo>

  </artheader>

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

    <para>
     <application>GnomerMind</application> is a puzzle game based 
     upon the original MasterMind(R) game. It has all the features of
     that classic game, plus full theme support, difficulty rating,
     preferences settings, rule configuration, and some other nice stuff.
    </para>
    
    <para>
      To run <application>GnomerMind</application>, select
      <menuchoice>
	<guisubmenu>Games</guisubmenu>
	<guimenuitem>GnomerMind</guimenuitem>
      </menuchoice>
      from the <guimenu>Main Menu</guimenu>, or type
      <command>gnomermind</command> on the command line.
      Type <command>gnomermind --help</command> for a list
      of available options.
  </para>

    <para>
      This document describes version
      &version; of <application>GnomerMind</application>.
    </para>
  </sect1>

  <sect1 id="usage">
    <title>Using GnomerMind</title>
    <para>
      <application>GnomerMind</application> is a simple yet intriguing 
      cunning and logic game. It disposes randomly a certain number of coloured
      tokens in a row. The objective of the game is to guess the disposition of
      the tokens.
    </para>
    <para>
      In order to do the correct guess, you can count on logic, and a little bit of luck. Infact after every guess, <application>GnomerMind</application> will give you two hints: how many tokens you've put in the correct place (both the token's colour and its position are correct) and how many tokens are present in the solution row but not in the position you put them (i.e.: only the token's colour is correct.) 
    </para>  
    <para>
      This section describes basic usage of
      <application>GnomerMind</application>.
    </para>

    <sect2>
      <title>Basic usage</title>
      <para>
        Starting <application>GnomerMind</application> opens the
        <interface>Game window</interface> and the <interface>Palette</interface> window. The game board is initially empty, while the palette window shows all the possible tokens and an operation icon.
      </para> 

      <para>Basically, the first thing to do is to select a token and place it in the &quot;active&quot; row. To do this, you have some different possibilities; just do whatever you want... GnomerMind is designed to allow you to do almost anything you can think of, to be just as immediate as possible!
      </para>

<variablelist>
	<varlistentry>
	  <term>Select a token from the palette, and put it in the row:</term>
	  <listitem><para>You can select a token from the <interface>Palette window</interface>, by left-clicking on it (for left-handed mice, right-clicking). It will be &quot;picked up&quot; and an hole will appear instead; now you've selected it, you can click on any empty hole of the active row (the first without hint pins, starting from the bottom of the field) to place it there. The pin remains selected, after this, by default; in the <link linkend="prefs"><interface>Preferences dialog</interface></link> you can specify a different behaviour.</para>
          <para>To put down a token, just select another one, or click on the empty hole</para></listitem>
	</varlistentry>
      	<varlistentry>
	  <term>Select a token from the game field:</term>
	  <listitem><para>You can also select tokens from the active row, or from a row you've yet composed and evaluated: just click on the desired token. Of course, if you select one from a yet-done row, you won't get a hole in that row; and if you have another token still selected, and click on a token of the active row, you'll only place there the selected one.</para></listitem>
	</varlistentry>
	<varlistentry>
	  <term>&quot;Direct&quot; placing:</term>
	  <listitem><para>If you right click on a token, either in the <interface>Palette window</interface> or in the <interface>Game field</interface>, you will directly place it in the first empty place. The currently selected colour won't change.</para></listitem>
	</varlistentry>
	<varlistentry>
	  <term>&quot;Random&quot; placing:</term>
	  <listitem><para>If you right click on an empty hole, you will place in it a random token. This is somehow &quot;smart&quot;; infact, if the field to guess doesn't contain repetitions (that is, if the proper rule is set), it won't place repeated tokens; and the currently selected colour won't change.</para></listitem>
	</varlistentry>
	<varlistentry>
	  <term>Use the keyboard:</term>
	  <listitem><para>You can play using the keyboard as well: use the default key-bindings or customize them via the <link linkend="prefs"><interface>Preferences Dialog</interface></link> to speed up the token selection and release operations. See next paragraph for further details.</para></listitem>
	</varlistentry>
</variablelist>

      <para>
      When the row is complete, the check icon in the palette window will activate changing its shape.
      If you click on it, <application>GnomerMind</application> will evaluate your guess. On the left
      hand of the game window you will see some pins.
      Their colour and/or shape change when you change the theme. In any case, they will tell you how many correct guesses you did. You can read a "textual" evaluation of your guess in the application's statusbar, at the bottom of the main window.
      For instance, in the Classic theme, you will find black and white pins.
      Each black pin means: "both the colour and the position of one token are correct."
      Each white pin means: "the colour of one token is correct. Not its position."
</para>
<note>
<para>
      Note that you still have to guess which is the token the pin refers to: the position of the pins doesn't match tokens' positions.
      </para>
</note>
<para>
      When you'll have guessed all the tokens correctly, the solution will be displayed, and a nice jingle will be played. You'll have won! Rejoice! :)) Now, to start another game, just click on the action icon (whose shape will be different), or press the action key (see below), or just close the solution window.
</para>
<para>
      If you finish all the available rounds, you'll lose! Again, the solution will be displayed, and you'll hear a teasing voice... ;) Don't get angry, and do the same as before to start another game!
</para>
    </sect2>  

    <sect2>
    <title>Default keys</title>
     <para>
      <variablelist>
	<varlistentry>
	  <term>To select a token from the palette:</term>
	  <listitem><para>
		Numbers from <keycap>1</keycap> (1st position) to <keycap>0</keycap> (10th position)
	  </para></listitem>
	</varlistentry>
      	<varlistentry>
	  <term>To select a place in the board to put the token:</term>
	  <listitem><para>
		Letters from <keycap>Q</keycap> (1st position) to <keycap>Y</keycap> (6th position)
	  </para></listitem>
	</varlistentry>
	<varlistentry>
	  <term>To evaluate the guess/close the solution window:</term>
	  <listitem><para>
		<keycap>Spacebar</keycap>
	  </para></listitem>
	</varlistentry>
</variablelist>
	Anyway, you can see and change these bindings in the <link linkend="prefs"><interface>Preferences Dialog</interface></link>.
</para>
    </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>File</guimenu></term>
	  <listitem>
	    <para>
	       This menu contains:
	       <itemizedlist>
		<listitem>
		  <para>
	            <menuchoice>
		      <guimenuitem>New Game</guimenuitem>
		     </menuchoice>
	             &mdash; This starts a new game. 
	           </para>
		</listitem>
                <listitem>
		  <para>
	             <menuchoice>
		      <guimenuitem>Save and Exit</guimenuitem>
		    </menuchoice>
	            &mdash; This saves the current game and exit. Next time you run <application>GnomerMind</application> you will continue the old game, if you don't choose otherwise with a commandline switch.
	          </para>
		</listitem>
		<listitem>
		  <para>
	             <menuchoice>
		      <guimenuitem>Exit</guimenuitem>
		    </menuchoice>
	            &mdash; This quits the game.
	          </para>
		</listitem>
	       </itemizedlist>
              </para>
	     </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><guimenu>Game</guimenu></term>
	  <listitem>
	    <para>
	   This menu contains:
	   <itemizedlist>
		<listitem>
		  <para>
	            <menuchoice>
		      <guimenuitem>Restart Game</guimenuitem>
		    </menuchoice>
	            &mdash; This restarts the current game. 
	          </para>
		</listitem>
		<listitem>
		  <para>
	            <menuchoice>
		      <guimenuitem>End Game</guimenuitem>
		    </menuchoice>
	            &mdash; This closes the current game and show you the solution. You will lose! 
	          </para>
		</listitem>
		<listitem>
		  <para>
	           <menuchoice>
		      <guimenuitem>Preferences</guimenuitem>
		    </menuchoice>
	            &mdash; This opens the <link linkend="prefs"><interface>Preferences Dialog</interface></link>,
			    which allows you to configure many settings. 
	          </para>
                </listitem>
            </itemizedlist>
	      </para>
	   </listitem>
	</varlistentry>
	
	<varlistentry>
	  <term><guimenu>Help</guimenu></term>
	  <listitem>
	    <para>
	      This menu contains:
	       <itemizedlist>
		<listitem>
		  <para>
	             <guimenuitem>Gnomermind</guimenuitem> &mdash; This
    	              opens the <application>GNOME Help
    	              Browser</application> and displays this manual.
	          </para>
		</listitem>
		
		<listitem>
		  <para>
	            <guimenuitem>About</guimenuitem> &mdash; This
    	            opens the <interface>About</interface> dialog
    	            which shows basic informations about
    	            <application>GnomerMind</application>, such as
    	            the author's name, the application version number,
    	            and the URL for the application's Web page. 
	          </para>
		</listitem>
		<listitem>
		  <para>
	            <guimenuitem>About theme</guimenuitem> &mdash; This
    	            opens another <interface>About</interface> dialog
    	            which shows informations about the current theme.
	          </para>
		</listitem>
	      </itemizedlist>
            </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </sect2>
  </sect1>

 <sect1>
  <title>Customization</title>
<sect2 id="prefs">
<title>The Preferences Dialog</title>
<para>
   To change the application settings, select
   <menuchoice>
    <guimenu>Game</guimenu>
    <guimenuitem>Preferences...</guimenuitem>
   </menuchoice>.  This opens the
   <interface>Preferences</interface> dialog.
  </para>

  <para>
   The properties in the <guilabel>Game settings</guilabel> tab are:
   
      <variablelist>
	<varlistentry>
	  <term> <guilabel>Tokens to guess</guilabel></term>
	  <listitem>
	    <para>
              Select how many tokens you have to guess. Of course, 
	      the more tokens, the more difficult.
            </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term> <guilabel>Token range extension</guilabel></term>
	  <listitem>
	    <para>
             Select how many different tokens you can choose from. Here
	     again, the more tokens, the more difficult. 
             </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><guilabel>Rounds available/visible</guilabel></term>
	  <listitem>
	    <para>
             Select how how many guesses you can do. The more guesses, the easier. In the case you've chosen the <guilabel>Play on infinite rounds</guilabel> option, below, it will specify how many rounds you can see.
             </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><guilabel>Play on infinite rounds</guilabel></term>
	  <listitem>
	    <para>
                Select it if you want to have endless rounds; you won't ever lose.
             </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><guilabel>Estimated difficulty level</guilabel></term>
	  <listitem>
	    <para>
             This is a rough estimation of the difficulty, in percentage. 
             </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </para>

    <para>
     The properties in the <guilabel>Advanced</guilabel> tab are:
       <variablelist>
	<varlistentry>
	  <term><guilabel>Allow repetitions in the row to guess</guilabel></term>
	  <listitem>
	    <para>
                This tells the hidden-row generator to allow repetitions. If unchecked, each token in the pattern to guess will be different from the others. This makes the game a little bit easier; of course, you can't uncheck it if there are less token types than token to guess.
             </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><guilabel>Allow to leave blank places in guessings</guilabel></term>
	  <listitem>
	    <para>
                If this is set, you will be able to leave some empty place in the row you're building, and make it evaluated all the same. This makes the game much easier, because you'll be able to verify the very position of groups of tokens, and modify your strategy accordingly.
             </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><guilabel>Estimated difficulty level</guilabel></term>
	  <listitem>
	    <para>
             Again, the same estimation of the difficulty. 
             </para>
	  </listitem>
	</varlistentry>
       </variablelist>
    </para>

    <para>
     The properties in the <guilabel>Controls</guilabel> tab are:
       <variablelist>
	<varlistentry>
	  <term><guilabel>Drop the token after each move</guilabel></term>
	  <listitem>
	    <para>
             If you set it off, you can place a token in a row more than once without having to select it from
	     the palette window each time. It's helpful if you notice you use to put the same token in a row two
             or three times in succession. 
             </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><guilabel>Activate the confirmation dialogs</guilabel></term>
	  <listitem>
	    <para>
              If you set it on and you change any settings in the preferences, or reset the game in any way, you will be asked whether you really want to apply those changes. You can safely set it off, if you get annoyed of that.
             </para>
	  </listitem>
	</varlistentry>
        <varlistentry>
	  <term><guilabel>Activate sounds</guilabel></term>
	  <listitem>
	    <para>
	      This turns on and off sounds. 
	    </para>
	  </listitem>
	</varlistentry>	
        <varlistentry>
          <term> <guilabel>Command</guilabel></term>
	  <listitem>
            <para>
	       If you want to play using the keyboard, here you can customize the key-bindings. Choose from the command list the command
               you want to bind a key to. When you have done, you can see the actual key-binding below the 
	       <guilabel>Key</guilabel> label. If you want to change it, just click on <guibutton>Set
	       </guibutton> and strike your favorite key. Note that you can not bind the same key to two 
               commands. Commands include picking a token (<guilabel>Token #n</guilabel>), putting a 
               token in a hole (<guilabel>Position #n</guilabel>) and evaluating a guess (<guilabel>Action
               </guilabel>). 
	     </para>
           </listitem>
	 </varlistentry>       
      </variablelist>
    </para>

  <para>
  There is only one property in the <guilabel>Themes</guilabel> tab:
    <variablelist>
     <varlistentry>
	<term><guilabel>Switch to theme</guilabel></term>
	<listitem>
	  <para>
	  Select the theme you prefer from the list. It shows you all the currently installed themes. The game will not restart.
          </para>
        </listitem>
     </varlistentry>
    </variablelist>
   </para>

  <para>
    After you have made all the changes you want, click on
    <guibutton>OK</guibutton> to apply the changes and close the
    <interface>Properties</interface> dialog. To cancel the changes
    and return to previous values, click the
    <guibutton>Cancel</guibutton> button. If you want to save the current updated changes as defaults,
    so that they apply any time you play GnomerMind again, just click on <guibutton>Make default</guibutton>.
  </para>
<note>
<para>
Please notice that the settings that are saved as defaults are the ones that currently appear in the <interface>Properties</interface> dialog, not the ones of the game you're playing. This means that you can play a game, enter the <interface>Properties</interface> dialog, then modify the parameters and save them; now, you can select the <guibutton>Cancel</guibutton> button and return to your previous game...
</para>
</note>
</sect2>
<sect2>
    <title>Commandline arguments</title>
<para>
You can specify some parameters on the <application>GnomerMind</application> commandline. In addition to the usual ones there are few others, which are often the correspondant of the <link linkend="prefs"><interface>Preferences dialog</interface></link> items. They are:
</para>
<itemizedlist>
<listitem>
<para>
<command>--help</command> &mdash; Displays an help for commandline arguments (as usual);
</para>
</listitem>
<listitem>
<para>
<command>-p</command>#n or <command>--places</command>=#n &mdash; Specifies how many tokens are there in a row to guess;
</para>
</listitem>
<listitem>
<para>
<command>-c</command>#n or <command>--colours</command>=#n &mdash; Specifies how many different tokens you have to choose among;
</para>
</listitem>
<listitem>
<para>
<command>-r</command>#n or <command>--rounds</command>=#n &mdash; Specifies how many rounds are available to guess the hidden row, or how many are visible if they are infinite (see below);
</para>
</listitem>
<listitem>
<para>
<command>-i</command>&lt;<command>y</command>/<command>n</command>&gt; or <command>--infinite</command>=&lt;<command>y</command>/<command>n</command>&gt; &mdash; Play on infinite rounds (valid options are <command>y</command>, <command>n</command>, <command>yes</command>, <command>no</command>, and their uppercase variations);
</para>
</listitem>
<listitem>
<para>
<command>-d</command>&lt;<command>y</command>/<command>n</command>&gt; or <command>--repetitions</command>=&lt;<command>y</command>/<command>n</command>&gt; &mdash; Allow repetitions in the field to guess; if your choice is incoherent with the othervalues, it will be ignored and you'll be warned (valid options are <command>y</command>, <command>n</command>, <command>yes</command>, <command>no</command>, and their uppercase variations);
</para>
</listitem>
<listitem>
<para>
<command>-b</command>&lt;<command>y</command>/<command>n</command>&gt; or <command>--blank-places</command>=&lt;<command>y</command>/<command>n</command>&gt; &mdash; Allow player to leave to leave some empty place in the row he's building, and make it evaluated all the same (valid options are <command>y</command>, <command>n</command>, <command>yes</command>, <command>no</command>, and their uppercase variations);
</para>
</listitem>
<listitem>
<para>
<command>--theme</command>=&lt;theme&gt; &mdash; Chooses the theme to use: this could be either the name of an installed theme, or the (absolute or relative) path to the directory where a theme is stored;
</para>
</listitem>
<listitem>
<para>
<command>--override</command> &mdash; If last time you exited choosing the <guimenuitem>Save and exit</guimenuitem> menu item, it overrides the loading of the saved game, which will be restored next time;
</para>
</listitem>
<listitem>
<para>
<command>--drop</command>=&lt;<command>y</command>/<command>n</command>&gt; &mdash; Chooses whether to drop the piece after each move or not (valid options are <command>y</command>, <command>n</command>, <command>yes</command>, <command>no</command>, and their uppercase variations);
</para>
</listitem>
<listitem>
<para>
<command>--confirmations</command>=&lt;<command>y</command>/<command>n</command>&gt; &mdash; Chooses whether to display the confirmation dialogs or not (valid options are <command>y</command>, <command>n</command>, <command>yes</command>, <command>no</command>, and their uppercase variations);
</para>
</listitem>
<listitem>
<para>
<command>--geometry</command>=<command>GEOMETRY</command> &mdash; It's the standard geometry argument of all the <application>X</application> applications; for now, it works partially (only for the offsets), and only for the game board window. For valid argument strings, see the <filename>X(1)</filename> manpage.
</para>
</listitem>
</itemizedlist>
</sect2>

 </sect1>

 <sect1 id="bugs">
  <title>Known Bugs and Limitations</title>
       <variablelist>
	<varlistentry>
	  <term>Gnomermind 0.7.8 &amp; GnomerMind 0.7.9</term>
	  <listitem>
	    <para>
		The name of the default theme is changed from 0.7.8 to 0.7.9; if you want to switch back, you possibly won't be able to start the game, because the game will search for the new theme name. If this happens, just delete the file <filename>~/.gnome/gnomermind</filename>, and it all will work fine.
            </para>
	    <para>
		Also passing from 0.7.8 to 0.7.9 will give problems; this bug is really corrected only in 0.9.0... :(
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>Gnomermind 0.7.8 cheat</term>
	  <listitem>
	    <para>
		There are many little bugs in <application>GnomerMind</application> 0.7.8; perhaps the most interesting one is a little trick that can be used to cheat in the game. Choose <menuchoice> <guimenu>Game</guimenu><guimenuitem>End game</guimenuitem></menuchoice> ; look at the solution, then select <menuchoice><guimenu>Game</guimenu><guimenuitem>Restart game</guimenuitem></menuchoice>. You will be playing the very same game of wich you already know the solution!! :) This is fixed in 0.7.9.
            </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>GLib/GTK+ &gt; 1.2.9 &amp; GnomerMind &lt; 0.7.0</term>
	  <listitem>
	    <para>
		Version 1.2.9 of <application>GLib</application> and <application>GTK+</application> adopt a different install path; <application>Gnomermind</application> 0.7.0 and earlier versions don't check for it, and fail to compile. The bug is fixed in 0.7.1 and later.
            </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>IceWM &lt; 1.0.6 &amp; GnomerMind &lt; 0.6.0</term>
	  <listitem>
	    <para>
		Using version 1.0.6 of <application>IceWM</application> and version 0.6.0 of <application>GnomerMind</application> (and probably also earlier versions of both), if the user modifies a parameter of the game that would make the game restart (redrawing the board), the window manager will crash. It's a bug of <application>IceWM</application>, actually; a workaround is present from version 0.6.1 of <application>GnomerMind</application>, and the bug is definitively solved in later versions of <application>IceWM</application>. 
            </para>
	  </listitem>
	</varlistentry>
       </variablelist>
 </sect1>

 <sect1>
 <title>Building themes</title>
<sect2>
<title>Basics</title>
 <para>
Building themes is a trivial matter. You may be discouraged by the several files you see in a theme directory, but it's just a question of fantasy and skill in drawing. An ideal application to use is <application>GIMP</application>, and creating a theme doesn't takes more then an hour, from the idea to the installation... :)
 </para>
 <para>
The game field is composed by several elements: a background (the game board itself), the tokens, the hint pins and the control icons. You must provide one or more pixmaps for each element, plus the masks that allow the program to cut out the elements in the desired shape. Infact, the tokens, the pins and the control icons aren't all square, nor have the same dimensions: this way, the graphics are much more flexible, and you can decide the position of the single pins, for example, or the token clickable area shape... for istance, in the Classic theme the tokens are round, and you can activate them by clicking on the very shape; this is allowed by the masks... notice also that the hint pins are differently positioned in the different themes; this is because you can put them just wherever you want! :))
</para>
<para>
Moreover, you must provide an <filename>ABOUT</filename> file with the infos on your theme.
</para>
</sect2>
<sect2>
<title>The background</title>
<para>
The background is actually composed by nine files; the main tile and the margins.
</para>
<para>
 The main tile is the background for just everything in the game; it must be square, and of the same size of all the other elements that will lie upon it.
</para>
<para> The margins are the elements surrounding the board, that will be the margin of it; e.g. in the Classic theme, the tile is the wood pattern, while the margins are the beveled borders. There are 8 of them, for upper margin, lower margin, left and right ones, and for the four corners. They are the only elements that can differ in dimension from the tile: infact, they have a 'margin width' and must adapt to it. So the upper margin will be as wide as the tile, while its height must be the margin width; the left margin will have the same height of the tile, and the width equal to the margin width; the corners will be square, with side dimension equal to the margin width, and so on.
</para>
<note>
<para> Please ensure that the tile and the margins connect seamlessly, and the margin with each other: the top margin can be flanked by another one, so it must graphically connect to it, and so on. An example is better than thousand words: please look at the files that are in the theme directories.
</para>
</note>
<sect3>
<title>Files</title>
<para>
The files must be PNG, any depth, the following are their names, and the dimensions they must have (we will call BASE the tile side length, and EXT the margin width):
</para>
<itemizedlist>
<listitem>
<para>
<filename>tile.png</filename> &mdash; the main tile (BASExBASE);
</para>
</listitem>
<listitem>
<para>
<filename>ul.png</filename> &mdash; upper-left corner (EXTxEXT);
</para>
</listitem>
<listitem>
<para>
<filename>u.png</filename> &mdash; upper margin (BASExEXT);
</para>
</listitem>
<listitem>
<para>
<filename>ur.png</filename> &mdash; upper-right corner (EXTxEXT);
</para>
</listitem>
<listitem>
<para>
<filename>r.png</filename> &mdash; right margin (EXTxBASE);
</para>
</listitem>
<listitem>
<para>
<filename>br.png</filename> &mdash; bottom-right corner (EXTxEXT);
</para>
</listitem>
<listitem>
<para>
<filename>b.png</filename> &mdash; lower margin (BASExEXT);
</para>
</listitem>
<listitem>
<para>
<filename>bl.png</filename> &mdash; bottom-left corner (EXTxEXT);
</para>
</listitem>
<listitem>
<para>
<filename>l.png</filename> &mdash; left margin (EXTxBASE).
</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2>
<title>Tokens</title>
<para>
You must provide ten different pixmaps for the tokens, plus the pixmap for the token hole. They must be painted on a square with the same dimensions as the background tile. So, from now on, all the pixmaps must be BASExBASE; I won't specify it anymore. Moreover, you must provide a common mask for them all; this mask will specify the visible (and clickable) part of every pixmap. So, you won't need to draw all the square; you can draw your token, and paint the invisible parts in an uniform colour.
</para>
<para>
Again, please look at the themes for examples. You'd better make tokens that can be easily distinguished, contrasting very well with the background tile and with each other. It's quite difficult with colours, to make ten of them, but with shapes or patterns it's just trivial. 
</para>
<para>
All the masks are stored in the alpha channel of a BASExBASE PNG pixmap. I use a 2-colours pixmap, painted all black (or white), with the alpha channel transparent where I want to hide the token tile.
</para>
<note>
<para>
If you don't need a pixmap, and just want the token image to overdraw the tile, you must still provide a pixmap, but you can make it without the alpha channel - just make a 1-bpp black PNG, for instance.
</para>
</note>
<sect3>
<title>Files</title>
<para>
Again, the files must be PNG, any depth:
</para>
<itemizedlist>
<listitem>
<para>
<filename>tokh.png</filename> &mdash; the pixmap for the token hole;
</para>
</listitem>
<listitem>
<para>
<filename>tok0.png &mdash; tok9.png</filename> &mdash; the pixmaps for the 10 tokens;
</para>
</listitem>
<listitem>
<para>
<filename>mtok.png</filename> &mdash; the token mask.
</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2>
<title>The hint pins</title>
<para>
You must provide three sets of six pins each. These are, one set for the 'correctly guessed' pins, one set for the 'misplaced' ones, and one set for the holes. These sets will be painted each on a tile; so for each tile there will be 6 pins. In addition, you must provide six masks to cut out the single pins.
</para>
<para>
No need to say that this sounds complicate... but it's easy. Just draw the three sets the same way, so that the same pin is in the same place; in other words, the three sets must be sovrapponible. Then make the masks, with the same rules as the one for the tokens (alpha channel, etc.), all trasparents but in correspondance of the pin you want to mask. Look at the themes... :)
</para>
<sect3>
<title>Files</title>
<itemizedlist>
<listitem>
<para>
<filename>pin0.png</filename> &mdash; the pixmap for the pin holes set;
</para>
</listitem>
<listitem>
<para>
<filename>pin1.png</filename> &mdash; the pixmap for the 'misplaced' pins set;
</para>
</listitem>
<listitem>
<para>
<filename>pin2.png</filename> &mdash; the pixmap for the 'correct' pins set;
</para>
</listitem>
<listitem>
<para>
<filename>mpin0.png &mdash; mpin5.png</filename> &mdash; the masks for each pin.
</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2>
<title>The control icons</title>
<para>
You must provide four control icons, one for each state: wait &mdash; when the program waits for the player to complete a row; ready &mdash; when a row is complete, and the player can evaluate it; failure and success &mdash; for, well, failure and success! :) Moreover, these will be masked by another mask. Just as ever.
</para>
<sect3>
<title>Files</title>
<itemizedlist>
<listitem>
<para>
<filename>stt0.png</filename> &mdash; the icon for the waiting state;
</para>
</listitem>
<listitem>
<para>
<filename>stt1.png</filename> &mdash; the icon for the ready state;
</para>
</listitem>
<listitem>
<para>
<filename>stt2.png</filename> &mdash; the icon for failure;
</para>
</listitem
<listitem>
<para>
<filename>stt3.png</filename> &mdash; the icon for success;
</para>
</listitem>
<listitem>
<para>
<filename>mstt.png</filename> &mdash; the mask for these icons.
</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2>
<title>The ABOUT file</title>
<para>
This is simply an ASCII file containing some fields. They are separated by the string "<command>&lt;&mdash;&mdash;&gt;</command>", and may contain line breaks. The fields are:
</para>
       <variablelist>
	<varlistentry>
	  <term>1st field: Theme version</term>
	  <listitem>
	    <para>
		The release version. Please, for uniformity, start from 0.1 and go on.
            </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>2nd field: Copyright notice</term>
	  <listitem>
	    <para>
		The copyright notice for the current theme. There must be only one, so, it's for you. Please include any other notice (like the copyright for the images you eventually copied) in the notes, below. Also, please use the (c) form for copyright, not the "<command>&copy;</command>" character, since some users with particular character sets may not be able to display it.
            </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>3rd field: Author</term>
	  <listitem>
	    <para>
		Your name, and your email written between "<command>&lt; &gt;</command>".
            </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>4th field: Theme notes</term>
	  <listitem>
	    <para>
		Anything else you want to say. History. Comments. Greetings. Fables... anything. Just write in english, and again, don't include 'strange' characters.
            </para>
	  </listitem>
	</varlistentry>
       </variablelist>
<para>
<warning>
<para>
If there's something wrong in the ABOUT file, when you'll select the <guimenuitem>About theme</guimenuitem> menu item, the dialog won't appear, and a message will show in the terminal window; of course this will happen only if you'll start the program from there. Obviously, the program can't check if all the fields make sense; it will only check if there is the right number of them. The rest is up to you. After having built a theme, select the <guimenuitem>About theme</guimenuitem> dialog and ensure all is OK.
</para>
</warning>
</para>
<sect3>
<title>Files</title>
<itemizedlist>
<listitem>
<para>
<filename>ABOUT</filename> &mdash; the file described above.
</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
<sect2>
<title>Final details</title>
<note>
<para>
A good theme should be around 30-40 kb. Please consider that each pixmap is stored in memory, and the larger are the BASE/EXT dimensions, the more memory they occupy... Moreover, if you make too large pixmaps, the game won't probably fit on the player screen, if they use lower resolutions.
</para>
</note>
<para>
When you have finished, to control everything's fine, just run:
</para>
<para>
<command>gnomermind --theme=&lt;your theme dir full path&gt;</command>
</para>
<para>
If it displays with the new theme, compliments! You've done it! :)) If not, you have made an error; since you have started the program from commandline, it should have warned you on the type of it.
</para>
<warning>
<para>
Please notice that you could get confused in interpreting the error message: infact, the game will take the dimensions of <filename>l.png</filename> as the base for evaluating the other pixmaps; so if the dimensions of this one are wrong, it will report an error on the other ones, not on that...
</para>
</warning>
<important>
<title>Share your theme!</title>
<para>
If you think your theme is really nice (if not, why did you make it? ;), please send it to us, referring to <email>mano78@users.sourceforge.net</email>, and it will be included in the site! :)
</para>
</important>
</sect2>
 </sect1>

 <sect1 id="authors">
  <title>Authors</title>
  <para>
   <application>GnomerMind</application> was written by Germano Rizzo
   <email>mano78@users.sourceforge.net</email>. To find more information about
   <application>GnomerMind</application>, please visit the <ulink
   url="http://gnomermind.sourceforge.net" type="http">GnomerMind Web
   page</ulink>.  Please send all comments, suggestions, and bug
   reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
   bug tracking database</ulink>.  (Instructions for submitting bug
   reports can be found <ulink
   url="http://bugs.gnome.org/Reporting.html" type="http">
   on-line</ulink>.)  You can also use <application>Bug Report
   Tool</application> (<command>bug-buddy</command>), available in the
   <guisubmenu>Utilities</guisubmenu> sub-menu of <guimenu>Main
   Menu</guimenu>, for submitting bug reports.
  </para>

  <para>
   This manual was written by Marco Cova 
   <email>mcova@users.sourceforge.org</email>. Please send all comments and
   suggestions regarding this manual to the <ulink type="http"
   url="http://developer.gnome.org/projects/gdp">GNOME Documentation
   Project</ulink> by sending an email to
   <email>docs@gnome.org</email>. You can also add your comments
   online by using the <ulink type="http"
   url="http://developer.gnome.org/projects/gdp/doctable/">GNOME
   Documentation Status Table</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>

 <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  <ulink type="help" url="gnome-help:gpl">
    <citetitle>GNU General Public License</citetitle></ulink> 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>59 Temple Place</street> - Suite 330
    <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
    <country>USA</country>
   </address>
  </para>
 </sect1>
</article>
