<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY legal SYSTEM "legal.xml">
]>
<book id="index" lang="en">
  <title>Pioneers player's guide</title>
  <bookinfo><authorgroup><author><firstname>Dave</firstname><surname>Cole</surname></author><author><firstname>Andy</firstname><surname>Heroff</surname></author></authorgroup><authorgroup><author><firstname>Roland</firstname><surname>Clobus</surname></author></authorgroup><releaseinfo>Documentation in progress</releaseinfo><copyright><year>2000</year><holder>Andy Heroff</holder></copyright><copyright><year>2004-2013</year><holder>Roland Clobus</holder></copyright>
    &legal;
  </bookinfo>
  <part id="players">
    <title>For players</title>
    <preface id="introduction">
      <title>Introduction</title>
      <simplesect id="download">
        <title>Obtaining newer versions</title>
        <para>
        New versions of Pioneers are regularly made available.
        See the <ulink url="http://pio.sourceforge.net">homepage</ulink>
        for latest version.
      </para>
      </simplesect>
      <simplesect id="bugs">
        <title>Reporting Bugs</title>
        <para>
        If you encounter a bug, report it with the bug tracker on SourceForge. 
        (<ulink url="http://sourceforge.net/p/pio/bugs/">
         http://sourceforge.net/p/pio/bugs/
        </ulink>). Please check first if you have the latest version.
      </para>
      </simplesect>
      <simplesect id="Authors">
        <title>Authors and History</title>
        <para>
        Pioneers is a GNOME game based upon the board game Settlers of Catan
        created by Mayfair Games. Pioneers was originally authored by Dave
        Cole in the spring and summer of 1999, under the name Gnocatan.
	Dave wanted to be able to
        play the game without having to travel, so he developed a computer
        implementation of the game. The Pioneers project stalled in the late
        summer of 1999 and saw little development until the early spring of
        2000 when the project was taken over by Andy Heroff and moved to
        SourceForge. Andy recruited several developers (including Dave) and
        they improved upon the original game as well as
        fixed bugs that have been found in older versions.
      </para>
        <para>
        After summer 2002 the Pioneers project lay dormant again, when 
	in summer 2003 Bas
	Wijnen found some security bugs, and started programming new features.
	A little later he was joined by Roland Clobus. Bas made the split 
	between the core code and the user interface, while Roland was working
	on the user interface.
      </para>
        <para>
        In June 2005 the project was renamed from Gnocatan to Pioneers.
      </para>
        <para>
        To be continued...
      </para>
      </simplesect>
    </preface>
    <chapter id="pioneers_ui">
      <title>The Pioneers user interface</title>
      <para>When you start <application>Pioneers</application>, the main
      window is displayed.  The user interface is built up from a
      number of panels.</para>
      <figure id="pioneers-FIG-clientui">
        <title>The client user interface</title>
        <screenshot>
          <graphic fileref="images/client.png"/>
        </screenshot>
      </figure>
      <sect1 id="identity">
        <title>The identity panel</title>
        <para>Before you have connected to a server, this panel will not
	be displayed.  Once you have connected, the panel is painted
        with your player color.  It also shows how many roads,
        settlements, and cities are still available to be
        built.</para>
        <para>Once the game play starts, the last dice roll performed by
        a player is also displayed.</para>
        <figure id="pioneers-FIG-identity">
          <title>The identity panel</title>
          <screenshot>
            <graphic fileref="images/identity.png"/>
          </screenshot>
        </figure>
      </sect1>
      <sect1 id="actions">
        <title>The actions panel</title>
        <sect2 id="waiting_prompt">
          <title>The waiting prompt</title>
          <para>When it is not your turn, a message is displayed in the
	status line at the very bottom for whom the game is waiting.</para>
        </sect2>
        <sect2 id="actions_buttons">
          <title>The actions buttons</title>
          <para>When it is your turn, one more more of the buttons in
	  the action toolbar are active.
	  Only the actions that you are allowed to perform will be
	  enabled.</para>
          <figure id="pioneers-FIG-actions">
            <title>The actions buttons</title>
            <screenshot>
              <graphic fileref="images/actions.png"/>
            </screenshot>
          </figure>
          <table id="pioneers-TBL-actions">
            <title>Action panel buttons</title>
            <tgroup cols="2">
              <thead>
                <row>
                  <entry>Button</entry>
                  <entry>Description</entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry>Roll Dice</entry>
                  <entry>Roll the dice to start your turn.</entry>
                </row>
                <row>
                  <entry>Trade</entry>
                  <entry>Perform trade with either the bank (maritime),
		  or with other players (domestic).</entry>
                </row>
                <row>
                  <entry>Undo</entry>
                  <entry>You can undo road, settlement,
		  and city building that has just been performed.  As
		  soon as you buy a development card, play a development
		  card, or finish your turn, you will not be able to
		  undo building.</entry>
                </row>
                <row>
                  <entry>Finish</entry>
                  <entry>Indicate that you have finished performing setup,
		  your turn, or road building.</entry>
                </row>
                <row>
                  <entry>Road</entry>
                  <entry>Build a road segment. It must join one of your own
		  settlements or cities, or one of your own roads. It can be
		  built on land or on the coast.
		</entry>
                </row>
                <row>
                  <entry>Ship</entry>
                  <entry>Build a ship. It must join one of your own settlements
		  or cities at the coast, or one of your own ships.
                  It can be built on water or on the coast.
		</entry>
                </row>
                <row>
                  <entry>Move Ship</entry>
                  <entry>Move a ship that is at the end of the line to another
		  place.
		</entry>
                </row>
                <row>
                  <entry>Bridge</entry>
                  <entry>Build a bridge. It must join one of you own settlements
		  or cities on the coast, one of your own bridges, or a road.
                  It can only be built on water.
		</entry>
                </row>
                <row>
                  <entry>Settlement</entry>
                  <entry>Build a settlement.</entry>
                </row>
                <row>
                  <entry>City</entry>
                  <entry>Upgrade a settlement to a city.</entry>
                </row>
                <row>
                  <entry>Develop</entry>
                  <entry>Purchase a development card from the bank.</entry>
                </row>
                <row>
                  <entry>City Wall</entry>
                  <entry>Build a wall around a city. Each city can have at most
                  one wall. For each wall you are allowed to keep two more
                  resource cards when a seven is thrown.</entry>
                </row>
              </tbody>
            </tgroup>
          </table>
        </sect2>
        <sect2 id="robber_prompt">
          <title>The robber prompt</title>
          <para>If you roll 7 on the dice, all players who are holding
	  more than 7 resources will be prompted to discard half of
	  them (rounded down).  While there are still players who have to
          discard resources, the actions panel will be replaced by a list of
	  those players.  Next to each player name is the number of
	  resources that they must discard.</para>
          <figure id="pioneers-FIG-discards">
            <title>The discard list</title>
            <screenshot>
              <graphic fileref="images/discards.png"/>
            </screenshot>
          </figure>
        </sect2>
        <sect2 id="place_robber_prompt">
          <title>The place robber prompt</title>
          <para>After all excess resources have been discarded, if you
	  were the player who rolled 7 on the dice, you must place the
	  robber on the map.  The actions panel is replaced by a
	  prompt to that effect.</para>
          <para>When you play a soldier development card, you must place
	  the robber on the map.  The actions panel is replaced by a
	  prompt to that effect.</para>
          <figure id="pioneers-FIG-place-robber">
            <title>The place robber prompt</title>
            <screenshot>
              <graphic fileref="images/place-robber.png"/>
            </screenshot>
          </figure>
        </sect2>
        <sect2 id="steal_prompt">
          <title>The steal from prompt</title>
          <para>If you ever place the robber on a hex which has
	  buildings owned by more than one other player, and more than
	  one of them is holding resources, you will need to select
	  the player from which you wish to steal resources.  The
	  actions panel will be replaced by a prompt which instructs
	  you to chose the victim of the robber by selecting one of
	  the buildings on the hex.</para>
          <figure id="pioneers-FIG-steal-from">
            <title>The steal from prompt</title>
            <screenshot>
              <graphic fileref="images/steal-from.png"/>
            </screenshot>
          </figure>
        </sect2>
      </sect1>
      <sect1 id="resources">
        <title>The resources panel</title>
        <para>As the game progresses you will accumulate resources.  The
	resources panel displays how many of each resource type you
	are holding.</para>
        <figure id="pioneers-FIG-resources">
          <title>The resources panel</title>
          <screenshot>
            <graphic fileref="images/resources.png"/>
          </screenshot>
        </figure>
      </sect1>
      <sect1 id="develop-cards">
        <title>The development cards panel</title>
        <para>If you spend the right combination of resources, you can
	purchase development cards from the bank.  All of the
	development cards that you are currently holding are displayed
	in this list.  Note that any cards in this list are not yet in
	play.  Other players only know how many development cards you
	are holding, not the types of those cards.  Once you play a
	development card, it will be removed from this list.</para>
        <figure id="pioneers-FIG-develop-cards">
          <title>The development cards panel</title>
          <screenshot>
            <graphic fileref="images/develop-cards.png"/>
          </screenshot>
        </figure>
      </sect1>
      <sect1 id="player-summary">
        <title>The player summary panel</title>
        <para>This panel contains a summary of public statistics about
	all players in the game.  Some of the rows in the summary have
	a number displayed on the right.  This number represents the
	number of victory points that have been earned by that
	statistic.</para>
        <para>If the panel grows too large to fit in the available
	space, it will automatically scroll to display the summary
	about the current player.</para>
        <figure id="pioneers-FIG-player-summary">
          <title>The player summary panel</title>
          <screenshot>
            <graphic fileref="images/player-summary.png"/>
          </screenshot>
        </figure>
      </sect1>
      <sect1 id="map">
        <title>The Pioneers map</title>
        <figure id="pioneers-FIG-map">
          <title>The Pioneers map</title>
          <screenshot>
            <graphic fileref="images/map.png"/>
          </screenshot>
        </figure>
        <para>Pioneers is played on a map which is built up from a grid
        of terrain hexes.  Each hex on the map has a terrain type
        which defines the resources, if any, that are produced by that
        hex.</para>
        <para>Settlements and cities are built on the corners of land
        hexes, while roads are built along the edges of land
        hexes.</para>
        <para>In the center of resource producing hexes, there is a
        circle containing a number.  At the start of each turn, two
        dice are rolled, all hexes that are labeled with a number
        equaling the sum of the two dice will produce resources for
        buildings on that hex.  Underneath the number in the circle
        are some dots.  The number of dots is equal to the number of
        different dice combinations that will generate this number.
        To highlight the two most commonly rolled numbers, the 6 and 8
        are displayed in red (there is no label with the number 7).
        In addition, the hexes that produced resources this turn are
        painted with a green background.</para>
        <para>The sea hexes which have a circle in them have building
        sites for ports where maritime trading can be performed. The
        location of the building sites is indicated by a dashed line
        drawn from the circle to a hex corner. The image in the circle
        indicates the resource type which may be traded at the ports.
        At the blue circles all resource types can be traded.</para>
        <para>The brown bottle shape is the robber.</para>
        <para>The following table shows each terrain type, and the resources
        produced by that terrain.</para>
        <table id="pioneers-TBL-terrain-types">
          <title>Pioneers terrain types</title>
          <tgroup cols="5">
            <colspec colnum="1" align="center"/>
            <colspec colnum="2" align="left"/>
            <colspec colnum="3" align="center"/>
            <colspec colnum="4" align="left"/>
            <colspec colnum="5" align="left"/>
            <thead>
              <row>
                <entry>Graphic</entry>
                <entry>Terrain</entry>
                <entry>Graphic</entry>
                <entry>Resource</entry>
                <entry>Description</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>
                  <inlinegraphic fileref="images/hill.png"/>
                </entry>
                <entry>Hill</entry>
                <entry>
                  <inlinegraphic fileref="images/brick.png"/>
                </entry>
                <entry>Brick</entry>
                <entry>Bricks are produced from the clay found in
	        hills.</entry>
              </row>
              <row>
                <entry>
                  <inlinegraphic fileref="images/field.png"/>
                </entry>
                <entry>Field</entry>
                <entry>
                  <inlinegraphic fileref="images/grain.png"/>
                </entry>
                <entry>Grain</entry>
                <entry>Grain is produced by crops grown in
	        fields.</entry>
              </row>
              <row>
                <entry>
                  <inlinegraphic fileref="images/mountain.png"/>
                </entry>
                <entry>Mountain</entry>
                <entry>
                  <inlinegraphic fileref="images/ore.png"/>
                </entry>
                <entry>Ore</entry>
                <entry>Ore is produced by quarries in mountains.</entry>
              </row>
              <row>
                <entry>
                  <inlinegraphic fileref="images/pasture.png"/>
                </entry>
                <entry>Pasture</entry>
                <entry>
                  <inlinegraphic fileref="images/wool.png"/>
                </entry>
                <entry>Wool</entry>
                <entry>Wool is produced by sheep in pastures.</entry>
              </row>
              <row>
                <entry>
                  <inlinegraphic fileref="images/forest.png"/>
                </entry>
                <entry>Forest</entry>
                <entry>
                  <inlinegraphic fileref="images/lumber.png"/>
                </entry>
                <entry>Lumber</entry>
                <entry>Lumber is produced by trees in forests.</entry>
              </row>
              <row>
                <entry>
                  <inlinegraphic fileref="images/gold.png"/>
                </entry>
                <entry>Gold mine</entry>
                <entry/>
                <entry>Any</entry>
                <entry>Any resource can be bought from the mined gold.</entry>
              </row>
              <row>
                <entry>
                  <inlinegraphic fileref="images/desert.png"/>
                </entry>
                <entry>Desert</entry>
                <entry/>
                <entry/>
                <entry>No resources are produced in the desert.</entry>
              </row>
              <row>
                <entry>
                  <inlinegraphic fileref="images/sea.png"/>
                </entry>
                <entry>Sea</entry>
                <entry/>
                <entry/>
                <entry>No resources are produced in the sea, but
	        maritime trading may be performed at ports.</entry>
              </row>
            </tbody>
          </tgroup>
        </table>
      </sect1>
      <sect1 id="chat">
        <title>The chat panel</title>
        <para>Underneath the map is a field where you can enter
	messages that will be broadcast to all other players.  When
	you type a message and press <keycap>Return</keycap>, the
	message will be broadcast to all players.</para>
        <figure id="pioneers-FIG-chat">
          <title>The chat panel</title>
          <screenshot>
            <graphic fileref="images/chat.png"/>
          </screenshot>
        </figure>
        <para>Normally, text that you type will appear with your player
	name, for example "<computeroutput>player1 said:
	foo</computeroutput>". If you start your text with
	"<userinput>:</userinput>" the output will omit the "said",
	like "<computeroutput>player1 needs more
	lumber</computeroutput>".</para>
        <para>The chat also knows some special commands that start with
      "<userinput>/</userinput>". The commands currently defined are:</para>
        <table id="pioneers-TBL-chatcommands">
          <title>Chat Commands</title>
          <tgroup cols="3">
            <thead>
              <row>
                <entry>Command</entry>
                <entry>Arguments</entry>
                <entry>Description</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>
                  <userinput>;</userinput>
                </entry>
                <entry>chat message</entry>
                <entry>The chat message is added directly behind the name of
	        the player.
		Example: <userinput>;'s victory is imminent</userinput>
		will become <quote>player name's victory is imminent</quote>
	      </entry>
              </row>
              <row>
                <entry>
                  <userinput>:</userinput>
                </entry>
                <entry>chat message</entry>
                <entry>The chat message is added after the name of the player
	        with a space in between.
		Example: <userinput>:needs lumber</userinput> will become
		<quote>player name needs lumber</quote>
	      </entry>
              </row>
              <row>
                <entry>
                  <userinput>/me</userinput>
                </entry>
                <entry>chat message</entry>
                <entry>This is the same as the
	      "<userinput>:</userinput>" described above, but IRC
	      addicts might prefer this variant.</entry>
              </row>
              <row>
                <entry>
                  <userinput>/beep</userinput>
                </entry>
                <entry>
                  <replaceable>player name</replaceable>
                </entry>
                <entry>Let <replaceable>player name</replaceable>'s client
	      beep.</entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>If you want to send a smiley that starts with a <symbol>:</symbol>
        or <symbol>;</symbol>, type a <symbol>space</symbol> before the smiley.
      </para>
      </sect1>
      <sect1 id="messages">
        <title>The messages panel</title>
        <para>Underneath the chat panel is a message area where all
        interesting game events are logged.</para>
        <figure id="pioneers-FIG-messages">
          <title>The messages panel</title>
          <screenshot>
            <graphic fileref="images/messages.png"/>
          </screenshot>
        </figure>
      </sect1>
      <sect1 id="statusbar">
        <title>The status bar</title>
        <para>The status bar is used for providing instructions about
        the current state of the game.</para>
        <para>To the right of the instructional message is an indicator
        which shows when the client program is waiting for response to
        a command sent to the server.  When packets are dropped
        between the server and client, the indicator will display the
        text "Waiting", and the game will be temporarily
        unresponsive.</para>
        <para>Rightmost in the status bar is the turn indicator.  This
        area identifies the player turn sequence.  The current player
        is highlighted with a thick black border.</para>
        <figure id="pioneers-FIG-status">
          <title>The status bar</title>
          <screenshot>
            <graphic fileref="images/status.png"/>
          </screenshot>
        </figure>
      </sect1>
    </chapter>
    <chapter id="playing">
      <title>Playing Pioneers</title>
      <sect1 id="joining">
        <title>Joining a Pioneers game</title>
        <para>The Pioneers client program is
        "<application>pioneers</application>". When you run this
        program, you will be presented with the connect dialog.</para>
        <sect2 id="connect-dialog">
          <title>The connect dialog</title>
          <para>Using the connect dialog, you identify the game which
          you wish to join. This dialog is automatically invoked when
          you start Pioneers. If the initial
          connection fails, you can invoke the dialog from the
          <menuchoice><guimenu>Game</guimenu><guimenuitem>New game</guimenuitem></menuchoice>
	  menu, or by using the
          <keycombo><keycap>Ctrl</keycap><keycap>N</keycap></keycombo>
          keyboard shortcut.</para>
          <figure id="pioneers-FIG-connect-dialog">
            <title>The connect dialog</title>
            <screenshot>
              <graphic fileref="images/connect-dialog.png"/>
            </screenshot>
          </figure>
          <para>Enter your name, and join an existing game or create a
	new game.</para>
          <para>Only if <application>pioneers-server-gtk</application> is
	 installed, you can create new games.</para>
        </sect2>
        <sect2 id="server-dialog">
          <title>Join public game</title>
          <para>The dialog displays a list of Pioneers games
          that are currently running on the Internet. The default
	  metaserver is <symbol>pioneers.debian.net</symbol></para>
          <figure id="pioneers-FIG-servers-dialog">
            <title>The Join a public game dialog</title>
            <screenshot>
              <graphic fileref="images/servers-dialog.png"/>
            </screenshot>
          </figure>
          <para>You join a game by selecting it and pressing the OK
          button in the connect dialog. To obtain an updated list, push
	  the Refresh button.</para>
          <para>Enter the 'Lobby' to meet other players and arrange that
          one player will start the server with the game you've agreed
          upon.</para>
          <para>Some metaservers also allow you to start new games
	  on their host (e.g. <symbol>pioneers.game-host.org</symbol>).
          If this is possible, the New remote game button will be active
          and will bring you to the Create a public game dialog.</para>
        </sect2>
        <sect2 id="server-create-dialog">
          <title>The Create a public game dialog</title>
          <para>In this dialog, you can select various parameters for
	  the new game: board name (available types will be retrieved
	  from the metaserver), the number of players, victory points
	  to reach, how many computer players should join the game,
          which sevens rule to apply and whether the terrain should be
          randomized.</para>
          <figure id="pioneers-FIG-server-create">
            <title>The Create a public game dialog</title>
            <screenshot>
              <graphic fileref="images/server-create.png"/>
            </screenshot>
          </figure>
          <para>Once you're satisfied with your choices, press the OK
        button. The game will be started once enough players have
	entered the game. The new game will of course be 
        registered to the metaserver it was started from. Other players
	can see it in the list if they press the Join public game button,
	or refresh the list of public games.</para>
          <para>The server started remotely will terminate itself
        automatically when the game is finished, or if sits around for
        more than 20 minutes without any connected players. Please
        also note that adding computer players will silently fail if the
        <application>pioneersai</application> program is not installed
        on the metaserver.</para>
        </sect2>
        <sect2>
          <title>Join private game</title>
          <para>You can manually specify the game that you wish to join
          by entering the server host and port in the Server Host and
          Server Port fields. The hostname/port combinations you used
          recently are remembered. You can recall them quickly with the Recent
          Games button at the bottom.</para>
          <figure id="pioneers-FIG-join-private-game">
            <title>The Join a private game dialog</title>
            <screenshot>
              <graphic fileref="images/join-private-dialog.png"/>
            </screenshot>
          </figure>
        </sect2>
      </sect1>
      <sect1 id="setup">
        <title>Pioneers setup phase</title>
        <para>Once you have successfully connected to a Pioneers game
        server, the game map will be downloaded from the server and
        displayed in the map area of the display.  You will be
        assigned a player color, which will be displayed in the
        identity panel, the player summary, and in the status bar.  As
        soon as all other players have connected to the server, the
        setup phase will begin.</para>
        <para>During the setup phase you must build one settlement and
        one road segment on the map.  The settlement can be built on
        any land hex, and the road must be built on a land edge
        connected to the settlement.</para>
        <para>Once you have built both your settlement and road, you
        must press the Finish Setup button.  The next player will then
        enter the setup phase.  The last player performs a double
        setup, that is, they build two settlements, each with a
        connecting road.  Once the last player has completed setup,
        all other players perform a second setup in reverse
        sequence.</para>
        <para>Once the first player has completed their second setup,
        the game will begin.</para>
      </sect1>
      <sect1 id="turn">
        <title>Pioneers turn sequence</title>
        <para>When it is your turn, the actions panel will show all of
        the actions that you can perform.  Some care must be
        exercised, as some actions can only be performed once per
        turn, and other actions can only be performed in strict
        sequence.</para>
        <procedure id="pioneers-turn-sequence">
          <title>Simplified turn sequence</title>
          <step>
            <para>Roll the dice.</para>
          </step>
          <step>
            <para>Optionally trade with the bank, or other
      	    players.</para>
          </step>
          <step>
            <para>Optionally build roads, settlements, and cities.
      	    Optionally buy development cards.</para>
          </step>
          <step>
            <para>Finish your turn.</para>
          </step>
        </procedure>
        <para>You may play one non-victory point development card at any
        time during your turn, even before you roll the dice.  You
        may play as many victory point cards as you like at any time
        during your turn.</para>
        <para>As soon as you have built a road, settlement, or city, you
        will not be able to trade for the rest of the turn.  Likewise,
        if you buy a development card, you will not be able to trade
        for the rest of the turn.</para>
        <sect2 id="pioneers-dice-roll">
          <title>Dice roll / resource collection</title>
          <para>When the dice are rolled, they are added together,
	  the total determines the resources that each player collects
	  during that turn.  In the center of each land hex (except
	  for the desert) is a number.  Whenever the dice roll matches
	  the number in the hex, all buildings on the corners of that
	  hex will collect resources of the type generated by that
	  hex.</para>
          <para>Settlements collect one resource, and cities receive two
	  resources.  If a player has multiple buildings on a hex,
	  each of those buildings will collect resources.</para>
          <para>The hex containing the robber never generates
	  resources.</para>
          <para>If you roll 7 on the dice, all players with excess
	  resources must discard them, then you must move the
	  robber.</para>
        </sect2>
        <sect2 id="discarding_resources">
          <title>Discarding resources</title>
          <para>If you roll 7 on the dice, all players holding more than
	  7 resources must discard half of them.  The discard
	  resources dialog will be displayed for all players who must
	  discard.</para>
          <figure id="pioneers-FIG-discard-dialog">
            <title>The discard dialog</title>
            <screenshot>
              <graphic fileref="images/discard-dialog.png"/>
            </screenshot>
          </figure>
          <para>You must choose the resources to be given back to the
	  bank.</para>
          <para>Once all players have discarded their excess resources,
	  the player who rolled the 7 will have to move the
	  robber.</para>
        </sect2>
        <sect2 id="moving_robber">
          <title>Moving the robber</title>
          <para>The robber begins the game in the desert, but can never
	  be moved back into the desert.</para>
          <para>If you roll 7 on the dice, you must move the robber to a
	  new location on the map.</para>
          <para>Whenever you play a soldier development card, you must
	  move the robber to a new location on the map.</para>
          <para>Once you have moved the robber to a new hex, the robber
	  will steal a random resource from another player who has a
	  building on that hex.  If there are multiple potential
	  victims for the robber, you will need to choose the victim
	  by selecting one of the buildings on the hex.  When the
	  robber steals the resource, only the players involved in the
	  transaction will be told which resource was stolen.</para>
        </sect2>
      </sect1>
      <sect1 id="trade">
        <title>Trade</title>
        <para>You may trade resources only after you have rolled the
	  dice, but before you build anything, or buy a development
	  card.  When you wish to trade resources, press the Trade
	  button in the actions panel and the trade interface will be
	  displayed.</para>
        <figure id="pioneers-FIG-trade">
          <title>The trade interface</title>
          <screenshot>
            <graphic fileref="images/trade.png"/>
          </screenshot>
        </figure>
        <para>On the left side of the interface are two tables; the
	  top table is where you specify which resources you wish to
	  receive in a trade, and the bottom table is where you
	  optionally specify which resources you wish to give to other
	  players during a trade.</para>
        <para>Each row of the table describes one resource.
          From left to right, the columns are:</para>
        <table id="pioneers-TBL-resource-controls">
          <title>Trade resource controls</title>
          <tgroup cols="2">
            <tbody>
              <row>
                <entry>Check</entry>
                <entry>Controls whether or not this resource will be
	    	  involved in the trade.  Trade quotes submitted by
	    	  either the bank or other players can only include
	    	  resource types that are checked.</entry>
              </row>
              <row>
                <entry>Name</entry>
                <entry>The resource type.</entry>
              </row>
              <row>
                <entry>In hand</entry>
                <entry>Shows how many of each resource type you have
	    	  in hand. If you select a valid trade, you see the
                  amount you will have if you accept the quote.</entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>The Call for Quotes button underneath the two tables is
	  used to invite other players to trade resources with
	  you.</para>
        <para>To the right of the tables is the list where all quotes
	  will be displayed.  The bank quotes are listed first,
	  followed by all quotes supplied by other players.
	  Next to each quote is tick or cross which indicates
	  whether or not you have the resources to perform the trade.
	  As you select quotes from the list, the Accept Quote button
	  sensitivity will also indicate whether or not you have the
	  resources required to perform the trade. Also the amount
	  of each resource shows a preview how many you will have
	  if you accept the quote.</para>
        <para>To finish trading, press the Finish Trading button at
	  the bottom right of the trading interface.</para>
        <sect2 id="bank_trading">
          <title>Trading with the bank</title>
          <para>Maritime trade is trade performed with the bank.  To
	    perform maritime trading, check one or more resources in
	    the I Want table.  If you have sufficient resources to
	    perform maritime trading, the bank will quote for each
	    possible trade. You don't have to press the Call for
            Quotes button.</para>
          <itemizedlist id="pioneers-bank-trading-procedure">
            <listitem>
              <para>Players who have built on a port with a resource
	  	label may trade two identical resources of that type
	  	for single resource of their choice.</para>
            </listitem>
            <listitem>
              <para>Players who have built on a port with the question
	  	mark label may trade three identical resources of any
	  	type for single resource of their choice.</para>
            </listitem>
            <listitem>
              <para>All players may trade four identical resources of
	  	any type for a single resource of their choice.</para>
            </listitem>
          </itemizedlist>
          <para>Select the trade that you wish to perform, then press
	    the Accept Quote button.</para>
        </sect2>
        <sect2 id="trading_players">
          <title>Trading with other players</title>
          <para>Domestic trade is trade performed with other players.
	    To perform domestic trading, check one or more resources
	    in the I Want table, and one or more resources in the Give
	    Them table.  Once you have specified the resources that
	    you wish to exchange in the trade, click the Call For
	    Quotes button.  All other players will then use the quote
	    interface to submit quotes within the trade parameters you
	    have set.</para>
          <para>Select the trade that you wish to perform, then press
	    the Accept Quote button.</para>
        </sect2>
        <sect2 id="trade_quote_submit">
          <title>Submitting trade quotes</title>
          <para>When another player presses the Call For Quotes button
	    in the trade interface, the quote interface will be
	    displayed.</para>
          <figure id="pioneers-FIG-quote">
            <title>The quote interface</title>
            <screenshot>
              <graphic fileref="images/quote.png"/>
            </screenshot>
          </figure>
          <para>The top of the interface has an indicator to show
	    which player initiated the trade.  It also describes the
	    trade parameters.</para>
          <para>On the left side of the interface are two tables; the
	    top table is where you specify which resources you wish to
	    receive in a trade, and the bottom table is where you
	    specify which resources you wish to give to the player who
	    initiated the trade exchange.</para>
          <para>Each row of the table
	    describes one resource.  The player who initiated the
	    trade controls which rows in each table can be used.  If
	    the initiating player calls for a resource that you do not
	    have, the corresponding row in the Give Them table will be
	    disabled.  From left to right, the columns are:</para>
          <table id="pioneers-TBL-quote-controls">
            <title>Quote resource controls</title>
            <tgroup cols="2">
              <tbody>
                <row>
                  <entry>Name</entry>
                  <entry>The resource type.</entry>
                </row>
                <row>
                  <entry>In hand</entry>
                  <entry>Shows how many of each resource type you will
	  	    have in hand after performing trade.</entry>
                </row>
                <row>
                  <entry>Less</entry>
                  <entry>Press this to decrease the number of the
	  	    resource you wish to receive / give.</entry>
                </row>
                <row>
                  <entry>More</entry>
                  <entry>Press this to increase the number of the
	  	    resource you wish to receive / give.</entry>
                </row>
                <row>
                  <entry>Number to trade</entry>
                  <entry>Shows how many of the resource you wish to
	  	    trade.</entry>
                </row>
              </tbody>
            </tgroup>
          </table>
          <para>Underneath the tables are two buttons.  Press the
	    Quote button to submit a new quote, or press the Delete
	    button to retract a quote.  Note that the Quote button
	    will be disabled if you have already submitted a matching
	    quote.</para>
          <para>To the right of the tables is the list where all
	    quotes will be displayed.  Quotes from all players are
	    listed. The first quote from each player is highlighted
	    with an indicator.</para>
          <para>To decline the offer to perform trading, press the
	    Reject Domestic Trade button at the bottom right of the
	    interface.</para>
        </sect2>
      </sect1>
      <sect1 id="development">
        <title>Development cards</title>
        <para>There are 24 development cards in the game, they are
	shuffled at the start of the game.  When you buy a development
	card from the bank, it is held secret in your hand.  Other
	players only learn how many development cards you have, not
	the types of those cards.</para>
        <para>When you play a development card, all other players will
	see the card.  There are victory point, and non victory point
	development cards.  Victory point development cards earn you
	one victory point as soon as you play them.  Non-victory point
	development cards have special effects as described
	below.</para>
        <table id="pioneers-TBL-development-cards">
          <title>Development cards</title>
          <tgroup cols="4">
            <colspec colnum="1" align="right"/>
            <colspec colnum="2" align="left"/>
            <colspec colnum="3" align="right"/>
            <colspec colnum="4" align="left"/>
            <thead>
              <row>
                <entry>VP</entry>
                <entry>Card</entry>
                <entry>Number</entry>
                <entry>Description</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry/>
                <entry>Road Building</entry>
                <entry>2</entry>
                <entry>When you play this card, you can build two road
		segments for free.  The normal limits on road building
		apply.</entry>
              </row>
              <row>
                <entry/>
                <entry>Monopoly</entry>
                <entry>2</entry>
                <entry>When you play this card, you choose a resource type
		that you want to monopolize.  All resources of that type
		that are held by other players will transferred to your
		hand.</entry>
              </row>
              <row>
                <entry/>
                <entry>Year of Plenty</entry>
                <entry>2</entry>
                <entry>When you play this card you can take any two
		resource cards from the bank.</entry>
              </row>
              <row>
                <entry/>
                <entry>Soldier</entry>
                <entry>13</entry>
                <entry>When you play this card, you must move the robber
		to a new hex.  The first player to play three soldiers
		will earn the largest army award.</entry>
              </row>
              <row>
                <entry>1</entry>
                <entry>Chapel</entry>
                <entry>1</entry>
                <entry>No special effects.</entry>
              </row>
              <row>
                <entry>1</entry>
                <entry>Pioneer University</entry>
                <entry>1</entry>
                <entry>No special effects.</entry>
              </row>
              <row>
                <entry>1</entry>
                <entry>Governors House</entry>
                <entry>1</entry>
                <entry>No special effects.</entry>
              </row>
              <row>
                <entry>1</entry>
                <entry>Library</entry>
                <entry>1</entry>
                <entry>No special effects.</entry>
              </row>
              <row>
                <entry>1</entry>
                <entry>Market</entry>
                <entry>1</entry>
                <entry>No special effects.</entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <sect2 id="monopolydlg">
          <title>The monopoly development card</title>
          <para>When you play the monopoly development card, the
	  monopoly dialog will be displayed.</para>
          <figure id="pioneers-FIG-monopoly-dialog">
            <title>The monopoly dialog</title>
            <screenshot>
              <graphic fileref="images/monopoly-dialog.png"/>
            </screenshot>
          </figure>
          <para>You must choose the resource type that you wish to
	  monopolize.  When you press OK, all resources of the
	  selected type held by other players will be transferred to
	  your hand.</para>
        </sect2>
        <sect2 id="yearofplentydlg">
          <title>The year of plenty development card</title>
          <para>When you play the year of plenty development card, the
	  year of plenty dialog will be displayed.</para>
          <figure id="pioneers-FIG-plenty-dialog">
            <title>The year of plenty dialog</title>
            <screenshot>
              <graphic fileref="images/plenty-dialog.png"/>
            </screenshot>
          </figure>
          <para>You must select any two resource cards that you wish to
	  take from the bank.</para>
          <para>If the bank has enough cards, <symbol>++</symbol> is shown
	  between the less and more buttons. Otherwise, the amount in the
	  bank is shown.</para>
        </sect2>
        <sect2 id="largest_army">
          <title>Largest army award</title>
          <para>The first player to play three soldier cards will earn
	  the largest army award.  This award is worth 2 victory
	  points.</para>
          <para>Only one player can have the largest army award at a
	  time.</para>
          <para>Ownership of the largest army award will change only
	  when another player builds a larger army.</para>
        </sect2>
      </sect1>
      <sect1 id="building">
        <title>Building</title>
        <para>By spending the right combination of resources, you can
	build roads, settlements, and cities.  At any time during the
	game you can check the resource cost of each type of building
	by consulting the legend dialog.</para>
        <figure id="pioneers-FIG-legend-dialog">
          <title>The legend dialog</title>
          <screenshot>
            <graphic fileref="images/legend-dialog.png"/>
          </screenshot>
        </figure>
        <para>At the start of the game, you have 15 road segments, five
	settlements, and four cities available.  You will not be able
	to build more of any item than you have available.  The
	identity panel tells you how many of each item you currently
	have available.</para>
        <para>A city is built by upgrading a settlement.  When you
	upgrade an existing settlement, that settlement is again
	available for building somewhere else on the map.</para>
        <para>Buildings must not be placed next to each other.  This
	means that a hex can have, at most, three buildings on it.
	During game play, you can only place a building adjacent to
	one of your road segments.</para>
        <para>Roads must be placed adjacent to one of your buildings, or
	one of your roads.  You cannot extend your road through a
	building owned by another player.</para>
        <sect2 id="longest_road">
          <title>Longest road</title>
          <para>The first player to build a continuous path of five or
	  more road segments will earn the longest road award.  The
	  length of your road is measured by determining the greatest
	  distance that can be traveled from one point on your road
	  to another without traveling over the same segment more
	  than once, and without backtracking.</para>
          <para>This award is worth 2 victory points.  Only one player
	  can have the longest road award at a time.</para>
          <para>If another player builds a longer road, the longest road
	  award will be transferred to that player.</para>
          <para>If the longest road is cut by a player placing a
	  building which divides the road, the ownership of the
	  longest road award is re-evaluated.  If after the longest
	  road has been cut, and more than one player has the longest
	  road, the award is temporarily removed from play.  If no
	  player has a road of five or more segments, the award is
	  temporarily removed from play.</para>
        </sect2>
      </sect1>
      <sect1 id="objective">
        <title>Game objective</title>
        <para>The objective of the game is to achieve a certain number
        of victory points before all other players.  There are several
        ways to earn victory points.</para>
        <itemizedlist mark="bullet">
          <listitem>
            <para>For each settlement you have on the map, you earn 1
	    victory point.</para>
          </listitem>
          <listitem>
            <para>For each city you have on the map, you earn 2
	    victory points.</para>
          </listitem>
          <listitem>
            <para>The player with the longest road of five or more
	    segments earns 2 victory points.</para>
          </listitem>
          <listitem>
            <para>The player with the largest number of soldiers in
	    play (minimum of three) earns 2 victory points.</para>
          </listitem>
          <listitem>
            <para>There are a number of special development cards which
	    when played are each worth 1 victory point.</para>
          </listitem>
        </itemizedlist>
        <sect2 id="gameoverdlg">
          <title>The game over dialog</title>
          <para>Once you have won the game, all players will to notified
	  of your glorious victory.</para>
          <figure id="pioneers-FIG-gameover-dialog">
            <title>The game over dialog</title>
            <screenshot>
              <graphic fileref="images/gameover-dialog.png"/>
            </screenshot>
          </figure>
        </sect2>
      </sect1>
    </chapter>
    <chapter id="faq">
      <title>Frequently asked questions</title>
      <qandaset defaultlabel="qanda">
        <qandadiv id="faq_playing_games">
          <title>Playing games</title>
          <qandaentry>
            <question>
              <para>
        Where can I find games?
      </para>
            </question>
            <answer>
              <para>
        You can find games at the metaserver (pioneers.debian.net)
      </para>
            </answer>
          </qandaentry>
          <qandaentry>
            <question>
              <para>
        But there hardly are any games present?
      </para>
            </question>
            <answer>
              <para>Perhaps people don't register their games (it is optional),
        or use their own metaservers.
      </para>
            </answer>
          </qandaentry>
          <qandaentry>
            <question>
              <para>
        I've seen a game at the metaserver, but I cannot join?
      </para>
            </question>
            <answer>
              <para>
        Is the Host something like 'localhost' or without dots? 
        In that case someone did register the game, 
        but it is not accessible from the outside of the intranet that hosts 
        the game.
      </para>
            </answer>
          </qandaentry>
          <qandaentry>
            <question>
              <para>
        I get the error: <quote>Error connecting to host 'AA.BB.CC.DD':
	Connection refused</quote>, what now?
      </para>
            </question>
            <answer>
              <para>The person hosting the game has incorrectly
	configured his firewall. See also 'Creating games'.
      </para>
            </answer>
          </qandaentry>
          <qandaentry>
            <question>
              <para>
        The button '<guibutton>New remote game</guibutton>' is always disabled.
	Why?
      </para>
            </question>
            <answer>
              <para>
        The metaserver at pioneers.debian.net acts only as a point where games
        can register. It has been configured not to create new games.
      </para>
            </answer>
          </qandaentry>
          <qandaentry>
            <question>
              <para>
        How can I play against the computer players, without starting a server?
      </para>
            </question>
            <answer>
              <para>
        You can play games at an alternative metaserver
	<quote>pioneers.game-host.org</quote>. It has a limited number
	of games that can be started. <guibutton>New remote game</guibutton>
	is available on this metaserver.
      </para>
            </answer>
          </qandaentry>
          <qandaentry>
            <question>
              <para>
        The dice are unfair, a twelve was rolled three times in a row!
      </para>
            </question>
            <answer>
              <para>
        The dice have been tested. They are fair, but there is always a chance
	that you'll roll a twelve three times in a row. When you've started a
	server, you can choose to use several dice decks (each of 36 cards)
	instead of regular dice.
      </para>
            </answer>
          </qandaentry>
        </qandadiv>
        <qandadiv id="faq_lobby">
          <title>The Lobby</title>
          <qandaentry>
            <question>
              <para>
        Why is nobody responding?
      </para>
            </question>
            <answer>
              <para>
        If you enter the lobby, and see several squares in the icon before
        the name of a player, it means that that player is disconnected.
      </para>
            </answer>
            <answer>
              <para>
        Perhaps they are playing another game, and don't monitor the Lobby.
      </para>
            </answer>
          </qandaentry>
          <qandaentry>
            <question>
              <para>
        This game will never start. How can I play?
      </para>
            </question>
            <answer>
              <para>
        One person has to create a new game. If it is set up, you can leave
	the lobby, and join that game (<menuchoice><guimenu>Game</guimenu><guimenuitem>Leave game</guimenuitem></menuchoice>).
      </para>
            </answer>
          </qandaentry>
        </qandadiv>
        <qandadiv id="faq_creating_games">
          <title>Creating games</title>
          <qandaentry>
            <question>
              <para>
        How do I do create new games?
      </para>
            </question>
            <answer>
              <para>
        Start <application>pioneers-server-gtk</application>.
        In the <guilabel>Server Parameters</guilabel>:
        <itemizedlist><listitem><para>
            Choose a <guilabel>Server Port</guilabel> that is publicly
	    accessible (create a hole in your firewall if needed)
          </para></listitem><listitem><para>
            Set <guilabel>Register Server</guilabel> to 'yes', so other people
	    can find the game
          </para></listitem><listitem><para>
            Select a <guilabel>Metaserver</guilabel>
          </para></listitem><listitem><para>
            Leave <guilabel>Reported hostname</guilabel> empty
          </para></listitem><listitem><para>
            Select a game of your liking, and click on 
	    <guibutton>Start Server</guibutton>
          </para></listitem></itemizedlist>
      </para>
            </answer>
          </qandaentry>
          <qandaentry>
            <question>
              <para>
        What exactly does '<guilabel>Reported hostname</guilabel>' do?
      </para>
            </question>
            <answer>
              <para>It overrides the hostname that is automatically
        detected by the metaserver.</para>
              <para>Only in special cases do you need to enter something:
	  <itemizedlist><listitem><para>You have an extra DNS name, and would like
	    to show that name instead of your normal DNS name.
	    </para></listitem><listitem><para>You run a private, publicly accessible metaserver,
	      and start a game from inside your local network.
	    </para></listitem></itemizedlist></para>
              <para>In all other cases, you are advised to keep it
	   <emphasis>empty</emphasis>.</para>
            </answer>
          </qandaentry>
          <qandaentry>
            <question>
              <para>
        How do I configure my router?
      </para>
            </question>
            <answer>
              <para>
        You'll need to set up port forwarding and you might want to use a dns
	service like DynDNS. Use a search engine like
	<ulink url="https://duckduckgo.com/?q=configure+router+port+forwarding+dyndns">DuckDuckGo</ulink>
	to see examples.
      </para>
            </answer>
          </qandaentry>
          <qandaentry>
            <question>
              <para>
        What if I only want to play against the computer players?
      </para>
            </question>
            <answer>
              <para>
        Start <application>pioneers-server-gtk</application>,
        and set <guilabel>Register Server</guilabel> to 'no', and add as many
	computer players as needed.
        In the client, choose '<guibutton>Join private game</guibutton>',
	the host is 'localhost',
        and use the port you have selected in the server.
      </para>
            </answer>
            <answer>
              <para>
        You can play games at an alternative metaserver
	<quote>pioneers.game-host.org</quote>. It has a limited number
	of games that can be started.
      </para>
            </answer>
          </qandaentry>
          <qandaentry>
            <question>
              <para>
        What if I only want to play games inside my own intranet?
      </para>
            </question>
            <answer>
              <para>
        Do not register your game at the metaserver, and choose 'Join 
        private game' on each computer that joins the game. Use the ip address
        of the server, and the port you have selected in the server.
      </para>
            </answer>
          </qandaentry>
        </qandadiv>
      </qandaset>
    </chapter>
  </part>
  <part id="gamemasters">
    <title>For game masters</title>
    <chapter id="server">
      <title>The Server</title>
      <para>Pioneers comes with two servers,
	<application>pioneers-server-console</application> and
	<application>pioneers-server-gtk</application>. Some options are
	highlighted here.</para>
      <variablelist>
        <title>Some options</title>
        <varlistentry>
          <term>Domestic trade</term>
          <listitem>
            <para>If this option is disabled, the players cannot trade with
	each other.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Reported hostname</term>
          <listitem>
            <para>Leave empty. It should only be filled when you've set up port
	forwarding. Then it should contain the hostname that is accessible from
	the Internet side.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Strict trade</term>
          <listitem>
            <para>After you have bought or built something, you may not trade
	any more.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>Use dice deck</term>
          <listitem>
            <para>In some games it might happen that the dice rolls are
	distributed unevenly (five times a twelve, no six). A number of decks
	of cards, each deck containing 36 cards (each card representing a dice
	roll), can be used instead of the dice. However, this might lead to
	predictable results when the dice deck has almost been drawn empty.
	The number of removed dice cards specifies the number of cards that are
	removed when the pile of dice cards is shuffled.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </chapter>
    <chapter id="ai">
      <title>The Computer Player</title>
      <para>
      Pioneers comes with a computer player, 
      <application>pioneersai</application>.
      This player isn't too bad at the moment, but doesn't know all game rules.
      Most notably, it cannot initiate domestic trade, and use the maritime
      rules such as ships and bridges.
    </para>
      <para><application>pioneersai</application> is a terminal application
      without GUI. Its command line options are:</para>
      <table id="pioneers-TBL-ai-options">
        <title><application>pioneersai</application> command line options
	</title>
        <tgroup cols="3">
          <thead>
            <row>
              <entry>Option</entry>
              <entry>Arguments</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>-s</entry>
              <entry>
                <replaceable>servername</replaceable>
              </entry>
              <entry>Connect to <replaceable>servername</replaceable>.</entry>
            </row>
            <row>
              <entry>-p</entry>
              <entry>
                <replaceable>port</replaceable>
              </entry>
              <entry>Connect to port <replaceable>port</replaceable>.</entry>
            </row>
            <row>
              <entry>-n</entry>
              <entry>
                <replaceable>name</replaceable>
              </entry>
              <entry>Set the player name.</entry>
            </row>
            <row>
              <entry>-a</entry>
              <entry>
                <replaceable>player type</replaceable>
              </entry>
              <entry>Choose the type of computer player.</entry>
            </row>
            <row>
              <entry>-t</entry>
              <entry>
                <replaceable>milliseconds</replaceable>
              </entry>
              <entry>Set time to wait between turns.</entry>
            </row>
            <row>
              <entry>-c</entry>
              <entry/>
              <entry>Stop the computer player from giving comments.</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <para>
The following player types are available:</para>
      <table id="computer-player-types">
        <title>Computer player types</title>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Player type</entry>
              <entry>Description</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>greedy</entry>
              <entry>The default. This computer player will play against you.</entry>
            </row>
            <row>
              <entry>genetic</entry>
              <entry>This computer player will play against you. It is a stronger opponent than 'greedy'.</entry>
            </row>
            <row>
              <entry>lobbybot</entry>
              <entry>This computer player is present in the lobby to greet you and provide some help. It will not play.</entry>
            </row>
            <row>
              <entry>logbot</entry>
              <entry>This computer player can be added to games to collect statistics about the game. It will not play.</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <para>
      However, most of the time you won't start
      <application>pioneersai</application> manually. Both game
      servers offer ways to start a number of computer players.
    </para>
    </chapter>
    <chapter id="configuration">
      <title>Configuration</title>
      <para>
        This chapter is included for the people who wish to control
        exactly the way <symbol>Pioneers</symbol> is running.
      </para>
      <para>The extra configuration options are processed in this order:</para>
      <orderedlist>
        <listitem>
          <para>Command line</para>
        </listitem>
        <listitem>
          <para>Settings file</para>
        </listitem>
        <listitem>
          <para>Environment</para>
        </listitem>
        <listitem>
          <para>Built-in settings</para>
        </listitem>
      </orderedlist>
      <sect1 id="configuration-client">
        <title>
          <application>pioneers</application>
        </title>
        <para>
          The client is controlled by the command line, the environment
          and the settings file.
	</para>
        <table id="configuration-client-commandline">
          <title><application>pioneers</application> command line options
	  </title>
          <tgroup cols="3">
            <thead>
              <row>
                <entry>Short</entry>
                <entry>Long</entry>
                <entry>Description</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>-s</entry>
                <entry>--server</entry>
                <entry>Hostname of the server</entry>
              </row>
              <row>
                <entry>-p</entry>
                <entry>--port</entry>
                <entry>Port of the server</entry>
              </row>
              <row>
                <entry>-n</entry>
                <entry>--name</entry>
                <entry>Player name</entry>
              </row>
              <row>
                <entry>-v</entry>
                <entry>--spectator</entry>
                <entry>Connect as a spectator</entry>
              </row>
              <row>
                <entry>-m</entry>
                <entry>--metaserver</entry>
                <entry>Metaserver host</entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>
	  When both the server and port are set, the client will not display
	  the connect dialog, but will directly connect to this port.
	  When the connection is closed (because the game is over, or the
	  connection fails), the client quits.
	</para>
        <para>
	  Server and port need both to be set, or not at all.
	</para>
        <table id="configuration-client-settingsfile">
          <title>Settings file <application>$XDG_CONFIG_HOME/pioneers</application></title>
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Section</entry>
                <entry>Key</entry>
                <entry>Type</entry>
                <entry>Description</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>connect</entry>
                <entry>server</entry>
                <entry>string</entry>
                <entry>Last used server for private game</entry>
              </row>
              <row>
                <entry>connect</entry>
                <entry>port</entry>
                <entry>string</entry>
                <entry>Last used port for private game</entry>
              </row>
              <row>
                <entry>connect</entry>
                <entry>metaserver</entry>
                <entry>string</entry>
                <entry>Address of the metaserver</entry>
              </row>
              <row>
                <entry>connect</entry>
                <entry>name</entry>
                <entry>string</entry>
                <entry>Last used player name</entry>
              </row>
              <row>
                <entry>favorites</entry>
                <entry>server%dname</entry>
                <entry>string</entry>
                <entry>History entry of private server games</entry>
              </row>
              <row>
                <entry>favorites</entry>
                <entry>server%dport</entry>
                <entry>string</entry>
                <entry>History entry of private server games</entry>
              </row>
              <row>
                <entry>settings</entry>
                <entry>color_chat</entry>
                <entry>boolean</entry>
                <entry>Display chat messages in user's color</entry>
              </row>
              <row>
                <entry>settings</entry>
                <entry>color_messages</entry>
                <entry>boolean</entry>
                <entry>Display colors in the message log</entry>
              </row>
              <row>
                <entry>settings</entry>
                <entry>color_summary</entry>
                <entry>boolean</entry>
                <entry>Use colors in the summary</entry>
              </row>
              <row>
                <entry>settings</entry>
                <entry>toolbar_show_accelerators</entry>
                <entry>boolean</entry>
                <entry>Show the keyboard accelerators in the toolbar</entry>
              </row>
              <row>
                <entry>settings</entry>
                <entry>show_toolbar</entry>
                <entry>boolean</entry>
                <entry>Show the toolbar</entry>
              </row>
              <row>
                <entry>settings</entry>
                <entry>legend_page</entry>
                <entry>boolean</entry>
                <entry>Display the legend page beside the map</entry>
              </row>
              <row>
                <entry>settings</entry>
                <entry>theme</entry>
                <entry>string</entry>
                <entry>The theme</entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <table id="configuration-client-environment">
          <title><application>pioneers</application> environment</title>
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Variable</entry>
                <entry>Description</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>PIONEERS_METASERVER</entry>
                <entry>The host name of the metaserver</entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>
          When the host name is not provided in the client, this environment
	  variable will be used. If it is not set, the default
	  (<symbol>pioneers.debian.net</symbol>) will be used.
	</para>
      </sect1>
      <sect1 id="configuration-server">
        <title>
          <application>pioneers-server-console</application>
        </title>
        <table id="configuration-server-console-commandline">
          <title><application>pioneers-server-console</application>
            command line</title>
          <tgroup cols="3">
            <thead>
              <row>
                <entry>M</entry>
                <entry>Short</entry>
                <entry>Long</entry>
                <entry>Type</entry>
                <entry>Description</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry/>
                <entry>-h</entry>
                <entry>--help-all</entry>
                <entry/>
                <entry>Show help</entry>
              </row>
              <row>
                <entry>*</entry>
                <entry>-r</entry>
                <entry>--register</entry>
                <entry/>
                <entry>Register with metaserver</entry>
              </row>
              <row>
                <entry/>
                <entry>-m</entry>
                <entry>--metaserver</entry>
                <entry>string</entry>
                <entry>Register at metaserver name (implies -r)</entry>
              </row>
              <row>
                <entry/>
                <entry>-n</entry>
                <entry>--hostname</entry>
                <entry>string</entry>
                <entry>Use this hostname when registering at the metaserver</entry>
              </row>
              <row>
                <entry>*</entry>
                <entry>-x</entry>
                <entry>--auto-quit</entry>
                <entry/>
                <entry>Quit after a player has won</entry>
              </row>
              <row>
                <entry>*</entry>
                <entry>-k</entry>
                <entry>--empty-timeout</entry>
                <entry>integer</entry>
                <entry>Kill after <symbol>n</symbol> seconds with no player</entry>
              </row>
              <row>
                <entry/>
                <entry>-t</entry>
                <entry>--tournament</entry>
                <entry>integer</entry>
                <entry>Tournament mode. Computer players are added after %d minutes</entry>
              </row>
              <row>
                <entry/>
                <entry>-a</entry>
                <entry>--admin-port</entry>
                <entry>integer</entry>
                <entry>Admin port to listen on</entry>
              </row>
              <row>
                <entry/>
                <entry>-s</entry>
                <entry>--admin-wait</entry>
                <entry/>
                <entry>Don't start game immediately, wait for command on admin port</entry>
              </row>
              <row>
                <entry/>
                <entry/>
                <entry>--fixed-seating-order</entry>
                <entry/>
                <entry>Give players numbers according to the order they enter
                  the game</entry>
              </row>
              <row>
                <entry/>
                <entry/>
                <entry>--debug</entry>
                <entry/>
                <entry>Enable debug messages</entry>
              </row>
              <row>
                <entry>*</entry>
                <entry>-g</entry>
                <entry>--game-title</entry>
                <entry>string</entry>
                <entry>Game name to use</entry>
              </row>
              <row>
                <entry/>
                <entry/>
                <entry>--file</entry>
                <entry>string</entry>
                <entry>Game file to use</entry>
              </row>
              <row>
                <entry>*</entry>
                <entry>-p</entry>
                <entry>--port</entry>
                <entry>string</entry>
                <entry>Port to listen on</entry>
              </row>
              <row>
                <entry>*</entry>
                <entry>-P</entry>
                <entry>--players</entry>
                <entry>integer</entry>
                <entry>Number of players</entry>
              </row>
              <row>
                <entry>*</entry>
                <entry>-v</entry>
                <entry>--point</entry>
                <entry>integer</entry>
                <entry>Number of points needed to win</entry>
              </row>
              <row>
                <entry/>
                <entry>-R</entry>
                <entry>--seven-rule</entry>
                <entry>0|1|2</entry>
                <entry>Seven rule</entry>
              </row>
              <row>
                <entry>*</entry>
                <entry>-T</entry>
                <entry>--terrain</entry>
                <entry>0|1</entry>
                <entry>Select terrain type (0=default, 1=random)</entry>
              </row>
              <row>
                <entry>*</entry>
                <entry>-c</entry>
                <entry>--computer-players</entry>
                <entry>integer</entry>
                <entry>Number of computer players to add</entry>
              </row>
              <row>
                <entry/>
                <entry/>
                <entry>--version</entry>
                <entry/>
                <entry>Show version information</entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>
          The column 'M' shows whether the switch is used by the metaserver
        </para>
        <table id="configuration-server-console-environment">
          <title><application>pioneers-server-console</application>
	    environment</title>
          <tgroup cols="2">
            <thead>
              <row>
                <entry>Variable</entry>
                <entry>Description</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>PIONEERS_DIR</entry>
                <entry>The location of the *.game files and the computer_names file</entry>
              </row>
              <row>
                <entry>PIONEERS_METASERVER</entry>
                <entry>The host name of the metaserver</entry>
              </row>
            </tbody>
          </tgroup>
        </table>
      </sect1>
    </chapter>
    <chapter id="server-admin-interface">
      <title>Server admin interface protocol</title>
      <para>
          When the server is started with the command line switch 
          <userinput>-a</userinput>, the following commands can be
          sent to that port:
        </para>
      <table id="configuration-server-console-admin">
        <title>Admin interface commands</title>
        <tgroup cols="2">
          <thead>
            <row>
              <entry>Command</entry>
              <entry>Argument type</entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry>
                <userinput>admin set-port</userinput>
              </entry>
              <entry>integer</entry>
            </row>
            <row>
              <entry>
                <userinput>admin start-server</userinput>
              </entry>
              <entry>none</entry>
            </row>
            <row>
              <entry>
                <userinput>admin stop-server</userinput>
              </entry>
              <entry>none</entry>
            </row>
            <row>
              <entry>
                <userinput>admin set-register-server</userinput>
              </entry>
              <entry>integer</entry>
            </row>
            <row>
              <entry>
                <userinput>admin set-num-players</userinput>
              </entry>
              <entry>integer</entry>
            </row>
            <row>
              <entry>
                <userinput>admin set-sevens-rule</userinput>
              </entry>
              <entry>integer</entry>
            </row>
            <row>
              <entry>
                <userinput>admin set-dice-deck</userinput>
              </entry>
              <entry>boolean (0/1)</entry>
            </row>
            <row>
              <entry>
                <userinput>admin set-num-dice-decks</userinput>
              </entry>
              <entry>integer</entry>
            </row>
            <row>
              <entry>
                <userinput>admin set-num-removed-dice-cards</userinput>
              </entry>
              <entry>integer</entry>
            </row>
            <row>
              <entry>
                <userinput>admin set-victory-points</userinput>
              </entry>
              <entry>integer</entry>
            </row>
            <row>
              <entry>
                <userinput>admin set-random-terrain</userinput>
              </entry>
              <entry>integer</entry>
            </row>
            <row>
              <entry>
                <userinput>admin set-game</userinput>
              </entry>
              <entry>string</entry>
            </row>
            <row>
              <entry>
                <userinput>admin quit</userinput>
              </entry>
              <entry>none</entry>
            </row>
            <row>
              <entry>
                <userinput>admin send-message</userinput>
              </entry>
              <entry>string</entry>
            </row>
            <row>
              <entry>
                <userinput>admin help</userinput>
              </entry>
              <entry>none</entry>
            </row>
            <row>
              <entry>
                <userinput>admin info</userinput>
              </entry>
              <entry>none</entry>
            </row>
            <row>
              <entry>
                <userinput>admin fix-dice</userinput>
              </entry>
              <entry>none</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <para><userinput>admin set-game</userinput> should be used before the
          other game parameters are changed, because it changes all game
          parameters.
        </para>
      <note>
        <para>
          If a game was running while a game parameter is changed,
          it will be aborted.
        </para>
      </note>
      <para>
          When no game is running when <userinput>admin quit</userinput>
          is issued, the server will quit.
        </para>
    </chapter>
  </part>
</book>
