<!doctype debiandoc public "-//DebianDoc//DTD DebianDoc//EN"><!--*-SGML-*-->
<!-- m4_changequote([<<],[>>]) -->
  <debiandoc><book>
    <titlepag>
      <title>
        The <prgn> cardwords </prgn> game
      </title>

      <author>
        <name>
          Tobias Peters
        </name>
        <email>
          cardwords@crosswinds.net
        </email>
      </author>

      <version>
        m4_include(VERSION)
      </version>

      <abstract>
         <prgn> cardwords </prgn> is a card game for your computer running
         Linux.
         You get cards showing letters and can lay words with them
         crossword-like on the table. This document describes how to
         compile, install, customize and run the game.
         Please note that the game is playable but still very alpha.
      </abstract>

      <copyright>
        <copyrightsummary>
          Copyright &copy; 1998 1999 Tobias Peters
        </copyrightsummary>
        <p>
          The <prgn> cardwords </prgn> program including this <file> README
          </file> is free software; you
          can redistribute it and/or modify
          it 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.
        </p>
        <p>
          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
          GNU General Public License for more details.
        </p>
        <p>
          You should have received a copy of the GNU General Public License
          along with this program; if not, write to the Free Software
          Foundation, Inc.,
          59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
        </p>
      </copyright>

    </titlepag>
    <toc>

    <chapt>
      <heading>
        Introduction
      </heading>

      <p>
        <prgn> cardwords </prgn> is a card game for your computer running Linux
        (it will
        probably run on other flavors of Unix, too).
      </p>
      <p>
        This software is in alpha state.
        It is possible to play a game against the computer or against other
        players over the net, but it is not very comfortable yet.
      </p>
      <p>
        <prgn> cardwords </prgn> is a client/server based program. The server
        accepts connections from clients all over the internet and manages
        the game.
        One client can authenticate as the owner and that client's
        user can do some administrative jobs such as deciding to add words to
        the dictionary of valid words while the others can not.
        You can play against other people over the internet or against as many
        computer generated robots as you like. Or against a mix of both.
      </p>
      <p>
        I want to have different clients in the long run. At the moment there
        is only a <prgn> gtk </prgn> client which requires <prgn> xwindows
        </prgn> with scalable fonts,
        <prgn> gtk+ </prgn> and <prgn> gtk-- </prgn>.
        I would like to
        have also a text mode client using <prgn> ncurses</prgn> or inside
        emacs.
      </p>
      <p>
        In the game you get cards showing a
        character and points.
        You try to lay words with them on the table in
        a crossword-like way.
      </p>
      <p>
        You can customize the game.
        However, this has currently to be done by editing some text files.
        I want to have tools for this task in the long run,
        but for customizing the game now, I will describe the format of the
        various files concerned in <ref id="customizing_cardwords">.
      </p>
      <p>
        These files are
      <list>
        <item>
          <p>
            a charset file which contains the
            characters that can form the words,
          </p>
        </item>
        <item>
          <p>
            one or more dictionary files of valid words,
          </p>
        </item>
        <item>
          <p>
            a file that lists all existing cards,
          </p>
        </item>
        <item>
          <p>
            a file containing information about the card-table,
          </p>
        </item>
        <item>
          <p>
            a file specifying bonus and penalty points for certain actions
            and (implicitly) the number of cards everybody gets handed out.
          </p>
        </item>
        
      </list>

        This way it is possible to have dictionarys
        in different languages and use the special characters of that language,
        but this is currently limited to the latin-1 charset.
      </p>
    </chapt>



    <chapt>
      <heading>
        Getting, compiling and installing <prgn> cardwords </prgn>
      </heading>
      <p>
        You can obtain the latest <prgn>cardwords</prgn> source from
        <url id="http://www.crosswinds.net/~cardwords/">
        or from your local sunsite mirror.
      </p>
      <p>
        You will currently need the <prgn>gtk+</prgn> and <prgn>gtk--</prgn>
        libraries in order to compile and run <prgn>cardwords</prgn>
        because the only existing client
        program uses the <prgn>gtk--</prgn> library.
        and run <prgn>cardwords</prgn>.
      </p>
      <p>
        Modify the <file>Makefile</file>:
        The <file>Makefile</file> has the following entrys:
      </p>
      <p>
        <example>
BINDIR = $(DESTDIR)/usr/local/bin
LIBDIR = $(DESTDIR)/usr/local/lib/games/cardwords
CONFDIR = $(DESTDIR)/usr/local/etc
LOCALEDIR = $(DESTDIR)/usr/local/share/locale
DEFAULT_HOMEDIR = getenv\(\"HOME\"\) # c expression.
DEFAULT_PORT = 27037
        </example>
      </p>
      <p>
        Adjust these entrys according to your needs.
        They have the following meaning:
        <taglist>
          <tag>
            <tt>BINDIR</tt>:
          </tag>
          <item>
            <p>
              The executable files will be installed into this directory.
            </p>
          </item>
          <tag>
            <tt>LIBDIR</tt>:
          </tag>
          <item>
            <p>
              This directory will contain the
              <qref id="charset file">charset files</qref>, the
              <qref id="dictionary file">dictionary files</qref>,
              the
              <qref id="card set file">card set files</qref>, the
              <qref id="card-table file">card-table files</qref> and the
              <qref id="bonus file">bonus files</qref>.
            </p>
          </item>
          <tag>
            <tt>LOCALEDIR</tt>:
          </tag>
          <item>
            <p>
              This is the directory where translated messages 
              (.mo files) will be stored under
              <file><tt>LOCALEDIR</tt>/<var>locale-abbrev</var>/cardwords.mo
              </file>.
            </p>
          </item>
          <tag>
            <tt>CONFDIR</tt>:
          </tag>
          <item>
            <p>
              This directory is not used yet.
              Later it will contain a system wide default configuration.
              A configuration consists of default values for charset files,
              the dictionary files, the card set files, the card-table
              files and the bonus files.
            </p>
          </item>
          <tag>
            <tt>DEFAULT_HOMEDIR</tt>:
          </tag>
          <item>
            <p>
              Unlike the previous ...<tt>DIR</tt> settings, this has to be a
              valid c++ expression, with shell escapes.
              Change it if your system does not set the
              environment variable <tt>HOME</tt> to your home directory or if
              you use a shell that does not use the backslash for quoting
              single characters.
            </p>
          </item>
          <tag>
            <tt>DEFAULT_PORT</tt>:
          </tag>
          <item>
            <p>
              The default tcp port the server listens to.
              Change it if this port is already in use on your system.
              This is unlikely.
            </p>
          </item>
        </taglist>
        Then type <tt>make</tt> to compile everything and
        <tt>make install</tt> to copy the created binaries to the
        <var>BINDIR</var>. The example files will be copied to the
        <var>LIBDIR</var>.
      </p>
    </chapt>

    <chapt id="customizing_cardwords">
      <heading> Customizing <prgn> cardwords </prgn> </heading>
      <p>
        <prgn> cardwords </prgn> is customized by supplying customized versions
        of the following files:
        <list>
          <item>
            <p> The charset file, see <ref id="charset file">.</p>
          </item>
          <item>
            <p> The dictionary files, see <ref id="dictionary file">.</p>
          </item>
          <item>
            <p> The card set file, see <ref id="card set file">.</p>
          </item>
          <item>
            <p> The card-table file, see <ref id="card-table file">.</p>
          </item>
          <item>
            <p> The bonus file, see <ref id="bonus file">.</p>
          </item>
        </list>
      </p>
      <p>
        You can put customized versions of these files anywhere you like
        and point the client programm to them with the options dialog and
        then save the options,
        but I suggest that you put these files either in <var> LIBDIR </var>
        (if you are the system administrator and these files are of interest
        for some of your users) or in the <file> .cardwords </file>
        subdirectory of your home directory.
      </p>
      <p>
        If you create a french version of these files
        for example, and all your users speek french as their native language,
        you should put these files in <var>LIBDIR</var> and make the symlinks
        <file> default.* </file> point to them.
      </p>
      <p>
        When you create new versions of these files and make them accessible
        to other people, you must be careful not to violate anyone's
        copyright.
      </p>
      <p>
        Yes, I mean it. It may be possible to customize this game so
        that it imitates other crossword computer games
        or real world crossword games.
        If you create such an customization, and you do not have the
        copyright for it, you must not distribute it.
        This does even mean
        that you must not play a game that is this way customized with other
        people over the net, because the server sends copies of these files
        to the clients, and this is an act of distribution and copying.
      </p>
      <p>
        I rather want to encourage you to be creative and invent your own
        charsets, card sets, card-tables, bonus and penalty rules etc, and
        publish them under a free license such as the GPL, BSD, Artistic etc.
      </p>

      <sect id="charset file">
        <heading>The charset file</heading>
        <p>
          The charset file has the format
        </p>
        <p>
          <example>
<var>n</var>
<var>character 1 equivalents</var>
<var>character 2 equivalents</var>
<var>character 3 equivalents</var>
  [...]
<var>character <var>n</var> equivalents</var>
          </example>
        </p>
        <p>
          where <var>n</var> is the number of different characters on your
          cards and
          <var>
            character
              <var>i</var><footnote><p>1 &le; i &le; n</p></footnote>
            equivalents
          </var>
          are characters from the computer's charset that this character
          represents. The <var>character equivalents</var> must not contain
          white space.
          This way it is possible to let uppercase and lowercase
          characters be represented by the same card character. Here is an
          example charset file for the english language (as distributed in
          example.charset with cardwords):
        </p>
        <p>
          <example>
26
Aa
Bb
Cc
Dd
Ee
Ff
Gg
Hh
Ii
Jj
Kk
Ll
Mm
Nn
Oo
Pp
Qq
Rr
Ss
Tt
Uu
Vv
Ww
Xx
Yy
Zz
          </example>
        </p>
        <p>
          The first character that you give in a set of equivalent characters
          will always be used by the program's output to refer to that card
          character, while all given characters are recognized in the input.
        </p>
        <p>
          If you really want to you can also separate lowercase from uppercase
          characters, and specify only one character on each line. This could
          make sense in some languages where several words always start with
          an uppercase letter, but I think it is generally unnecessarily
          complicated.
        </p>
        <p>
          You might wonder why you have to specify the characters in a file,
          A to Z uppercase and lowercase is not too hard to think of, is it?
          My main motivation to write <prgn>cardwords</prgn> was the lack of
          crossword computer games that featured the german umlauts
          &Auml;, &Ouml; and &Uuml; and the &sz;.
          While it is common practice to
          replace these even in german newspaper's crossword puzzles with
          AE, OE, UE and SS,
          the result is sometimes ugly.
          With <prgn>cardwords</prgn>, this is no more necessary.
        </p>
        <p>
          The programs I saw also had hardwired
          assumptions about the distribution of the characters in the
          language that fits the english language, but is ridiculous in
          other languages.
          This distribution of characters can be customized
          within the card set file described in <ref id="card set file">.
        </p>
      </sect>

      <sect id="dictionary file">
        <heading>The dictionary files</heading>
        <p>
          You have to use a dictionary file if you want to play against
          robots.
          The robots would otherwise have no clue what a valid word is.
          If you start the server without specifying a dictionary, it will
          crash currently when a robot tries to make his move.
          I recommend using a dictionary file.
          The server sometimes interrupts the connection when a client
          tries to perform an action that it is not allowed to.
          If this happens (and remember, the software is alpha, this
          <em> can </em>
          happen now) or the connection breaks otherwise, then the remote
          player is replaced by a robot, even if you started a game with no
          robots at all.
        </p>
        <p>
          A dictionary file is just a text file that contains the words that
          you want the server to allow, like this:
        </p>
        <p>
          <example>
salt
pepper
collapsible
jaw
eat
so
          </example>
        </p>
        <p>
        The words do not need to be sorted in any way.
        The only restrictions are:
        <list>
          <item>
            <p>The words must consist of at least 2 characters.</p>
          </item>
          <item>
            <p>
              The words must be build up from characters that you put in the
              <qref id="charset file">charset file</qref>. This implies that
              they must not contain white space.
            </p>
          </item>
        </list>
        </p>
        <p>
        The <prgn> cardwords </prgn> server program can use dictionary files in
        three different ways:<footnote>
            <p>
             It is in fact not the server program <prgn>cardwords_server</prgn>
             that makes this distinction, but <prgn> cardwords_dicbot </prgn>,
             which is started by the server and handles all dictionary related
             tasks like checking the validity of words and finding the best
             moves for the robots.
            </p>
          </footnote>
          <list>
            <item>
              <p>
                As a normal, read-only dictionary.
                The server could handle several of these, adding all contained
                words to its internal dictionary, but this is not yet
                implemented in the client that starts the server.
              </p>
            </item>
            <item>
              <p>
                As a dictionary file that is read when the server starts and
                to which new words, that are introduced by the owner of the
                server, will be appended.
              </p>
            </item>
            <item>
              <p>
                As a file that contains words to remove from the internal
                dictionary.
                This is not implemented yet, and when it is, you should not add
                a dictionary file which contains many words you do not want to
                have and then remove them using a remove-file, because it
                works very slow.
                I optimized the internal dictionary to quickly
                find the best move for a given set of cards (the robots need
                this), and the result was that removing a word is not only
                slow, but very slow<footnote><p> O(N) </p></footnote>.
              </p>
            </item>
          </list>
        </p>
        <p>
          Dictionaries are a source of conflicts between human players.
          Find a consensus with your
          players what kinds of words should go into the dictionary before
          starting the game.
        </p>
        <p>
          The robots will of course accept any dictionarys that you provide.
          With a combination of a read-only file and a read write file, you
          can have a system wide read-only dictionary that everybody agrees
          on and a writeable personal dictionary where you put your own
          special words.
        </p>
        <p>
          You can also use the writeable dictionary to add just a few words to
          the dictionary in the beginning and let the program add new words as
          they occur during the game. I recommend this way, it is the
          conveniest and it ensures that you win the first games against the
          robots <tt>:-)</tt>.
        </p>
      </sect>

      <sect id="card set file">
        <heading>The card set file</heading>
        <p>
          You can decide what cards you want to play with. Each card shows
          a character and a points value.
          You can also create special wildcards that can represent any
          character the player wants.
          You can create any combinations of characters and point values.
        </p>
        <p>
         The card set file just lists all existing cards, preceeded by the
         total number of cards.
         A card in the file has the following format:
        </p>
        <p>
         <example>
   [<var>x</var> <var>#</var>]
         </example>
        </p>
        <p>
         where
         <taglist>
           <tag>[ and ]</tag>
            <item>
              <p> are literal brackets. </p>
            </item>
           <tag><var>x</var></tag>
            <item>
              <p>
                is a character that is contained in the
                <qref id="charset file">charset file.</qref>
                This is the character the card shows.
                For wildcards, this
                must be a space.
             </p>
            </item>
           <tag><var> (the space in the middle)</var></tag>
            <item>
              <p>is a literal space. This is required.</p>
            </item>
           <tag><var>#</var></tag>
            <item>
              <p>is an int in decimal, the points of that card.</p>
            </item>
         </taglist>
        </p>
        <p>
          Clients can restrict the points of the cards to certain values,
          while the server does not.
          The only client existing by now restricts the points of cards
          to the range from -9 to 99.
          This is because of the space where the points are displayed on
          the screen is designed to hold two digits, or one digit and the
          minus sign at maximum.
          Other clients can have other restrictions.
        </p>
        <p>
          Here is an example card set file that can be used together with the 
          <qref id="charset file">example charset file</qref>:
        </p>
        <p>
          <example>
14
[A 6] [A 6] [A 6] [A 7]
[B 2] [B 2] [B 9]
[E 1] [E 0] [E -1][K 19]
[  0] [  -2] [  -1] 
          </example>
        </p>
        <p>
          The card descriptions can be separated from each other by
          white space.
          Remember the required space in each card description!
          The last line in this example shows three wildcards. Theese
          need two spaces, one to mark it as a wildcard and the other one
          is the required space.<footnote>
            <p>
              You might wonder what the sense of the middle space is. 
              <prgn>cardwords</prgn> uses exactly this card description
              format when client and server communicate.
              Sometimes the meaning of wildcards needs to be specified.
              This is done by replacing this space with a character with that
              meaning.
            </p>
          </footnote>
        </p>
        <p>
          You might want to count the distribution of characters in documents
          written in your language, in order to create a card set file.
          You can use <prgn> cardwords_count </prgn> to do this.
          Create <prgn> cardwords_count </prgn> by typing <tt> make
          cardwords_count</tt>.
          <prgn> cardwords_count </prgn> takes a
          <qref id="charset file"> charset file </qref>
          as argument and parses its standard input.
          It will ignore all chars that do not occur in the
          <qref id="charset file"> charset file </qref>
          and write the total number of occurrences of every recognized
          character to its standard output.
        </p>
        <p>
          I must admit I have no idea if and how the copyright propagates
          from the document in which you count the characters to the output
          of <prgn> cardwords_count</prgn>, and if you base your card set file
          on it, to this card set file.
          I think it could be declared as a derivative work.
          So, unless you know it better than
          me, you should use only documents that you wrote entirely yourself
          or that are in the public domain. 
        </p>
        <p>
          You might also want to set the total number of cards in some
          relation to the total number of places on the card table.
        </p>
      </sect>

      <sect id="card-table file">
        <heading>The card-table file</heading>
        <p>
          The card-table is the place where the words are created.
          Because the words should appear crossword-like, the card-table
          has a grid of cells where the cards can be put.
          This grid has always the form of a rectangle, but you can
          customize its width and height.
        </p>
        <p>
          You can also give a start condition.
          This means you can restrict the first word to areas where it touches
          a certain row of the grid, or a certain column, or even a single
          cell.
        </p>
        <p>
          Subsequent new words must then touch existing cards on the
          card-table.
        </p>
        <p>
          The format of a card-table file that creates a very simple
          card-table is
        </p>
        <p>
          <example>
<var>dimensions</var>
<var>start condition</var>
<var>end tag</var>
          </example>
        </p>
        <p>
          where 
          
          <taglist>
            <tag>
              <tt><var>dimensions</var></tt>
            </tag>
            <item>
              <p>
                have the form <tt><var>width</var>*<var>height</var></tt>,
                <tt><var>width</var></tt> and <tt><var>height</var></tt>
                being decimal integers describing the width and height of the
                grid, <tt>* </tt> is a literal asterisk;
              </p>
            </item>
            <tag>
              <tt><var>start condition</var></tt>
            </tag>
            <item>
              <p>
                has the form <tt>(<var>column</var>, <var>row</var>)</tt>,
                with the parentheses and the comma being literal parentheses
                and comma, with <tt><var>column</var></tt> and
                <tt><var>row</var></tt> being decimal integers.
                If 0 &le; <tt><var>column</var></tt> &lt;
                <tt><var>width</var></tt>, then this column must be touched
                by the first word on the card-table.
                If 0 &le; <tt><var>row</var></tt>  &lt;
                <tt><var>height</var></tt>, then this row must be touched
                by the first word on the card-table.
                As you see, valid <tt><var>column</var></tt> and
                <tt><var>row</var></tt> row numbers start with 0.
                <tt>(0,0)</tt> is the upper left corner;
              </p>
            </item>
            <tag>
              <tt><var>end tag</var></tt>
            </tag>
            <item>
              <p>
                is a <tt>(<var>column</var>, <var>row</var>)</tt> pair with
                at least one of the following conditions:
               <list>
                  <item>
                    <p>
                      <tt><var>column</var></tt> &ge; <tt><var>width</var></tt>
                      or
                    </p>
                  </item>
                  <item>
                    <p>
                      <tt><var>row</var></tt> &ge; <tt><var>height</var></tt> .
                    </p>
                  </item>
                </list>
              </p>
            </item>
          </taglist>
          I will give some examples of simple card-table files to make it
          clear what they look like:
        </p>
        <p>
          <list>
            <item>
              <p>
                A file defining a card-table with width 18, height 10 and
                no start condition:
              </p>
              <p><example>
18*10
(18,10)
(18,10)
              </example></p>
            </item>
            <item>
              <p>
                A file defining a card-table with width 18, height 10 and
                a start condition that restricts the first word to touch the
                rightmost column:
              </p>
              <p><example>
18*10
(17,10)
(18,10)
              </example></p>
            </item>
            <item>
              <p>
                A file defining a card-table with width 18, height 10 and
                a start condition that restricts the first word to touch the
                left bottom cell:
              </p>
              <p><example>
18*10
(0,9)
(18,10)
              </example></p>
            </item>
          </list>
        </p>
        <p>
          But that is not all that can be specified in card-table files.
          You can set certain attributes of the card-table grid cells:
          <list>
            <item>
              <p>
                Cells can be unuseable (blocked).
                This means, they can not hold a card,
                and no word can cross them.
                To block a cell add a line
                <example>
(<var>column</var>, <var>row</var>) B;
                </example>
                to the card table file between the
                <tt><var>start condition</var></tt>
                line and the
                <tt><var>end tag</var></tt>
                line.
              </p>
            </item>
            <item>
              <p>
                Cells can have a points value.<footnote>
                  All cells have a points value in fact. The default points
                  value is 0.
                </footnote>
                The player who occupies this cell with a card gets these
                points.
                To change the points value of a cell add a line
                <example>
(<var>column</var>, <var>row</var>) C <var>points</var>;
                </example>
                to the card table file between the
                <tt><var>start condition</var></tt>
                line and the
                <tt><var>end tag</var></tt>
                line.
              </p>
            </item>
            <item>
              <p>
                Cells can have a letter factor.<footnote>
                  All cells have a letter factor in fact. The default letter
                  factor is 1.
                </footnote>
                This means that the points of the card that is put there are
                multiplied by this factor when the points are counted.
                To change the letter factor of a cell add a line
                <example>
(<var>column</var>, <var>row</var>) L <var>factor</var>;
                </example>
                to the card table file between the
                <tt><var>start condition</var></tt>
                line and the
                <tt><var>end tag</var></tt>
                line.
              </p>
            </item>
            <item>
              <p>
                Cells can have a word factor.<footnote>
                  All cells have a word factor. The default word factor is 1.
                </footnote>
                This means that the points of the card that is put there
                and the points of all other cards that form a word together
                with the card in this cell are
                multiplied by this factor when the points are counted.
                To change the word factor of a cell add a line
                <example>
(<var>column</var>, <var>row</var>) W <var>factor</var>;
                </example>
                to the card table file between the
                <tt><var>start condition</var></tt>
                line and the
                <tt><var>end tag</var></tt>
                line.
              </p>
            </item>
          </list>
          Multiple attributes of a single cell can be grouped into a single
          line like
          <example>
(<var>column</var>, <var>row</var>) W <var>word_factor</var> C <var>cell_points</var>;
          </example>
          or any other combination.
          The gtk client does not support more than 2 non-default cell
          attributes per cell.
        </p>
        <p>
          You should perhaps only use one cell attribute per cell at maximum,
          and let most of the cells have their default values in order to not
          make it too complicated for humans to play the game. Here is the
          example card-table file as shipped with <prgn>cardwords</prgn>:
        </p>
        <p>
          <example>
19*10
(10,11)

(0 ,0) B;
(0 ,1) B;
(1 ,0) B;

(17,0) B;
(18,0) B;
(18,1) B;

(0 ,9) B;
(1 ,9) B;
(0 ,8) B;

(18,9) B;
(17,9) B;
(18,8) B;

(10,0) C 5;
(10,9) C 5;

(1 ,1) W 2;

(17,8) L 2;

(20,12)
          </example>
        </p>
      </sect>

      <sect id="bonus file">
        <heading>The bonus file</heading>
        <p>
          This file has the following format:
        </p>
        <p>
          There are 2*<var>N</var>+1 pairs <var>int</var>:<var>int</var>
          with the following restrictions
          and meanings:
        </p>
        <p>
          <example>
-<var>N</var>:<var>trade_N_score</var>
..:..
-1:<var>trade_1_score</var>
0:<var>pass_score</var>
1:<var>1-bonus</var>
..:..
<var>N</var>:<var>N-bonus</var>
          </example>
        </p>
        <p>
          The <var>trade_i_score</var> is added to the player's score
          when he changes <var>i</var> cards.
          <var>trade_i_score</var> will usually be &le; 0.
        </p>
        <p>
          The <var>pass_score</var> is added to the players score
          when he passes. Usually <= 0.
        </p>
        <p>
          <var>1-bonus</var>, ..., <var>N-Bonus</var> are added
          to the player's score on top of the move
          count for a move with that many cards.
        </p>
        <p>
          <var>N</var> is the number of cards every player has got in his
          hand.
          <var>N</var> is only implicitly defined in the bonus file
          and nowhere else.
        </p>
        <p>
          Here is an example bonus file:
        </p>
        <p>
          <example>
-6:-10
-5:-10
-4:-10
-3:-5
-2:-5
-1:-5
0:-1
1:0
2:0
3:0
4:0
5:5
6:10
          </example>
        </p>
        <p>
          This bonus file sets the number of cards in every player's hand
          to 6.
          Trading cards and passing results in penalty points, putting 5 or 6
          cards simultaneously onto the table results in bonus points.
        </p>
      </sect>
    </chapt>


    <chapt>
      <heading>Running <prgn> cardwords </prgn></heading>
      <p>
        This chapter describes how to run cardwords using the gtk client
        <prgn>cardwords_gtkclient</prgn>.
        The client's user interface urgently needs to be improved,
        but as long as it is as unfriendly as by now, this chapter will guide you
        through the program.
      </p>
      <p>
        While running X, type <tt>cardwords_gtkclient</tt>,
        or type the full path of the programm, if the directory where you
        installed it is not in your <tt>PATH</tt> environment variable.
      </p>
      <p>
        After the program starts, you will see a dialog
        where you can set options.
      </p>
      <sect id="gtk_optionsdialog">
        <heading>The option settings</heading>
      <p>
        I will now explain this dialog which is divided into several parts:
      <sect1 id="gtk_identitydialog">
        <heading>Identity</heading>
        <p>
<!-- BEGIN_HELP_TEXT gtk_identitydialog -->
          The fields in this dialog are:
          <taglist>
            <tag>Your name:</tag>
            <item>
              <p>
                You have to fill in your name here.
                This name will show up later in every human player's
                client programs.
              </p>
              <p>
                The computer fills your user name in here as a default, but you can
                change the name.
              </p>
              <p>
                <em>The name must not contain white space.</em>
              </p>
            </item>

            <tag>Alternative name:</tag>
            <item>
              <p>
                Several human players can participate in the same game.
                All must have different names.
                You can give another name here that will be used when your first
                name is already used by someone else.
                This way you can avoid the client asking you for another name.
                (Currently, it will not ask you for another name.)
              </p>
              <p>
                You can leave this field blank.
              </p>
              <p>
                <em>The alternative name must not contain white space.</em>
              </p>
            </item>
          </taglist>
<!-- END_HELP_TEXT gtk_identitydialog -->
        </p>
      </sect1>


      <sect1>
	<heading>Appearance</heading>
        <p>
<!-- BEGIN_HELP_TEXT gtk_appearancedialog -->
          The fields in this dialog are:
          <taglist>
            <tag>Card width:</tag>
            <item>
              <p>
                Some <prgn> xwindows </prgn> programs open a window that is
                larger than your screen, while other ones use so little room
                on the screen that you might want to switch to a lesser screen
                resolution.
              </p>
              <p>
                This is an attempt to let the user decide how much room the
                window will occupy, however it is very incomplete.
                You can only change the size (in pixels) a card will occupy
                on the screen.
                This will also change the fonts used inside the
                cards and card-table cells, but it does not affect the fonts
                used in other places of the window.
                And if you have no idea
                about the width and height of the card-table grid, you will have
                no clue which values to use here.
                This has to change in the future.
              </p>
            </item>

            <tag>Card height:</tag>
            <item>
              <p>
                Should be equal or nearly equal to card width, because square
                cards look best when forming words with them in a crossword way.
              </p>
            </item>

            <tag>Use digits for the columns</tag>
            <item>
              <p>
                You can choose if you want to have coodinates with digits for
                the columns and characters for the rows or the other way round.
              </p>
            </item>

            <tag>Column indices grow rightwards</tag>
            <item>
              <p>
                If you want the leftmost column to have the least index (`A'
                or `1'), check this button.
              </p>
            </item>

            <tag>Row indices grow upwards</tag>
            <item>
              <p>
                If you want the bottom-most row to have the least index (`A'
                or `1'), check this button.
              </p>
            </item>
	</taglist>
<!-- END_HELP_TEXT gtk_appearancedialog -->
        </p>
      </sect1>


      <sect1>
	<heading>Local server options</heading>
        <p>
<!-- BEGIN_HELP_TEXT gtk_startserverdialog -->
          The fields in this dialog have the following meaning:
          <taglist>
            <tag>Server program:</tag>
            <item>
              <p>
                This is the location where the <file>cardwords_server</file>
                executable file is installed.
                If you compiled the program with make and installed it with
                make install, the computer will fill in the correct location
                here. You should not change it.
              </p>
            </item>
            <tag>Charset file:</tag>
            <item>
              <p>
                The location of the charset file you want to use for this
                game,
                see <ref id="charset file">
<!-- ADDITIONAL_HELP_TEXT the README -->
                for an explanation of charset files.
              </p>
            </item>
            <tag>Cardset file:</tag>
            <item>
              <p>
                The location of the cardset file you want to use for this
                game,
                see <ref id="card set file">
<!-- ADDITIONAL_HELP_TEXT the README -->
                for an explanation of cardset files.
              </p>
            </item>
            <tag>Card-table file:</tag>
            <item>
              <p>
                The location of the card-table file you want to use for
                this game,
                see <ref id="card-table file">
<!-- ADDITIONAL_HELP_TEXT the README -->
                for an explanation of card-table files.
              </p>
            </item>
            <tag>Bonus file:</tag>
            <item>
              <p>
                The location of the bonus file you want to use for
                this game,
                see <ref id="bonus file">
<!-- ADDITIONAL_HELP_TEXT the README -->
                for an explanation of bonus files.
              </p>
            </item>

            <tag>Dictionary file:</tag>
            <item>
              <p>
                The location of a read-only dictionary file you want to
                use for this game,
                see <ref id="dictionary file">
<!-- ADDITIONAL_HELP_TEXT the README -->
                for an explanation of dictionary files.
              </p>
            </item>

            <tag>Personal dictionary file:</tag>
            <item>
              <p>
                The location of a dictionary file to which new words
                that are added during the game will be appended,
                see <ref id="dictionary file">
<!-- ADDITIONAL_HELP_TEXT the README -->
                for an explanation of dictionary files.
              </p>
            </item>

            <tag>Number of human players:</tag>
            <item>
              <p>
                The number of players who can connect to the server,
                should be at least 1, because you want to play.
              </p>
              <p>
                You can choose any number of players you like as long as
                there are enough cards in the
                <qref id="card set file"> card set </qref>
                so that every player has a full hand of cards at least when
                the game starts.
              </p>
            </item>

            <tag>Number of robot players:</tag>
            <item>
              <p>
                The number of robot players that the server creates.
                The robots are named Robot1 ... Robot<var>N</var>.  
              </p>
              <p>
                You can choose any number of robots you like as long as
                there are enough cards in the
                <qref id="card set file"> card set </qref>
                so that every player has a full hand of cards at least when
                the game starts.
              </p>
            </item>

            <tag>Number of watchers:</tag>
            <item>
              <p>
                The number of watchers who can connect to the server
                and observe the game without playing.
              </p>
              <p>
                You should leave the 0 the computer filled in untouched
                because logging in as a watcher does not work yet.
              </p>
            </item>

            <tag>Port number:</tag>
            <item>
              <p>
                The number of the tcp port that the server listens to.
                If you have once started a server and are now trying to start
                a new one, change it a bit, and exec
                <tt>killall cardwords_server</tt> regularly between restarts.
              </p>
              <p>
                Running servers are sometimes left over when the client
                exits (remember, it's in alpha state), and a new server
                usually can not use the same port as another server uses
                already or has used until a few minutes ago.
              </p>
            </item>
          </taglist>
<!-- END_HELP_TEXT gtk_startserverdialog -->
        </p>
      </sect1>


      <sect1>
	<heading>Remote server</heading>
        <p>
<!-- BEGIN_HELP_TEXT gtk_connectdialog -->
          Here you see a dialog where you can set
          the host name and port number of the remote
          <prgn> cardwords_server</prgn>.
        </p>
        <p>
          Set these if you want to connnect to a <prgn>cardwords_server</prgn>
          that is already running somewhere.
<!-- END_HELP_TEXT gtk_connectdialog -->
        </p>
      </sect1>
      </sect>
      <sect>
        <heading>
          Playing the game
        </heading>
        <p>
          You can save all options that you have set or start a local server
          or connect to a remote server or exit the program by clicking on
          the appropriate button. Use the `Start a local server'-button
          if you want to play a game against the computer.
        </p>
        <p>
          If everything went well, you will now see a window displaying
          the card-table and some other info.
        </p>
        <p>
          When all human players have logged on, the game starts.
        </p>
	<sect1>
	  <heading> The game window </heading>
        <p>
          You can see the card-table in the upper left area of the window.
          When most cells in the card-table grid are set to their default
          values, as I proposed in <ref id="card-table file">, the board
          will appear mostly green. This is because I think card-tables in
          casinos always have a green surtface (but I have not seen one yet).
        </p>
        <p>
          Cell attributes different from the default values are displayed
          inside the cells on a background of a different color.
          You can recognize cell points by the letter `C', word factors by
          the letter `W', and letter factors by the letter `L'.
        </p>
        <p>
          All info about the cell currently under the mouse pointer is shown
          in the upper right corner of the window.
        </p>
        <p>
          Below this, there is the score board.
          It shows whose go it is, how many points and cards every player has,
          how many points everyone got in the last round, and of course the
          names of the other players. The column entitled `Type' contains a
          `H' if this is a human player and an `R' if that player is a robot.
          When the network connection to a particular player breaks, then
          this player will become a robot.
        </p>
        <p>
          One row in the score board is automatically highlighted when the
          game runs. This line indicates whose go it is.
        </p>
        <p>
          Below the score board you can see a single line telling you how
          many cards are left in the pile.
        </p>
        <p>
          The client can tell you what cards are there at all
          in the game or what cards can still be in
          the pile (or in the other players' hands) by opening two windows
          showing lists. Access these lists via the menu.
        </p>
        <p>
          And now to the most important thing in this game: How to tell the
          game what move/trade/pass you want to do next.
        </p>
        <p>
          On the lowest line in the window you can see the cards in your hand.
          When you click with the mouse on one of these cards, it
          usually<footnote>
	    <p>
              Wildcards do not move immediately, the program expects that you
              type the desired meaning in the keyboard (one character,
              <em>without</em> <var>return</var>) before it moves the 
              wildcard to the line above your hand.
            </p>
	  </footnote>
          moves to the line above the hand.
          I call this line the action selection area.
        </p>
        <p>
          You use the action selection area to decide whether you move, trade
          or pass and which card to use.
          And where to move in the case of a move.
        </p>
        <p>
          While you can do moves and passes alone with mouse-clicking
          (except for the wildcards), you
          might have difficulties trying to trade card(s) this way.
          That is why I will first tell you about the `keyboard way' to do
          things in the action selection area in the following subsection:
        </p>
	</sect1>
	<sect1>
        <heading>
          Composing moves, trades and passes with the action selection area
        </heading>
        <p>
          Let me first describe what you see in the action selection area.
          The action selection area consists of the following items
          (from left to right):
          <taglist>
            <tag>The current card-table location display:</tag>
            <item>
              <p>
                This display shows the current card-table location.
                Moves will start at the card-table grid cell with these
                coordinates.
              </p>
              <p>
                The order of the coordinate pair (consisting of a character
                and a number) has a special meaning:
                Whatever coordinate appears first will be one coordinate of
                <em>every</em> card that you move. That means you are
                restricted to a single row or column of the card table with
                one move.<footnote>
                  <p>
                    The restriction is even tighter: There must not be
                    free cells between the cards that you lay on the board in
                    a single move.
                  </p>
		  </footnote>
              </p>
              <p>
                There are braces around the coordinate pair whenever the
                current state of the action selection area is not a move,
                but a trade or a pass.
                This happens in either of the following cases:
                <list>
                  <item>
                    <p>
                      when there are no cards inside the action selection
                      area.
                      Pressing the <tt>OK</tt> button in this state will
                      result in a pass.
                    </p>
                  </item>
                  <item>
                    <p>
                      when the cards would not fit on the card-table if a
                      move started from this location.
                    </p>
                  </item>
                  <item>
                    <p>
                      when the card table is empty and a move starting from
                      this location would not obeye the start condition.
                    </p>
                  </item>
                  <item>
                    <p>
                      when the user explicitly wants to trade cards.
                    </p>
                  </item>
                </list>
              </p>
              <p>
                In all these cases, when there are braces around the
                coordinate pair,
                pressing the <tt>OK</tt> button while there are
                cards inside the action selection area will result in trading
                these cards, or, if there are no cards in the action selection
                area, pressing the <tt>OK</tt> button will result in a pass.
              </p>
            </item>
            <tag>The composing area</tag>
            <item>
              <p>
                consists of card cells that contain your cards while you are
                composing your move or trade.
                When you want to get rid of a
                that is already in this area, you can click on it with the
                mouse or, if it is the last card, remove it with the backspace
                key.
              </p>
            </item>
            <tag>The direction button:</tag>
            <item>
              <p>
                By pressing this button you can change the direction of your
                move.
                The button's label tells you if you are currently composing
                a horizontal move or a vertical move.
                Note that the order of the coordinates in the current
                card-table location display changes accordingly when you press
                this button.
              </p>
            </item>
            <tag>The <tt>OK</tt> button</tag>
            <item>
              <p>
                can be pressed when you have finished your action selection.
              </p>
            </item>
          </taglist>
        </p>
        <p>
          I will now describe how to use the action selection area via the
          keyboard:
        </p>
        <p>
          The action selection area is roughly in two different states:
          it expects either a coordinate pair or a card specification.
        </p>
        <p>
          When your go begins, it expects a coordinate pair.
          If you want to make a move, and I think this is what you want most
          of the time, you can now change the current card-table location.
          type in a character and a number, in an order so that the
          coordinate which is common to all the card destinations of this move
          comes first.<footnote>
            <p>
              I avoid speeking of horizontal and vertical here, like "for a
              horizontal move, type the character coordinate first", because
              it is (not yet, but very soon) costomizable if you want to use
              the characters for the columns and the numbers for the rows
              or vice versa. I think only a dialog field and a value setting
              is missing now, but I first want to get the program out.
            </p>
	  </footnote>
        </p>
        <p>
          If you do not want to make a move, but rather a trade, you can
          invalidate the current card-table location by typing the point `.'.
          The current card-table location will then be shown with braces
          around and the button that previously held the label
          <tt>vertical</tt> or <tt>horizontal</tt> will be empty.
        </p>
        <p>
          After typing the current card-table location or invalidating it,
          the action selection area is in card input mode.
        </p>
        <p>
          You can then specify the cards that you want to move or trade by
          first typing their meaning, and in case this is not to uniquely
          identify any card from your hand because there are cards with the
          same face value but different points, type in the card's points
          thereafter. As soon as the program recognizes which card you mean,
          it will be moved to the composing area.          
        </p>
        <p>
          Specify wildcards by first typing space, then the desired meaning
          of the wildcard (even when you want to trade the card, in which case
          the meaning is irrelevant), and, if this was again not enough to
          identify the wildcard because there are wildcards with different
          points on your hand, type in the points of the desired card.
        </p>
        <p>
          You can remove the last card from the composing area by typing the
          backspace key while in card input mode. 
        </p>
        <p>
          You can change the current card-table location while in card input
          mode by typing once `.' and then typing the new card-table location.
        </p>
        <p>
          You can change a move into a trade while in card input mode by twice
          typing `.': The first `.' sets the state of the action selection
          area to expecting a new card-table location, the second `.'
          invalidates the current card-table location.
        </p>
        <p>
          You can change a trade into a move while in card input mode by typing
          `.' followed by the new card-table location.
        </p>
        <p>
          You can change the direction of a move by typing `/'.
        </p>
        <p>
          Finish your go by typing <var>return</var>.
        </p>
        <p>
          With the info in the previous subsection, I think you can find out
          how to do your moves with the mouse. But one thing has not yet been
          mentioned: You can change the current card-table location with the
          mouse by clicking in the desired cell in the card-table.
        </p>
	</sect1>
        <sect1>
        <heading>Valid moves and score-counting</heading>
        <p>
          The first move has to obeye the start condition, see
          <ref id="card-table file">.
          Subsequent moves must touch at least one card that is already on
          the card-table.
        </p>
        <p>
          All words created by the new move must be valid, ie they have to be
          contained in the server's dictionary and have to have a length of
          at least 2 characters.
        </p>
        <p>
          If a player tries a move that creates a word that is unknown to the
          server, the owner of the server (the player that started the server)
          will be asked if he liked to add this word to the dictionary of
          known words. The player whose move was rejected can try another move
          or trade or pass, or wait until the owner adds the missing word and
          then retry the previous move.
          Players will not be notified about new words.
          Use an irc client to communicate with the other human players
          or whatever you like.
        </p>
        <p>
          When making a move, all cell points of the cells that are being
          covered by the new cards are directly added to the moving players
          score.
          The points of the cards he moves are counted word-wise:
          for every new word that is being created the points of the new cards
          are first multiplied with the cell's letter factor.
          The products are then summed up.
          The plain points of all cards that have already been on the board
          before this move are added to this sum.
          This sum is then subsequently multiplied with every newly occupied
          cell's word factor. When the sum has been multiplied with each and
          every of these word factors, the result is also added to the
          player's points.
        </p>
        <p>
          The winner is the player with the most points in the end.
          But the end of the game is just beginning to be implemented. 
          This will change.
        </p>
        <p>
          Have fun!
        </p>
        </sect1>

      </sect>
    </chapt>

  </book></debiandoc>
