<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
  <!ENTITY kappname "&kbackgammon;">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
  
   
]>

<book lang="&language;">

<bookinfo>
<title>The &kbackgammon; Handbook</title>
    
<authorgroup>
<author>
<firstname>Jens</firstname>
<surname>Hoefkens</surname>
<affiliation><address><email>jens@hoefkens.com</email></address></affiliation>
</author>
      
<othercredit role="developer">
<firstname>Bo</firstname>
<surname>Thorsen</surname>
<affiliation><address><email>gobo@imada.sdu.dk</email></address></affiliation>
<contrib>Developer</contrib>
</othercredit>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->
    
<copyright>
<year>1999</year><year>2000</year>
<holder>Jens Hoefkens</holder>
</copyright>
    
<legalnotice>&FDLNotice;</legalnotice>
    
<date>2000-12-22</date>
<releaseinfo>1.96.01</releaseinfo>
    
<abstract>
<para>&kbackgammon; is a graphical backgammon program for &kde;. It
supports backgammon games with other players, games against computer
engines like &GNU; <application>bg</application> and even on-line games
on the <ulink url="http://www.fibs.com/">First Internet Backgammon
Server</ulink>.</para>
</abstract>
    
<keywordset>
<keyword>KDE</keyword>
<keyword>game</keyword>
<keyword>backgammon</keyword>
<keyword>FIBS</keyword>
<keyword>gnubg</keyword>
</keywordset>
    
</bookinfo>
  
  <chapter id="introduction">
    <title>Introduction</title>
    
    <para>&kbackgammon; is a graphical backgammon program. The
    objective of backgammon is to move your checkers off the board
    before your opponent does. While the rules of backgammon are
    moderately difficult (the most difficult part apparently being the
    initial positioning of the checkers), this document does not try
    to teach these rules: please refer to the Web, a book, or
    (probably best) a friend for this.</para>

    <para>&kbackgammon; offers you a graphical backgammon board that
    can be used almost entirely by using the mouse (although textual
    commands are also available and it should be possible to play
    backgammon without the mouse, too). Therefore, &kbackgammon; is
    easy to use and allows you to concentrate on the important aspects
    of playing backgammon.</para>

    <para>In order to play backgammon, you usually need an
    opponent. &kbackgammon; offers you to play against hundreds of
    different opponents of various strength on the <ulink
    url="http://www.fibs.com/">First Internet Backgammon
    Server</ulink>. If you prefer, you may also use the <link
    linkend="engine-offline">Offline Engine</link> which allows you to
    play against yorself or friends that are with you at your
    computer.</para>

    <para>In the near future &kbackgammon; will allow you to play
    against <link linkend="engine-gnubg">&GNU; Backgammon</link>,
    which is a powerful backgammon program that usually runs without a
    graphical frontend. It plays on <acronym>FIBS</acronym> with a
    rating of about 2000 (which is quite high).</para>

    <para>Additionally, plans are on the way that will allow games
    over the Internet between two &kbackgammon; programs (and their
    respective users). Finally, the architecture of &kbackgammon; is
    quite open and it is possible to include support for other
    engines easily (if you are interested in this, please contact the
    author).</para>

  </chapter>

  <chapter id="use-the-board">
    <title>How to use the Board</title>

    <para>&kbackgammon; is centered around a graphical backgammon
    board. This board consists of the checkers, the dice, and the
    cube. All these game elements can be conviniently manipulated with
    the mouse.</para>

    <para>The following image shows a typical game situation with the
    white player moving from 1 to 24 and the black player moving from
    24 to 1. Currently, the white player owns the cube and has just
    rolled 3 and 4.</para>

    <screenshot>
      <screeninfo>The backgammon board</screeninfo>
      <mediaobject>
	<imageobject>
	  <imagedata fileref="board.png" format="PNG"/>
	</imageobject>
	<textobject>
	  <phrase>The Board</phrase>
	</textobject>
      </mediaobject>
    </screenshot>

    <para>If it is their turn, players can roll the dice by double
    clicking on the squares representing the dice or by using the
    corresponding menu entry or toolbar icon (if the toolbar is
    visible and rolling has been included in the toolbar).</para>

    <para>If they own the cube, players can double the cube by either
    double clicking on the square representing the cube or by using
    the corresponding menu entry or toolbar icon (if the toolbar is
    visible and the cube has been included in the toolbar).</para>

    <para>If it is their turn to move, players can move checkers by
    clicking on them and moving the mouse pointer to the desired
    location (while holding the mouse button continuously
    pressed). This is called dragging the checker. Depending on the
    selection made in the current <link
    linkend="engines">engine's</link> <link
    linkend="prefs">configuration</link>, the move will be finished
    once the maximum number of checkers has been moved (this may be
    anywhere between 1 and 4 checkers, although it will usually be 2
    checkers).</para>

    <para>In addition to dragging the checkers, the board offers a
    feature called "short move feature". If this has been enabled in
    the board's configuration menu, checkers can be moved by simply
    clicking on them. The board will then automatically make the
    shortest move possible away from the current field. If the "short
    move feature" <link linkend="prefs">is enabled</link>, it may be
    set to single or double click. This option is very useful for
    users of touchpads that are sometimes difficult to use for
    dragging.</para>

    <para>Finally, the board has a certain smartness: it will only
    accept moves that are allowed (based on the current dice). While
    the <link linkend="engine-offline">offline engine</link> allows
    this to be switched off (for the <guilabel>Edit Mode</guilabel>),
    this is usually very helpful for unexperienced users (and advanced
    players will probably never notice this). This featue can also be
    used to cancel a move in progress: just drop it over an illegal
    field.</para>

  </chapter>


  <chapter id="engines">
    <title>Backgammon Engines</title>
    
    <para>&kbackgammon; is built around the backgammon board, which
    doesn't know anything about how to play backgammon. The whole
    infrastructure (rolling the dice, etc.) that allows backgammon
    games is handled by backgammon engines.</para>
    
    <sect1 id="engine-offline">
      <title>The Offline Engine</title>
      
      <para>Some words about the offline engine</para>

    </sect1>
    
    <sect1 id="engine-FIBS">
      <title>The <acronym>FIBS</acronym> Engine</title>
      
      <para>Some words about the <acronym>FIBS</acronym> engine</para>
      
    </sect1>
    
    <sect1 id="engine-gnubg">
      <title>The &GNU; Backgammon Engine</title>
      
      <para>The GNUbg engine does not yet exist (although it already
      has an entry in the <guilabel>Engines</guilabel>
      menu). Therefore, the remainder of this chapter should be taken
      with a grain of salt.</para>
      
      <para>Use of the GNUbg engine requires a working installation of
      the actual GNUbg program. &kbackgammon; then starts GNUbg in the
      background and communicates with it. All this is transparent to
      the user (i.e. it is hidden from the user) and all ineraction
      with GNUbg is through the GUI elements of &kbackgammon;.</para>

      <para>If there are other enhancements that can help using GNUbg
      from &kbackgammon;, please contact the author of &kbackgammon;
      (or better: send a patch). Some of the more advanced features
      will probably be position analysis and save/restore
      functions. However, playing is the most pressing issue.</para>

      <para>The one thing that will never happen is a combination of
      the GNUbg and the FIBS engine! Using computer programs to
      enhance user ratings is cheating!</para>

    </sect1>
    
  </chapter>
  
  <chapter id="prefs">
    <title>Game options</title>
    
    <para>The options to &kbackgammon; are set by selecting
    <menuchoice> <guimenu>Settings</guimenu>
    <guimenuitem>Preferences</guimenuitem> </menuchoice> from the
    menubar. This will bring up a dialog box.</para>
    
  </chapter>
  
  <chapter id="command">
    <title>Commands/Keyboard Shortcuts</title>
    
    <para>The following sections briefly describe each menubar option.</para>
    
    <sect1 id="file-menu">
      <title><guimenu>File</guimenu> Menu</title>
      
      <para>Information missing...</para>
      
    </sect1>
    
    <sect1 id="engines-menu">
      <title><guimenu>Engines</guimenu> Menu</title>
      
      <para>Information missing...</para>
      
    </sect1>
    
    <sect1 id="play-menu">
      <title><guimenu>Play</guimenu> Menu</title>
      
      <para>Information missing...</para>
      
    </sect1>
    
    <sect1 id="settings-menu">
      <title><guimenu>Settings</guimenu> Menu</title>
      
      <para>Information missing...</para>
      
    </sect1>
    
    <sect1 id="help-menu">
      <title><guimenu>Help</guimenu> Menu</title>
      
      <variablelist>
	
	<varlistentry>
	  <term><anchor id="contents"/><menuchoice>
	      <shortcut><keycombo action="simul"><keycap>F1</keycap></keycombo></shortcut>
	      <guimenu><accel>H</accel>elp</guimenu><guimenuitem><accel>C</accel>ontents</guimenuitem></menuchoice></term>
	  <listitem><para>This invokes the &kde; help system starting at the &kbackgammon;
help pages (this document).</para>
	  </listitem>
</varlistentry>

<varlistentry>
<term><anchor id="bug"/><menuchoice>
<shortcut><keycombo action="simul"><keycap>Shift</keycap><keycap>F1</keycap></keycombo></shortcut>
<guimenu><accel>H</accel>elp</guimenu><guimenuitem>What's <accel>T</accel>his?</guimenuitem></menuchoice></term>
<listitem><para>This changes the mouse cursor to a combination arrow and
question mark.  Clicking on items within &kbackgammon; with this arrow will open a help
window (if one exists for the particular item) explaining the item's
function.</para></listitem>
</varlistentry>

<varlistentry>
<term><anchor id="whats-this"/><menuchoice>
<guimenu><accel>H</accel>elp</guimenu><guimenuitem><accel>R</accel>eport
Bug...</guimenuitem></menuchoice></term>
<listitem>
<para>If you have a good idea for the next version of the game, or the program
crashes on you, you can select this option to send a bug report to the
author.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><anchor id="about-kbackgammon"/><menuchoice>
<guimenu><accel>H</accel>elp</guimenu><guimenuitem><accel>A</accel>bout
KBackgammon</guimenuitem></menuchoice></term>
<listitem>
<para>This will displays version and author information</para>
</listitem>
</varlistentry>

<varlistentry>
<term><anchor id="about-kde"/><menuchoice>
<guimenu><accel>H</accel>elp</guimenu><guimenuitem>About
<accel>K</accel>DE</guimenuitem></menuchoice></term>
<listitem>
<para>This displays the &kde; version and other basic information.</para>
</listitem>
</varlistentry>
</variablelist>
</sect1>



<sect1 id="keys"><title>Default Key Bindings</title>

<para>The following tables show you the default key bindings of
&kbackgammon;.</para>


<table>
<title>Key bindings</title>
<tgroup cols="2">
<thead><row><entry>Key Combo</entry><entry>Action</entry></row></thead>
<tbody>
<row><entry><keycombo action="simul"><keycap>Ctrl</keycap><keycap>P</keycap></keycombo></entry><entry>Print Game</entry></row>
<row><entry><keycombo action="simul"><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo></entry><entry>Quit &kbackgammon;</entry></row>
<row><entry><keycombo action="simul"><keycap>F1</keycap></keycombo></entry><entry>Help Contents</entry></row>
<row><entry><keycombo action="simul"><keycap>Shift</keycap><keycap>F1</keycap></keycombo></entry><entry>Whats This Help</entry></row>
<row><entry><keycombo action="simul"><keycap>Ctrl</keycap><keycap>Z</keycap></keycombo></entry><entry>Undo move</entry></row>
<row><entry><keycombo action="simul"><keycap>Shift</keycap><keycap>Ctrl</keycap><keycap>Z</keycap></keycombo></entry><entry>Redo previously undone move</entry></row>
</tbody>
</tgroup>
</table>

<para>These key bindings can be changed by selecting <menuchoice>
<guimenu>Settings</guimenu> <guimenuitem>Configure Key Bindings</guimenuitem>
</menuchoice> from the menubar.</para>

</sect1>

</chapter>


<chapter id="credits">
<title>Credits and License</title>
 
<para>&kbackgammon;</para>

<para>Program copyright 1999-2000 Jens Hoefkens
<email>jens@hoefkens.com</email></para>

<para>Documentation copyright 2000 Jens Hoefkens
<email>jens@hoefkens.com</email></para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;
&underGPL;

</chapter>                  

<appendix id="installation">
<title>Installation</title>
 
<sect1 id="getting-kapp"><title>How to obtain &kbackgammon;</title>
 
<para>&kbackgammon; is part of the &kde; project <ulink
url="http://www.kde.org">http://www.kde.org</ulink>. &kbackgammon; can be found
in the kdegames package on <ulink
url="ftp://ftp.kde.org/pub/kde/">ftp://ftp.kde.org/pub/kde/</ulink>, the main
&FTP; site of the &kde; project.</para>

<para>The home page of &kbackgammon; is located at <ulink
url="http://backgammon.sourceforge.net/">http://backgammon.sourceforge.net</ulink>.
It will usually contain the most up-to-date informationon the program
available.</para>

</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>
 
<para>In order to compile and install &kbackgammon; on your system, type the
following in the base directory of the &kde; distribution:</para>

<screen width="40">
  <prompt>%</prompt> <userinput><command>cd</command> <replaceable>kdegames</replaceable></userinput>
  <prompt>%</prompt> <userinput><command>./configure</command></userinput>
  <prompt>%</prompt> <userinput><command>make</command></userinput>
  <prompt>%</prompt> <userinput><command>make</command> <option>install</option></userinput>
</screen>

<para>Since &kbackgammon; uses <application>autoconf</application> and
<application>automake</application> you should have not trouble compiling
it. Should you run into problems please report them to the &kde; mailing
lists.</para>
 
</sect1>         

</appendix>

    <!-- <screenshot> -->
    <!--   <screeninfo>&kbackgammon; Preferences</screeninfo> -->
    <!--   <mediaobject> -->
    <!--   <imageobject><imagedata fileref="kbackgammon2.png" format="PNG"/></imageobject> -->
    <!-- </mediaobject> -->
    <!-- </screenshot>   -->
    
    <!-- <para>This dialog box is divided into two tabs.</para> -->
    
    <!-- <variablelist> -->
    <!-- <varlistentry> -->
    <!-- <term><guilabel>Main settings</guilabel></term> -->
<!-- <listitem><para>The top option, entitled <guilabel>case size</guilabel>, -->
<!-- determines the size of each of the squares in the playing area.  By default, -->
<!-- they are set small.  You can increase the size, if you are working on a very -->
<!-- high resolution monitor.</para>  -->

<!-- <para>The next option down, labelled <guilabel>Enable ? Mark</guilabel>, -->
<!-- determines whether you can mark squares as <quote>questionable</quote>.  If -->
<!-- there is a mark in front of this option, then right clicking the mouse will -->
<!-- first cause a case to be flaged. If you click again on the same square, the flag -->
<!-- will change to a <guiicon>?</guiicon>, to indicate you don't know if there is a -->
<!-- bomb there or not.  If you click again, the square will change back to -->
<!-- blank.</para> -->

<!-- <para>If there is not a mark in front of this option, the first -->
<!-- <mousebutton>right</mousebutton> mouse click will change the case to a red flag. -->
<!-- The second will make it blank again, thus skipping the ? symbol.</para> -->

<!-- <para>The next option down, labelled <guilabel>Enable keyboard</guilabel>, -->
<!-- determins if the keyboard shortcuts will work while playing the game.</para> -->

<!-- <note><para>The only keyboard shortcuts affected, are those responsible for -->
<!-- playing the game.  Keyboard commands such as <guimenuitem>New -->
<!-- Game</guimenuitem>, and <guimenuitem>Quit</guimenuitem>, still -->
<!-- work, regardless of this option.</para></note> -->

<!-- <para>The last section of this tab, allows you to change the action of each of -->
<!-- the three mouse buttons.  Your options are:</para> -->

<!-- <variablelist> -->
<!-- <varlistentry> -->
<!-- <term>Reveal</term> -->
<!-- <listitem><para>This will reveal the contents of the case.  If there is no bomb, -->
<!-- then a number will appear.  If there is a bomb under that case, then the bomb -->
<!-- will explode, and the game will be over.</para></listitem> -->
<!-- </varlistentry> -->
<!-- <varlistentry> -->
<!-- <term>Toggle Mark</term> -->
<!-- <listitem><para>Clicking with this button on a case, will mark/unmark with a red -->
<!-- flag.</para></listitem> -->
<!-- </varlistentry> -->
<!-- <varlistentry> -->
<!-- <term>Autoreveal</term> -->
<!-- <listitem><para>Clicking on a case with this button, will automatically reveal -->
<!-- all neighboring cases, that are not marked with red flags.  If one of those -->
<!-- neighboring cases has a bomb under it, the bomb will explode, and the game will -->
<!-- be over.</para></listitem> -->
<!-- </varlistentry> -->
<!-- <varlistentry> -->
<!-- <term>Toggle ? Mark</term> -->
<!-- <listitem><para>Clicking with this button on a case, will mark/unmark with a -->
<!-- question mark.</para></listitem> -->
<!-- </varlistentry> -->
<!-- </variablelist> -->
<!-- </listitem> -->
<!-- </varlistentry> -->
<!-- <varlistentry> -->
<!-- <term><guilabel>Color Settings</guilabel></term> -->
<!-- <listitem><para>This dialog box will allow you to adjust the color of the kbackgammon -->
<!-- screen.  To adjust, simply click the color button beside each description, and -->
<!-- select the new color.</para></listitem> -->
<!-- </varlistentry> -->
<!-- <varlistentry> -->
<!-- <term>Saving your changes</term> -->
<!-- <listitem><para>Once your changes are complete, click -->
<!-- "<guibutton>OK</guibutton>" to make them permenant.</para> -->
<!-- <para>If you want to abandon your changes, click "<guibutton>Cancel</guibutton>" -->
<!-- to abort the changes.</para> -->
<!-- <para>If you click on "<guilabel>Default</guilabel>", the default settings will -->
<!-- be restored.  Click "<guilabel>OK</guilabel>" to make these default changes -->
<!-- permenant, or edit the settings some more.</para> -->
<!-- </listitem> -->
<!-- </varlistentry> -->
<!-- </variablelist> -->



</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->


