<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
<!ENTITY version "1.4.2">
<!-- replace version above with actual application version number-->
<!--  Template Version: 1.0.1  (do not remove this line) -->
]>


<!-- ===== DOCUMENT HEADER ===== -->

<article id="index"> <!-- please do not change the id -->

<artheader>
  <title>Gnect</title>
  <copyright>
    <year>2001</year>
    <holder>Timothy Musson</holder>
  </copyright>

<!-- translators: uncomment this:

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

-->

  <legalnotice>
    <para>
      Permission is granted to copy, distribute and/or modify this
      document under the terms of the <citetitle>GNU Free
      Documentation License</citetitle>, 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. You may obtain a copy of the <citetitle>GNU Free
      Documentation 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: Free Software Foundation, Inc., 59 Temple Place - Suite
      330, Boston, MA 02111-1307, USA.
    </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 1.0 of the Gnect manual.
  </releaseinfo>

</artheader>



<!-- ===== INTRODUCTION ===== -->

<sect1 id="intro">

  <title>Introduction</title>

  <para>
    <application>Gnect</application> is a "Four In A Row" game for GNOME.
    The object of the game is to build a line of four of your counters while
    trying to stop your opponent (human or computer) building a line of his
    or her own. A line can be horizontal, vertical or diagonal.
  </para>

  <para>
    <application>Gnect</application> has two computer-driven players.
    One's very simple - it's included to provide a fun opponent for
    young children. The other is driven by Giuliano Bertoletti's Velena
    Engine. The Velena Engine takes a much more sophisticated approach;
    its strongest level is unbeatable if it makes the first move.
  </para>

  <para>
    To run <application>Gnect</application>, select
    <menuchoice>
      <guisubmenu>Games</guisubmenu>
      <guimenuitem>Gnect</guimenuitem>
    </menuchoice>
    from the <guimenu>Main Menu</guimenu>, or type
    <command>gnect</command> on the command line.
  </para>

  <para>
    <application>Gnect</application> is included in the
    <filename>gnome-games</filename> package, which is part of the
    GNOME desktop environment.
    This document describes version &version; of <application>Gnect</application>.
  </para>

</sect1>


<!-- ===== USAGE ===== -->

<sect1 id="usage">

  <title>Using Gnect</title>

  <sect2 id="mainwin">

    <title>Basic usage</title>

    <para>
      Once you've started <application>Gnect</application>, select
      <menuchoice>
        <guisubmenu>Game</guisubmenu>
        <guisubmenu>New game</guisubmenu>
      </menuchoice>
      to begin playing.
    </para>

    <para>
      The game display consists of seven columns and seven rows. The top row
      is only used to show the current player's cursor, so the actual playing
      area measures seven by six cells. To make a move, just move your pointer
      over the column you'd like to drop a counter into and select that
      column (for most people, that'll be a left-click). If you'd rather play
      by keyboard, keys can be assigned using the
      <link linkend="prefs"><interface>Preferences Dialog</interface></link>.
    </para>

  </sect2>


  <!-- ===== TOOLBAR ===== -->

  <sect2 id="toolbar">

    <title>Toolbar</title>

    <para>
      The toolbar, which can be toggled on or off from the <guisubmenu>Settings
      Menu</guisubmenu>, contains the following buttons:

      <variablelist>

        <varlistentry>
          <term>New</term>
          <listitem>
            <para>
              This resets the board and starts a new game.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Undo</term>
          <listitem>
            <para>
              If you're playing against a friend, this will undo one move.
              If you're playing against the computer, this will undo the
              computer's last move and then yours. Repeating this will return
              the board to its initial state.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>Hint</term>
          <listitem>
            <para>
              This'll tell you the best move you can make, in the form of a column
              number. Columns are numbered from left to right, with 1 being the
              leftmost column.
            </para>
          </listitem>
        </varlistentry>
<!--
        <varlistentry>
          <term>Scores</term>
          <listitem>
            <para>
              This opens a small window containing the number of wins
              each player has had. The number of drawn games is also shown.
            </para>
          </listitem>
        </varlistentry>
-->
        <varlistentry>
          <term>Exit</term>
          <listitem>
            <para>
              This quits the game.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

    </para>

  </sect2>


  <!-- ===== MENUS ===== -->


  <sect2 id="menubar">

    <title>Menus</title>

    <para>
      The menu bar, located at the top of the game window, contains the
      following menus:
    </para>

    <variablelist>


      <!-- ===== GAME MENU ===== -->


      <varlistentry>
        <term><guimenu>Game</guimenu></term>
        <listitem>
          <para>
            This menu contains:
            <itemizedlist>

              <listitem>
                <para>
                  <menuchoice>
                    <shortcut>
                      <keycombo><keycap>Ctrl</keycap><keycap>N</keycap></keycombo>
                    </shortcut>
                    <guimenuitem>New game</guimenuitem>
                  </menuchoice>
                  &mdash;
                  This resets the board and starts a new game.
                </para>
              </listitem>

              <listitem>
                <para>
                  <menuchoice>
                    <shortcut>
                      <keycombo><keycap>Ctrl</keycap><keycap>Z</keycap></keycombo>
                    </shortcut>
                    <guimenuitem>Undo move</guimenuitem>
                  </menuchoice>
                  &mdash;
                  If you're playing against a friend, this will undo one move.
                  If you're playing against the computer, this will undo the
                  computer's last move and then yours. Repeating this will
                  return the board to its initial state.
                </para>
              </listitem>

              <listitem>
                <para>
                  <menuchoice>
                    <guimenuitem>Hint</guimenuitem>
                  </menuchoice>
                  &mdash;
                  This'll tell you the best move you can make, in the form of a column
                  number. Columns are numbered from left to right, with 1 being the
                  leftmost column.
                </para>
              </listitem>

              <listitem>
                <para>
                  <menuchoice>
                    <guimenuitem>Scores&hellip;</guimenuitem>
                  </menuchoice>
                  &mdash;
                  This opens a small window containing the number of wins each player
                  has had. The number of drawn games is also shown.
                </para>
              </listitem>

              <listitem>
                <para>
                  <menuchoice>
                    <shortcut>
                      <keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo>
                    </shortcut>
                    <guimenuitem>Exit</guimenuitem>
                  </menuchoice>
                  &mdash;
                  This quits the game.
                </para>
              </listitem>

            </itemizedlist>
          </para>

        </listitem>
      </varlistentry>


      <!-- ===== SETTINGS MENU ===== -->


      <varlistentry>
        <term><guimenu>Settings</guimenu></term>
        <listitem>
          <para>
            This menu contains:
            <itemizedlist>

              <listitem>
                <para>
                  <guimenuitem>Show toolbar</guimenuitem>
                  &mdash;
                  This toggle switches the toolbar on and off.
                </para>
              </listitem>

              <listitem>
                <para>
                  <guimenuitem>Enable sound</guimenuitem>
                  &mdash;
                  This toggle switches the game's sound effects on and off.
                </para>
              </listitem>

              <listitem>
                <para>
                  <guimenuitem>Draw grid</guimenuitem>
                  &mdash;
                  This toggles the display of a grid over the game board.
                  Some themes will disable the grid themselves if they don't need it
                  (...that is, if they already have something like a grid in their
                  tile sets or background images). So don't be surprised if this
                  option doesn't always have an effect.
                </para>
              </listitem>

              <listitem>
                <para>
                  <guimenuitem>Preferences&hellip;</guimenuitem>
                  &mdash;
                  This opens the <link linkend="prefs"><interface>Preferences
                  Dialog</interface></link>, which allows you to configure the
                  game.
                </para>
              </listitem>

            </itemizedlist>
          </para>
        </listitem>
      </varlistentry>


      <!-- ===== HELP MENU ===== -->


      <varlistentry>
        <term><guimenu>Help</guimenu></term>
        <listitem>
          <para>
            This menu contains:
            <itemizedlist>

              <listitem>
                <para>
                  <guimenuitem>Manual</guimenuitem>
                  &mdash;
                  This item opens a browser and displays this manual.
                </para>
              </listitem>

              <listitem>
                <para>
                  <guimenuitem>About</guimenuitem>
                  &mdash;
                  This opens the <interface>About</interface> dialog
                  which shows basic information about
                  <application>Gnect</application>, such as the names
                  of its authors, the program's version number, and the
                  URL for the program's Web page.
                </para>
              </listitem>

            </itemizedlist>
          </para>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>



<!-- ===== CUSTOMIZATION ===== -->

<sect1 id="prefs">

  <title>Customization</title>

  <sect2 id="prefsdialog">

    <title>Preferences</title>

    <para>
      To change the game's settings, select
      <menuchoice>
        <guimenu>Settings</guimenu>
        <guimenuitem>Preferences...</guimenuitem>
      </menuchoice>.
      This opens the <interface>Preferences</interface> dialog.
    </para>

    <para>
      The properties in the <guilabel>Player Selection</guilabel> tab are:

      <variablelist>

        <varlistentry>
          <term>
            <guilabel>Player 1</guilabel> and
            <guilabel>Player 2</guilabel>
          </term>
          <listitem>
            <para>
              These options tell <application>Gnect</application> who's
              playing. To play against a friend, select Human for both
              Player 1 and Player 2. (Note that changing players will end
              a game in progress and reset the scores.)
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>
            <guilabel>Who starts?</guilabel>
          </term>
          <listitem>
            <para>
              These options let you select which player starts when a
              new game begins.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>
    </para>

    <para>
      The properties in the <guilabel>Appearance and Behaviour</guilabel> tab are:

      <variablelist>

        <varlistentry>
          <term><guilabel>Theme selection</guilabel></term>
          <listitem>
            <para>
              The theme menu lists available themes and lets
              you choose between them.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><guilabel>Keyboard control</guilabel></term>
          <listitem>
            <para>
              These options let you arrange keyboard play to your liking.
              Select the entry box of the action you'd like to change,
              then press the key you'd like to perform that action.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><guilabel>Animation</guilabel></term>
          <listitem>
            <para>
              Here you can toggle all animation on or off, or just enable or
              disable the wipe effects between games.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><guilabel>Sound type</guilabel></term>
          <listitem>
            <para>
              <application>Gnect</application> can make sounds when certain
              events occur. If you choose the Speaker beep option,
              <application>Gnect</application> will beep when a game ends or
              if you make an illegal move. If you choose the GNOME sound option,
              <application>Gnect</application> will play the audio files you
              specify using the <application>GNOME Control Center</application>.
              To disable sound altogether, use the sound toggle in the
              <guimenu>Settings</guimenu> menu.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><guilabel>If stopping an unfinished game: Ask me first</guilabel></term>
          <listitem>
            <para>
              If this option is selected, the program will ask you before quitting
              or starting a new game while there's a still game in progress.
            </para>
          </listitem>
        </varlistentry>


      </variablelist>
    </para>

    <para>
      To check your changes without closing the <interface>Preferences</interface>
      dialog, use the <guibutton>Apply</guibutton> button. Once you've made all
      the changes you want, select <guibutton>OK</guibutton>.
    </para>

  </sect2>

  <sect2 id="themes">

    <title>Custom Themes</title>

    <para>
      This section's included in case you'd like to make your own themes for
      <application>Gnect</application>. It assumes you're familiar with basic
      text editing, graphics software and the command line.
    </para>

    <sect3 id="images">

      <title>Images</title>

      <para>
        <application>Gnect</application>'s tilesets contain six tiles of
        equal size, lined up horizontally. From left to right:
      </para>

      <orderedlist>
        <listitem>
          <para>Player One's counter as it'll appear on the main board</para>
        </listitem>
        <listitem>
          <para>Player Two's counter as it'll appear on the main board</para>
        </listitem>
        <listitem>
          <para>Main board background</para>
        </listitem>
        <listitem>
          <para>Top row background</para>
        </listitem>
        <listitem>
          <para>Player One's counter as it'll appear on the top row</para>
        </listitem>
        <listitem>
          <para>Player Two's counter as it'll appear on the top row</para>
        </listitem>
      </orderedlist>

      <figure id="shot1">
        <title>An example tileset</title>
        <screenshot>
          <screeninfo>This image shows the six tiles in a tileset</screeninfo>
          <graphic format="PNG" fileref="figures/tileset" srccredit="TRM"></graphic>
        </screenshot>
      </figure>

      <tip>
        <title>TIP</title>
        <para>
          PNG format is recommended for tilesets. They should usually
          contain transparency in tiles 1, 2, 5 and 6. Tiles 3 and 4
          should be solid, with no transparency, even if you'll be
          supplying a full window background image.
        </para>
      </tip>

      <para>
        <application>Gnect</application> automatically calculates the tile
        dimensions:
      </para>

<programlisting>
tile height = tileset height
tile width  = tileset width / 6
</programlisting>


      <para>
        That is, your tiles can be square or rectangular - and any size you
	    like. Most of the tilesets that come with
        <application>Gnect</application> use square tiles measuring either
        40x40 pixels ("small") or 50x50 ("large").
      </para>

      <para>
        So, what if you want a full-window background image, rather than
        repeating tiles 3 and 4 over the game board? For that, you'll need to
        make a separate image. Say each tile in your set measures 50 by 50
        pixels. The game board measures 7 by 7 tiles, including the top row,
        so the ideal background for your tileset measures 350 by 350 pixels.
        But if your background doesn't fit, <application>Gnect</application>
        will scale it for you.
      </para>

      <para>
        Before you can try your new tileset and background image, you'll need
        to create a theme file.
      </para>


    </sect3>

    <sect3 id="themefiles">

      <title>Theme Files</title>

      <para>
        Here's an example theme file, showing all possible keywords.
        Lines starting with a hash (#) are ignored. Note that values
        containing white space must be quoted.
      </para>


<programlisting>
#
# buttons_50x50.gnect (an example theme file)
#

# This theme's title (required)
Title = "Button Shop (large)"

# Tileset filename (required)
Tileset = tileset_50x50_buttonshop.png

# Full-window background image (optional)
Background = bg_buttonshop.jpg

# Description of player one's counter (required)
Player1 = Green

# Description of player two's counter (required)
Player2 = Yellow

# Grid colour (optional, defaults to RGB:52/5F/6C)
GridRGB = RGB:/FF/FF/FF

# Disable the grid for this theme (optional)
NoGrid

# Details (optional)
Tooltip = "artwork credits or whatever you like"
</programlisting>

    <para>
      Legal values for the <literal>Player1</literal> and
      <literal>Player2</literal> keywords are as follows:

      <!-- please don't translate this list: -->
      <literal>Light</literal>,
      <literal>Dark</literal>,
      <literal>Black</literal>,
      <literal>White</literal>,
      <literal>Grey</literal>,
      <literal>Yellow</literal>,
      <literal>Red</literal>,
      <literal>Blue</literal>,
      <literal>Green</literal>,
      <literal>Orange</literal>,
      <literal>Purple</literal>,
      <literal>Pink</literal>,
      <literal>Violet</literal>,
      <literal>Brown</literal>.
    <para>


    </sect3>

    <sect3 id="directories">

      <title>Putting it all together</title>

      <para>
        So, you've made a tileset, a theme file and maybe a background
        image. Now what?
      </para>

      <para>
        Make a <filename class="directory">~/.gnect</filename> directory,
        a <filename class="directory">~/.gnect/pixmaps</filename> directory
        and a <filename class="directory">~/.gnect/themes</filename> directory.
        Copy the image(s) into the pixmaps directory and the theme file into
        the themes directory. Make sure the theme file has
        <filename>.gnect</filename> as the suffix. Next time you start
        <application>Gnect</application>, you should find your new theme
        listed in the Preferences dialog. If not, try running
        <application>Gnect</application> from the command-line - if your theme is
        found, <application>Gnect</application> should display a message
        to let you know what the problem is.
      </para>


    </sect3>


  </sect2>


</sect1>



<!-- ===== BUGS ===== -->

<sect1 id="bugs">

  <title>Known Bugs and Limitations</title>

  <para>
    The latest plans and currently known bugs are listed the <ulink type="http"
    url="http://homepages.ihug.co.nz/~trmusson/stuff/gnect-todo.txt">online
    TODO file</ulink>.
  </para>

  <para>Known bugs in gnect-1.4.2:</para>

  <para>
    Occasionally a counter-dropping animation doesn't look as smooth as it
    should.
  </para>

  <para>
    Typing certain keys (eg., TAB and the cursor keys) into the Keyboard control
    boxes in Preferences changes the focus.
  </para>

  <para>If upgrading:</para>

  <para>
    Theme file format changed slightly between Gnect versions 1.2.1 and 1.2.2,
    so if you have any pre-1.2.2 themes hanging about you'll have to edit them,
    wrapping any values containing spaces with quote (") characters. For example:
  </para>

<programlisting>

Title = This theme's title

# ...becomes...

Title = "This theme's title"

</programlisting>

</sect1>



<!-- ===== AUTHORS ===== -->

<sect1 id="authors">

  <title>Authors</title>

  <para>
    <application>Gnect</application> was written by
    Timothy Musson (<email>trmusson@ihug.co.nz</email>) and
    David Neary (<email>dneary@eircom.net</email>).
    The Velena Engine was written by Giuliano Bertoletti.
    Giuliano has very kindly granted permission to include
    his Velena Engine with <application>Gnect</application> and
    distribute the result under the GPL.
  </para>

  <para>
    For more information about <application>Gnect</application>,
    please visit <ulink
      url="http://homepages.ihug.co.nz/~trmusson/gnect.html"
      type="http">Gnect's homepage</ulink>.
    To find out more about the Velena Engine, please visit <ulink
      url="http://www.ce.unipr.it/~gbe/velena.html"
      type="http">Velena's homepage</ulink>.
  </para>

  <para>
<!--
    Please send all comments, suggestions, and bug reports to
    Timothy Musson (<email>trmusson@ihug.co.nz</email>).
-->
    Please send all comments, suggestions, and bug
    reports to the <ulink
      url="http://bugzilla.gnome.org"
      type="http">GNOME bug tracking database</ulink>.

    You can also use <application>Bug Report Tool</application>
    (<command>bug-buddy</command>), available in the
    <guisubmenu>Utilities</guisubmenu> submenu of
    <guimenu>Main Menu</guimenu>, for submitting bug reports.

  </para>


  <para>
    This manual was written by Timothy Musson.
    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://www.gnome.org/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>



<!-- ===== 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>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>59 Temple Place</street> - Suite 330
      <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
      <country>USA</country>
    </address>
  </para>

</sect1>


</article>

